Amazon Redshift Data API 사용
Amazon Redshift 데이터 API는 데이터베이스 드라이버, 연결, 네트워크 구성, 데이터 버퍼링, 자격 증명 등을 관리할 필요가 없도록 하여 Amazon Redshift 데이터 웨어하우스에 대한 액세스를 간소화합니다. AWS SDK에서 데이터 API 작업을 사용하여 SQL 문을 실행할 수 있습니다. 데이터 API 작업에 대한 자세한 내용은 Amazon Redshift 데이터 API 참조를 참조하세요.
데이터 API는 데이터베이스에 대한 지속적인 연결을 요구하지 않습니다. 대신에 AWS SDK와의 통합과 보안 HTTP 엔드포인트를 제공합니다. 연결을 관리하지 않고 엔드포인트를 사용하여 SQL 문을 실행할 수 있습니다. Data API에 대한 호출은 비동기식입니다. Data API는 AWS Secrets Manager에 저장된 자격 증명 또는 임시 데이터베이스 자격 증명을 사용합니다. 두 인증 방법 중 하나를 사용하여 API 호출에서 암호를 전달할 필요가 없습니다. AWS Secrets Manager에 대한 자세한 내용은 AWS Secrets Manager User Guide의 What Is AWS Secrets Manager?를 참조하세요.
이 데이터 API를 사용하면 프로그래밍 방식으로 AWS Lambda, Amazon SageMaker AI 노트북, AWS Cloud9을 포함한 웹 서비스 기반 애플리케이션으로 Amazon Redshift 데이터에 액세스할 수 있습니다. 이러한 애플리케이션에 대한 자세한 내용은 AWS Lambda
데이터 API에 대해 자세히 알아보려면 AWS 빅 데이터 블로그에서 Get started with the Amazon Redshift Data API
Amazon Redshift Data API 작업
Amazon Redshift Data API를 사용하기 전에 다음 단계를 검토합니다.
-
Data API의 호출자로서 권한이 있는지 확인합니다. 권한 부여에 대한 자세한 내용은 Amazon Redshift Data API에 대한 액세스 권한 부여 섹션을 참조하세요.
-
Secrets Manager의 인증 자격 증명 또는 임시 자격 증명을 사용하여 Data API를 호출할 계획인지 결정합니다. 자세한 내용은 Amazon Redshift 데이터 API를 호출할 때 데이터베이스 인증 보안 인증 정보 선택 단원을 참조하십시오.
-
인증 자격 증명에 Secrets Manager 사용하는 경우 보안 암호를 설정합니다. 자세한 내용은 AWS Secrets Manager에 데이터베이스 자격 증명 저장 단원을 참조하십시오.
-
Data API를 호출할 때 고려 사항과 제한 사항을 검토합니다. 자세한 내용은 Amazon Redshift Data API 호출 시 고려 사항 단원을 참조하십시오.
-
AWS Command Line Interface(AWS CLI), 자체 코드 또는 Amazon Redshift 콘솔의 쿼리 편집기를 사용하여 Data API를 호출합니다. AWS CLI에서 호출 예는 데이터 API 호출 섹션을 참조하세요.
Amazon Redshift Data API 호출 시 고려 사항
Data API를 호출할 때는 다음 사항을 고려하세요.
-
Amazon Redshift 데이터 API는 Amazon Redshift 프로비저닝 클러스터와 Redshift Serverless 작업 그룹의 데이터베이스에 액세스할 수 있습니다. Redshift 데이터 API를 사용할 수 있는 AWS 리전 목록은 Amazon Web Services 일반 참조의 Redshift 데이터 API에 나열된 엔드포인트를 참조하세요.
-
최대 쿼리 기간은 24시간입니다.
-
Amazon Redshift 클러스터당 최대 활성 쿼리(
STARTED
및SUBMITTED
쿼리) 수는 500개입니다. -
최대 쿼리 결과 크기는 100MB(gzip 압축 후)입니다. 호출이 100MB를 초과하는 응답 데이터를 반환하면 호출이 종료됩니다.
-
쿼리 결과의 최대 보존 시간은 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 역할 또는 IAM 권한을 가진 사용자는CancelStatement
,DescribeStatement
,GetStatementResult
,GetStatementResultV2
및ListStatements
API 작업을 사용하여 동일한 문에 대해 작업할 수 있습니다. 다른 사용자의 동일한 SQL 문에 대해 작업을 수행하려면 사용자가 SQL 문을 실행한 사용자의 IAM 역할을 맡을 수 있어야 합니다. 역할 수임 방법에 대한 자세한 내용은 Amazon Redshift Data API에 대한 액세스 권한 부여 단원을 참조하세요.-
BatchExecuteStatement
API 작업의Sqls
파라미터에 포함된 SQL 문은 단일 트랜잭션으로 실행됩니다. 배열 순서대로 순차 실행됩니다. 후순위 SQL 문은 배열 내 선순위 명령문이 완료될 때까지 시작되지 않습니다. SQL 문이 실패하면 하나의 트랜잭션으로 실행되므로 모든 작업이 롤백됩니다. -
ExecuteStatement
또는BatchExecuteStatement
API 작업에 사용되는 클라이언트 토큰의 최대 보존 시간은 8시간입니다. -
Redshift 데이터 API의 각 API에는 요청을 제한하기 전에 초당 트랜잭션 할당량이 있습니다. 할당량에 대한 내용은 Amazon Redshift 데이터 API의 할당량 섹션을 참조하세요. 요청 비율이 할당량을 초과하면 HTTP 상태 코드가 400인
ThrottlingException
오류가 반환됩니다. 제한에 대응하려면 AWSSDK 및 도구 참조 안내서의 재시도 동작에 설명된 재시도 전략을 사용하세요. 이 전략은 일부 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 개발자 안내서의 내장 함수를 참조하세요.{ "Database": "dev", "Sql": "select 1;", "ClusterIdentifier": "MyCluster", "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)" }
Amazon Redshift 데이터 API를 호출할 때 데이터베이스 인증 보안 인증 정보 선택
Data API를 호출할 때 일부 API 작업에 대해 다음 인증 방법 중 하나를 사용합니다. 각 방법에는 서로 다른 파라미터 조합이 필요합니다.
- AWS Secrets Manager
-
이 방법에서는
username
및password
가 있는 AWS Secrets Manager에 저장된 암호의secret-arn
을 입력합니다. 지정된 보안 암호에는 지정하는database
에 연결하기 위한 자격 증명이 포함되어 있습니다. 클러스터에 연결할 때는 데이터베이스 이름도 제공하며, 클러스터 식별자(dbClusterIdentifier
)를 제공하는 경우 암호에 저장된 클러스터 식별자와 일치해야 합니다. 서버리스 작업 그룹에 연결할 때는 데이터베이스 이름도 제공합니다. 자세한 내용은 AWS Secrets Manager에 데이터베이스 자격 증명 저장 단원을 참조하십시오. - 임시 자격 증명
-
이 방법에서는 다음 옵션 중 하나를 선택합니다.
-
서버리스 작업 그룹에 연결할 때는 작업 그룹 이름과 데이터베이스 이름을 지정합니다. 데이터베이스 사용자 이름은 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
작업을 호출할 수 있는 권한이 필요합니다. 이 방법으로 연결할 때 데이터베이스 그룹에 가입하는 방법에 대한 자세한 내용은 클러스터에 연결할 때 데이터베이스 그룹에 조인을 참조하세요.
-
이 방법에서는 데이터가 위치한 AWS 리전을 지정하는 region
값을 제공할 수도 있습니다.
Amazon Redshift Data API를 호출할 때 JDBC 데이터 형식 매핑
다음 표는 JDBC(Java Database Connectivity) 데이터 유형을 데이터 API 호출에서 지정하는 데이터 형식에 매핑합니다.
JDBC 데이터 형식 |
데이터 API 데이터 형식 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
다른 형식(날짜 및 시간과 관련된 형식 포함) |
|
문자열 값은 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"
)의 열 이름을 대체하지 않으며 오류가 보고됩니다(오류: \"FROM\" 또는 근처에 구문 오류가 있음\n 위치: 12
). -
집계 함수의 열 이름(예:
COUNT(column-name)
,AVG(column-name)
또는SUM(column-name)
)은 대체할 수 없습니다. -
JOIN 절의 열 이름은 대체할 수 없습니다.
-
-
SQL 실행 시 암시적으로 데이터가 데이터 형식으로 캐스팅됩니다. 데이터 형식 캐스팅에 대한 자세한 내용은 Amazon Redshift 데이터베이스 개발자 안내서의 데이터 형식을 참조하세요.
-
값을 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 예제를 참조하세요.
다음 execute-statement
AWS CLI 명령은 멱등성을 위한 선택적 client-token
파라미터를 보여줍니다.
aws redshift-data execute-statement
--secret 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 시리즈 응답 코드 |
다시 시도하지 않음 |
다음 중에서는 요청에 문제가 있습니다.
요청에 상태 변경 프로세스에 있는 리소스가 포함된 경우 요청 재시도가 성공할 수 있습니다. |
500 시리즈 응답 코드 |
재시도 |
이 오류는 AWS 서버 측 문제로 인해 발생하며 일반적으로 일시적입니다. 적절한 백오프 전략으로 요청을 반복합니다. |
Amazon Redshift 응답 코드에 대한 자세한 내용은 Amazon Redshift API 참조의 Common Errors(일반 오류)를 참조하세요.
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": "
<token>
", "Records": [ [ { "longValue": 1 } ] ], "TotalNumRows":<number>
}
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": "
<token>
", "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":<number>
}