Amazon Redshift는 패치 198부터 새 Python UDF 생성을 더 이상 지원하지 않습니다. 기존 Python UDF는 2026년 6월 30일까지 계속 작동합니다. 자세한 내용은 [블로그 게시물](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)을 참조하세요.
# Amazon Redshift Data API 사용
Amazon Redshift 데이터 API는 데이터베이스 드라이버, 연결, 네트워크 구성, 데이터 버퍼링, 자격 증명 등을 관리할 필요가 없도록 하여 Amazon Redshift 데이터 웨어하우스에 대한 액세스를 간소화합니다. AWS SDK에서 데이터 API 작업을 사용하여 SQL 문을 실행할 수 있습니다. 데이터 API 작업에 대한 자세한 내용은 [Amazon Redshift 데이터 API 참조](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)를 참조하세요.
데이터 API는 데이터베이스에 대한 지속적인 연결을 요구하지 않습니다. 대신에 AWS SDK와의 통합과 보안 HTTP 엔드포인트를 제공합니다. 연결을 관리하지 않고 엔드포인트를 사용하여 SQL 문을 실행할 수 있습니다. Data API에 대한 호출은 비동기식입니다. 데이터 API는 AWS Secrets Manager에 저장된 자격 증명 또는 임시 데이터베이스 자격 증명을 사용할 수 있습니다. 두 인증 방법 중 하나를 사용하여 API 호출에서 암호를 전달할 필요가 없습니다. AWS Secrets Manager에 대한 자세한 내용은 *AWS Secrets Manager User Guide*의 [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)를 참조하세요. 권한 부여에 AWS IAM Identity Center을 사용할 수도 있습니다.
이 데이터 API를 사용하면 프로그래밍 방식으로 AWS Lambda, Amazon SageMaker AI 노트북, AWS Cloud9을 포함한 웹 서비스 기반 애플리케이션으로 Amazon Redshift 데이터에 액세스할 수 있습니다. 이러한 애플리케이션에 대한 자세한 내용은 [AWS Lambda](https://aws.amazon.com/lambda/), [Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) 및 [AWS Cloud9](https://aws.amazon.com/cloud9/) 섹션을 참조하세요.
데이터 API에 대해 자세히 알아보려면 AWS 빅 데이터 블로그에서 [Get started with the Amazon Redshift Data API](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/)를 참조하세요**.
## Amazon Redshift Data API 작업
Amazon Redshift Data API를 사용하기 전에 다음 단계를 검토합니다.
1. Data API의 호출자로서 권한이 있는지 확인합니다. 권한 부여에 대한 자세한 내용은 [Amazon Redshift Data API에 대한 액세스 권한 부여](data-api-access.md) 섹션을 참조하세요.
1. Secrets Manager의 인증 자격 증명, 임시 자격 증명 또는 AWS IAM Identity Center을 사용하여 데이터 API를 직접적으로 호출할 계획인지 결정합니다. 자세한 내용은 [Amazon Redshift 데이터 API를 호출할 때 데이터베이스 인증 보안 인증 정보 선택](#data-api-calling-considerations-authentication) 섹션을 참조하세요.
1. 인증 자격 증명에 Secrets Manager 사용하는 경우 보안 암호를 설정합니다. 자세한 내용은 [AWS Secrets Manager에 데이터베이스 자격 증명 저장](data-api-secrets.md) 섹션을 참조하세요.
1. Data API를 호출할 때 고려 사항과 제한 사항을 검토합니다. 자세한 내용은 [Amazon Redshift Data API 호출 시 고려 사항](#data-api-calling-considerations) 섹션을 참조하세요.
1. AWS Command Line Interface(AWS CLI), 자체 코드 또는 Amazon Redshift 콘솔의 쿼리 편집기를 사용하여 Data API를 호출합니다. AWS CLI에서 호출 예는 [데이터 API 호출](data-api-calling.md) 섹션을 참조하세요.
## Amazon Redshift Data API 호출 시 고려 사항
Data API를 호출할 때는 다음 사항을 고려하세요.
+ Amazon Redshift 데이터 API는 Amazon Redshift 프로비저닝 클러스터와 Redshift Serverless 작업 그룹의 데이터베이스에 액세스할 수 있습니다. Redshift 데이터 API를 사용할 수 있는 AWS 리전 목록은 *Amazon Web Services 일반 참조*의 [Redshift 데이터 API](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html)에 나열된 엔드포인트를 참조하세요.
+ 최대 쿼리 기간은 24시간입니다.
+ Amazon Redshift 클러스터당 최대 활성 쿼리(`STARTED` 및 `SUBMITTED` 쿼리) 수는 500개입니다.
+ 최대 쿼리 결과 크기는 500MB(gzip 압축 후)입니다. 직접 호출이 500MB를 초과하는 응답 데이터를 반환하면 직접 호출이 종료됩니다.
+ 쿼리 결과의 최대 보존 시간은 24시간입니다.
+ 최대 쿼리 문 크기는 100KB입니다.
+ Data API는 다음 노드 유형의 단일 노드 및 다중 노드 클러스터를 쿼리하는 데 사용할 수 있습니다.
+ dc2.large
+ dc2.8xlarge
+ ra3.large
+ ra3.xlplus
+ ra3.4xlarge
+ ra3.16xlarge
+ 클러스터는 Amazon VPC 서비스 기반의 Virtual Private Cloud(VPC)에 있어야 합니다.
+ 기본적으로 `ExecuteStatement` 또는 `BatchExecuteStatement` API 작업의 실행자와 동일한 IAM 역할을 가진 사용자는 `CancelStatement`, `DescribeStatement`, `GetStatementResult`, `GetStatementResultV2` 및 `ListStatements` API 작업을 사용하여 동일한 문에 대해 작업할 수 있습니다. 다른 사용자의 동일한 SQL 문에 대해 작업을 수행하려면 사용자가 SQL 문을 실행한 사용자의 IAM 역할을 맡을 수 있어야 합니다. 역할 수임 방법에 대한 자세한 내용은 [Amazon Redshift Data API에 대한 액세스 권한 부여](data-api-access.md) 섹션을 참조하세요.
+ `BatchExecuteStatement` API 작업의 `Sqls` 파라미터에 포함된 SQL 문은 단일 트랜잭션으로 실행됩니다. 배열 순서대로 순차 실행됩니다. 후순위 SQL 문은 배열 내 선순위 명령문이 완료될 때까지 시작되지 않습니다. SQL 문이 실패하면 하나의 트랜잭션으로 실행되므로 모든 작업이 롤백됩니다.
+ `ExecuteStatement` 또는 `BatchExecuteStatement` API 작업에 사용되는 클라이언트 토큰의 최대 보존 시간은 8시간입니다.
+ Amazon Redshift 프로비저닝된 클러스터와 Redshift Serverless 작업 그룹이 고객 관리형 키를 사용하여 암호화된 경우 Redshift는 Redshift 데이터 API가 작업에 키를 사용할 수 있도록 허용하는 권한을 생성합니다. 자세한 내용은 [Amazon Redshift 데이터 API와 함께 AWS KMS 사용](data-api-kms.md) 단원을 참조하세요.
+ Redshift 데이터 API의 각 API에는 요청을 제한하기 전에 초당 트랜잭션 할당량이 있습니다. 할당량에 대한 내용은 [Amazon Redshift 데이터 API의 할당량](amazon-redshift-limits.md#data-api-quotas-account) 섹션을 참조하세요. 요청 비율이 할당량을 초과하면 HTTP 상태 코드가 400인 `ThrottlingException` 오류가 반환됩니다. 제한에 대응하려면 **AWSSDK 및 도구 참조 안내서의 [재시도 동작](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)에 설명된 재시도 전략을 사용하세요. 이 전략은 일부 AWS SDK의 제한 오류에 대해 자동으로 구현됩니다.
**참고**
AWS Step Functions에서는 기본적으로 재시도가 활성화되지 않습니다. Step Functions 상태 머신에서 Redshift 데이터 API를 호출해야 하는 경우 Redshift 데이터 API 호출에 `ClientToken` 멱등성 파라미터를 포함하세요. `ClientToken`의 값은 재시도 시 지속되어야 합니다. `ExecuteStatement` API에 대한 다음 요청 스니펫 예시에서 `States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)` 식은 내장 함수를 사용하여 `$$.Execution.Id`의 UUID 부분을 추출합니다. UUID 부분은 상태 머신을 실행할 때마다 고유합니다. 자세한 내용은 **AWS Step Functions 개발자 안내서의 [내장 함수](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html)를 참조하세요.
```
{
"Database": "dev",
"Sql": "select 1;",
"ClusterIdentifier": "MyCluster",
"ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```
## Amazon Redshift 데이터 API를 호출할 때 데이터베이스 인증 보안 인증 정보 선택
Data API를 호출할 때 일부 API 작업에 대해 다음 인증 방법 중 하나를 사용합니다. 각 방법에는 서로 다른 파라미터 조합이 필요합니다.
**AWS IAM Identity Center**
데이터 API는 AWS IAM Identity Center에 등록된 Single Sign-On 사용자로 액세스할 수 있습니다. IAM Identity Center를 설정하는 단계에 대한 자세한 내용은 [신뢰할 수 있는 자격 증명 전파와 함께 데이터 API 사용](data-api-trusted-identity-propagation.md) 섹션을 참조하세요.
**AWS Secrets Manager**
이 방법에서는 `username` 및 `password`가 있는 AWS Secrets Manager에 저장된 암호의 `secret-arn`을 입력합니다. 지정된 보안 암호에는 지정하는 `database`에 연결하기 위한 자격 증명이 포함되어 있습니다. 클러스터에 연결할 때는 데이터베이스 이름도 제공하며, 클러스터 식별자(`dbClusterIdentifier`)를 제공하는 경우 암호에 저장된 클러스터 식별자와 일치해야 합니다. 서버리스 작업 그룹에 연결할 때는 데이터베이스 이름도 제공합니다. 자세한 내용은 [AWS Secrets Manager에 데이터베이스 자격 증명 저장](data-api-secrets.md) 섹션을 참조하세요.
이 방법에서는 데이터가 위치한 AWS 리전을 지정하는 `region` 값을 제공할 수도 있습니다.
**임시 자격 증명**
이 방법에서는 다음 옵션 중 하나를 선택합니다.
+ 서버리스 작업 그룹에 연결할 때는 작업 그룹 이름과 데이터베이스 이름을 지정합니다. 데이터베이스 사용자 이름은 IAM ID에서 파생됩니다. 예를 들어, `arn:iam::123456789012:user:foo`에는 데이터베이스 사용자 이름인 `IAM:foo`가 포함되어 있습니다. 또한 `redshift-serverless:GetCredentials` 작업을 호출할 수 있는 권한이 필요합니다.
+ 클러스터에 IAM ID로 연결할 때는 클러스터 식별자 및 데이터베이스 이름을 지정합니다. 데이터베이스 사용자 이름은 IAM ID에서 파생됩니다. 예를 들어, `arn:iam::123456789012:user:foo`에는 데이터베이스 사용자 이름인 `IAM:foo`가 포함되어 있습니다. 또한 `redshift:GetClusterCredentialsWithIAM` 작업을 호출할 수 있는 권한이 필요합니다.
+ 클러스터에 데이터베이스 사용자로 연결할 때는 클러스터 식별자, 데이터베이스 이름 및 데이터베이스 사용자 이름을 지정합니다. 또한 `redshift:GetClusterCredentials` 작업을 호출할 수 있는 권한이 필요합니다. 이 방법으로 연결할 때 데이터베이스 그룹에 가입하는 방법에 대한 자세한 내용은 [클러스터에 연결할 때 데이터베이스 그룹에 조인](data-api-dbgroups.md)을 참조하세요.
이 방법에서는 데이터가 위치한 AWS 리전을 지정하는 `region` 값을 제공할 수도 있습니다.
## Amazon Redshift Data API를 호출할 때 JDBC 데이터 형식 매핑
다음 표는 JDBC(Java Database Connectivity) 데이터 유형을 데이터 API 호출에서 지정하는 데이터 형식에 매핑합니다.
****
| JDBC 데이터 형식 | 데이터 API 데이터 형식 |
| --- | --- |
| `INTEGER, SMALLINT, BIGINT` | `LONG` |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY` | `BLOB` |
| `VARBINARY` | `STRING` |
| `CLOB` | `STRING` |
| 다른 형식(날짜 및 시간과 관련된 형식 포함) | `STRING` |
문자열 값은 Amazon Redshift 데이터베이스로 전달되고 암시적으로 데이터베이스 데이터 형식으로 변환됩니다.
**참고**
현재, Data API는 범용 고유 식별자(UUID) 배열을 지원하지 않습니다.
## Amazon Redshift Data API를 호출할 때 파라미터로 SQL 문 실행
SQL 문의 일부에 대한 파라미터로 Data API 작업을 호출하여 데이터베이스 엔진에 제출된 SQL 텍스트를 제어할 수 있습니다. 명명된 파라미터는 SQL 텍스트에 하드코딩하지 않고 파라미터를 전달할 수 있는 유연한 방법을 제공합니다. SQL 텍스트를 재사용하고 SQL 삽입 문제를 방지하는 데 도움이 됩니다.
다음 예에서는 `execute-statement` AWS CLI 명령의 `parameters` 필드의 명명된 파라미터를 보여줍니다.
```
--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"
```
명명된 파라미터를 사용할 때는 다음 사항을 고려하세요.
+ 명명된 파라미터는 SQL 문의 값을 대체하는 데만 사용할 수 있습니다.
+ INSERT 문의 값을 대체할 수 있습니다(예: `INSERT INTO mytable VALUES(:val1)`).
명명된 파라미터는 임의의 순서로 지정할 수 있으며 SQL 텍스트에서 파라미터를 두 번 이상 사용할 수 있습니다. 이전 예에 표시된 파라미터 옵션에서 값 `1` 및 `Seattle`이 테이블 열 `id` 및 `address`에 삽입됩니다. SQL 텍스트에서 다음과 같이 명명된 파라미터를 지정합니다.
```
--sql "insert into mytable values (:id, :address)"
```
+ 조건 절의 값(예: `WHERE attr >= :val1`, `WHERE attr BETWEEN :val1 AND :val2` 및 `HAVING COUNT(attr) > :val`)을 대체할 수 있습니다.
+ SQL 문의 열 이름(예: `SELECT column-name`, `ORDER BY column-name` 또는 `GROUP BY column-name`)은 대체할 수 없습니다.
예를 들어, 다음 SELECT 문은 잘못된 구문으로 실패합니다.
```
--sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"
```
구문 오류가 있는 문을 설명(`describe-statement` 작업)하면 반환된 `QueryString`이 파라미터(`"QueryString": "SELECT :colname, FROM event"`)의 열 이름을 대체하지 않으며 오류가 보고됩니다(오류: \$1"FROM\$1" 또는 근처에 구문 오류가 있음\$1n 위치: 12).
+ 집계 함수의 열 이름(예: `COUNT(column-name)`, `AVG(column-name)` 또는 `SUM(column-name)`)은 대체할 수 없습니다.
+ JOIN 절의 열 이름은 대체할 수 없습니다.
+ SQL 실행 시 암시적으로 데이터가 데이터 형식으로 캐스팅됩니다. 데이터 형식 캐스팅에 대한 자세한 내용은 *Amazon Redshift 데이터베이스 개발자 안내서*의 [데이터 형식](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)을 참조하세요.
+ 값을 NULL로 설정할 수 없습니다. Data API는 이를 리터럴 문자열 `NULL`로 해석합니다. 다음 예에서는 `id`를 리터럴 문자열 `null`로 바꿉니다. SQL NULL 값이 아닙니다.
```
--parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
```
+ 길이가 0인 값을 설정할 수 없습니다. Data API SQL 문이 실패합니다. 다음 예에서는 `id`를 길이가 0인 값으로 설정하려고 하여 SQL 문이 실패합니다.
```
--parameters "[{\"name\": \"id\", \"value\": \"\"}]"
```
+ 파라미터를 사용하여 SQL 문에서 테이블 이름을 설정할 수 없습니다. Data API는 JDBC `PreparedStatement`의 규칙을 따릅니다.
+ `describe-statement` 작업의 출력은 SQL 문의 쿼리 파라미터를 반환합니다.
+ `execute-statement` 작업만 파라미터가 있는 SQL 문을 지원합니다.
## Amazon Redshift Data API를 호출할 때 멱등성 토큰으로 SQL 문 실행
변형 API 요청을 만들 때 요청은 일반적으로 작업의 비동기 워크플로가 완료되기 전에 결과를 반환합니다. 요청이 이미 결과를 반환했더라도 작업이 완료되기 전에 시간이 초과되거나 다른 서버 문제가 발생할 수도 있습니다. 이로 인해 요청의 성공 여부를 판단하기 어려울 수 있으며 작업이 성공적으로 완료되었는지 확인하기 위해 여러 번의 재시도가 발생할 수 있습니다. 그러나 원래 요청과 후속 재시도가 성공하면 작업이 여러 번 완료됩니다. 즉, 의도한 것보다 더 많은 리소스를 업데이트할 수 있습니다.
*멱등성*은 API 요청이 한 번만 완료되도록 합니다. 멱등성 요청을 사용하면 원래 요청이 성공적으로 완료되면 추가 작업을 수행하지 않고 후속 재시도가 성공적으로 완료됩니다. 데이터 API `ExecuteStatement` 및 `BatchExecuteStatement` 작업에는 선택적 `ClientToken` 멱등성 파라미터가 있습니다. `ClientToken`은 8시간 후에 만료됩니다.
**중요**
AWS SDK에서 `ExecuteStatement` 및 `BatchExecuteStatement` 작업을 호출하면 재시도 시 사용할 클라이언트 토큰이 자동으로 생성됩니다. 이 경우 `ExecuteStatement` 및 `BatchExecuteStatement` 작업과 함께 `client-token` 파라미터를 사용하지 않는 것이 좋습니다. ClientToken을 보려면 `ClientToken`를 참조하세요. CloudTrail 로그 예제는 [Amazon Redshift Data API 예제](logging-with-cloudtrail.md#data-api-cloudtrail)를 참조하세요.
다음 `execute-statement` AWS CLI 명령은 멱등성을 위한 선택적 `client-token` 파라미터를 보여줍니다.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
--client-token b855dced-259b-444c-bc7b-d3e8e33f94g1
```
다음 테이블은 멱등성 API 요청에 대해 얻을 수 있는 몇 가지 일반적인 응답을 보여주고 재시도 권장 사항을 제공합니다.
| 응답 | 권장 사항 | 설명 |
| --- | --- | --- |
| 200 OK | 다시 시도하지 않음 | 원래 요청이 성공적으로 완료되었습니다. 이후의 모든 재시도는 성공적으로 반환됩니다. |
| 400 시리즈 응답 코드 | 다시 시도하지 않음 | 다음 중에서는 요청에 문제가 있습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/redshift/latest/mgmt/data-api.html) 요청에 상태 변경 프로세스에 있는 리소스가 포함된 경우 요청 재시도가 성공할 수 있습니다. |
| 500 시리즈 응답 코드 | 재시도 | 이 오류는 AWS 서버 측 문제로 인해 발생하며 일반적으로 일시적입니다. 적절한 백오프 전략으로 요청을 반복합니다. |
Amazon Redshift 응답 코드에 대한 자세한 내용은 *Amazon Redshift API 참조*의 [Common Errors](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html)(일반 오류)를 참조하세요.
## Amazon Redshift Data API를 직접 호출할 때 세션 재사용으로 SQL 문 실행
SQL 문을 실행하기 위해 API를 요청하면 일반적으로 SQL이 종료될 때 SQL이 실행되는 세션이 종료됩니다. 지정된 시간 동안 세션을 활성화하려면 Data API `ExecuteStatement` 및 `BatchExecuteStatement` 작업에는 옵션인 `SessionKeepAliveSeconds` 파라미터가 있습니다. `SessionId` 응답 필드에는 세션의 ID가 포함되어 있으며, 이는 후속 `ExecuteStatement` 및 `BatchExecuteStatement` 작업에 사용할 수 있습니다. 후속 직접 호출에서 유휴 제한 시간을 변경하려면 다른 `SessionKeepAliveSeconds`를 지정할 수 있습니다. `SessionKeepAliveSeconds`를 변경하지 않으면 초기 유휴 제한 시간 설정이 그대로 유지됩니다. 세션 재사용을 활용할 때는 다음을 고려하세요.
+ `SessionKeepAliveSeconds`의 최댓값은 24시간입니다.
+ 세션은 최대 24시간 동안 지속될 수 있습니다. 24시간이 지나면 세션이 강제로 닫히고 진행 중인 쿼리가 종료됩니다.
+ Amazon Redshift 클러스터 또는 Redshift Serverless 작업 그룹당 최대 세션 수는 500개입니다.
+ 세션에서 한 번에 하나의 쿼리만 실행할 수 있습니다. 동일한 세션에서 다음 쿼리를 실행하려면 쿼리가 완료될 때까지 기다려야 합니다. 즉, 제공된 세션에서는 쿼리를 병렬로 실행할 수 없습니다.
+ Data API는 지정된 세션에 대해 쿼리를 대기열에 넣을 수 없습니다.
`ExecuteStatement` 및 `BatchExecuteStatement` 작업에 대한 직접 호출에서 사용되는 `SessionId`를 검색하려면 `DescribeStatement` 및 `ListStatements` 작업을 직접 호출합니다.
다음 예제는 세션을 활성화하고 재사용하기 위해 `SessionKeepAliveSeconds` 및 `SessionId` 파라미터를 사용하는 방법을 보여줍니다. 먼저 옵션인 `session-keep-alive-seconds` 파라미터를 `2`로 설정한 상태에서 `execute-statement` AWS CLI 명령을 직접 호출합니다.
```
aws redshift-data execute-statement
--session-keep-alive-seconds 2
--sql "select 1"
--database dev
--workgroup-name mywg
```
응답에는 세션 식별자가 포함됩니다.
```
{
"WorkgroupName": "mywg",
"CreatedAt": 1703022996.436,
"Database": "dev",
"DbUser": "awsuser",
"Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
"SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}
```
그런 다음 첫 번째 직접 호출에서 반환된 `SessionId`를 사용하여 `execute-statement` AWS CLI 명령을 직접 호출합니다. 또한, 팔요에 따라 `session-keep-alive-seconds` 파라미터를 `10`으로 설정하여 유휴 제한 시간 값을 변경합니다.
```
aws redshift-data execute-statement
--sql "select 1"
--session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
--session-keep-alive-seconds 10
```
## SQL 문의 결과 가져오기
결과 형식에 따라 다른 데이터 API 작업을 사용하여 SQL 결과를 가져옵니다. `ExecuteStatement` 및 `BatchExecuteStatement` 작업을 직접 호출할 때 결과를 JSON 또는 CSV 형식으로 지정할 수 있습니다. 지정하지 않으면 기본값은 JSON입니다. JSON 결과를 검색하려면 `GetStatementResult` 작업을 사용합니다. CSV 결과를 검색하려면 `GetStatementResultV2` 작업을 사용합니다.
JSON 형식으로 반환된 결과는 각 열에 대한 메타데이터를 포함하는 레코드입니다. 각 레코드는 JSON 형식입니다. 예를 들어, `GetStatementResult`의 응답은 다음과 유사합니다.
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"longValue": 1
}
]
],
"TotalNumRows":
}
```
CSV 형식으로 반환된 결과는 각 열에 대한 메타데이터를 포함하는 레코드입니다. 결과는 1MB의 청크로 반환되며, 각 청크는 CSV 형식으로 행 수를 제한 없이 저장할 수 있습니다. 각 요청은 최대 15MB의 결과를 반환합니다. 결과가 15MB보다 크면 결과를 계속 검색하기 위해 다음 페이지 토큰이 반환됩니다. 예를 들어, `GetStatementResultV2`의 응답은 다음과 유사합니다.
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk
},
{
"CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk
}
...
]
],
"ResultFormat" : "CSV",
"TotalNumRows":
}
```
# Amazon Redshift Data API에 대한 액세스 권한 부여
Data API에 액세스하려면 사용자에게 권한이 부여되어야 합니다. 해당 사용자에게 미리 정의된 AWS Identity and Access Management(IAM) 정책인 관리형 정책을 추가하여 Data API에 액세스할 수 있는 권한을 부여할 수 있습니다. 가장 좋은 방법은 권한 정책을 IAM 역할에 연결한 다음 필요에 따라 사용자 및 그룹에 할당하는 것입니다. 자세한 내용은 [Amazon Redshift의 Identity and Access Management](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)를 참조하세요. 관리형 정책에서 허용 및 거부하는 권한을 보려면 IAM 콘솔([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/))을 봅니다.
# IAM 권한 구성
Amazon Redshift는 `AmazonRedshiftDataFullAccess` 관리형 정책을 제공합니다. 이 정책은 Amazon Redshift Data API 작업에 대한 전체 액세스 권한을 제공합니다. 이 정책은 또한 Amazon Redshift 클러스터 또는 Redshift Serverless 작업 그룹을 인증하고 이에 액세스하는 데 필요한 특정 Amazon Redshift, AWS Secrets Manager 및 IAM API 작업에 대한 범위 액세스를 허용합니다.
특정 리소스에 대한 액세스를 허용하는 자체 IAM 정책을 생성할 수도 있습니다. 정책을 생성하려면 `AmazonRedshiftDataFullAccess` 정책을 시작 템플릿으로 사용합니다. 정책을 생성한 후에는 해당 정책을 Data API에 액세스해야 하는 각 사용자에게 추가합니다.
사용자와 연결된 IAM 정책의 다음과 같은 요구 사항을 고려합니다.
+ AWS Secrets Manager를 사용하여 인증하는 경우 정책이 `secretsmanager:GetSecretValue` 작업을 사용하여 `RedshiftDataFullAccess` 키로 태그가 지정된 비밀을 검색하도록 허용하는지 확인합니다.
+ 임시 보안 인증 정보를 사용하여 클러스터에 인증하는 경우 정책이 클러스터의 모든 데이터베이스에 대해 데이터베이스 사용자 이름 `redshift_data_api_user`에 `redshift:GetClusterCredentials` 작업을 사용하도록 허용하는지 확인합니다. 이 사용자 이름은 데이터베이스에 이미 생성되어 있어야 합니다.
+ 임시 보안 인증 정보를 사용하여 서버리스 작업 그룹에 인증하는 경우 정책이 `RedshiftDataFullAccess` 키로 태깅된 작업 그룹을 가져오는 `redshift-serverless:GetCredentials` 작업의 사용을 허용하는지 확인합니다. 데이터베이스 사용자는 소스 AWS Identity and Access Management(IAM) 아이덴티티에 일대일로 매핑됩니다. 예를 들어 사용자 sample\$1user는 데이터베이스 사용자 `IAM:sample_user`로 매핑되고 IAM 역할 sample\$1role은 `IAMR:sample_role`로 매핑됩니다. 다양한 IAM 아이덴티티에 대한 자세한 내용은 IAM 사용 설명서에서 [IAM 자격 증명(사용자, 그룹 및 역할)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html)을 참조하세요.
+ IAM 작업 `redshift-data:GetStatementResult`는 `GetStatementResult` 및 `GetStatementResultV2` API 작업 모두에 대한 액세스를 허용합니다.
다음 링크는 *IAM User Guide*에서 AWS Identity and Access Management에 대한 자세한 정보를 제공합니다.
+ IAM 역할 생성에 대한 자세한 내용은 [IAM 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)을 참조하세요.
+ IAM 정책 생성에 대한 자세한 내용은 [IAM 정책 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)을 참조하세요.
+ 사용자에게 IAM 정책 추가에 대한 자세한 내용은 [IAM 자격 증명 권한 추가 및 제거](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)를 참조하세요.
## 다른 계정에서 소유하고 있는 클러스터에서 쿼리 실행
다른 계정이 소유한 클러스터에서 쿼리를 실행하려면 소유 계정이 호출 계정에서 Data API가 수임할 수 있는 IAM 역할을 제공해야 합니다. 예를 들어 계정 B가 계정 A가 액세스해야 하는 클러스터를 소유하고 있다고 가정합니다. 계정 B는 AWS 관리형 정책 `AmazonRedshiftDataFullAccess`를 계정 B의 IAM 역할에 연결할 수 있습니다. 그런 다음 계정 B는 다음과 같은 신뢰 정책을 사용하여 계정 A를 신뢰합니다.``
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/someRoleA"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
마지막으로 계정 A IAM 역할은 계정 B IAM 역할을 수임할 수 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/someRoleB"
}
}
```
------
## AWS 계정의 Redshift Serverless 작업 그룹 및 Amazon Redshift 클러스터로 리소스를 제한하는 IAM 역할 지정
ID 기반 정책에서 리소스 ARN을 지정하여 AWS 계정의 Redshift Serverless 작업 그룹 및 Amazon Redshift 클러스터에 대한 액세스 권한을 제어할 수 있습니다. 이 예제는 지정된 AWS 계정의 작업 그룹 및 클러스터에만 Data API에 액세스할 수 있는 정책을 만드는 방법을 보여줍니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "redshift-data:*",
"Resource": [
"arn:aws:redshift:us-east-1:111122223333:workgroup/*",
"arn:aws:redshift:us-east-1:111122223333:cluster:*"
]
}
]
}
```
------
## SQL 문 정보에 대한 액세스 권한을 문 소유자로만 제한하는 IAM 정책 구성
기본적으로 Amazon Redshift Data API는 `ExecuteStatement` 및 `BatchExecuteStatement` 직접 호출 시 사용되는 IAM 역할을 SQL 문의 소유자로 취급합니다. 역할을 맡을 수 있는 사람은 누구나 결과를 포함하여 SQL 문에 대한 정보에 액세스할 수 있습니다. IAM 역할 세션에 대한 SQL 문 정보 액세스 권한을 특정 소유자로 제한하려면 `redshift-data:statement-owner-iam-userid: "${aws:userid}"` 조건을 추가하세요. 다음 IAM 정책은 액세스를 제한합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:statement-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
`CancelStatement`, `DescribeStatement`, `GetStatementResult`, `ListStatements`와 함께 `statement-owner-iam-userid` 조건을 사용할 수 있습니다. 자세한 내용은 [Amazon Redshift Data API에서 정의한 작업](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)을 참조하세요.
## SQL 결과에 대한 액세스 권한을 세션 소유자로만 제한하는 IAM 정책 구성
기본적으로 Amazon Redshift Data API는 `ExecuteStatement` 및 `BatchExecuteStatement` 직접 호출 시 사용되는 IAM 역할을 SQL 문을 실행하는 데이터베이스 세션의 소유자로 취급합니다. 역할을 맡을 수 있는 사람은 누구나 데이터베이스 세션에 쿼리를 제출할 수 있습니다. 특정 소유자와의 IAM 역할 세션에 대한 세션 액세스를 제한하려면 ` redshift-data:session-owner-iam-userid: "${aws:userid}"` 조건을 추가하세요. 다음 IAM 정책은 액세스를 제한합니다.
다음 IAM 정책은 세션 소유자만 문 결과를 얻을 수 있도록 허용합니다. `session-owner-iam-userid` 조건은 리소스 액세스 권한을 지정된 `userid`로 제한하는 데 사용됩니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:ExecuteStatement",
"redshift-data:BatchExecuteStatement"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:session-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
`ExecuteStatement`, `BatchExecuteStatement`와 함께 `session-owner-iam-userid` 조건을 사용할 수 있습니다. 자세한 내용은 [Amazon Redshift Data API에서 정의한 작업](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)을 참조하세요.
# AWS Secrets Manager에 데이터베이스 자격 증명 저장
Data API를 호출할 때 AWS Secrets Manager의 비밀을 사용하여 클러스터 또는 서버리스 작업 그룹에 대한 보안 인증 정보를 전달할 수 있습니다. 이 방식으로 자격 증명을 전달하려면 보안 암호의 이름 또는 보안 암호의 Amazon 리소스 이름(ARN)을 지정합니다.
Secrets Manager로 자격 증명을 저장하려면 `SecretManagerReadWrite` 관리형 정책 권한이 필요합니다. 최소 권한에 대한 자세한 내용은 *AWS Secrets Manager User Guide*의 [Creating and Managing Secrets with AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)를 참조하세요.
**Amazon Redshift 클러스터의 보안 암호에 자격 증명을 저장하려면**
1. AWS Secrets Manager 콘솔을 사용하여 클러스터의 보안 인증 정보를 포함하는 비밀을 생성합니다.
+ [**새 보안 암호 저장(Store a new secret)**]을 선택할 때 [**Redshift 클러스터용 자격 증명(Credentials for Redshift cluster)**]을 선택합니다.
+ 보안 암호에 [**사용자 이름(User name)**](데이터베이스 사용자), [**암호(Password)**] 및 [**DB 클러스터(DB cluster)**](클러스터 식별자) 값을 저장합니다.
+ 키 `RedshiftDataFullAccess`로 보안 암호에 태그를 지정합니다. AWS 관리형 정책 `AmazonRedshiftDataFullAccess`는 키 `RedshiftDataFullAccess`로 태그가 지정된 보안 암호에 대해서만 작업 `secretsmanager:GetSecretValue`를 허용합니다.
이에 관한 지침은 *AWS Secrets Manager User Guide*의 [Creating a Basic Secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)을 참조하세요.
1. AWS Secrets Manager 콘솔을 사용하여 생성한 보안 암호에 대한 세부 정보를 보거나 `aws secretsmanager describe-secret` AWS CLI 명령을 실행합니다.
보안 암호의 이름 및 ARN을 적어둡니다. 이러한 이름이나 ARN은 Data API 호출에서 사용할 수 있습니다.
**서버리스 작업 그룹의 비밀에 보안 인증 정보를 저장하려면**
1. 서버리스 작업 그룹에 대한 보안 인증 정보를 포함하는 비밀을 저장하려면 AWS Secrets Manager AWS CLI 명령을 사용합니다.
+ 파일에 보안 암호를 생성합니다(예: `mycreds.json` 이름의 JSON 파일) 파일에 **사용자 이름**(데이터베이스 사용자) 및 **암호** 값을 제공합니다.
```
{
"username": "myusername",
"password": "mypassword"
}
```
+ 비밀에 값을 저장하고 `RedshiftDataFullAccess` 키를 사용하여 비밀에 태그를 지정합니다.
```
aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json
```
다음은 출력값을 보여줍니다.
```
{
"ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf",
"Name": "MyRedshiftSecret",
"VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE"
}
```
자세한 내용은 [AWS CLI 사용 설명서](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api)에서 *AWS Secrets Manager로 기본 보안 암호 생성*을 참조하세요.
1. AWS Secrets Manager 콘솔을 사용하여 생성한 보안 암호에 대한 세부 정보를 보거나 `aws secretsmanager describe-secret` AWS CLI 명령을 실행합니다.
보안 암호의 이름 및 ARN을 적어둡니다. 이러한 이름이나 ARN은 Data API 호출에서 사용할 수 있습니다.
# Data API에 대한 Amazon VPC 엔드포인트(AWS PrivateLink) 생성
Amazon Virtual Private Cloud(Amazon VPC)를 사용하면 Amazon Redshift 클러스터 및 애플리케이션과 같은 AWS 리소스를 Virtual Private Cloud(VPC)에서 시작할 수 있습니다. AWS PrivateLink는 Amazon 네트워크에서 Virtual Private Cloud(VPC)와 AWS 서비스 간의 프라이빗 연결을 안전하게 제공합니다. AWS PrivateLink를 사용하면 VPC 엔드포인트를 생성하여 Amazon VPC 기반의 다른 계정 및 VPC에서 서비스에 연결할 수 있습니다. AWS PrivateLink에 대한 자세한 내용은 *Amazon Virtual Private Cloud 사용 설명서*의 [VPC 엔드포인트 서비스(AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html)를 참조하세요.
Amazon VPC 엔드포인트를 사용하여 데이터 API를 호출할 수 있습니다. Amazon VPC 엔드포인트를 사용하면 퍼블릭 IP 주소를 사용하지 않고 Amazon VPC의 애플리케이션과 AWS 네트워크에서 데이터 API 간에 트래픽을 유지합니다. Amazon VPC 엔드포인트를 사용하면 퍼블릭 인터넷 연결 제한과 관련된 규정 준수 및 규정 요구 사항을 충족할 수 있습니다. 예를 들어 Amazon VPC 엔드포인트를 사용하는 경우 Amazon EC2 인스턴스에서 실행되는 애플리케이션과 해당 애플리케이션이 포함된 VPC의 데이터 API 간 트래픽을 유지할 수 있습니다.
Amazon VPC 엔드포인트를 생성한 후에는 애플리케이션에서 코드나 구성을 변경하지 않고 엔드포인트를 사용할 수 있습니다.
**데이터 API에 대한 Amazon VPC 엔드포인트를 생성하려면**
1. AWS Management Console에 로그인하고 [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)에서 Amazon VPC 콘솔을 엽니다.
1. **엔드포인트**를 선택한 다음 **엔드포인트 생성**을 선택합니다.
1. **엔드포인트 생성** 페이지에서 **서비스 범주**에 대해 **AWS 서비스**를 선택합니다. [**서비스 이름(Service Name)**]에서 [**redshift-data**](`com.amazonaws.region.redshift-data`)를 선택합니다.
1. **VPC**의 경우 엔드포인트를 생성할 VPC를 선택합니다.
데이터 API를 호출하는 애플리케이션이 포함된 VPC를 선택합니다.
1. **서브넷**의 경우 애플리케이션을 실행 중인 AWS 서비스에서 사용하는 각 가용 영역(AZ)의 서브넷을 선택합니다.
Amazon VPC 엔드포인트를 생성하려면 엔드포인트에 액세스할 수 있는 프라이빗 IP 주소 범위를 지정합니다. 이렇게 하려면 각 가용 영역에 대한 서브넷을 선택합니다. 이렇게 하면 VPC 엔드포인트가 각 가용 영역별 프라이빗 IP 주소 범위로 제한되고 각 가용 영역에 Amazon VPC 엔드포인트가 생성됩니다.
1. **Enable DNS name(DNS 이름 활성화)**에서 **이 엔드포인트에 대해 활성화**를 선택합니다.
프라이빗 DNS는 표준 데이터 API DNS 호스트 이름(`https://redshift-data.region.amazonaws.com`)을 Amazon VPC 엔드포인트에 특정한 DNS 호스트 이름과 연결된 프라이빗 IP 주소로 확인합니다. 따라서 데이터 API 엔드포인트 URL을 업데이트하기 위해 코드나 구성을 변경하지 않고도 AWS CLI 또는 AWS SDK를 사용하여 데이터 API VPC 엔드포인트에 액세스할 수 있습니다.
1. **보안 그룹**의 경우 Amazon VPC 엔드포인트와 연결할 보안 그룹을 선택합니다.
애플리케이션을 실행 중인 AWS 서비스에 대한 액세스를 허용하는 보안 그룹을 선택합니다. 예를 들어 Amazon EC2 인스턴스가 애플리케이션을 실행 중인 경우 Amazon EC2 인스턴스에 대한 액세스를 허용하는 보안 그룹을 선택합니다. 보안 그룹을 사용하면 VPC의 리소스에서 Amazon VPC 엔드포인트로 가는 트래픽을 제어할 수 있습니다.
1. [**Create endpoint**]를 선택합니다.
엔드포인트를 생성한 후 AWS Management Console에서 링크를 선택하여 엔드포인트 세부 정보를 봅니다.
엔드포인트 **세부 정보** 탭에는 Amazon VPC 엔드포인트를 만드는 동안 생성된 DNS 호스트 이름이 표시됩니다.
표준 엔드포인트(`redshift-data.region.amazonaws.com`) 또는 VPC 관련 엔드포인트 중 하나를 사용하여 Amazon VPC에서 데이터 API를 호출할 수 있습니다. 표준 데이터 API 엔드포인트는 자동으로 Amazon VPC 엔드포인트로 라우팅됩니다. 이 라우팅은 Amazon VPC 엔드포인트를 생성할 때 프라이빗 DNS 호스트 이름을 활성화했기 때문에 발생합니다.
데이터 API 호출에서 Amazon VPC 엔드포인트를 사용하는 경우 애플리케이션과 데이터 API 간의 모든 트래픽은 해당 트래픽이 포함된 Amazon VPC에 남아 있습니다. 모든 유형의 데이터 API 호출에 Amazon VPC 엔드포인트를 사용할 수 있습니다. 데이터 API 호출에 대한 자세한 내용은 [Amazon Redshift Data API 호출 시 고려 사항](data-api.md#data-api-calling-considerations) 섹션을 참조하세요.
# 클러스터에 연결할 때 데이터베이스 그룹에 조인
데이터베이스 그룹은 데이터베이스 사용자의 모음입니다. 그룹에 데이터베이스 권한을 부여할 수 있습니다. 관리자는 데이터 API로 SQL을 실행할 때 이러한 데이터베이스 그룹이 고려되도록 IAM 역할을 구성할 수 있습니다. 자세한 내용은 **Amazon Redshift 데이터베이스 개발자 안내서의 [그룹](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html)을 참조하세요.
데이터 API가 클러스터에 연결할 때 호출에 지정된 데이터베이스 사용자가 데이터베이스 그룹에 조인하도록 데이터 API 호출자의 IAM 역할을 구성할 수 있습니다. 이 기능은 프로비저닝된 클러스터에 연결할 때만 지원됩니다. Redshift Serverless 작업 그룹에 연결할 때는 지원되지 않습니다. 데이터 API 호출자의 IAM 역할도 `redshift:JoinGroup` 작업을 허용해야 합니다.
IAM 역할에 태그를 추가하여 이를 구성합니다. 호출자의 IAM 역할의 관리자는 `RedshiftDbGroups` 키와 데이터베이스 그룹 목록의 키 값을 사용하여 태그를 추가합니다. 값은 콜론(:)으로 구분된 데이터베이스 그룹의 이름을 총 256자까지 나열한 목록입니다. 데이터베이스 그룹은 연결된 데이터베이스에 이전에 정의되어 있어야 합니다. 지정된 그룹이 데이터베이스에서 발견되지 않으면 무시됩니다. 예를 들어 `accounting` 및 `retail` 데이터베이스 그룹의 경우 키-값은 `accounting:retail`입니다. 태그 키-값 쌍 `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}`은 데이터 API에서 데이터 API 호출에서 제공된 데이터베이스 사용자와 연관된 데이터베이스 그룹을 결정하는 데 사용됩니다.
**데이터베이스 그룹에 조인하려면**
1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)에서 IAM 콘솔을 엽니다.
1. 콘솔의 탐색 창에서 [**역할(Roles)**]을 선택한 다음 편집할 역할의 이름을 선택합니다.
1. **태그** 탭을 선택한 후 **태그 관리**를 선택합니다.
1. **태그 추가**를 선택한 다음 **RedshiftDbGroups** 키와 *database-groups-colon-separated* 목록인 값을 추가합니다.
1. **변경 사항 저장**을 선택합니다.
이제 이 IAM 역할이 첨부된 IAM 주체가 Data API를 호출하면 지정된 데이터베이스 사용자가 IAM 역할에 지정된 데이터베이스 그룹에 조인합니다.
IAM 역할 및 IAM 사용자를 포함하여 보안 주체에 태그를 연결하는 방법에 대한 자세한 내용은 *IAM 사용 설명서*의 [IAM 리소스에 태깅](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)을 참조하세요.
# 신뢰할 수 있는 자격 증명 전파와 함께 데이터 API 사용
Amazon Redshift 계정 관리자는 Amazon Redshift 클러스터 또는 작업 그룹을 AWS IAM Identity Center와 통합할 수 있으므로 Single Sign-On으로 Amazon Redshift에 대한 인력 액세스를 관리하는 데 도움이 됩니다. 자세한 내용은 [Amazon Redshift와 AWS IAM Identity Center 통합 설정](redshift-iam-access-control-idp-connect-console.md) 섹션을 참조하세요. Amazon Redshift 데이터 API는 IAM Identity Center 사용자 ID를 Amazon Redshift 클러스터 또는 작업 그룹 및 AWS Lake Formation과 같은 체인 아래 단계의 다른 서비스에 전파하는 것을 지원합니다. [신뢰할 수 있는 ID 전파를 사용하여 프로그래밍 방식으로 AWS 서비스 액세스](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/)의 단계에 따라 데이터 API를 사용하여 설정하고 쿼리할 수 있습니다.
ID 강화 IAM 역할 세션에서 IAM Identity Center 사용자 ID를 사용하여 데이터 API를 직접적으로 호출하는 경우, 동일한 IAM Identity Center 사용자를 사용하여 결과 문 및 문 결과에만 액세스할 수 있습니다. 예를 들어 다음 AWS CLI 명령은 `execute-statement` 작업을 직접적으로 호출함으로써 신뢰할 수 있는 ID 전파를 사용하여 SQL 명령을 실행합니다.
```
aws redshift-data execute-statement
--sql "select current_user;"
--cluster-id mycluster
--database dev
```
다음 AWS CLI 명령은 `batch-execute-statement` 작업을 직접적으로 호출하여 두 개의 SQL 명령을 실행합니다.
```
aws redshift-data batch-execute-statement
--sqls "select current_user;" "select current_date;"
--cluster-id mycluster
--database dev
```
자격 증명 강화 IAM 역할 세션에서 제출한 `cancel-statement`, `describe-statement`, `get-statement-result` 및 `get-statement-result-v2`를 사용하여 문에 액세스하려면 IAM Identity Center 사용자 및 IAM 역할이 `execute-statment` 또는 `batch-execute-statement`를 실행하는 데 사용된 자격 증명과 일치해야 합니다. 예를 들어 다음 AWS CLI 명령은 SQL 문의 결과를 가져옵니다.
```
aws redshift-data get-statement-result
--id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
문을 나열하려면 IAM Identity Center 사용자가 할당된 Amazon Redshift IAM Identity Center 애플리케이션에만 액세스할 수 있도록 `cluster-identifier` 또는 `workgroup-name` 파라미터를 제공해야 합니다. 예를 들어 다음 AWS CLI 명령은 특정 클러스터에 대한 문을 나열합니다.
```
aws redshift-data list-statements
--cluster-identifier mycluster
```
또한 신뢰할 수 있는 자격 증명 전파를 사용하여 클러스터 또는 작업 그룹의 데이터베이스 객체에 액세스하는 데이터 API 작업을 간접적으로 호출할 수 있습니다. 여기에는 `list-databases`, `list-schemas`, `list-tables` 및 `describe-table` 작업이 포함됩니다.
IAM Identity Center 사용자가 수행한 API 직접 호출은 AWS CloudTrail에서 추적할 수 있습니다. CloudTrail 이벤트의 `onBehalfOf` 섹션에는 IAM Identity Center 사용자 ID와 ID 스토어 ARN이 표시됩니다. 다음 예제는 IAM Identity Center 사용자 ID가 `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111`이고 Identity 스토어 ARN이 `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2`인 `onBehalfOf` 섹션이 표시된 CloudTrail 이벤트의 스니펫을 보여줍니다.
```
{
"eventVersion":"1.10",
"userIdentity":{
"type":"AssumedRole",
...
},
"onBehalfOf":{
"userId":"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"identityStoreArn":"arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2"
}
},
"eventTime":"2025-01-13T04:46:27Z",
"eventSource":"redshift-data.amazonaws.com",
"eventName":"ExecuteStatement",
"awsRegion":"us-east-1"
}
```
다음 SQL 명령을 실행하여 IAM Identity Center 사용자가 제출한 쿼리를 확인할 수 있습니다. 이 예제에서 Identity Center에 등록된 이메일은 `username@example.com`입니다.
```
SELECT
h.query_id,
h.database_name,
h.status,
h.query_text,
u.usename,
h.start_time,
h.end_time
FROM
sys_query_history h
LEFT JOIN
pg_user u
ON
h.user_id = u.usesysid
where u.usename='awsidc:username@example.com'
ORDER BY
h.start_time DESC;
```
# 데이터 API 호출
Data API 또는 AWS CLI를 호출하여 클러스터 또는 서버리스 작업 그룹에서 SQL 문을 실행할 수 있습니다. SQL 문을 실행하는 프라이머리 작업은 *Amazon Redshift Data API 참조* 내 [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) 및 [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html)입니다. Data API는 AWS SDK에서 지원되는 프로그래밍 언어를 지원합니다. 이에 대한 자세한 내용은 [AWS 기반의 도구](https://aws.amazon.com/tools/)를 참조하세요.
Data API 호출의 코드 예제를 보려면 *GitHub*에서 [Getting Started with Redshift Data API](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api)를 참조하세요. 이 리포지토리에는 AWS Lambda를 사용하여 Amazon EC2, AWS Glue Data Catalog 및 Amazon SageMaker Runtime에서 Amazon Redshift 데이터에 액세스하는 예가 있습니다. 프로그래밍 언어의 예로는 Python, Go, Java 및 Javascript가 있습니다.
AWS CLI를 사용하여 Data API를 호출할 수 있습니다.
다음 예에서는 AWS CLI를 사용하여 Data API를 호출합니다. 예제를 실행하려면 환경에 맞게 파라미터 값을 편집합니다. 많은 예제에서 `cluster-identifier`가 클러스터에 대해 실행되도록 제공됩니다. 서버리스 작업 그룹에 대해 실행할 때는 `workgroup-name`을 대신 제공해야 합니다. 이 예에서는 몇 가지 Data API 작업을 보여줍니다. 자세한 내용은 *AWS CLI 명령 참조*를 참조하세요.
다음 예의 명령은 가독성을 위해 분할되고 형식이 지정되었습니다. 모든 파라미터와 응답이 모든 예시에 표시되는 것은 아닙니다. 전체 요청 구문, 요청 파라미터, 응답 구문 및 응답 요소의 API 정의는 [Amazon Redshift Data API Reference](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)를 참조하세요.
# Amazon Redshift 데이터 웨어하우스에 SQL 스테이트먼트 전달
이 페이지의 예제에서는 데이터 웨어하우스에 SQL 스테이트먼트를 전달하는 다양한 방법을 다룹니다.
## SQL 스테이트먼트 실행
SQL 문을 실행하려면 `aws redshift-data execute-statement` AWS CLI 명령을 사용합니다.
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하고 결과를 가져올 식별자를 반환합니다. 이 예에서는 AWS Secrets Manager 인증 방법을 사용합니다.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
```
다음은 이 응답의 예입니다.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하고 결과를 가져올 식별자를 반환합니다. 이 예에서는 임시 자격 증명 인증 방법을 사용합니다.
```
aws redshift-data execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sql "select * from stl_query limit 1"
```
다음은 이 응답의 예입니다.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
다음 AWS CLI 명령은 서버리스 작업 그룹에 대해 SQL 문을 실행하고 결과를 가져올 식별자를 반환합니다. 이 예에서는 임시 자격 증명 인증 방법을 사용합니다.
```
aws redshift-data execute-statement
--database dev
--workgroup-name myworkgroup
--sql "select 1;"
```
다음은 이 응답의 예입니다.
```
{
"CreatedAt": "2022-02-11T06:25:28.748000+00:00",
"Database": "dev",
"DbUser": "IAMR:RoleName",
"Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e",
"WorkgroupName": "myworkgroup"
}
```
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하고 결과를 가져올 식별자를 반환합니다. 이 예에서는AWS Secrets Manager 인증 방법과 멱등성 토큰을 사용합니다.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
--client-token b855dced-259b-444c-bc7b-d3e8e33f94g1
```
다음은 이 응답의 예입니다.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
## 파라미터가 있는 SQL 스테이트먼트 실행
SQL 문을 실행하려면 `aws redshift-data execute-statement` AWS CLI 명령을 사용합니다.
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하고 결과를 가져올 식별자를 반환합니다. 이 예에서는 AWS Secrets Manager 인증 방법을 사용합니다. SQL 텍스트에는 명명된 파라미터 `distance`가 있습니다. 이 경우, 조건자에 사용되는 거리는 `5`입니다. SELECT 문에서는 열 이름에 대해 명명된 파라미터를 조건자에서만 사용할 수 있습니다. SQL 문의 명명된 파라미터 값은 `parameters` 옵션에 지정됩니다.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance"
--parameters "[{\"name\": \"distance\", \"value\": \"5\"}]"
--database dev
```
다음은 이 응답의 예입니다.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
다음 예에서는 샘플 데이터베이스의 `EVENT` 테이블을 사용합니다. 자세한 내용은 *Amazon Redshift 데이터베이스 개발자 안내서*의 [EVENT 테이블](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html)을 참조하세요.
데이터베이스에 `EVENT` 테이블이 없으면 다음과 같이 Data API를 사용하여 생성할 수 있습니다.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "create table event( eventid integer not null distkey,
venueid smallint not null,
catid smallint not null,
dateid smallint not null sortkey,
eventname varchar(200),
starttime timestamp)"
```
다음 명령은 `EVENT` 테이블에 한 행을 삽입합니다.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)"
--parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"},
{\"name\": \"catid\", \"value\": \"1\"},
{\"name\": \"dateid\", \"value\": \"1\"},
{\"name\": \"eventname\", \"value\": \"event 1\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"}]"
```
다음 명령은 `EVENT` 테이블에 두 번째 행을 삽입합니다. 이 예제에서는 다음 작업을 설명합니다.
+ `id`라는 파라미터가 SQL 텍스트에서 4번 사용됩니다.
+ 파라미터 `starttime`을 삽입할 때 암시적 형식 변환이 자동으로 적용됩니다.
+ `venueid` 열은 SMALLINT 데이터 형식으로 캐스팅됩니다.
+ DATE 데이터 형식을 나타내는 문자열은 암시적으로 TIMESTAMP 데이터 형식으로 변환됩니다.
+ 주석은 SQL 텍스트 내에서 사용할 수 있습니다.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/"
--parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"},
{\"name\": \"id\", \"value\": \"2\"}]"
```
다음은 삽입된 두 행을 보여줍니다.
```
eventid | venueid | catid | dateid | eventname | starttime
---------+---------+-------+--------+-----------+---------------------
1 | 1 | 1 | 1 | event 1 | 2022-02-22 00:00:00
2 | 2 | 2 | 2 | event 2 | 2022-02-22 00:00:00
```
다음 명령은 WHERE 절에서 명명된 파라미터를 사용하여 행을 검색합니다. 여기서 `eventid`는 `1`입니다.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "select * from event where eventid=:id"
--parameters "[{\"name\": \"id\", \"value\": \"1\"}]"
```
다음 명령을 실행하여 이전 SQL 문의 SQL 결과를 가져옵니다.
```
aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a
```
다음 결과를 제공합니다.
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"stringValue": "event 1"
},
{
"stringValue": "2022-02-22 00:00:00.0"
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "eventid",
"length": 0,
"name": "eventid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "venueid",
"length": 0,
"name": "venueid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "catid",
"length": 0,
"name": "catid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "dateid",
"length": 0,
"name": "dateid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "eventname",
"length": 0,
"name": "eventname",
"nullable": 1,
"precision": 200,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "varchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 1,
"precision": 29,
"scale": 6,
"schemaName": "public",
"tableName": "event",
"typeName": "timestamp"
}
],
"TotalNumRows": 1
}
```
## 여러 SQL 스테이트먼트 실행
하나의 명령으로 여러 SQL 문을 실행하려면 `aws redshift-data batch-execute-statement` AWS CLI 명령을 사용합니다.
다음 AWS CLI 명령은 클러스터에 대해 3개의 SQL 문을 실행하고 결과를 가져올 식별자를 반환합니다. 이 예에서는 임시 자격 증명 인증 방법을 사용합니다.
```
aws redshift-data batch-execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sqls "set timezone to BST" "select * from mytable" "select * from another_table"
```
다음은 이 응답의 예입니다.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
# SQL 스테이트먼트에 대한 메타데이터 나열
SQL 문에 대한 메타데이터를 나열하려면 `aws redshift-data list-statements` AWS CLI 명령을 사용합니다. 이 명령을 실행하기 위한 권한 부여는 호출자의 IAM 권한을 기반으로 합니다.
다음 AWS CLI 명령은 실행된 SQL 문을 나열합니다.
```
aws redshift-data list-statements
--status ALL
```
다음은 이 응답의 예입니다.
```
{
"Statements": [
{
"CreatedAt": 1598306924.632,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
},
{
"CreatedAt": 1598311717.437,
"Id": "e0ebd578-58b3-46cc-8e52-8163fd7e01aa",
"QueryString": "select * from stl_query limit 1",
"Status": "FAILED",
"UpdatedAt": 1598311719.008
},
{
"CreatedAt": 1598313683.65,
"Id": "c361d4f7-8c53-4343-8c45-6b2b1166330c",
"QueryString": "select * from stl_query limit 1",
"Status": "ABORTED",
"UpdatedAt": 1598313685.495
},
{
"CreatedAt": 1598306653.333,
"Id": "a512b7bd-98c7-45d5-985b-a715f3cfde7f",
"QueryString": "select 1",
"Status": "FINISHED",
"UpdatedAt": 1598306653.992
}
]
}
```
# SQL 스테이트먼트에 대한 메타데이터 설명
SQL 문에 대한 메타데이터에 대한 설명을 가져오려면 `aws redshift-data describe-statement` AWS CLI 명령을 사용합니다. 이 명령을 실행하기 위한 권한 부여는 호출자의 IAM 권한을 기반으로 합니다.
다음 AWS CLI 명령은 SQL 문을 설명합니다.
```
aws redshift-data describe-statement
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
다음은 이 응답의 예입니다.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Duration": 1095981511,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"RedshiftPid": 20859,
"RedshiftQueryId": 48879,
"ResultRows": 1,
"ResultSize": 4489,
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
}
```
다음은 여러 SQL 문으로 `batch-execute-statement` 명령을 실행한 후 `describe-statement` 응답의 예입니다.
```
{
"ClusterIdentifier": "mayo",
"CreatedAt": 1623979777.126,
"Duration": 6591877,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652",
"RedshiftPid": 31459,
"RedshiftQueryId": 0,
"ResultRows": 2,
"ResultSize": 22,
"Status": "FINISHED",
"SubStatements": [
{
"CreatedAt": 1623979777.274,
"Duration": 3396637,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:1",
"QueryString": "select 1;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979777.903
},
{
"CreatedAt": 1623979777.274,
"Duration": 3195240,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2",
"QueryString": "select 2;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979778.076
}
],
"UpdatedAt": 1623979778.183
}
```
# SQL 스테이트먼트 결과 가져오기
실행된 SQL 문에서 결과를 가져오려면 `redshift-data get-statement-result` 또는 `redshift-data get-statement-result-v2` AWS CLI 명령을 사용합니다. `get-statement-result`의 결과는 JSON 형식입니다. `get-statement-result-v2`의 결과는 CSV 형식입니다. `execute-statement` 또는 `batch-execute-statement`에 대한 응답으로 수신하는 `Id`를 제공할 수 있습니다. `batch-execute-statement`에 의해 실행된 SQL 문의 `Id` 값은 `describe-statement`의 결과에서 검색할 수 있으며 `b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2`와 같이 콜론과 시퀀스 번호가 접미사로 붙습니다. `batch-execute-statement`가 있는 여러 SQL 문을 실행하면 `describe-statement`와 같이 각 SQL 문에 `Id` 값이 있습니다. 이 명령을 실행하기 위한 권한 부여는 호출자의 IAM 권한을 기반으로 합니다.
다음 문은 `ResultFormat`이 `JSON`의 기본값을 갖게 하는 `execute-statement`에 의해 실행되는 SQL 문의 결과를 반환합니다. 결과를 검색하려면 `get-statement-result` 작업을 직접 호출합니다.
```
aws redshift-data get-statement-result
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
다음 문은 `batch-execute-statement`에 의해 실행되는 두 번째 SQL 문의 결과를 반환합니다.
```
aws redshift-data get-statement-result
--id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2
```
다음은 SQL 결과가 응답 키 `Records`의 JSON 형식으로 반환되는 `get-statement-result` 직접 호출에 대한 응답의 예입니다.
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "userid",
"length": 0,
"name": "userid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "query",
"length": 0,
"name": "query",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "label",
"length": 0,
"name": "label",
"nullable": 0,
"precision": 320,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "xid",
"length": 0,
"name": "xid",
"nullable": 0,
"precision": 19,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int8"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "pid",
"length": 0,
"name": "pid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "database",
"length": 0,
"name": "database",
"nullable": 0,
"precision": 32,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "querytxt",
"length": 0,
"name": "querytxt",
"nullable": 0,
"precision": 4000,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "endtime",
"length": 0,
"name": "endtime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"type": 93,
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "aborted",
"length": 0,
"name": "aborted",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "insert_pristine",
"length": 0,
"name": "insert_pristine",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "concurrency_scaling_status",
"length": 0,
"name": "concurrency_scaling_status",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
}
],
"Records": [
[
{
"longValue": 1
},
{
"longValue": 3
},
{
"stringValue": "health"
},
{
"longValue": 1023
},
{
"longValue": 15279
},
{
"stringValue": "dev"
},
{
"stringValue": "select system_status from stv_gui_status;"
},
{
"stringValue": "2020-08-21 17:33:51.88712"
},
{
"stringValue": "2020-08-21 17:33:52.974306"
},
{
"longValue": 0
},
{
"longValue": 0
},
{
"longValue": 6
}
]
],
"TotalNumRows": 1
}
```
다음 예시에서는 결과를 JSON으로 반환하기 위해 `execute-statement`로 실행되는 SQL 문을 보여줍니다. 테이블 `testingtable`에는 3개의 정수 열(col1, col2, col3)이 있고, 값(1, 2, 3), (4, 5, 6), (7, 8, 9)이 있는 3개의 행이 있습니다.
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format JSON
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
다음은 SQL 결과가 응답 키 `Records`의 JSON 형식으로 반환되는 `get-statement-result` 직접 호출에 대한 응답의 예입니다.
```
aws redshift-data get-statement-result
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 2
},
{
"longValue": 3
}
],
[
{
"longValue": 4
},
{
"longValue": 5
},
{
"longValue": 6
}
],
[
{
"longValue": 7
},
{
"longValue": 8
},
{
"longValue": 9
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3
}
```
다음 예시에서는 결과를 CSV로 반환하기 위해 `execute-statement`로 실행되는 SQL 문을 보여줍니다. 테이블 `testingtable`에는 3개의 정수 열(col1, col2, col3)이 있고, 값(1, 2, 3), (4, 5, 6), (7, 8, 9)이 있는 3개의 행이 있습니다.
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format CSV
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
다음은 SQL 결과가 응답 키 `Records`의 CSV 형식으로 반환되는 `get-statement-result-v2` 직접 호출에 대한 응답의 예입니다. 행은 캐리지 리턴과 줄 바꿈(\$1r\$1n)으로 구분됩니다. `Records`에서 반환되는 첫 번째 행은 열 헤더입니다. CSV 형식으로 반환된 결과는 1MB로 반환되며, 각 청크는 최대 1MB까지 행 수를 저장할 수 있습니다.
```
aws redshift-data get-statement-result-v2
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
{
"CSVRecords": "col1,col2,col3\r\n1,2,3\r\n4,5,6\r\n7,8,9\r\n"
}
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3,
"ResultFormat": "csv"
}
```
# 테이블 설명
테이블을 설명하는 메타데이터를 가져오려면 `aws redshift-data describe-table` AWS CLI 명령을 사용합니다.
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하고 테이블을 설명하는 메타데이터를 반환합니다. 이 예에서는 AWS Secrets Manager 인증 방법을 사용합니다.
```
aws redshift-data describe-table
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
```
다음은 이 응답의 예입니다.
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
다음 AWS CLI 명령은 클러스터에 대해 테이블을 설명하는 SQL 문을 실행합니다. 이 예에서는 임시 자격 증명 인증 방법을 사용합니다.
```
aws redshift-data describe-table
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
```
다음은 이 응답의 예입니다.
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_supported",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_verified_by",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "comments",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
# 클러스터의 데이터베이스 나열
클러스터의 데이터베이스를 나열하려면 `aws redshift-data list-databases` AWS CLI 명령을 사용합니다.
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하여 데이터베이스를 나열합니다. 이 예에서는 AWS Secrets Manager 인증 방법을 사용합니다.
```
aws redshift-data list-databases
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
다음은 이 응답의 예입니다.
```
{
"Databases": [
"dev"
]
}
```
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하여 데이터베이스를 나열합니다. 이 예에서는 임시 자격 증명 인증 방법을 사용합니다.
```
aws redshift-data list-databases
--db-user myuser
--cluster-identifier mycluster-test
--database dev
```
다음은 이 응답의 예입니다.
```
{
"Databases": [
"dev"
]
}
```
# 데이터베이스의 스키마 나열
데이터베이스의 스키마를 나열하려면 `aws redshift-data list-schemas` AWS CLI 명령을 사용합니다.
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하여 데이터베이스의 스키마를 나열합니다. 이 예에서는 AWS Secrets Manager 인증 방법을 사용합니다.
```
aws redshift-data list-schemas
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
다음은 이 응답의 예입니다.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하여 데이터베이스의 스키마를 나열합니다. 이 예에서는 임시 자격 증명 인증 방법을 사용합니다.
```
aws redshift-data list-schemas
--db-user mysuser
--cluster-identifier mycluster-test
--database dev
```
다음은 이 응답의 예입니다.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
# 데이터베이스의 테이블 나열
데이터베이스의 테이블을 나열하려면 `aws redshift-data list-tables` AWS CLI 명령을 사용합니다.
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하여 데이터베이스의 테이블을 나열합니다. 이 예에서는 AWS Secrets Manager 인증 방법을 사용합니다.
```
aws redshift-data list-tables
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
다음은 이 응답의 예입니다.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
}
```
다음 AWS CLI 명령은 클러스터에 대해 SQL 문을 실행하여 데이터베이스의 테이블을 나열합니다. 이 예에서는 임시 자격 증명 인증 방법을 사용합니다.
```
aws redshift-data list-tables
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
다음은 이 응답의 예입니다.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
]
}
```
# Amazon Redshift Data API 문제 해결
공통 오류 메시지를 소개하는 다음 섹션부터는 데이터 API를 사용하면서 발생하는 문제를 해결하는 데 유용합니다.
**Topics**
+ [쿼리 패킷이 너무 큽니다](#data-api-troubleshooting-packet-too-large)
+ [데이터베이스 응답이 크기 제한을 초과했습니다](#data-api-troubleshooting-response-size-too-large)
## 쿼리 패킷이 너무 큽니다
쿼리에 대한 패킷이 너무 크다는 오류가 표시되면 일반적으로 행에 대해 반환된 결과 집합이 너무 큽니다. 데이터 API는 데이터베이스에서 반환되는 결과 집합에서 각 행의 크기를 64KB로 제한합니다.
이 문제를 해결하려면 결과 집합의 각 행마다 크기를 64KB 이하로 유지해야 합니다.
## 데이터베이스 응답이 크기 제한을 초과했습니다
데이터베이스 응답이 크기 제한을 초과했음을 나타내는 오류가 표시되면 일반적으로 데이터베이스에서 반환된 결과 집합의 크기가 너무 큽니다. Data API는 데이터베이스에서 반환되는 결과 집합의 크기를 500MB로 제한합니다.
이러한 문제를 해결하려면 Data API 직접 호출 시 반환되는 데이터 크기를 500MB 이하로 유지해야 합니다. 반환해야 하는 결과 집합의 크기가 500MB를 넘으면 쿼리에서 `LIMIT` 절을 사용하여 여러 문의 직접 호출을 실행할 수 있습니다.
# Amazon EventBridge로 Amazon Redshift Data API 작업 예약
선택된 이벤트와 일치할 경우 대상으로 라우팅하여 작업을 실행하는 규칙을 생성할 수 있습니다. 규칙을 사용하여 미리 결정된 일정에 따라 조치를 취할 수도 있습니다. 자세한 내용은 [Amazon EventBridge 사용 가이드](https://docs.aws.amazon.com/eventbridge/latest/userguide/)를 참조하세요.
EventBridge로 Data API 작업을 예약하려면 연결된 IAM 역할이 CloudWatch Events(events.amazonaws.com)의 보안 주체를 신뢰해야 합니다. 이 역할에는 관리형 정책 `AmazonEventBridgeFullAccess`에 해당하는 정책이 연결되어 있어야 합니다. Data API에 의해 관리되는 `AmazonRedshiftDataFullAccess` 정책 권한도 있어야 합니다. IAM 콘솔에서 이러한 권한으로 IAM 역할을 생성할 수 있습니다. IAM 콘솔에서 역할을 생성할 때 CloudWatch Events에 대해 AWS 서비스 신뢰할 수 있는 엔터티를 선택합니다. EventBridge 대상의 `RoleArn` JSON 값에 IAM 역할을 지정합니다. 서비스 역할 생성에 대한 자세한 내용은 *IAM User Guide*의 [Creating a Role for an AWS Service (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console)를 참조하세요.
Amazon EventBridge에서 생성하는 규칙의 `name`은 `RedshiftDataParameters`의 `StatementName`과 일치해야 합니다.
다음 예제는 한 개 또는 여러 개의 SQL 문을 사용하고 Amazon Redshift 클러스터 또는 Amazon Redshift Serverless 작업 그룹을 데이터 웨어하우스로 사용하여 EventBridge 규칙을 생성하는 변형을 보여줍니다.
## 단일 SQL 문 및 클러스터를 사용한 호출
다음 예에서는 AWS CLI를 사용하여 Amazon Redshift 클러스터에 대해 SQL 문을 실행하는 데 사용되는 EventBridge 규칙을 생성합니다.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
그런 다음 규칙에 지정된 일정에 따라 실행되도록 EventBridge 대상이 생성됩니다.
```
aws events put-targets
--cli-input-json file://data.json
```
입력 data.json 파일은 다음과 같습니다. `Sql` JSON 키는 단일 SQL 문이 있음을 나타냅니다. `Arn` JSON 값에는 클러스터 식별자가 포함됩니다. `RoleArn` JSON 값에는 앞서 설명한 대로 SQL을 실행하는 데 사용되는 IAM 역할이 포함됩니다.
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"DbUser": "root",
"Sql": "select 1;",
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## 단일 SQL 문 및 작업 그룹을 사용한 호출
다음 예에서는 AWS CLI를 사용하여 Amazon Redshift Serverless 작업 그룹에 대해 SQL 문을 실행하는 데 사용되는 EventBridge 규칙을 생성합니다.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
그런 다음 규칙에 지정된 일정에 따라 실행되도록 EventBridge 대상이 생성됩니다.
```
aws events put-targets
--cli-input-json file://data.json
```
입력 data.json 파일은 다음과 같습니다. `Sql` JSON 키는 단일 SQL 문이 있음을 나타냅니다. `Arn` JSON 값에는 작업 그룹 이름이 포함됩니다. `RoleArn` JSON 값에는 앞서 설명한 대로 SQL을 실행하는 데 사용되는 IAM 역할이 포함됩니다.
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sql": "select 1;",
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
## 여러 SQL 문 및 클러스터를 사용한 호출
다음 예에서는 AWS CLI를 사용하여 Amazon Redshift 클러스터에 대해 여러 SQL 문을 실행하는 데 사용되는 EventBridge 규칙을 생성합니다.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
그런 다음 규칙에 지정된 일정에 따라 실행되도록 EventBridge 대상이 생성됩니다.
```
aws events put-targets
--cli-input-json file://data.json
```
입력 data.json 파일은 다음과 같습니다. `Sqls` JSON 키는 여러 SQL 문이 있음을 나타냅니다. `Arn` JSON 값에는 클러스터 식별자가 포함됩니다. `RoleArn` JSON 값에는 앞서 설명한 대로 SQL을 실행하는 데 사용되는 IAM 역할이 포함됩니다.
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## 여러 SQL 문 및 작업 그룹을 사용한 호출
다음 예에서는 AWS CLI를 사용하여 Amazon Redshift Serverless 작업 그룹에 대해 여러 SQL 문을 실행하는 데 사용되는 EventBridge 규칙을 생성합니다.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
그런 다음 규칙에 지정된 일정에 따라 실행되도록 EventBridge 대상이 생성됩니다.
```
aws events put-targets
--cli-input-json file://data.json
```
입력 data.json 파일은 다음과 같습니다. `Sqls` JSON 키는 여러 SQL 문이 있음을 나타냅니다. `Arn` JSON 값에는 작업 그룹 이름이 포함됩니다. `RoleArn` JSON 값에는 앞서 설명한 대로 SQL을 실행하는 데 사용되는 IAM 역할이 포함됩니다.
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
# Data API 모니터링
Data API 및 다른 AWS 솔루션의 안정성, 가용성 및 성능을 유지하려면 모니터링이 중요합니다. AWS는 Data API를 모니터링하고, 이상이 있을 때 이를 보고하고, 필요한 경우 자동 조치를 취할 수 있도록 다음과 같은 모니터링 도구를 제공합니다.
+ Amazon EventBridge를 사용하면 AWS 서비스를 자동화하고 애플리케이션 가용성 문제나 리소스 변경 같은 시스템 이벤트에 자동으로 대응할 수 있습니다. AWS 서비스의 이벤트는 거의 실시간으로 EventBridge로 전송됩니다. 원하는 이벤트만 표시하도록 간단한 규칙을 작성한 후 규칙과 일치하는 이벤트 발생 시 실행할 자동화 작업을 지정할 수 있습니다. 자세한 내용은 [Amazon EventBridge 사용 설명서](https://docs.aws.amazon.com/eventbridge/latest/userguide/)를 참조하세요.
+ AWS CloudTrail은 직접 수행하거나 AWS 계정을 대신하여 수행한 API 호출 및 관련 이벤트를 캡처하고 지정한 Amazon S3 버킷에 로그 파일을 전송합니다. 어떤 사용자 및 계정이 AWS를 직접적으로 호출했는지, 어떤 소스 IP 주소에 직접 호출이 이루어졌는지, 언제 직접 호출이 발생했는지 확인할 수 있습니다. Amazon Redshift를 AWS CloudTrail에 통합하는 방법을 자세히 알아보려면 [CloudTrail을 사용한 로깅](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html)을 참조하세요. CloudTrail에 대한 자세한 내용은 [AWS CloudTrail 사용자 안내서](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)를 참조하세요.
**Topics**
+ [Amazon EventBridge에서 Amazon Redshift Data API에 대한 이벤트 모니터링](data-api-monitoring-events.md)
# Amazon EventBridge에서 Amazon Redshift Data API에 대한 이벤트 모니터링
자체 애플리케이션, SaaS(Software-as-a-Service) 애플리케이션 및 AWS 서비스의 실시간 데이터 스트림을 제공하는 EventBridge의 Data API 이벤트를 모니터링할 수 있습니다. EventBridge는 해당 데이터를 AWS Lambda, Amazon SNS 등의 대상으로 라우팅합니다. 이러한 이벤트는 CloudWatch Events에 나타나는 이벤트와 동일하며, AWS 리소스의 변경 사항을 설명하는 시스템 이벤트의 스트림을 거의 실시간 제공합니다. Amazon Redshift 데이터베이스가 포함된 계정으로 이벤트가 전송됩니다. 예를 들어 다른 계정의 역할을 수임하면 이벤트가 해당 계정으로 전송됩니다. 자세한 내용은 *Amazon EventBridge 사용 설명서*의 [Amazon EventBridge 이벤트](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)를 참조하세요.
`ExecuteStatement` 또는 `BatchExecuteStatement` API 작업이 `WithEvent` 옵션을 `true`로 설정하면 Data API 이벤트가 전송됩니다. 이벤트의 `state` 필드에는 다음 값 중 하나가 포함됩니다.
+ ABORTED – 쿼리 실행이 사용자에 의해 중지되었습니다.
+ [실패(FAILED)] – 쿼리 실행에 실패했습니다.
+ [완료(FINISHED)] – 쿼리 실행이 완료되었습니다.
이벤트는 보장된 방식으로 전달됩니다. 자세한 내용은 *Amazon EventBridge 사용 설명서*의 [AWS 서비스 이벤트](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)를 참조하세요.
## Data API 완료 이벤트의 예
다음 예에서는 `ExecuteStatement` API 작업이 완료될 때 Data API에 대한 이벤트를 보여줍니다. 이 예에서 `test.testtable`이라는 문이 실행을 완료했습니다.
```
{
"version": "0",
"id": "18e7079c-dd4b-dd64-caf9-e2a31640dab0",
"detail-type": "Redshift Data Statement Status Change",
"source": "aws.redshift-data",
"account": "123456789012",
"time": "2020-10-01T21:14:26Z",
"region": "us-east-1",
"resources": [
"arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster-1"
],
"detail": {
"principal": "arn:aws:iam::123456789012:user/myuser",
"statementName": "test.testtable",
"statementId": "dd2e1ec9-2ee3-49a0-819f-905fa7d75a4a",
"redshiftQueryId": -1,
"state": "FINISHED",
"rows": 1,
"expireAt": 1601673265
}
}
```
# Amazon Redshift 데이터 API와 함께 AWS KMS 사용
Amazon Redshift 클러스터 또는 Redshift Serverless 작업 그룹을 고객 관리형 키로 암호화하는 경우 Amazon Redshift 데이터 API는 동일한 고객 관리형 키를 사용하여 쿼리와 결과를 저장하고 암호화합니다.
데이터 API는 기본적으로 데이터를 암호화하여 쿼리 텍스트 및 쿼리 결과와 같은 민감한 정보를 보호합니다. 이 보호를 위해 AWS에서 소유한 AWS KMS 암호화 키를 사용합니다.
저장 데이터의 기본 암호화는 민감한 데이터를 보호하는 데 수반되는 운영 오버헤드와 복잡성을 줄여줍니다. 이 방법으로 엄격한 암호화 규정 준수 및 규제 요구 사항을 충족하는 안전한 애플리케이션을 구축할 수 있습니다.
## AWS KMS에서 권한 부여 사용
데이터 API는 고객 관리형 키를 사용하려면 권한 부여가 필요합니다.
고객 관리형 키로 암호화된 클러스터에 대해 `ExecuteStatement` 또는 `BatchExecuteStatement`를 직접 호출하면 Amazon Redshift는 AWS KMS에 [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) 요청을 전송하여 사용자를 대신하여 권한 부여를 생성합니다. AWS KMS는 권한 부여를 사용하여 계정의 KMS 키에 대한 데이터 API 액세스 권한을 부여합니다.
데이터 API는 다음 작업에 대해 고객 관리형 키를 사용할 수 있는 권한이 필요합니다.
+ AWS KMS에 [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) 요청을 보내 고객 관리형 키로 쿼리 메타데이터를 암호화합니다.
+ AWS KMS에 [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) 요청을 보내 고객 관리 키로 암호화된 데이터 키를 생성합니다.
+ 암호화된 데이터 키를 암호화할 수 있도록 암호화된 데이터 키의 암호를 해독하기 위한 [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 요청을 AWS KMS에 보냅니다.
언제든지 권한 부여에 대한 액세스 권한을 취소하거나 고객 관리형 키에 대한 Amazon Redshift 액세스 권한을 제거할 수 있습니다. 그렇게 할 경우 API는 고객이 관리하는 키로 암호화된 데이터에 더 이상 접근할 수 없게 되어 해당 데이터에 의존하는 작업에 영향을 미칩니다. 예를 들어 권한 부여를 취소한 후 쿼리 결과를 검색하거나 쿼리 상태를 추적하려고 하면 데이터 API가 `AccessDeniedException`을 반환합니다.
## 고객 관리형 키에 대한 키 정책
키 정책은 고객 관리형 키에 대한 액세스를 제어합니다. 모든 고객 관리형 키에는 키를 사용할 수 있는 사람과 키를 사용하는 방법을 결정하는 문장이 포함된 정확히 하나의 키 정책이 있어야 합니다. 고객 관리형 키를 만들 때 키 정책을 지정할 수 있습니다. 자세한 내용은 *AWS Key Management Service 개발자 안내서*의 [고객 관리형 키](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key)를 참조하세요.
데이터 API에서 고객 관리형 키를 사용하려면 먼저 Amazon Redshift에 대한 액세스를 허용해야 합니다. 키 정책에서 다음 API 작업을 허용해야 합니다.
+ `kms:CreateGrant` – 고객 관리형 키에 권한 부여를 추가합니다. 권한 부여는 지정된 AWS KMS 키에 대한 액세스를 제어하여 Amazon Redshift에 필요한 권한 부여 작업에 대한 액세스를 허용합니다. 자세한 내용은 [AWS KMS에서 권한 부여 사용](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations)을 참조하세요.
다음은 예제 키 정책입니다.
```
"Statement":[
{
"Sid":"Allow access to principals authorized to use Amazon Redshift",
"Effect":"Allow",
"Principal":{
"AWS":"*"
},
"Action":[
"kms:DescribeKey",
"kms:CreateGrant"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"kms:ViaService":"redshift.amazonaws.com",
"kms:CallerAccount":"111122223333"
}
}
},
{
"Sid":"AllowKeyAdministratorsAccess",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole"
},
"Action":"kms:*",
"Resource":"*"
},
{
"Sid":"AllowKeyUseForExampleRole",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleUserRole"
},
"Action":[
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource":"*"
}
]
```
## 데이터 API 암호화 컨텍스트
암호화 컨텍스트는 데이터에 대한 추가 컨텍스트 정보를 포함하는 키-값 페어의 선택적 집합입니다. AWS KMS는 암호화 컨텍스트를 인증된 암호화를 지원하기 위한 추가 인증 데이터로 사용합니다. 데이터 암호화 요청에 암호화 컨텍스트를 포함하는 경우, AWS KMS는 암호화된 데이터에 암호화 컨텍스트를 바인딩합니다. 이 데이터를 해독하려면 요청에 동일한 암호화 컨텍스트를 포함해야 합니다.
데이터 API는 프로비저닝된 클러스터의 모든 AWS KMS 암호화 작업에서 동일한 세 개의 암호화 컨텍스트 키-값 페어를 사용합니다.
+ `aws:redshift:arn` - 클러스터의 Amazon 리소스 이름(ARN)
+ `aws:redshift:createtime` - 클러스터 생성을 요청한 시점의 타임스탬프
+ `serviceName` – `RedshiftDataAPI`
```
"EncryptionContextSubset": {
"aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster",
"aws:redshift:createtime": "20250815T0000Z",
"serviceName": "RedshiftDataAPI",
}
```
데이터 API는 서버리스 작업 그룹의 모든 AWS KMS 암호화 작업에 두 개의 암호화 컨텍스트 키-값 페어를 사용합니다.
+ `aws:redshift-serverless:arn` - 네임스페이스의 Amazon 리소스 이름(ARN)
+ `serviceName` – RedshiftDataAPI
```
"EncryptionContextSubset": {
"aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012",
"serviceName": "RedshiftDataAPI"
}
```
암호화에 대한 자세한 내용은 [AWS KMS의 암호화 세부 정보 소개](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html)를 참조하세요. Amazon Redshift 및 AWS KMS 통합에 대한 자세한 내용은 [Amazon Redshift가 AWS KMS를 사용하는 방법](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html)을 참조하세요.