기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # Amazon QLDB에서 저널 데이터 스트리밍 **중요** 지원 종료 공지: 기존 고객은 07/31/2025에 지원이 종료될 때까지 Amazon QLDB를 사용할 수 있습니다. 자세한 내용은 [Amazon QLDB 원장을 Amazon Aurora PostgreSQL로 마이그레이션](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)을 참조하세요. Amazon QLDB는 *저널*이라고 하는 변경 불가능한 트랜잭션 로그를 데이터 스토리지에 사용합니다. 저널은 커밋된 데이터의 모든 변경 내용을 추적하고 시간이 지나면서 완전하고 확인 가능한 시간대별 변경 기록을 유지합니다. QLDB에서 저널에 커밋된 모든 문서 수정본을 수집하고 이 데이터를 [Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams)에 거의 실시간으로 전송할 수 있는 *스트림*을 QLDB에서 생성할 수 있습니다. QLDB 스트림은 원장의 저널에서 Kinesis 데이터 스트림 리소스로의 지속적인 데이터 흐름입니다. 그런 다음 Kinesis 스트리밍 플랫폼 또는 *Kinesis Client Library*를 사용하여 스트림을 사용하고, 데이터 레코드를 처리하고, 데이터 콘텐츠를 분석할 수 있습니다. QLDB 스트림은 *제어*, *블록 요약*, *수정 세부 정보* 등 세 가지 유형의 레코드로 Kinesis Data Streams에 데이터를 씁니다. 자세한 내용은 [Kinesis의 QLDB 스트림 레코드](streams.records.md)을 참조하십시오. **Topics** + [일반 사용 사례](#streams.use-cases) + [스트림 사용](#streams.consuming) + [전송 보증](#streams.delivery) + [전송 지연 시간 고려 사항](#streams.delivery-latency) + [데이터 스트림 시작하기](#streams.getting-started) + [QLDB에서 스트림 생성 및 관리](streams.create.md) + [QLDB에서 스트림을 사용한 개발](streams.sdk.md) + [Kinesis의 QLDB 스트림 레코드](streams.records.md) + [QLDB의 스트림 권한](streams.perms.md) + [QLDB의 저널 스트림에 대한 일반적인 오류](streams.errors.md) ## 일반 사용 사례 스트리밍을 사용하면 저널 데이터를 다른 서비스와 통합하면서 QLDB를 확인 가능한 단일 진실 공급원으로 사용할 수 있습니다. 다음은 QLDB 저널 스트림이 지원하는 몇 가지 일반적인 사용 사례입니다. + **이벤트 기반 아키텍처** - 분리된 구성 요소를 사용하여 이벤트 기반 아키텍처 스타일로 애플리케이션을 빌드합니다. 예를 들어 은행은 AWS Lambda 함수를 사용하여 계정 잔액이 임계값 아래로 떨어질 때 고객에게 알리는 알림 시스템을 구현할 수 있습니다. 이러한 시스템에서는 계정 잔액이 QLDB 원장에 유지되며 잔액 변경 사항은 저널에 기록됩니다. AWS Lambda 함수는 저널에 커밋되어 Kinesis 데이터 스트림으로 전송되는 밸런스 업데이트 이벤트를 소비할 때 알림 로직을 트리거할 수 있습니다. + **실시간 분석** - 이벤트 데이터에 대한 실시간 분석을 실행하는 Kinesis 소비자 애플리케이션을 빌드합니다. 이 기능을 사용하면 거의 실시간으로 통찰력을 얻고 변화하는 비즈니스 환경에 신속하게 대응할 수 있습니다. 예를 들어, 전자 상거래 웹 사이트는 제품 판매 데이터를 분석하고 판매량이 한도에 도달하는 즉시 할인된 제품에 대한 광고를 중단할 수 있습니다. + **기록 분석**- 과거 이벤트 데이터를 재생하여 Amazon QLDB의 저널 지향 아키텍처를 활용합니다. 과거 어느 시점에서든 QLDB 스트림을 시작하도록 선택할 수 있으며, 이 경우 해당 시점 이후의 모든 수정본이 Kinesis Data Streams에 전달됩니다. 이 기능을 사용하면 기록 데이터에 대한 분석 작업을 실행하는 Kinesis 소비자 애플리케이션을 빌드할 수 있습니다. 예를 들어 전자 상거래 웹 사이트는 필요에 따라 분석을 실행하여 이전에 포착되지 않았던 과거 판매 지표를 생성할 수 있습니다. + **목적별 데이터베이스로 복제** - QLDB 저널 스트림을 사용하여 QLDB 원장을 다른 목적별 데이터 스토어에 연결합니다. 예를 들어 Kinesis 스트리밍 데이터 플랫폼을 사용하여 QLDB 문서에 대한 전체 텍스트 검색 기능을 제공할 수 있는Amazon OpenSearch Service와 통합할 수 있습니다. 또한 사용자 지정 Kinesis 소비자 애플리케이션을 빌드하여 저널 데이터를 다양한 구체화된 뷰를 제공하는 다른 목적별 데이터베이스에 복제할 수 있습니다. 예를 들어 관계형 데이터의 경우 Amazon Aurora로, 그래프 기반 데이터의 경우 Amazon Neptune으로 복제합니다. ## 스트림 사용 Kinesis Data Streams를 사용하여 대량의 데이터 레코드 스트림을 지속적으로 소비, 처리 및 분석할 수 있습니다. Kinesis Data Streams 외에도 Kinesis 스트리밍 데이터 플랫폼에는 [Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/) 및 [Amazon Managed Service for Apache Flink](https://docs.aws.amazon.com/kinesisanalytics/latest/dev/)가 포함되어 있습니다. 이 플랫폼을 사용하여Amazon OpenSearch Service, Amazon Redshift, Amazon S3 또는 Splunk와 같은 서비스에 데이터 레코드를 직접 보낼 수 있습니다. 자세한 내용을 알아보려면 *Amazon Kinesis Data Streams 개발자 안내서*의 [Amazon Kinesis Streams 주요 개념](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-consumers.html)을 참조하세요. Kinesis Client Library(KCL)를 사용하여 사용자 지정 방식으로 데이터 레코드를 처리하는 스트림 소비자 애플리케이션을 빌드할 수도 있습니다. KCL은 하위 수준의 Kinesis Data Streams API에 유용한 추상화를 제공하여 코딩을 단순화합니다. KCL에 대한 자세한 내용은 *Amazon Kinesis Data Streams 개발자 안내서*의 [Kinesis Client Library를 사용](https://docs.aws.amazon.com/streams/latest/dev/shared-throughput-kcl-consumers.html)을 참조하세요. ## 전송 보증 QLDB 스트림은 *최소 한 번* 전송 보장을 제공합니다. QLDB 스트림에서 생성된 각 [데이터 레코드](streams.records.md)는 Kinesis Data Streams에 한 번 이상 전송됩니다. Kinesis 데이터 스트림에는 동일한 레코드가 여러 번 표시될 수 있습니다. 따라서 사용 사례에 필요한 경우 소비자 애플리케이션 계층에 중복 제거 로직이 있어야 합니다. 순서 또한 보장되지 않습니다. 경우에 따라 Kinesis 데이터 스트림에서 QLDB 블록 및 수정본이 순서대로 생성되지 않을 수 있습니다. 자세한 내용은 [중복되거나 순서가 잘못된 레코드 처리](streams.records.md#streams.records.ordering)을 참조하십시오. ## 전송 지연 시간 고려 사항 QLDB 스트림은 일반적으로 거의 실시간으로 Kinesis Data Streams에 업데이트를 전송합니다. 하지만 다음 시나리오에서는 새로 커밋된 QLDB 데이터가 Kinesis 데이터 스트림으로 전송되기 전에 추가 지연이 발생할 수 있습니다. + Kinesis는 Kinesis Data Streams 프로비저닝에 따라 QLDB에서 스트리밍되는 데이터를 제한할 수 있습니다. 예를 들어, 단일 Kinesis 데이터 스트림에 쓰는 QLDB 스트림이 여러 개 있고 QLDB의 요청률이 Kinesis 스트림 리소스의 용량을 초과하는 경우, 이 문제가 발생할 수 있습니다. Kinesis의 제한은 온디맨드 프로비저닝을 사용할 때도 15분 이내에 처리량이 이전 최고치의 두 배 이상으로 증가하는 경우 발생할 수 있습니다. Kinesis 지표 `WriteProvisionedThroughputExceeded`를 모니터링하여 초과 처리량을 측정할 수 있습니다. 자세한 내용과 가능한 해결 방법은 [Kinesis Data Streams에서 제한 오류를 해결하려면 어떻게 해야 하나요?](https://aws.amazon.com/premiumsupport/knowledge-center/kinesis-data-stream-throttling-errors/) 섹션을 참조하세요. + QLDB 스트림을 사용하면 *시작 날짜 및 시간*이 과거이고 *종료 날짜 및 시간*이 없는 무기한 스트림을 만들 수 있습니다. 설계상 QLDB는 지정된 시작 날짜 및 시간의 모든 이전 데이터가 성공적으로 전송된 후에만 Kinesis Data Streams에 새로 커밋된 데이터를 내보내기 시작합니다. 이 시나리오에서 추가 지연이 감지되면 이전 데이터가 전송될 때까지 기다리거나 나중의 시작 날짜 및 시간부터 스트림을 시작할 수도 있습니다. ## 데이터 스트림 시작하기 다음은 Kinesis Data Streams로 저널 데이터 스트리밍을 시작하는 데 필요한 단계에 대한 상위 수준의 개요입니다. 1. Kinesis Data Streams 리소스를 생성합니다. 지침은 *Amazon Kinesis Data Streams 개발자 안내서*의 [데이터 스트림 만들기 및 업데이트](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html)를 참조하세요. 1. QLDB가 Kinesis 데이터 스트림에 대한 쓰기 권한을 맡을 수 있도록 허용하는 IAM 역할을 생성합니다. 지침은 [QLDB의 스트림 권한](streams.perms.md) 섹션을 참조하세요. 1. QLDB 저널 스트림을 생성합니다. 지침은 [QLDB에서 스트림 생성 및 관리](streams.create.md) 섹션을 참조하세요. 1. 이전 섹션 [스트림 사용](#streams.consuming)에서 설명한 대로 Kinesis 데이터 스트림을 사용합니다. Kinesis Client Library를 사용하는 방법을 보여주는 코드 예제는 섹션을 AWS Lambda참조하세요[QLDB에서 스트림을 사용한 개발](streams.sdk.md). # QLDB에서 스트림 생성 및 관리 **중요** 지원 종료 공지: 기존 고객은 07/31/2025에 지원이 종료될 때까지 Amazon QLDB를 사용할 수 있습니다. 자세한 내용은 [Amazon QLDB 원장을 Amazon Aurora PostgreSQL로 마이그레이션](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)을 참조하세요. Amazon QLDB는 원장에서 Amazon Kinesis Data Streams로 전달되는 저널 데이터 스트림을 생성하고 관리하기 위한 API 작업을 제공합니다. QLDB 스트림은 저널에 커밋된 모든 문서 수정본을 캡처하여 Kinesis 데이터 스트림으로 보냅니다. AWS Management Console, AWS SDK 또는 AWS Command Line Interface (AWS CLI)를 사용하여 저널 스트림을 생성할 수 있습니다. 또한 [AWS CloudFormation](https://aws.amazon.com/cloudformation) 템플릿을 사용하여 스트림을 생성할 수도 있습니다. 자세한 설명은 *AWS CloudFormation 사용자 가이드*의 [AWS::QLDB::Stream](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qldb-stream.html) 리소스를 참조하세요. **Topics** + [스트림 파라미터](#streams.create.params) + [스트림 ARN](#streams.create.arn) + [AWS Management Console](#streams.create.con) + [스트림 상태](#streams.create.states) + [손상된 스트림 처리](#streams.create.impaired) ## 스트림 파라미터 QLDB 저널 스트림을 생성하려면 다음 구성 파라미터를 제공해야 합니다. **원장 이름** 저널 데이터를 Kinesis Data Streams로 스트리밍하려는 QLDB 원장. **스트림 이름** QLDB 저널 스트림에 할당할 명칭입니다. 사용자 정의 명칭은 스트림의 목적을 식별하고 나타내는 데 도움이 될 수 있습니다. 주어진 원장의 경우, 스트림 명칭은 다른 *활성* 스트림들 사이에서 고유해야 합니다. 스트림 이름은 [Amazon QLDB 할당량 및 제한](limits.md#limits.naming)에 정의된 원장 이름과 동일한 명명 제약 조건을 갖습니다. QLDB는 스트림 이름 외에도 사용자가 생성하는 각 QLDB 스트림에 *스트림 ID*를 할당합니다. 스트림 ID는 상태에 관계없이 주어진 원장의 모든 스트림에서 고유합니다. **현재 날짜 및 시간** 스트리밍 저널 데이터를 시작할 시작 날짜 및 시간(경계값 포함)입니다. 이 값은 과거의 모든 날짜 및 시간일 수 있지만, 미래에는 사용할 수 없습니다. **현재 날짜 및 시간** 스트림이 끝날 때를 지정하는 독점 날짜 및 시간입니다. 종료 시간이 없는 무제한 스트림을 생성하는 경우 스트림을 종료하려면 수동으로 취소해야 합니다. 지정된 종료 날짜 및 시간에 아직 도달하지 않은 유한한 활성 스트림을 취소할 수도 있습니다. **대상 Kinesis 데이터 스트림** 스트림이 데이터 레코드를 쓰는 Kinesis Data Streams 대상 리소스입니다. Kinesis 데이터 스트림 생성 방법을 알아보려면 *Amazon Kinesis Data Streams 개발자 안내서*의 [데이터 스트림 만들기 및 업데이트](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html)를 참조하세요. + 크로스 리전 및 크로스 계정 간 스트림은 지원되지 않습니다. 지정된 Kinesis 데이터 스트림은 원장과 동일한 AWS 리전 과 계정에 있어야 합니다. + Kinesis Data Streams의 ***레코드 집계*는 기본적으로 활성화되어 있습니다.** QLDB에서 단일 Kinesis Data Streams 레코드에 여러 데이터 레코드를 게시하여 API 직접 호출당 전송되는 레코드 수를 늘릴 수 있도록 합니다. 레코드 집계는 레코드 처리에 중요한 영향을 미치며 **스트림 소비자의 집계를 해제해야 합니다**. 자세한 내용을 알아보려면 *Amazon Kinesis Data Streams 개발자 안내서*의 [KPL 주요 개념](https://docs.aws.amazon.com/streams/latest/dev/kinesis-kpl-concepts.html#kinesis-kpl-concepts-aggretation)과 [소비자 분해](https://docs.aws.amazon.com/streams/latest/dev/kinesis-kpl-consumer-deaggregation.html)를 참조하세요. **IAM 역할** QLDB가 Kinesis 데이터 스트림에 대한 쓰기 권한을 맡을 수 있도록 허용하는 IAM 역할입니다. QLDB 콘솔을 사용하여 이 역할을 자동으로 생성하거나 IAM에서 수동으로 생성할 수 있습니다. 수동으로 생성하는 방법을 알아보려면 [스트림 권한](streams.perms.md) 섹션을 참조하세요. 저널 스트림을 요청할 때 QLDB에 역할을 전달하려면 IAM 역할 리소스에서 `iam:PassRole` 작업을 수행할 수 있는 권한이 있어야 합니다. ## 스트림 ARN 모든 QLDB 저널 스트림은 원장의 하위 리소스이며 Amazon 리소스 이름(ARN)으로 고유하게 식별됩니다. 다음은 이름이 `exampleLedger`인 원장의 스트림 ID가 `IiPT4brpZCqCq3f4MTHbYy`인 QLDB 스트림의 예제 ARN입니다. ``` arn:aws:qldb:us-east-1:123456789012:stream/exampleLedger/IiPT4brpZCqCq3f4MTHbYy ``` 다음 섹션에서는 AWS Management Console을 사용하여 QLDB 스트림을 생성 및 취소하는 방법에 대해 설명합니다. ## AWS Management Console QLDB 콘솔을 사용하여 QLDB 스트림을 생성하거나 취소하려면 다음 단계에 따르세요. **태그를 만들려면(콘솔)** 1. 에 로그인 AWS Management Console하고 [https://console.aws.amazon.com/qldb](https://console.aws.amazon.com/qldb) Amazon QLDB 콘솔을 엽니다. 1. 탐색 창에서 **스트림**을 선택합니다. 1. **QLDB 스트림 생성**을 선택합니다. 1. **QLDB 스트림 생성** 페이지에서 다음 설정을 입력합니다. + **스트림 이름** - QLDB 저널 스트림에 할당할 이름입니다. + **원장** - 스트리밍하려는 저널 데이터가 있는 원장입니다. + **시작 날짜 및 시간** - 저널 데이터 스트리밍을 시작할 포함되는 타임스탬프로, 협정 세계시(UTC) 기준입니다. 이 타임스탬프의 기본값은 현재 날짜 및 시간입니다. 이 날짜는 미래일 수 없으며 **종료 날짜 및 시간**보다 이전이어야 합니다. + **종료 날짜 및 시간** - (선택 사항)스트림이 종료되는 시기를 지정하는 불포함되는 타임스탬프(UTC)입니다. 이 파라미터를 정의하지 않으면 취소하기 전까지 스트림이 무기한 실행됩니다. + **대상 스트림** - 스트림이 데이터 레코드를 쓰는 Kinesis Data Streams 대상 리소스입니다. ARN 형식을 사용합니다. ``` arn:aws:kinesis:aws-region:account-id:stream/kinesis-stream-name ``` 다음은 예입니다. ``` arn:aws:kinesis:us-east-1:123456789012:stream/stream-for-qldb ``` 크로스 리전 및 크로스 계정 간 스트림은 지원되지 않습니다. 지정된 Kinesis 데이터 스트림은 원장과 동일한 AWS 리전 및 계정에 있어야 합니다. + **Kinesis Data Streams에서 레코드 집계 활성화** - (기본적으로 활성화됨) QLDB가 단일 Kinesis Data Streams 레코드에 여러 데이터 레코드를 게시하여 API 직접 호출당 전송되는 레코드 수를 늘릴 수 있도록 합니다. + **서비스 액세스** - Kinesis 데이터 스트림에 QLDB 쓰기 권한을 부여하는 IAM 역할입니다. *저널 스트림을 요청할 때 QLDB에 역할을 전달하려면 IAM 역할 리소스에서 `iam:PassRole` 작업을 수행할 수 있는 권한이 있어야 합니다.* + **새 서비스 역할 생성 및 사용** - 콘솔에서 지정된 Kinesis 데이터 스트림에 필요한 권한을 가진 새 역할을 생성하도록 합니다. + **기존 서비스 역할 사용** - IAM에서 이 역할을 수동으로 생성하는 방법을 알아보려면 [스트림 권한](streams.perms.md) 섹션을 참조하세요. + **태그** - (선택 사항) 태그를 키 값 페어로 연결하여 메타데이터를 역할에 추가합니다. 태그를 구성하고 식별하는 데 도움이 되는 태그를 스트림에 추가할 수 있습니다. 자세한 내용은 [Amazon QLDB 리소스 태그 지정](tagging.md)을 참조하십시오. **태그 추가**를 선택한 다음 키-값 쌍을 적절히 입력합니다. 1. 원하는 대로 설정되었으면 **QLDB 스트림 생성**을 선택합니다. 요청이 성공적으로 제출되면 콘솔이 기본 **스트림** 페이지로 돌아가고 QLDB 스트림이 현재 상태와 함께 나열됩니다. 1. 스트림이 활성화되면 Kinesis를 사용하여 [소비자 애플리케이션](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-consumers.html)으로 스트림 데이터를 처리합니다. [https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis/)에서 Kinesis Data Streams 콘솔을 엽니다. 스트림 데이터 레코드의 형식에 대한 자세한 내용은 [Kinesis의 QLDB 스트림 레코드](streams.records.md) 섹션을 참조하세요. 오류가 발생하는 스트림을 처리하는 방법을 알아보려면 [손상된 스트림 처리](#streams.create.impaired) 섹션을 참조하세요. **스트림을 취소하려면(콘솔)** QLDB 스트림을 취소한 후에는 다시 시작할 수 없습니다. Kinesis Data Streams로의 데이터 전송을 재개하려면 새 QLDB 스트림을 생성하면 됩니다. 1. [https://console.aws.amazon.com/qldb](https://console.aws.amazon.com/qldb)에서 Amazon QLDB 콘솔을 엽니다. 1. 탐색 창에서 **스트림**을 선택합니다. 1. QLDB 스트림 목록에서 취소하려는 활성 스트림을 선택합니다. 1. **스트림 취소**를 선택합니다. 제공된 상자에 **cancel stream**를 입력하여 확인합니다. AWS SDK 또는와 함께 QLDB API를 사용하여 저널 스트림을 생성하고 관리하는 AWS CLI 방법에 대한 자세한 내용은 섹션을 참조하세요[QLDB에서 스트림을 사용한 개발](streams.sdk.md). ## 스트림 상태 QLDB 스트림의 상태는 다음 중 하나일 수 있습니다. + `ACTIVE` - 현재 스트리밍 중이거나 데이터 스트리밍을 위해 대기 중입니다(종료 시간이 없는 무제한 스트림용). + `COMPLETED` - 지정된 시간 범위 내에 모든 저널 블록 스트리밍을 성공적으로 마쳤습니다. 이것은 종료 상태입니다. + `CANCELED` - 지정된 종료 시간 전에 사용자 요청으로 종료되었으며, 더 이상 데이터를 스트리밍하지 않습니다. 이것은 종료 상태입니다. + `IMPAIRED` - 사용자 조치가 필요한 오류 때문에 Kinesis에 레코드를 쓸 수 없습니다. 이는 복구 가능한 터미널이 아닌 상태입니다. 1시간 이내에 오류를 해결하면 스트림은 자동으로 `ACTIVE` 상태로 전환됩니다. 1시간 후에도 오류가 해결되지 않으면 스트림은 자동으로 `FAILED` 상태로 전환됩니다. + `FAILED` - 오류로 인해 Kinesis에 레코드를 쓸 수 없으며 복구할 수 없는 터미널 상태입니다. 다음 다이어그램은 QLDB 스트림 리소스가 상태 사이를 전환하는 방법을 보여줍니다. ![\[QLDB 스트림 리소스가 활성, 취소, 완료, 손상 및 장애 상태 사이에서 어떻게 전환될 수 있는지를 보여주는 상태 다이어그램입니다.\]](http://docs.aws.amazon.com/ko_kr/qldb/latest/developerguide/images/stream-states.png) ### 터미널 스트림 만료 터미널 상태(`CANCELED`, `COMPLETED`, `FAILED`)에 있는 스트림 리소스에는 7일의 보존 기간이 적용됩니다. 이 한도가 만료되면 해당 파일은 자동으로 영구 삭제됩니다. 터미널 스트림이 삭제된 후에는 더 이상 QLDB 콘솔 또는 QLDB API를 사용하여 스트림 리소스를 설명하거나 나열할 수 없습니다. ## 손상된 스트림 처리 스트림에 오류가 발생하면 먼저 `IMPAIRED` 상태로 전환됩니다. QLDB는 최대 1시간 동안 `IMPAIRED` 스트림을 계속 재시도합니다. 1시간 이내에 오류를 해결하면 스트림은 자동으로 `ACTIVE` 상태로 전환됩니다. 1시간 후에도 오류가 해결되지 않으면 스트림은 자동으로 `FAILED` 상태로 전환됩니다. 손상되거나 장애가 발생한 스트림의 오류 원인은 다음 오류 원인 중 하나일 수 있습니다. + `KINESIS_STREAM_NOT_FOUND` - 대상 Kinesis Data Streams 리소스가 존재하지 않습니다. QLDB 스트림 요청에서 제공한 Kinesis 데이터 스트림이 올바른지 확인하세요. 그런 다음 Kinesis로 이동하여 지정한 데이터 스트림을 생성합니다. + `IAM_PERMISSION_REVOKED` - QLDB에 지정된 Kinesis 데이터 스트림에 데이터 레코드를 쓸 수 있는 충분한 권한이 없습니다. 지정된 Kinesis 데이터 스트림에 대해 QLDB 서비스(`qldb.amazonaws.com`)에 다음 작업에 대한 권한을 부여하는 정책을 정의했는지 확인하세요. + `kinesis:PutRecord` + `kinesis:PutRecords` + `kinesis:DescribeStream` + `kinesis:ListShards` ### 손상된 스트림 모니터링 스트림이 손상되면 QLDB 콘솔은 스트림에 대한 세부 정보와 발생한 오류를 보여주는 배너를 표시합니다. 또한 `DescribeJournalKinesisStream` API 작업을 사용하여 스트림의 상태와 기본 오류 원인을 확인할 수 있습니다. 또한 Amazon CloudWatch를 사용하여 스트림의 `IsImpaired` 지표를 모니터링하는 경보를 생성할 수 있습니다. CloudWatch와 함께 QLDB 지표 모니터링에 대한 자세한 내용은 [Amazon QLDB 차원 및 지표](monitoring-cloudwatch.md#qldb-metrics-dimensions) 섹션을 참조하세요. # QLDB에서 스트림을 사용한 개발 **중요** 지원 종료 공지: 기존 고객은 07/31/2025에 지원이 종료될 때까지 Amazon QLDB를 사용할 수 있습니다. 자세한 내용은 [Amazon QLDB 원장을 Amazon Aurora PostgreSQL로 마이그레이션](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)을 참조하세요. 이 섹션에서는 AWS SDK 또는와 함께 사용하여 Amazon QLDB에서 저널 스트림 AWS CLI 을 생성하고 관리할 수 있는 API 작업을 요약합니다. 또한 이러한 작업을 시연하고 Kinesis Client Library(KCL) 또는 AWS Lambda 를 사용하거나 스트림 소비자를 구현하는 샘플 애플리케이션에 대해서도 설명합니다. KCL을 사용하여 Amazon Kinesis Data Streams의 소비자 애플리케이션을 빌드할 수 있습니다. KCL은 하위 수준의 Kinesis Data Streams API에 유용한 추상화를 제공하여 코딩을 단순화합니다. KCL에 대한 자세한 내용은 *Amazon Kinesis Data Streams 개발자 안내서*의 [Kinesis Client Library를 사용](https://docs.aws.amazon.com/streams/latest/dev/shared-throughput-kcl-consumers.html)을 참조하세요. **Contents** + [QLDB 저널 스트림 API](#streams.sdk.api) + [샘플 애플리케이션](#streams.sdk.samples) + [기본 작업(Java)](#streams.sdk.samples.basic) + [OpenSearch Service과의 통합(Python)](#streams.sdk.samples.elastic) + [Amazon SNS 및 Amazon SQS와의 통합(Python)](#streams.sdk.samples.sns) ## QLDB 저널 스트림 API 애플리케이션 프로그램에서 사용할 수 있는 다음과 같은 기능이 QLDB API에서 제공됩니다. + `StreamJournalToKinesis` - 주어진 QLDB 원장에 대한 저널 스트림을 생성합니다. 스트림은 원장의 저널에 커밋된 모든 문서 개정본을 캡처하고 지정된 Kinesis Data Streams 리소스로 데이터를 전송합니다. + Kinesis Data Streams의 ***레코드 집계*는 기본적으로 활성화되어 있습니다.** QLDB에서 단일 Kinesis Data Streams 레코드에 여러 데이터 레코드를 게시하여 API 직접 호출당 전송되는 레코드 수를 늘릴 수 있도록 합니다. 레코드 집계는 레코드 처리에 중요한 영향을 미치며 **스트림 소비자의 집계를 해제해야 합니다**. 자세한 내용을 알아보려면 *Amazon Kinesis Data Streams 개발자 안내서*의 [KPL 주요 개념](https://docs.aws.amazon.com/streams/latest/dev/kinesis-kpl-concepts.html#kinesis-kpl-concepts-aggretation)과 [소비자 분해](https://docs.aws.amazon.com/streams/latest/dev/kinesis-kpl-consumer-deaggregation.html)를 참조하세요. + `DescribeJournalKinesisStream` - 주어진 QLDB 저널 스트림에 대한 세부 정보를 반환합니다. 출력에는 ARN, 스트림 이름, 현재 상태, 생성 시간, 원래 스트림 생성 요청의 파라미터가 포함됩니다. + `ListJournalKinesisStreamsForLedger` - 주어진 원장의 모든 QLDB 저널 스트림 설명자 목록을 반환합니다. 각 스트림 설명자의 출력에는 `DescribeJournalKinesisStream`에서 반환한 것과 동일한 세부 정보가 포함됩니다. + `CancelJournalKinesisStream` - 주어진 QLDB 저널 스트림을 종료합니다. 스트림을 취소하려면 스트림의 현재 상태가 `ACTIVE`이어야 합니다. 스트리밍을 취소한 후에는 다시 시작할 수 없습니다. Kinesis Data Streams로의 데이터 전송을 재개하려면 새 QLDB 스트림을 생성하면 됩니다. 이러한 API작업 설명 전체를 보려면 [Amazon QLDB API 참조](api-reference.md) 섹션을 참조하세요. 를 사용하여 저널 스트림을 생성하고 관리하는 방법에 대한 자세한 AWS CLI내용은 [AWS CLI 명령 참조](https://docs.aws.amazon.com/cli/latest/reference/qldb/index.html)를 참조하세요. ## 샘플 애플리케이션 QLDB는 저널 스트림을 사용한 다양한 작업을 시연하는 샘플 애플리케이션을 제공합니다. 이러한 애플리케이션은 [AWS 샘플 GitHub 사이트](https://github.com/aws-samples/?q=qldb)의 오픈 소스입니다. **Topics** + [기본 작업(Java)](#streams.sdk.samples.basic) + [OpenSearch Service과의 통합(Python)](#streams.sdk.samples.elastic) + [Amazon SNS 및 Amazon SQS와의 통합(Python)](#streams.sdk.samples.sns) ### 기본 작업(Java) QLDB 저널 스트림의 기본 작업을 보여주는 Java 코드 예제는 GitHub 리포지토리 [aws-samples/amazon-qldb-dmv-sample-java](https://github.com/aws-samples/amazon-qldb-dmv-sample-java/tree/master/src/main/java/software/amazon/qldb/tutorial/streams)를 참조하세요. 이 샘플 애플리케이션을 다운로드하여 설치하는 방법에 대한 자세한 내용은 [Amazon QLDB Java 샘플 애플리케이션 설치](sample-app.java.md) 섹션을 참조하세요. **참고** 애플리케이션을 설치한 후에는 원장을 만들기 위해 Java 자습서의 *1단계*로 진행하지 마세요. 이 스트리밍용 샘플 애플리케이션은 `vehicle-registration` 원장을 자동으로 생성합니다. 이 샘플 애플리케이션은 다음 모듈을 포함하여 [Java 자습서](getting-started.java.tutorial.md)와 관련 종속성의 전체 소스 코드를 패키징합니다. + [AWS SDK for Java](https://aws.amazon.com/sdk-for-java) - 원장, QLDB 저널 스트림, Kinesis 데이터 스트림을 비롯한 QLDB 및 Kinesis Data Streams 리소스를 모두 생성하고 삭제합니다. + [Java용 Amazon QLDB 드라이버](getting-started.java.md) - PartiQL 문을 사용하여 원장에 대한 데이터 트랜잭션을 실행합니다(테이블 생성 및 문서 삽입 포함). + [Kinesis Client Library](https://docs.aws.amazon.com/streams/latest/dev/developing-consumers-with-kcl.html) - Kinesis 데이터 스트림의 데이터를 사용하고 처리합니다. **코드 실행** [StreamJournal](https://github.com/aws-samples/amazon-qldb-dmv-sample-java/blob/master/src/main/java/software/amazon/qldb/tutorial/streams/StreamJournal.java) 클래스에는 다음 작업을 보여주는 자습서 코드가 포함되어 있습니다. 1. `vehicle-registration`라는 이름의 원장을 만들고 테이블을 만든 다음 샘플 데이터와 함께 로드합니다. **참고** 이 코드를 실행하기 전에 이미 `vehicle-registration`라는 이름이 지정된 활성화된 원장이 없는지 확인하세요. 1. Kinesis 데이터 스트림, QLDB가 Kinesis 데이터 스트림에 대한 쓰기 권한을 맡을 수 있도록 허용하는 Kinesis 데이터 스트림, IAM 역할을 생성합니다. 1. KCL을 사용하여 Kinesis 데이터 스트림을 처리하고 각 QLDB 데이터 레코드를 기록하는 스트림 리더를 시작할 수 있습니다. 1. 스트림 데이터를 사용하여 `vehicle-registration` 샘플 원장의 해시 체인을 확인할 수 있습니다. 1. 스트림 리더를 중지하고, QLDB 저널 스트림을 취소하고, 원장을 삭제하고, Kinesis 데이터 스트림을 삭제하여 모든 리소스를 정리합니다. `StreamJournal` 자습서 코드를 실행하려면 프로젝트 루트 디렉터리에서 다음 Gradle 명령을 입력합니다. ``` ./gradlew run -Dtutorial=streams.StreamJournal ``` ### OpenSearch Service과의 통합(Python) QLDB 스트림을 Amazon OpenSearch Service와 통합하는 방법을 보여주는 Python 샘플 애플리케이션을 보려면 GitHub 리포지토리 [aws-samples/amazon-qldb-streaming-amazon-opensearch-service-sample-python](https://github.com/aws-samples/amazon-qldb-streaming-amazon-opensearch-service-sample-python)을 참조하세요. 이 애플리케이션은 AWS Lambda 함수를 사용하여 Kinesis Data Streams 소비자를 구현합니다. 다음 `git` 명령을 입력하여 리포지토리를 복제합니다. ``` git clone https://github.com/aws-samples/amazon-qldb-streaming-amazon-opensearch-service-sample-python.git ``` 샘플 애플리케이션을 실행하려면 GitHub의 [README](https://github.com/aws-samples/amazon-qldb-streaming-amazon-opensearch-service-sample-python/blob/master/README.md)에서 지침을 참조하세요. ### Amazon SNS 및 Amazon SQS와의 통합(Python) QLDB 스트림을 Amazon Simple Notification Service(SNS)와 통합하는 방법을 보여주는 Python 샘플 애플리케이션은 GitHub 리포지토리 [aws-samples/amazon-qldb-streams-dmv-sample-lambda-python](https://github.com/aws-samples/amazon-qldb-streams-dmv-sample-lambda-python)을 참조하세요. 이 애플리케이션은 AWS Lambda 함수를 사용하여 Kinesis Data Streams 소비자를 구현합니다. Amazon Simple Queue Service(Amazon SQS) 대기열이 구독되어 있는 Amazon SNS 주제로 메시지를 전송합니다. 다음 `git` 명령을 입력하여 리포지토리를 복제합니다. ``` git clone https://github.com/aws-samples/amazon-qldb-streams-dmv-sample-lambda-python.git ``` 샘플 애플리케이션을 실행하려면 GitHub의 [README](https://github.com/aws-samples/amazon-qldb-streams-dmv-sample-lambda-python/blob/master/README.md)에서 지침을 참조하세요. # Kinesis의 QLDB 스트림 레코드 **중요** 지원 종료 공지: 기존 고객은 07/31/2025에 지원이 종료될 때까지 Amazon QLDB를 사용할 수 있습니다. 자세한 내용은 [Amazon QLDB 원장을 Amazon Aurora PostgreSQL로 마이그레이션](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)을 참조하세요. Amazon QLDB 스트림은 주어진 Amazon Kinesis Data Streams 리소스에 *control*, *블록 요약*, *수정 세부 정보* 등 세 가지 유형의 데이터 레코드를 기록합니다. 세 가지 레코드 유형은 모두 [Amazon Ion 형식](ion.md)의 *이진수 표현*으로 작성됩니다. 제어 레코드는 QLDB 스트림의 시작과 완료를 나타냅니다. 수정본이 저널에 커밋될 때마다 QLDB 스트림은 연결된 모든 저널 블록 데이터를 블록 요약 및 수정 세부 정보 레코드에 기록합니다. 세 가지 레코드 유형은 다형성입니다. 이들은 모두 QLDB 스트림 ARN, 레코드 유형 및 레코드 페이로드를 포함하는 공통 최상위 레코드로 구성됩니다. 이 최상위 수준 레코드의 형식은 다음과 같습니다. ``` { qldbStreamArn: string, recordType: string, payload: { //control | block summary | revision details record } } ``` `recordType` 필드는 다음 세 가지 값 중 하나를 가질 수 있습니다. + `CONTROL` + `BLOCK_SUMMARY` + `REVISION_DETAILS` 다음 섹션에서는 각 개별 페이로드 레코드의 형식과 콘텐츠를 설명합니다. **참고** QLDB는 모든 스트림 레코드를 Amazon Ion의 이진수 표현으로 Kinesis Data Streams에 씁니다. 다음 예는 레코드 콘텐츠를 읽기 쉬운 형식으로 설명하기 위해 Ion의 텍스트 표현으로 제공됩니다. **Topics** + [제어 레코드](#streams.records.control) + [블록 요약 레코드](#streams.records.block) + [수정본 세부 정보 레코드](#streams.records.revision) + [중복되거나 순서가 잘못된 레코드 처리](#streams.records.ordering) ## 제어 레코드 QLDB 스트림은 *제어* 레코드를 기록하여 시작 및 완료 이벤트를 표시합니다. 다음은 각 `controlRecordType`에 대한 샘플 데이터가 포함된 제어 레코드의 예입니다. + `CREATED` - QLDB 스트림이 새로 생성한 스트림이 활성 상태임을 나타내기 위해 Kinesis에 쓰는 첫 번째 레코드입니다. ``` { qldbStreamArn:"arn:aws:qldb:us-east-1:123456789012:stream/exampleLedger/IiPT4brpZCqCq3f4MTHbYy", recordType:"CONTROL", payload:{ controlRecordType:"CREATED" } } ``` + `COMPLETED` - QLDB 스트림이 스트림이 지정된 종료 날짜 및 시간에 도달했음을 나타내기 위해 Kinesis에 쓰는 마지막 레코드입니다. 스트림을 취소하면 이 레코드가 기록되지 않습니다. ``` { qldbStreamArn:"arn:aws:qldb:us-east-1:123456789012:stream/exampleLedger/IiPT4brpZCqCq3f4MTHbYy", recordType:"CONTROL", payload:{ controlRecordType:"COMPLETED" } } ``` ## 블록 요약 레코드 *블록 요약* 레코드는 문서 수정본이 커밋되는 저널 블록을 나타냅니다. [블록](journal-contents.md)은 트랜잭션 중에 QLDB 저널에 커밋되는 객체입니다. 블록 요약 레코드의 페이로드에는 블록을 커밋한 트랜잭션의 블록 주소, 타임스탬프 및 기타 메타데이터가 포함됩니다. 또한 블록 내 수정본의 요약 속성과 이를 커밋한 PartiQL 문도 포함됩니다. 다음은 샘플 데이터가 포함된 블록 요약 레코드의 예입니다. **참고** 이 블록 요약 예제는 정보 제공 목적으로만 제공됩니다. 표시된 해시는 실제 계산된 해시 값이 아닙니다. ``` { qldbStreamArn:"arn:aws:qldb:us-east-1:123456789012:stream/exampleLedger/IiPT4brpZCqCq3f4MTHbYy", recordType:"BLOCK_SUMMARY", payload:{ blockAddress:{ strandId:"ElYL30RGoqrFCbbaQn3K6m", sequenceNo:60807 }, transactionId:"9RWohCo7My4GGkxRETAJ6M", blockTimestamp:2019-09-18T17:00:14.601000001Z, blockHash:{{6Pk9KDYJd38ci09oaHxx0D2grtgh4QBBqbDS6i9quX8=}}, entriesHash:{{r5YoH6+NXDXxgoRzPREGAWJfn73KlZE0eTfbTxZWUDU=}}, previousBlockHash:{{K3ti0Agk7DEponywKcQCPRYVHb5RuyxdmQFTfrloptA=}}, entriesHashList:[ {{pbzvz6ofJC7mD2jvgfyrY/VtR01zIZHoWy8T1VcxlGo=}}, {{k2brC23DLMercmiOWHiURaGwHu0mQtLzdNPuviE2rcs=}}, {{hvw1EV8k4oOkIO36kblO/+UUSFUQqCanKuDGr0aP9nQ=}}, {{ZrLbkyzDcpJ9KWsZMZqRuKUkG/czLIJ4US+K5E31b+Q=}} ], transactionInfo:{ statements:[ { statement:"SELECT * FROM Person WHERE GovId = ?", startTime:2019-09-18T17:00:14.587Z, statementDigest:{{p4Dn0DiuYD3Xm9UQQ75YLwmoMbSfJmopOmTfMnXs26M=}} }, { statement:"INSERT INTO Person ?", startTime:2019-09-18T17:00:14.594Z, statementDigest:{{klMLkLfa5VJqk6JUPtHkQpOsDdG4HmuUaq/VaApQflU=}} }, { statement:"INSERT INTO VehicleRegistration ?", startTime:2019-09-18T17:00:14.598Z, statementDigest:{{B0gO9BWVNrzRYFoe7t+GVLpJ6uZcLKf5t/chkfRhspI=}} } ], documents:{ '7z2OpEBgVCvCtwvx4a2JGn':{ tableName:"Person", tableId:"LSkFkQvkIOjCmpTZpkfpn9", statements:[1] }, 'K0FpsSLpydLDr7hi6KUzqk':{ tableName:"VehicleRegistration", tableId:"Ad3A07z0ZffC7Gpso7BXyO", statements:[2] } } }, revisionSummaries:[ { hash:{{uDthuiqSy4FwjZssyCiyFd90XoPSlIwomHBdF/OrmkE=}}, documentId:"7z2OpEBgVCvCtwvx4a2JGn" }, { hash:{{qJID/amu0gN3dpG5Tg0FfIFTh/U5yFkfT+g/O6k5sPM=}}, documentId:"K0FpsSLpydLDr7hi6KUzqk" } ] } } ``` `revisionSummaries` 필드의 일부 수정본에는 `documentId`가 없을 수 있습니다. 이는 사용자 데이터를 포함하지 않는 내부 전용 시스템 수정본입니다. 이러한 수정본의 해시는 저널의 전체 해시 체인의 일부이기 때문에 QLDB 스트림은 해당 블록 요약 레코드에 이러한 수정본을 포함합니다. 암호화 확인에는 전체 해시 체인이 필요합니다. 다음 섹션에 설명된 대로 문서 ID가 있는 수정본만 별도의 수정본 세부 정보 레코드에 게시됩니다. ## 수정본 세부 정보 레코드 *수정 세부 정보* 레코드는 저널에 커밋된 문서 수정본을 나타냅니다. 페이로드에는 수정본의 [커밋된 보기](working.metadata.md)의 모든 속성이 관련 테이블 이름 및 테이블 ID와 함께 포함되어 있습니다. 다음은 샘플 데이터가 포함된 수정 레코드의 예입니다. ``` { qldbStreamArn:"arn:aws:qldb:us-east-1:123456789012:stream/exampleLedger/IiPT4brpZCqCq3f4MTHbYy", recordType:"REVISION_DETAILS", payload:{ tableInfo:{ tableName:"VehicleRegistration", tableId:"Ad3A07z0ZffC7Gpso7BXyO" }, revision:{ blockAddress:{ strandId:"ElYL30RGoqrFCbbaQn3K6m", sequenceNo:60807 }, hash:{{qJID/amu0gN3dpG5Tg0FfIFTh/U5yFkfT+g/O6k5sPM=}}, data:{ VIN:"1N4AL11D75C109151", LicensePlateNumber:"LEWISR261LL", State:"WA", City:"Seattle", PendingPenaltyTicketAmount:90.25, ValidFromDate:2017-08-21, ValidToDate:2020-05-11, Owners:{ PrimaryOwner:{PersonId:"7z2OpEBgVCvCtwvx4a2JGn"}, SecondaryOwners:[] } }, metadata:{ id:"K0FpsSLpydLDr7hi6KUzqk", version:0, txTime:2019-09-18T17:00:14.602Z, txId:"9RWohCo7My4GGkxRETAJ6M" } } } } ``` ## 중복되거나 순서가 잘못된 레코드 처리 QLDB 스트림은 중복되거나 순서가 잘못된 레코드를 Kinesis Data Streams에 게시할 수 있습니다. 따라서 소비자 애플리케이션은 이러한 시나리오를 식별하고 처리하기 위해 자체 로직을 구현해야 할 수 있습니다. 블록 요약 및 수정 세부 정보 레코드에는 이러한 목적으로 사용할 수 있는 필드가 포함되어 있습니다. 이러한 필드를 다운스트림 서비스의 기능과 함께 사용하면 고유한 ID와 레코드의 엄격한 순서를 모두 나타낼 수 있습니다. 문서에 대한 전체 텍스트 검색 기능을 제공하기 위해 QLDB를 OpenSearch 인덱스와 통합하는 스트림을 예로 들어 보겠습니다. 이 사용 사례에서는 문서의 오래된(잘못된 순서) 수정본을 인덱싱하지 않도록 해야 합니다. 정렬 및 중복 제거를 적용하려면 OpenSearch의 문서 ID 및 외부 버전 필드를 수정 세부 정보 레코드의 문서 ID 및 버전 필드와 함께 사용할 수 있습니다. QLDB를 Amazon OpenSearch Service와 통합하는 샘플 애플리케이션의 중복 제거 로직의 예는 GitHub 리포지토리 [aws-samples/amazon-qldb-streaming-amazon-opensearch-service-sample-python](https://github.com/aws-samples/amazon-qldb-streaming-amazon-opensearch-service-sample-python)을 참조하세요. # QLDB의 스트림 권한 **중요** 지원 종료 공지: 기존 고객은 07/31/2025에 지원이 종료될 때까지 Amazon QLDB를 사용할 수 있습니다. 자세한 내용은 [Amazon QLDB 원장을 Amazon Aurora PostgreSQL로 마이그레이션](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)을 참조하세요. Amazon QLDB 스트림을 생성하기 전에 지정된 Amazon Kinesis Data Streams 리소스에 대한 쓰기 권한을 QLDB에 제공해야 합니다. Kinesis 스트림의 서버 측 암호화에 고객 관리형 AWS KMS key 를 사용하는 경우 QLDB에 지정된 대칭 암호화 키를 사용할 수 있는 권한도 제공해야 합니다. Kinesis Data Streams는 [비대칭 KMS 키](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)를 지원하지 않습니다. QLDB 스트림에 필요한 권한을 제공하려면 적절한 권한 정책을 사용하여 QLDB가 IAM 서비스 역할을 맡도록 합니다. 서비스 역할은 서비스가 사용자를 대신하여 작업을 수행하는 것으로 가정하는 [IAM 역할](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)입니다. IAM 관리자는 IAM 내에서 서비스 역할을 생성, 수정 및 삭제할 수 있습니다. 자세한 정보는 *IAM 사용 설명서*의 [Create a role to delegate permissions to an AWS 서비스](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)를 참조하세요. **참고** 저널 스트림을 요청할 때 QLDB에 역할을 전달하려면 IAM 역할 리소스에서 `iam:PassRole` 작업을 수행할 수 있는 권한이 있어야 합니다. 이는 QLDB 스트림 하위 리소스에 대한 `qldb:StreamJournalToKinesis` 권한에 추가됩니다. IAM을 사용하여 QLDB에 대한 액세스를 제어하는 방법을 알아보려면 [Amazon QLDB에서 IAM을 사용하는 방법](security_iam_service-with-iam.md) 섹션을 참조하세요. QLDB 정책 예제는 [Amazon QLDB의 자격 증명 기반 정책 예](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-stream-to-kinesis) 섹션을 참조하세요. 이 예시에서는 QLDB가 사용자 대신 Kinesis 데이터 스트림에 데이터 레코드를 기록하도록 허용하는 역할을 생성합니다. 자세한 내용은 *IAM 사용자 설명서*의 [역할을 생성하여  AWS 서비스에게 권한 위임](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)을 참조하세요. 에서 QLDB 저널을 AWS 계정 처음 스트리밍하는 경우 먼저 다음을 수행하여 적절한 정책으로 IAM 역할을 생성해야 합니다. 또는 [QLDB 콘솔을 사용](streams.create.md#streams.create.con)하여 자동으로 역할을 생성할 수 있습니다. 또는 이전에 생성한 역할을 선택할 수 있습니다. **Topics** + [권한 정책 생성](#streams.perms.create-policy) + [IAM 역할 생성](#streams.perms.create-role) ## 권한 정책 생성 QLDB 스트림에 대한 권한 정책을 생성하려면 다음 단계를 완료합니다. 이 예제는 지정된 Kinesis 데이터 스트림에 데이터 레코드를 쓸 수 있는 권한을 QLDB에 부여하는 Kinesis Data Streams 정책을 보여줍니다. 해당하는 경우 이 예제에서는 QLDB가 대칭 암호화 KMS 키를 사용하도록 허용하는 키 정책도 보여줍니다. Kinesis Data Streams 정책에 대한 자세한 내용은 *Amazon Kinesis Data Streams 개발자 안내서*의 [IAM을 사용하여 Amazon Kinesis Data Streams 리소스에 대한 액세스 제어](https://docs.aws.amazon.com/streams/latest/dev/controlling-access.html) 및 [사용자 생성 KMS 키를 사용할 수 있는 권한](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html)을 참조하세요. AWS KMS 키 정책에 대한 자세한 내용은 *AWS Key Management Service 개발자 안내서*의 [에서 키 정책 사용을 AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) 참조하세요. **참고** Kinesis 데이터 스트림과 KMS 키는 모두 QLDB 원장과 동일한 AWS 리전 및 계정에 있어야 합니다. **JSON 정책 편집기를 사용하여 정책을 생성하려면** 1. 에 로그인 AWS Management Console 하고 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) IAM 콘솔을 엽니다. 1. 왼쪽의 탐색 열에서 **정책**을 선택합니다. **정책**을 처음으로 선택하는 경우 **관리형 정책 소개** 페이지가 나타납니다. **시작**을 선택합니다. 1. 페이지 상단에서 **정책 생성**을 선택합니다. 1. **JSON** 탭을 선택합니다. 1. JSON 정책 문서를 입력합니다. + Kinesis 스트림의 서버 측 암호화에 고객 관리형 KMS 키를 사용하는 경우 다음 예제 정책 문서를 사용하세요. 이 정책을 사용하려면 예제의*us-east-1*, *123456789012*, *kinesis-stream-name*, *1234abcd-12ab-34cd-56ef-1234567890ab*를 사용자 고유의 정보로 바꾸세요. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "QLDBStreamKinesisPermissions", "Action": [ "kinesis:PutRecord*", "kinesis:DescribeStream", "kinesis:ListShards" ], "Effect": "Allow", "Resource": "arn:aws:kinesis:us-east-1:123456789012:stream/kinesis-stream-name" }, { "Sid": "QLDBStreamKMSPermission", "Action": [ "kms:GenerateDataKey" ], "Effect": "Allow", "Resource": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ] } ``` + 다음은 정책 문서의 예입니다. 이 정책을 사용하려면 예제의*us-east-1*, *123456789012*, *kinesis-stream-name*을 사용자 고유의 정보로 바꾸세요 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "QLDBStreamKinesisPermissions", "Action": [ "kinesis:PutRecord*", "kinesis:DescribeStream", "kinesis:ListShards" ], "Effect": "Allow", "Resource": "arn:aws:kinesis:us-east-1:123456789012:stream/kinesis-stream-name" } ] } ``` 1. **정책 검토**를 선택합니다. **참고** 언제든지 **시각적 편집기** 및 **JSON** 탭을 전환할 수 있습니다. 그러나 변경을 수행하거나 **시각적 편집기** 탭에서 **정책 검토**를 선택한 경우 IAM은 시각적 편집기에 최적화되도록 정책을 재구성할 수 있습니다. 자세한 내용은 *IAM 사용자 설명서*의 [정책 재구성](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_policies.html#troubleshoot_viseditor-restructure)을 참조하세요. 1. **정책 검토** 페이지에서 생성하려는 정책의 **이름**과 **설명**(선택 사항)을 입력합니다. 정책 **요약**을 검토하여 정책이 부여한 권한을 확인합니다. 그런 다음 **정책 생성**을 선택하여 작업을 저장합니다. ## IAM 역할 생성 QLDB 스트림에 대한 권한 정책을 생성한 후 IAM 역할을 생성하고 정책을 여기에 연결할 수 있습니다. **QLDB에 대한 서비스 역할을 생성하는 방법(IAM 콘솔)** 1. 에 로그인 AWS Management Console 하고 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) IAM 콘솔을 엽니다. 1. IAM 콘솔의 탐색 창에서 **역할**을 선택하고 **역할 생성**을 선택합니다. 1. **신뢰할 수 있는 엔터티 유형**에 **AWS 서비스**를 선택합니다. 1. **서비스 또는 사용 사례**의 경우 **QLDB**를 선택한 다음 **QLDB** 사용 사례를 선택합니다. 1. **다음**을 선택합니다. 1. 앞에서 생성한 정책 옆의 상자를 선택합니다. 1. (선택 사항)[권한 경계](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)로서 설정됩니다. 이는 서비스 역할에서 가능한 고급 기능이며 서비스 링크된 역할은 아닙니다. 1. **권한 경계 설정** 섹션을 열고 **최대 역할 권한을 관리하기 위한 권한 경계 사용**을 선택합니다. IAM에는 계정의 AWS 관리형 및 고객 관리형 정책 목록이 포함됩니다. 1. 정책을 선택하여 권한 경계를 사용하세요. 1. **다음**을 선택합니다. 1. 역할의 목적을 식별하는 데 도움이 되는 역할 이름이나 역할 이름 접미사를 입력합니다. **중요** 역할 이름을 지정할 때는 다음 사항에 유의하세요. 역할 이름은 내에서 고유해야 하며 대/소문자를 구분할 AWS 계정수 없습니다. 예를 들어, 이름이 **PRODROLE**과 **prodrole**, 두 가지로 지정된 역할을 만들지 마세요. 역할 이름이 정책 또는 ARN의 일부로 사용되는 경우 역할 이름은 대소문자를 구분합니다. 그러나 로그인 프로세스와 같이 콘솔에서 역할 이름이 고객에게 표시되는 경우에는 역할 이름이 대소문자를 구분하지 않습니다. 다른 엔터티가 역할을 참조할 수 있기 때문에 역할이 생성된 후에는 역할 이름을 편집할 수 없습니다. 1. (선택 사항)**설명**에 역할에 대한 설명을 입력합니다. 1. (선택 사항) 역할에 대한 사용 사례와 권한을 편집하려면 **1단계: 신뢰할 수 있는 엔터티 선택** 또는 **2단계: 권한 추가** 섹션에서 **편집**을 선택합니다. 1. (선택 사항) 태그를 키-값 페어로 연결하여 역할을 식별, 구성 또는 검색합니다. IAM에서 태그를 사용하는 방법에 대한 자세한 내용은 *IAM 사용 설명서*의 [AWS Identity and Access Management 리소스에 대한 태그를 참조하세요](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html). 1. 역할을 검토한 다음 **역할 생성**을 선택합니다. 다음 JSON 문서는 QLDB가 특정 권한이 부여된 IAM 역할을 맡도록 허용하는 신뢰 정책의 예입니다. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "qldb.amazonaws.com" }, "Action": [ "sts:AssumeRole" ], "Condition": { "ArnEquals": { "aws:SourceArn": "arn:aws:qldb:us-east-1:123456789012:stream/myExampleLedger/*" }, "StringEquals": { "aws:SourceAccount": "123456789012" } } } ] } ``` **참고** 이 신뢰 정책 예시에서 `aws:SourceArn` 및 `aws:SourceAccount` 전역 조건 컨텍스트 키를 사용하여 *혼동된 대리자* 문제를 방지하는 방법을 보여줍니다. 이 신뢰 정책을 사용하면 QLDB는 원장 `myExampleLedger`에 대한 계정 `123456789012`의 모든 QLDB 스트림에 대한 역할만 맡을 수 있습니다. 자세한 내용은 [교차 서비스 혼동된 대리자 방지](cross-service-confused-deputy-prevention.md)을 참조하십시오. IAM 역할을 생성한 후 QLDB 콘솔로 돌아가서 **QLDB 스트림 생성** 페이지를 새로 고쳐 새 역할을 찾을 수 있도록 합니다. # QLDB의 저널 스트림에 대한 일반적인 오류 **중요** 지원 종료 공지: 기존 고객은 07/31/2025에 지원이 종료될 때까지 Amazon QLDB를 사용할 수 있습니다. 자세한 내용은 [Amazon QLDB 원장을 Amazon Aurora PostgreSQL로 마이그레이션](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)을 참조하세요. 이 섹션에서는 저널 스트림 요청에 대해 Amazon QLDB에서 발생하는 런타임 오류를 설명합니다. 다음은 서비스에서 반환하는 일반적인 예외 목록입니다. 각 예외에는 특정 오류 메시지와 가능한 해결 방법에 대한 간단한 설명 및 제안이 포함됩니다. **AccessDeniedException** 메시지: User: *userARN* is not authorized to perform: iam:PassRole on resource: *roleARN* IAM 역할을 QLDB 서비스에 전달할 권한이 없습니다. QLDB에는 모든 저널 스트림 요청에 대한 역할이 필요하며 이 역할을 QLDB에 전달할 수 있는 권한이 있어야 합니다. 이 역할은 지정된 Amazon Kinesis Data Streams 리소스에 대한 쓰기 권한을 QLDB에 제공합니다. QLDB 서비스(`qldb.amazonaws.com`)의 지정된 IAM 역할 리소스에서 `PassRole` API 작업을 수행할 권한을 부여하는 IAM 정책을 정의했는지 확인하세요. 정책 예제는 [Amazon QLDB의 자격 증명 기반 정책 예](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-stream-to-kinesis)을 참조하십시오. **IllegalArgumentException** 메시지: QLDB encountered an error validating Kinesis Data Streams: Response from Kinesis: *errorCode**errorMessage* 이 오류의 가능한 원인은 제공된 Kinesis Data Streams 리소스가 존재하지 않기 때문입니다. 또는 QLDB에 지정된 Kinesis 데이터 스트림에 데이터 레코드를 쓸 수 있는 충분한 권한이 없습니다. 스트림 요청에서 제공하는 Kinesis 데이터 스트림이 올바른지 확인하세요. 자세한 내용은 *Amazon Kinesis Data Streams 개발자 안내서*의 [데이터 스트림 생성 및 업데이트](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html)를 참조하세요. 또한 다음 작업에 QLDB 서비스(`qldb.amazonaws.com`) 권한을 부여하는 지정된 Kinesis 데이터 스트림에 대한 정책을 정의했는지 확인합니다. 자세한 내용은 [스트림 권한](streams.perms.md)을 참조하십시오. + `kinesis:PutRecord` + `kinesis:PutRecords` + `kinesis:DescribeStream` + `kinesis:ListShards` **IllegalArgumentException** 메시지: Kinesis 구성을 검증하는 동안 Kinesis 데이터 스트림에서 예상치 못한 응답이 발생했습니다. Kinesis의 응답: *errorCode**errorMessage* 제공된 Kinesis 오류 응답으로 인해 제공된 Kinesis 데이터 스트림에 데이터 레코드를 쓰려는 시도가 실패했습니다. 발생 가능한 원인에 대한 자세한 내용은 *Amazon Kinesis Data Streams 개발자 안내서*의 [Amazon Kinesis Data Streams 생산자 문제 해결](https://docs.aws.amazon.com/streams/latest/dev/troubleshooting-producers.html)을 참조하세요. **IllegalArgumentException** 메시지: 시작 날짜는 종료 날짜보다 이후일 수 없습니다. `InclusiveStartTime` 및 `ExclusiveEndTime`은 [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 날짜 및 시간 형식이어야 하며 협정 세계시(UTC)여야 합니다. **IllegalArgumentException** 메시지: 종료일은 미래일 수 없습니다 `InclusiveStartTime` 및 `ExclusiveEndTime`은 UTC 기준의 `ISO 8601` 날짜 및 시간 형식이어야 합니다. **LimitExceededException** 메시지: Kinesis Data Streams에 대한 동시 실행 저널 스트림 제한인 5개를 초과했습니다‭ ‬ QLDB는 기본적으로 동시 저널 스트림을 5개로 제한합니다.