Amazon Redshift Data API 사용

기본 제공 Amazon Redshift Data API를 사용하여 Amazon Redshift 데이터베이스에 액세스할 수 있습니다. 이 API를 사용하면 AWS Lambda, Amazon SageMaker 노트북, AWS Cloud9을 포함한 웹 서비스 기반 애플리케이션으로 Amazon Redshift 데이터에 액세스할 수 있습니다. 이러한 애플리케이션에 대한 자세한 내용은 AWS Lambda, Amazon SageMaker 및 AWS Cloud9 섹션을 참조하세요.

데이터 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?를 참조하세요.

Data API 작업에 대한 자세한 내용은 Amazon Redshift Data API Reference를 참조하세요.

Amazon Redshift Data API 작업

Amazon Redshift Data API를 사용하기 전에 다음 단계를 검토합니다.

1. Data API의 호출자로서 권한이 있는지 확인합니다. 권한 부여에 대한 자세한 내용은 Amazon Redshift Data API에 대한 액세스 권한 부여 섹션을 참조하세요.

2. Secrets Manager의 인증 자격 증명 또는 임시 자격 증명을 사용하여 Data API를 호출할 계획인지 결정합니다. 자세한 내용은 Amazon Redshift 데이터 API를 호출할 때 데이터베이스 인증 보안 인증 정보 선택 단원을 참조하십시오.

3. 인증 자격 증명에 Secrets Manager 사용하는 경우 보안 암호를 설정합니다. 자세한 내용은 AWS Secrets Manager에 데이터베이스 자격 증명 저장 단원을 참조하십시오.

4. Data API를 호출할 때 고려 사항과 제한 사항을 검토합니다. 자세한 내용은 Amazon Redshift Data API 호출 시 고려 사항 단원을 참조하십시오.

5. 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 쿼리) 수는 200개입니다.

• 최대 쿼리 결과 크기는 100MB(gzip 압축 후)입니다. 호출이 100MB를 초과하는 응답 데이터를 반환하면 호출이 종료됩니다.

• 쿼리 결과의 최대 보존 시간은 24시간입니다.

• 최대 쿼리 문 크기는 100KB입니다.

• Data API는 다음 노드 유형의 단일 노드 및 다중 노드 클러스터를 쿼리하는 데 사용할 수 있습니다.

  • dc2.large

  • dc2.8xlarge

  • ra3.xlplus

  • ra3.4xlarge

  • ra3.16xlarge

• 클러스터는 Amazon VPC 서비스 기반의 Virtual Private Cloud(VPC)에 있어야 합니다.

• 기본적으로 ExecuteStatement 또는 BatchExecuteStatement API 작업의 실행자와 동일한 IAM 역할 또는 IAM 권한을 가진 사용자는 CancelStatement, DescribeStatement, GetStatementResult 및 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 데이터 형식
INTEGER, SMALLINT, BIGINT	LONG
FLOAT, REAL, DOUBLE	DOUBLE
DECIMAL	STRING
BOOLEAN, BIT	BOOLEAN
BLOB, BINARY, LONGVARBINARY, VARBINARY	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")의 열 이름을 대체하지 않으며 오류가 보고됩니다(오류: \"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 
    --region us-west-2 
    --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(일반 오류)를 참조하세요.