리전 및 버전 사용 가능 여부 제한 사항 Serverless v2 및 프로비저닝과의 비교 및 Aurora Serverless v1 액세스 권한 부여 RDS 데이터 API 활성화 Amazon VPC 엔드포인트 생성 RDS 데이터 API 호출 Java 클라이언트 라이브러리 사용 JSON 형식의 쿼리 결과 처리 데이터 API 문제 해결

RDS 데이터 API 사용

RDS 데이터 API(데이터 API)를 사용하면 Aurora DB 클러스터에 대한 웹 서비스 인터페이스로 작업할 수 있습니다. 데이터 API에서 DB 클러스터에 지속적으로 연결하지 않아도 됩니다. 대신에 AWS SDK와의 통합과 보안 HTTP 엔드포인트를 제공합니다. 연결을 관리하지 않고 엔드포인트를 사용하여 SQL 문을 실행할 수 있습니다.

데이터 API에 대한 모든 호출은 동기식입니다. 기본적으로 45초 내에 처리가 완료되지 않으면 호출 시간이 초과됩니다. 그러나 continueAfterTimeout 파라미터를 사용하여 호출 시간이 초과되는 경우 SQL 문을 계속 실행할 수 있습니다. 관련 예제는 SQL 트랜잭션 실행 섹션을 참조하세요

데이터 API는 AWS Secrets Manager에 저장된 데이터베이스 보안 인증 정보를 사용하기 때문에 사용자는 데이터 API 호출과 함께 보안 인증 정보를 전달할 필요가 없습니다. Secrets Manager에 보안 인증 정보를 저장하려면 사용자에게 Secrets Manager 및 데이터 API를 사용할 수 있는 적절한 권한을 부여해야 합니다. 사용자 인증에 대한 자세한 내용은 RDS 데이터 API에 대한 액세스 권한 부여 단원을 참조하세요.

또한 데이터 API를 사용하여 Amazon Aurora를 다른 AWS 애플리케이션(예: AWS Lambda, AWS AppSync, AWS Cloud9)과 통합할 수 있습니다 데이터 API는 AWS Lambda를 사용하는 더 안전한 방법도 제공합니다. Virtual Private Cloud(VPC)의 리소스에 액세스하는 Lambda 함수를 구성할 필요 없이 DB 클러스터에 액세스할 수 있습니다. 자세한 내용은 AWS Lambda, AWS AppSync, AWS Cloud9 단원을 참조하십시오.

Aurora DB 클러스터를 생성할 때 데이터 API를 활성화할 수 있습니다. 나중에 구성을 수정할 수도 있습니다. 자세한 내용은 RDS 데이터 API 활성화 섹션을 참조하세요.

데이터 API를 활성화하면 VPC에서 Aurora에 액세스하도록 쿼리 도구를 구성하지 않고도 쿼리 편집기를 사용하여 임시 쿼리를 실행할 수 있습니다. 자세한 내용은 쿼리 편집기 사용하기 섹션을 참조하세요.

주제

리전 및 버전 사용 가능 여부
RDS 데이터 API의 제한
Serverless v2 및 프로비저닝과 RDS 데이터 API의 비교 및 Aurora Serverless v1
RDS 데이터 API에 대한 액세스 권한 부여
RDS 데이터 API 활성화
RDS 데이터 API(AWS PrivateLink)에 대한 Amazon VPC 엔드포인트 생성
RDS 데이터 API 호출
RDS 데이터 API용 Java 클라이언트 라이브러리 사용
JSON 형식의 쿼리 결과 처리
RDS 데이터 API 문제 해결
AWS CloudTrail을 사용하여 RDS 데이터 API 호출 로깅

리전 및 버전 사용 가능 여부

데이터 API에 사용할 수 있는 리전 및 엔진 버전에 대한 자세한 내용은 다음 섹션을 참조하세요.

클러스터 유형	리전 및 버전 사용 가능 여부
Aurora PostgreSQL 프로비저닝 및 Serverless v2	Aurora PostgreSQL Serverless v2를 사용하고 프로비저닝된 Data API
Aurora PostgreSQL Serverless v1	Aurora PostgreSQL Serverless v1을 사용하는 Data API
Aurora MySQL Serverless v1	Aurora MySQL Serverless v1을 사용하는 Data API

참고

현재 Aurora MySQL 프로비저닝 또는 Serverless v2 DB 클러스터에는 데이터 API를 사용할 수 없습니다.

명령줄 인터페이스 또는 API를 통해 데이터 API에 액세스할 때 FIPS 140-2에서 유효성을 검사한 암호화 모듈이 필요한 경우 FIPS 엔드포인트를 사용합니다. 사용 가능한 FIPS 엔드포인트에 대한 자세한 내용은 Federal Information Processing Standard(FIPS) 140-2 섹션을 참조하세요.

RDS 데이터 API의 제한

RDS 데이터 API(데이터 API)에는 다음과 같은 제한 사항이 적용됩니다.

DB 클러스터의 라이터 인스턴스에서만 데이터 API 쿼리를 실행할 수 있습니다. 하지만 라이터 인스턴스는 쓰기 쿼리와 읽기 쿼리를 모두 수락할 수 있습니다.
Aurora 글로벌 데이터베이스를 사용하면 기본 및 보조 DB 클러스터 모두에서 데이터 API를 활성화할 수 있습니다. 하지만 보조 클러스터를 기본 클러스터로 승격하기 전까지는 라이터 인스턴스가 존재하지 않습니다. 따라서 보조 클러스터로 보내는 데이터 API 쿼리는 실패합니다. 승격된 보조 클러스터에 사용 가능한 라이터 인스턴스가 있으면 해당 DB 인스턴스에 대한 데이터 API 쿼리가 성공해야 합니다.
성능 개선 도우미는 데이터 API를 사용하여 만든 데이터베이스 쿼리 모니터링을 지원하지 않습니다.
T DB 인스턴스 클래스에서는 데이터 API가 지원되지 않습니다.
Aurora PostgreSQL Serverless v2 및 프로비저닝된 DB 클러스터의 경우 RDS 데이터 API는 열거형 유형을 지원하지 않습니다. 지원되는 유형 목록은 Serverless v2 및 프로비저닝과 RDS 데이터 API의 비교 및 Aurora Serverless v1 섹션을 참조하세요.
Aurora PostgreSQL 버전 14 이상에서는 데이터 API가 암호 암호화에 scram-sha-256만 지원합니다.

Serverless v2 및 프로비저닝과 RDS 데이터 API의 비교 및 Aurora Serverless v1

다음 표에는 Aurora PostgreSQL Serverless v2와 프로비저닝된 DB 클러스터 및 Aurora Serverless v1 DB 클러스터를 사용하는 RDS 데이터 API(데이터 API) 간의 차이점이 나와 있습니다.

차이	Aurora PostgreSQL Serverless v2 및 프로비저닝	Aurora Serverless v1
초당 최대 요청 수	무제한	1,000
RDS API 또는 AWS CLI를 사용하여 기존 데이터베이스에서 데이터 API 활성화 또는 비활성화	RDS API – `EnableHttpEndpoint` 및 `DisableHttpEndpoint` 작업을 사용합니다. AWS CLI - `enable-http-endpoint` 및 `disable-http-endpoint` 작업을 사용합니다.	RDS API – `ModifyDBCluster` 작업을 사용하고 `EnableHttpEndpoint` 파라미터에 대해 `true` 또는 `false`(해당하는 경우)를 지정합니다. AWS CLI – 해당하는 경우 `--enable-http-endpoint` 또는 `--no-enable-http-endpoint` 옵션과 함께 `modify-db-cluster` 작업을 사용합니다.
CloudTrail 이벤트	데이터 API 호출의 이벤트는 데이터 이벤트입니다. 이러한 이벤트는 기본적으로 추적에서 자동으로 제외됩니다. 자세한 내용은 AWS CloudTrail 추적에서 데이터 API 이벤트 포함 섹션을 참조하세요.	데이터 API 호출의 이벤트는 관리 이벤트입니다. 이러한 이벤트는 기본적으로 추적에 자동으로 포함됩니다. 자세한 내용은 AWS CloudTrail 추적에서 데이터 API 이벤트 제외(Aurora Serverless v1 전용) 섹션을 참조하세요.
다중 문 지원	다중 문은 지원되지 않습니다. 이 경우 데이터 API가 `ValidationException: Multistatements aren't supported`를 표시합니다.	Aurora PostgreSQL의 경우 다중 문은 첫 번째 쿼리 응답만 반환합니다. Aurora MySQL의 경우 다중 문이 지원되지 않습니다.
BatchExecuteStatement	업데이트 결과에서 생성된 필드 객체가 비어 있습니다.	업데이트 결과에서 생성된 필드 객체에는 삽입된 값이 포함됩니다.
ExecuteSQL	지원되지 않음	Deprecated
ExecuteStatement	`ExecuteStatement`는 다차원 배열 열 검색을 지원하지 않습니다. 이 경우 데이터 API가 `UnsupportedResultException`를 표시합니다. 데이터 API는 기하학적 유형 및 화폐 유형과 같은 일부 데이터 유형을 지원하지 않습니다. 이 경우 데이터 API가 `UnsupportedResultException: The result contains the unsupported data type data_type`를 표시합니다. 다음 유형만 지원됩니다. `BOOL` `BYTEA` `DATE` `DECIMAL`, `NUMERIC` `FLOAT8`, `DOUBLE PRECISION` `INT`, `INT4`, `SERIAL` `INT2`, `SMALLINT`, `SMALLSERIAL` `INT8`, `BIGINT`, `BIGSERIAL` `JSONB`, `JSON` `REAL`, `FLOAT` `TEXT`, `CHAR(N)`, `VARCHAR`, `NAME` `TIME` `TIMESTAMP` `UUID` `VECTOR` 다음 배열 유형만 지원됩니다. `BOOL[]`, `BIT[]` `DATE[]` `DECIMAL[]`, `NUMERIC[]` `FLOAT8[]`, `DOUBLE PRECISION[]` `INT[]`, `INT4[]` `INT2[]` `INT8[]`, `BIGINT[]` `JSON[]` `REAL[]`, `FLOAT[]` `TEXT[]`, `CHAR(N)[]`, `VARCHAR[]`, `NAME[]` `TIME[]` `TIMESTAMP[]` `UUID[]`	`ExecuteStatement`는 다차원 배열 열 및 모든 고급 데이터 유형 검색을 지원합니다.

RDS 데이터 API에 대한 액세스 권한 부여

사용자는 권한이 있는 경우에만 RDS 데이터 API(데이터 API) 작업을 간접 호출할 수 있습니다. 권한을 정의하는 AWS Identity and Access Management(IAM) 정책을 연결하여 데이터 API를 사용할 수 있는 권한을 사용자에게 부여할 수 있습니다. IAM 역할을 사용하는 경우 정책을 역할에 연결할 수도 있습니다. AWS 관리형 정책인 AmazonRDSDataFullAccess에는 데이터 API에 대한 권한이 포함되어 있습니다.

AmazonRDSDataFullAccess 정책에는 사용자가 AWS Secrets Manager에서 보안 암호 값을 가져올 수 있는 권한도 포함되어 있습니다. 사용자는 데이터 API 호출에 사용할 수 있는 보안 암호를 저장하는 데 Secrets Manager를 사용해야 합니다. 보안 암호를 사용하면 사용자가 데이터 API 호출의 대상이 되는 리소스에 대한 데이터베이스 보안 인증 정보를 포함할 필요가 없습니다. 데이터 API는 투명하게 Secrets Manager를 호출하여 사용자의 보안 암호에 대한 요청을 허용(또는 거부)합니다. 데이터 API와 함께 사용할 보안 암호 설정에 대한 자세한 내용은 AWS Secrets Manager에 데이터베이스 자격 증명 저장 섹션을 참조하세요.

AmazonRDSDataFullAccess 정책은 데이터 API를 통해 리소스에 대한 완전한 액세스를 제공합니다. 리소스의 Amazon 리소스 이름(ARN)을 지정하는 사용자 고유의 정책을 정의하여 범위를 좁힐 수 있습니다.

예를 들어, 다음 정책은 사용자가 ARN으로 식별되는 DB 클러스터의 데이터 API에 액세스하는 데 필요한 최소 권한을 보여줍니다. 정책에는 Secrets Manager에 액세스하고 사용자의 DB 인스턴스에 대한 권한 부여를 얻는 데 필요한 권한이 포함되어 있습니다.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SecretsManagerDbCredentialsAccess",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*"
        },
        {
            "Sid": "RDSDataServiceAccess",
            "Effect": "Allow",
            "Action": [
                "rds-data:BatchExecuteStatement",
                "rds-data:BeginTransaction",
                "rds-data:CommitTransaction",
                "rds-data:ExecuteStatement",
                "rds-data:RollbackTransaction"
            ],
            "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod"
        }
    ]
}

예제와 같이 정책 문에서 와일드카드(*) 대신 “Resources” 요소에 대한 특정 ARN을 사용하는 것이 좋습니다.

태그 기반 권한 부여 작업

RDS 데이터 API(데이터 API) 및 Secrets Manager 모두 태그 기반 권한 부여를 지원합니다. 태그는 RDS 클러스터와 같은 리소스에 추가 문자열 값을 사용하여 레이블을 지정하는 키-값 쌍입니다. 예를 들면 다음과 같습니다.

environment:production
environment:development

비용 할당, 운영 지원, 액세스 제어 및 기타 여러 이유로 리소스에 태그를 적용할 수 있습니다. 리소스에 아직 태그가 없는 상태에서 태그를 적용하려는 경우 Amazon RDS 리소스 태그 지정에서 자세한 내용을 확인할 수 있습니다. 정책 문의 태그를 사용하여 이러한 태그로 레이블이 지정된 RDS 클러스터에 대한 액세스를 제한할 수 있습니다. 예를 들어 Aurora DB 클러스터에는 환경을 프로덕션 또는 개발로 식별하는 태그가 있을 수 있습니다.

다음 예제에서는 정책 문에서 태그를 사용하는 방법을 보여줍니다. 이 문을 사용하려면 클러스터와 데이터 API 요청에 전달된 보안 암호에 environment:production 태그가 있어야 합니다.

정책이 적용되는 방법은 다음과 같습니다. 사용자가 데이터 API를 사용하여 호출하면 요청이 서비스로 전송됩니다. 데이터 API는 먼저 요청에서 전달된 클러스터 ARN에 environment:production으로 태그가 지정되어 있는지 확인합니다. 그런 다음 Secrets Manager를 호출하여 요청에서 사용자의 비밀 값을 검색합니다. Secrets Manager는 또한 environment:production이 사용자의 비밀에 태깅되었는지 확인됩니다. 그렇다면 데이터 API는 사용자의 DB 암호에 대해 검색된 값을 사용합니다. 마지막으로, 올바른 경우 사용자에 대해 데이터 API 요청이 성공적으로 호출됩니다.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SecretsManagerDbCredentialsAccess",
            "Effect": "Allow",
            "Action": [
                 "secretsmanager:GetSecretValue"
               ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*",
            "Condition": {
                    "StringEquals": {
                        "aws:ResourceTag/environment": [
                                         "production"
                                        ]
                     }
             }
        },
        {
            "Sid": "RDSDataServiceAccess",
            "Effect": "Allow",
            "Action": [
                  "rds-data:*"
               ],
            "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*",
            "Condition": {
                    "StringEquals": {
                        "aws:ResourceTag/environment": [
                                         "production"
                                        ]
                     }
             }
         }
     ]
}

이 예제에서는 데이터 API 및 Secrets Manager의 rds-data 및 secretsmanager에 대한 별도의 작업을 보여줍니다. 그러나 여러 가지 방법으로 작업을 결합하고 태그 조건을 정의하여 특정 사용 사례를 지원할 수 있습니다. 자세한 내용은 Secrets Manager에 대한 자격 증명 기반 정책(IAM 정책) 사용을 참조하십시오.

정책의 “Condition” 요소에 대해 다음 중에서 태그 키를 선택할 수 있습니다.

aws:TagKeys
aws:ResourceTag/${TagKey}

리소스 태그 및 aws:TagKeys 사용 방법에 대한 자세한 내용은 리소스 태그를 사용하여 AWS 리소스에 대한 액세스 제어를 참조하십시오.

참고

데이터 API 및 AWS Secrets Manager 모두 사용자에게 권한을 부여합니다. 정책에 정의된 모든 작업에 대한 권한이 없는 경우 AccessDeniedException 오류가 발생합니다.

AWS Secrets Manager에 데이터베이스 자격 증명 저장

RDS 데이터 API(데이터 API)를 호출할 때 Secrets Manager에서 보안 암호를 사용하여 Aurora DB 클러스터에 대한 보안 인증 정보를 전달합니다. 이 방식으로 자격 증명을 전달하려면 보안 암호의 이름 또는 보안 암호의 Amazon 리소스 이름(ARN)을 지정합니다.

보안 암호에 DB 클러스터 자격 증명을 저장하려면

Secrets Manager을 사용하여 Aurora DB 클러스터의 자격 증명을 포함하는 보안 암호를 생성합니다.

이에 관한 지침은 AWS Secrets Manager 사용 설명서의 데이터베이스 암호 생성에서 확인하세요.
Secrets Manager 콘솔을 사용하여 생성한 비밀에 대한 세부 정보를 보거나 aws secretsmanager describe-secret AWS CLI 명령을 실행합니다.

보안 암호의 이름 및 ARN을 적어둡니다. 이러한 이름이나 ARN은 데이터 API 호출에서 사용할 수 있습니다.

Secrets Manager 사용에 대한 자세한 내용은 AWS Secrets Manager 사용 설명서를 참조하세요.

Amazon Aurora이 자격 증명 및 액세스를 관리하는 방법을 이해하려면 IAM에서 Amazon Aurora을 사용하는 방식을 참조하십시오.

IAM 정책 생성에 대한 자세한 내용은 IAM 사용 설명서의 IAM 정책 생성을 참조하십시오. 사용자에게 IAM 정책 추가에 대한 자세한 내용은 IAM 사용 설명서의 IAM 자격 증명 권한 추가 및 제거를 참조하십시오.

RDS 데이터 API 활성화

RDS 데이터 API(데이터 API)를 사용하려면 Aurora DB 클러스터에 대해 RDS 데이터 API(데이터 API)를 활성화합니다. DB 클러스터를 생성하거나 수정할 때 데이터 API를 활성화할 수 있습니다.

참고

Aurora PostgreSQL의 경우 Aurora Serverless v2, Aurora Serverless v1 및 프로비저닝된 데이터베이스에서 데이터 API가 지원됩니다. Aurora MySQL의 경우 데이터 API는 Aurora Serverless v1 데이터베이스에서만 지원됩니다.

데이터베이스를 생성할 때 RDS 데이터 API 활성화

RDS 데이터 API(데이터 API)를 지원하는 데이터베이스를 생성하는 동안 이 기능을 활성화할 수 있습니다. 다음 절차에서는 AWS Management Console, AWS CLI 또는 RDS API를 사용할 때 해당 작업을 수행하는 방법을 설명합니다.

DB 클러스터를 생성할 때 데이터 API를 활성화하려면 다음 스크린샷과 같이 데이터베이스 생성 페이지의 연결 섹션에서 RDS 데이터 API 활성화 확인란을 선택합니다.

데이터베이스 생성 페이지의 연결 섹션에 RDS 데이터 API 활성화 확인란이 선택됨.

데이터베이스를 만드는 방법에 대한 지침은 다음을 참조하세요.

Aurora PostgreSQL Serverless v2 및 프로비저닝된 데이터베이스의 경우 – Amazon Aurora DB 클러스터 생성
Aurora Serverless v1의 경우 – Aurora Serverless v1 DB 클러스터 생성

Aurora DB 클러스터를 생성하는 동안 데이터 API를 활성화하려면 --enable-http-endpoint 옵션과 함께 create-db-cluster AWS CLI 명령을 실행합니다.

다음 예제에서는 데이터 API가 활성화된 Aurora PostgreSQL DB 클러스터를 생성합니다.

Linux, macOS, Unix:


aws rds create-db-cluster \
    --db-cluster-identifier my_pg_cluster \
    --engine aurora-postgresql \
    --enable-http-endpoint

Windows의 경우:


aws rds create-db-cluster ^
    --db-cluster-identifier my_pg_cluster ^
    --engine aurora-postgresql ^
    --enable-http-endpoint

Aurora DB 클러스터를 생성하는 동안 데이터 API를 활성화하려면 EnableHttpEndpoint 파라미터 값을 true로 설정한 상태에서 CreateDBCluster 작업을 사용하세요.

기존 데이터베이스에서 RDS 데이터 API 활성화

RDS 데이터 API(데이터 API)를 지원하는 DB 클러스터를 수정하여 이 기능을 활성화하거나 비활성화할 수 있습니다.

주제

데이터 API 활성화 또는 비활성화(Aurora PostgreSQL Serverless v2 및 프로비저닝)
데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)

데이터 API 활성화 또는 비활성화(Aurora PostgreSQL Serverless v2 및 프로비저닝)

다음 절차를 사용하여 Aurora PostgreSQL Serverless v2 및 프로비저닝된 데이터베이스에서 데이터 API를 활성화하거나 비활성화할 수 있습니다. Aurora Serverless v1 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)의 절차를 사용하세요.

이 기능을 지원하는 DB 클러스터의 RDS 콘솔을 사용하여 데이터 API를 활성화 또는 비활성화할 수 있습니다. 이렇게 하려면 데이터 API를 활성화하거나 비활성화하려는 데이터베이스의 클러스터 세부 정보 페이지를 열고 연결 및 보안 탭에서 RDS 데이터 API 섹션으로 이동합니다. 이 섹션에는 데이터 API의 상태가 표시되며 이를 활성화하거나 비활성화할 수 있습니다.

다음 스크린샷은 활성화되지 않은 RDS 데이터 API를 보여줍니다.

DB 클러스터 세부 정보 페이지의 연결 및 보안 탭에 있는 RDS 데이터 API 섹션. 데이터 API의 상태가 비활성화된 것으로 표시되고 RDS 데이터 API 활성화 버튼이 나타납니다.

기존 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 enable-http-endpoint 또는 disable-http-endpoint AWS CLI 명령을 실행하고 DB 클러스터의 ARN을 지정합니다.

다음 예제에서는 데이터 API를 활성화합니다.

Linux, macOS, Unix:


aws rds enable-http-endpoint \
    --resource-arn cluster_arn

Windows의 경우:


aws rds enable-http-endpoint ^
    --resource-arn cluster_arn

기존 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 EnableHttpEndpoint 및 DisableHttpEndpoint 작업을 사용합니다.

데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)

다음 절차를 사용하여 기존 Aurora Serverless v1 데이터베이스에서 데이터 API를 활성화 또는 비활성화합니다. Aurora PostgreSQL Serverless v2 및 프로비저닝된 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 데이터 API 활성화 또는 비활성화(Aurora PostgreSQL Serverless v2 및 프로비저닝)의 절차를 참조하세요.

Aurora Serverless v1 DB 클러스터를 수정할 때 RDS 콘솔의 연결 섹션에서 데이터 API를 활성화합니다.

다음 스크린샷은 Aurora DB 클러스터를 수정할 때 활성화된 데이터 API를 보여줍니다.

DB 클러스터 수정 페이지의 연결 섹션에서 데이터 API 확인란이 선택됨.

Aurora Serverless v1 DB 클러스터를 수정하는 방법에 대한 지침은 Aurora Serverless v1 DB 클러스터 수정 섹션을 참조하세요.

데이터 API를 활성화하거나 비활성화하려면 해당하는 경우 --enable-http-endpoint 또는 --no-enable-http-endpoint와 함께 modify-db-cluster AWS CLI 명령을 실행합니다.

다음 예제에서는 sample-cluster에서 데이터 API를 활성화합니다.

Linux, macOS, Unix:


aws rds modify-db-cluster \
    --db-cluster-identifier sample-cluster \
    --enable-http-endpoint

Windows의 경우:


aws rds modify-db-cluster ^
    --db-cluster-identifier sample-cluster ^
    --enable-http-endpoint

데이터 API를 활성화하려면 ModifyDBCluster 작업을 사용하고 해당하는 경우 EnableHttpEndpoint 의 값을 true 또는 false로 설정합니다.

RDS 데이터 API(AWS PrivateLink)에 대한 Amazon VPC 엔드포인트 생성

Amazon VPC를 사용하면 Aurora DB 클러스터 및 애플리케이션과 같은 AWS 리소스를 Virtual Private Cloud(VPC)에서 시작할 수 있습니다. AWS PrivateLink는 Amazon 네트워크에서 VPC 및 AWS 서비스 간의 프라이빗 연결을 안전하게 제공합니다. AWS PrivateLink를 사용하면 Amazon VPC 엔드포인트를 생성하여 Amazon VPC 기반의 다른 계정 및 VPC에서 서비스에 연결할 수 있습니다. AWS PrivateLink에 대한 자세한 내용은 Amazon Virtual Private Cloud 사용 설명서의 VPC 엔드포인트 서비스(AWS PrivateLink)를 참조하세요.

Amazon VPC 엔드포인트를 사용하여 RDS 데이터 API(데이터 API)를 호출할 수 있습니다. Amazon VPC 엔드포인트를 사용하면 퍼블릭 IP 주소를 사용하지 않고 Amazon VPC의 애플리케이션과 AWS 네트워크의 데이터 API 간에 트래픽을 유지합니다. Amazon VPC 엔드포인트를 사용하면 퍼블릭 인터넷 연결 제한과 관련된 규정 준수 및 규정 요구 사항을 충족할 수 있습니다. 예를 들어, Amazon VPC 엔드포인트를 사용하는 경우 Amazon EC2 인스턴스에서 실행되는 애플리케이션과 해당 애플리케이션이 포함된 VPC의 데이터 API 간 트래픽을 유지할 수 있습니다.

Amazon VPC 엔드포인트를 생성한 후에는 애플리케이션에서 코드나 구성을 변경하지 않고 엔드포인트를 사용할 수 있습니다.

데이터 API에 대한 Amazon VPC 엔드포인트를 생성하려면

AWS Management Console에 로그인하고 https://console.aws.amazon.com/vpc/에서 Amazon VPC 콘솔을 엽니다.
엔드포인트를 선택한 다음 엔드포인트 생성을 선택합니다.
엔드포인트 생성 페이지에서 서비스 범주에 대해 AWS 서비스를 선택합니다. 서비스 이름에 대해 rds-data를 선택합니다.
VPC의 경우 엔드포인트를 생성할 VPC를 선택합니다.

데이터 API를 호출하는 애플리케이션이 포함된 VPC를 선택합니다.
서브넷의 경우 애플리케이션을 실행 중인 AWS 서비스에서 사용하는 각 가용 영역(AZ)의 서브넷을 선택합니다.

Amazon VPC 엔드포인트를 생성하려면 엔드포인트에 액세스할 수 있는 프라이빗 IP 주소 범위를 지정합니다. 이렇게 하려면 각 가용 영역에 대한 서브넷을 선택합니다. 이렇게 하면 VPC 엔드포인트가 각 가용 영역별 프라이빗 IP 주소 범위로 제한되고 각 가용 영역에 Amazon VPC 엔드포인트가 생성됩니다.
Enable DNS name(DNS 이름 활성화)에서 이 엔드포인트에 대해 활성화를 선택합니다.

프라이빗 DNS는 표준 데이터 API DNS 호스트 이름(https://rds-data.region.amazonaws.com)을 Amazon VPC 엔드포인트에 특정한 DNS 호스트 이름과 연결된 프라이빗 IP 주소로 확인합니다. 따라서 데이터 API 엔드포인트 URL을 업데이트하기 위해 코드나 구성을 변경하지 않고도 AWS CLI 또는 AWS SDK를 사용하여 데이터 API VPC 엔드포인트에 액세스할 수 있습니다.
보안 그룹의 경우 Amazon VPC 엔드포인트와 연결할 보안 그룹을 선택합니다.

애플리케이션을 실행 중인 AWS 서비스에 대한 액세스를 허용하는 보안 그룹을 선택합니다. 예를 들어 Amazon EC2 인스턴스가 애플리케이션을 실행 중인 경우 Amazon EC2 인스턴스에 대한 액세스를 허용하는 보안 그룹을 선택합니다. 보안 그룹을 사용하면 VPC의 리소스에서 Amazon VPC 엔드포인트로 가는 트래픽을 제어할 수 있습니다.
정책의 경우 모든 액세스를 선택하여 Amazon VPC에 있는 모든 사용자가 이 엔드포인트를 통해 데이터 API에 액세스할 수 있도록 허용합니다. 또는 사용자 지정을 선택하여 액세스를 제한하는 정책을 지정합니다.

사용자 지정을 선택한 경우 정책 생성 도구에 정책을 입력합니다.
[Create endpoint]를 선택합니다.

엔드포인트를 생성한 후 AWS Management Console에서 링크를 선택하여 엔드포인트 세부 정보를 봅니다.

엔드포인트 세부 정보 탭에는 Amazon VPC 엔드포인트를 만드는 동안 생성된 DNS 호스트 이름이 표시됩니다.

표준 엔드포인트(rds-data.region.amazonaws.com) 또는 VPC 관련 엔드포인트 중 하나를 사용하여 Amazon VPC에서 데이터 API를 호출할 수 있습니다. 표준 데이터 API 엔드포인트는 자동으로 Amazon VPC 엔드포인트로 라우팅됩니다. 이 라우팅은 Amazon VPC 엔드포인트를 생성할 때 프라이빗 DNS 호스트 이름을 활성화했기 때문에 발생합니다.

데이터 API 호출에서 Amazon VPC 엔드포인트를 사용하는 경우 애플리케이션과 데이터 API 간의 모든 트래픽은 해당 트래픽이 포함된 Amazon VPC에 남아 있습니다. 모든 유형의 데이터 API 호출에 Amazon VPC 엔드포인트를 사용할 수 있습니다. 데이터 API 호출에 대한 자세한 내용은 RDS 데이터 API 호출 섹션을 참조하세요.

RDS 데이터 API 호출

Aurora DB 클러스터에서 RDS 데이터 API(데이터 API)를 활성화하면 데이터 API 또는 AWS CLI를 사용하여 Aurora DB 클러스터에서 SQL 문을 실행할 수 있습니다. 데이터 API는 AWS SDK에서 지원되는 프로그래밍 언어를 지원합니다. 자세한 내용은 AWS 기반 구축 도구를 참조하세요.

참고

현재, 데이터 API는 범용 고유 식별자(UUID) 배열을 지원하지 않습니다.

데이터 API는 SQL 문을 수행하는 다음 작업을 제공합니다.

데이터 API 작업	AWS CLI 명령	설명
`ExecuteStatement`	`aws rds-data execute-statement`	데이터베이스에서 SQL 문을 실행합니다.
`BatchExecuteStatement`	`aws rds-data batch-execute-statement`	대량 업데이트 및 삽입 작업을 위해 데이터 배열을 통해 일괄 SQL 문을 실행합니다. 파라미터 집합 배열을 사용하여 데이터 조작 언어(DML) 문을 실행할 수 있습니다. 일괄 SQL 문은 개별 삽입 및 업데이트 문을 통해 중요한 성능 개선을 제공합니다.

두 작업 중 하나를 사용하여 개별 SQL 문을 실행하거나 트랜잭션을 실행할 수 있습니다. 트랜잭션의 경우 데이터 API는 다음과 같은 작업을 제공합니다.

데이터 API 작업	AWS CLI 명령	설명
`BeginTransaction`	`aws rds-data begin-transaction`	SQL 트랜잭션을 시작합니다.
`CommitTransaction`	`aws rds-data commit-transaction`	SQL 트랜잭션을 종료하고 변경을 수행합니다.
`RollbackTransaction`	`aws rds-data rollback-transaction`	트랜잭션의 롤백을 수행합니다.

SQL 문을 수행하고 트랜잭션을 지원하기 위한 작업에는 다음과 같은 일반적인 데이터 API 파라미터와 AWS CLI 옵션이 있습니다. 일부 작업은 다른 파라미터 또는 옵션을 지원합니다.

데이터 API 작업 파라미터	AWS CLI 명령 옵션	필수	설명
`resourceArn`	`--resource-arn`	예	Aurora DB 클러스터의 Amazon 리소스 이름(ARN)입니다.
`secretArn`	`--secret-arn`	예	DB 클러스터에 대한 액세스를 활성화하는 보안 암호의 이름 또는 ARN.

ExecuteStatement 및 BatchExecuteStatement에 대한 데이터 API 호출에서, 그리고 AWS CLI 명령 execute-statement 및 batch-execute-statement 실행 시 파라미터를 사용할 수 있습니다. 파라미터를 사용하려면 SqlParameter 데이터 형식에 이름-값 페어를 지정합니다. Field 데이터 형식으로 값을 지정하십시오. 다음 표는 JDBC(Java Database Connectivity) 데이터 형식을 Data API 호출에서 지정하는 데이터 형식에 매핑합니다.

JDBC 데이터 형식	데이터 API 데이터 형식
`INTEGER, TINYINT, SMALLINT, BIGINT`	`LONG` – , 또는 `STRING`
`FLOAT, REAL, DOUBLE`	`DOUBLE`
`DECIMAL`	`STRING`
`BOOLEAN, BIT`	`BOOLEAN`
`BLOB, BINARY, LONGVARBINARY, VARBINARY`	`BLOB`
`CLOB`	`STRING`
다른 형식(날짜 및 시간과 관련된 형식 포함)	`STRING`

참고

데이터베이스에서 반환된 LONG 값에 대한 Data API 호출에서 STRING 또는 LONG 데이터 형식을 지정할 수 있습니다. JavaScript로 작업할 때 발생할 수 있는 매우 큰 수의 정밀도를 잃지 않도록 하는 것이 좋습니다.

DECIMAL 및 TIME 등 특정 유형에는 데이터 API가 String 값을 데이터베이스에 올바른 유형으로 전달할 수 있도록 힌트가 필요합니다. 힌트를 사용하려면 typeHint에 대한 값을 SqlParameter 데이터 형식에 포함합니다. typeHint에 가능한 값은 다음과 같습니다.

DATE – 해당되는 String 파라미터 값은 DATE 유형의 객체로 데이터베이스에 전송됩니다. 승인된 형식은 YYYY-MM-DD입니다.
DECIMAL – 해당되는 String 파라미터 값은 DECIMAL 유형의 객체로 데이터베이스에 전송됩니다.
JSON – 해당되는 String 파라미터 값은 JSON 유형의 객체로 데이터베이스에 전송됩니다.
TIME – 해당되는 String 파라미터 값은 TIME 유형의 객체로 데이터베이스에 전송됩니다. 승인된 형식은 HH:MM:SS[.FFF]입니다.
TIMESTAMP – 해당되는 String 파라미터 값은 TIMESTAMP 유형의 객체로 데이터베이스에 전송됩니다. 승인된 형식은 YYYY-MM-DD HH:MM:SS[.FFF]입니다.
UUID – 해당되는 String 파라미터 값은 UUID 유형의 객체로 데이터베이스에 전송됩니다.

참고

Amazon Aurora PostgreSQL의 경우 데이터 API는 항상 UTC 시간대로 Aurora PostgreSQL 데이터 형식 TIMESTAMPTZ를 반환합니다.

AWS CLI를 사용하여 RDS 데이터 API 호출

AWS CLI를 사용하여 RDS 데이터 API(데이터 API)를 호출할 수 있습니다.

다음 예제에서는 데이터 API용 AWS CLI를 사용합니다. 자세한 내용은 AWS CLI Data API 참조를 참조하세요.

각 예에서 DB 클러스터의 Amazon 리소스 이름(ARN)을 Aurora DB 클러스터의 ARN으로 바꿉니다. 또한 DB 클러스터에 대한 액세스를 허용하는 Secrets Manager의 보안 암호의 ARN으로 보안 암호 ARN을 바꿉니다.

참고

AWS CLI는 응답을 JSON 형식으로 지정할 수 있습니다.

주제

SQL 트랜잭션 시작
SQL 문 실행
데이터 배열에서 일괄 SQL 문 실행
SQL 트랜잭션 커밋
SQL 트랜잭션 롤백

SQL 트랜잭션 시작

aws rds-data begin-transaction CLI 명령을 사용하여 SQL 트랜잭션을 시작할 수 있습니다. 이 호출은 트랜잭션 식별자를 반환합니다.

중요

3분 안에 트랜잭션 ID를 사용하는 호출이 없는 경우 트랜잭션 시간이 초과됩니다. 커밋되기 전에 트랜잭션 시간이 초과되면 자동으로 롤백됩니다.

트랜잭션 내의 데이터 정의 언어(DDL) 문은 암시적 커밋을 발생시킵니다. execute-statement 옵션과 함께 별도의 --continue-after-timeout 명령으로 각 DDL 문을 실행하는 것이 좋습니다.

일반 옵션 외에도, 데이터베이스 이름을 제공하는 --database 옵션을 지정합니다.

예를 들어, 다음 CLI 명령은 SQL 트랜잭션을 시작합니다.

Linux, macOS, Unix:


aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

Windows의 경우:


aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

다음은 이 응답의 예입니다.


{
    "transactionId": "ABC1234567890xyz"
}

SQL 문 실행

aws rds-data execute-statement CLI 명령을 사용하여 SQL 문을 실행할 수 있습니다.

--transaction-id 옵션으로 트랜잭션 식별자를 지정하여 트랜잭션에서 SQL 문을 실행할 수 있습니다. aws rds-data begin-transaction CLI 명령을 사용하여 트랜잭션을 시작할 수 있습니다. aws rds-data commit-transaction CLI 명령을 사용하여 트랜잭션을 끝내고 커밋할 수 있습니다.

중요

--transaction-id 옵션을 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.

일반 옵션 외에도 다음 옵션을 지정하십시오.

--sql (필수) – DB 클러스터에서 실행할 SQL 문.
--transaction-id (선택 사항) – begin-transaction CLI 명령을 사용하여 시작된 트랜잭션의 식별자. SQL 문을 포함할 트랜잭션의 트랜잭션 ID를 지정하십시오.
--parameters (선택 사항) – SQL 문의 파라미터.
--include-result-metadata | --no-include-result-metadata (선택 사항) – 메타데이터를 결과에 포함할지 나타내는 값. 기본값은 --no-include-result-metadata입니다.
--database (선택 사항) – 데이터베이스 이름.

이전 요청에서 --sql "use database_name;"를 실행한 후 SQL 문을 실행하면 --database 옵션이 작동하지 않을 수 있습니다. --sql "use database_name;" 문을 실행하는 대신 --database 옵션을 사용하는 것이 좋습니다.
--continue-after-timeout | --no-continue-after-timeout (선택 사항) – 호출 시간이 초과된 후에 문을 계속 실행할지 나타내는 값. 기본값은 --no-continue-after-timeout입니다.

데이터 정의 언어(DDL) 문에 대해서는 오류 및 데이터 구조 손상 가능성을 피하기 위해 호출 시간이 초과된 후 문을 계속 실행하는 것이 좋습니다.
--format-records-as "JSON"|"NONE" - 결과 집합의 형식을 JSON 문자열로 지정할지를 결정하는 선택적 값입니다. 기본값은 "NONE"입니다. JSON 결과 집합 처리에 대한 사용 정보는 JSON 형식의 쿼리 결과 처리 섹션을 참조하세요.

DB 클러스터는 각 호출에 대한 응답을 반환합니다.

참고

응답 크기 제한은 1MiB입니다. 호출이 1MiB를 초과하는 응답 데이터를 반환하면 호출이 종료됩니다.

Aurora Serverless v1의 경우 초당 최대 요청 수는 1,000개입니다. 지원되는 다른 모든 데이터베이스의 경우 제한이 없습니다.

예를 들어, 다음 CLI 명령은 단일 SQL 문을 실행하고 결과에서 메타데이터를 생략합니다(기본값).

Linux, macOS, Unix:


aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"

Windows의 경우:


aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"

다음은 이 응답의 예입니다.


{
    "numberOfRecordsUpdated": 0,
    "records": [
        [
            {
                "longValue": 1
            },
            {
                "stringValue": "ValueOne"
            }
        ],
        [
            {
                "longValue": 2
            },
            {
                "stringValue": "ValueTwo"
            }
        ],
        [
            {
                "longValue": 3
            },
            {
                "stringValue": "ValueThree"
            }
        ]
    ]
}

다음 CLI 명령은 --transaction-id 옵션을 지정하여 트랜잭션에서 단일 SQL 문을 실행합니다.

Linux, macOS, Unix:


aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

Windows의 경우:


aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

다음은 이 응답의 예입니다.


{
    "numberOfRecordsUpdated": 1
}

다음 CLI 명령은 파라미터가 있는 단일 SQL 문을 실행합니다.

Linux, macOS, Unix:


aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

Windows의 경우:


aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

다음은 이 응답의 예입니다.


{
    "numberOfRecordsUpdated": 1
}

다음 CLI 명령은 데이터 정의 언어(DDL) SQL 문을 실행합니다. DDL 문은 job 열을 role 열로 이름을 바꿉니다.

중요

DDL 문에 대해서는 호출 시간이 초과된 후에도 문을 계속 실행하는 것이 좋습니다. DDL 문 실행이 끝나기 전에 종료되면 오류가 발생하고 데이터 구조가 손상될 수 있습니다. 호출 시간이 초과된 후 문을 계속 실행하려면 --continue-after-timeout 옵션을 지정하십시오.

Linux, macOS, Unix:


aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

Windows의 경우:


aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

다음은 이 응답의 예입니다.


{
    "generatedFields": [],
    "numberOfRecordsUpdated": 0
}

참고

generatedFields 데이터는 Aurora PostgreSQL에서 지원하지 않습니다. 생성된 필드의 값을 가져오려면 RETURNING 절을 사용하십시오. 자세한 내용은 PostgreSQL 설명서의 수정된 행에서 데이터 반환 단원을 참조하십시오.

데이터 배열에서 일괄 SQL 문 실행

aws rds-data batch-execute-statement CLI 명령을 사용하여 데이터 배열에 대해 일괄 SQL 문을 실행할 수 있습니다. 이 명령을 사용하여 일괄 가져오기 또는 업데이트 작업을 수행할 수 있습니다.

중요

--transaction-id 옵션을 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.

일반 옵션 외에도 다음 옵션을 지정하십시오.

--sql (필수) – DB 클러스터에서 실행할 SQL 문.

작은 정보
MySQL 호환 문의 경우 --sql 파라미터 끝에 세미콜론을 포함하지 마세요. 후행 세미콜론을 사용하면 구문 오류가 발생할 수 있습니다.
--transaction-id (선택 사항) – begin-transaction CLI 명령을 사용하여 시작된 트랜잭션의 식별자. SQL 문을 포함할 트랜잭션의 트랜잭션 ID를 지정하십시오.
--parameter-set (선택 사항) – 일괄 처리를 위한 파라미터 집합.
--database (선택 사항) – 데이터베이스 이름.

DB 클러스터는 호출에 대한 응답을 반환합니다.

참고

파라미터 세트 수는 상한이 정해져 있지 않습니다. 그러나 데이터 API를 통해 전송된 HTTP 요청의 최대 크기는 4MiB입니다. 요청이 이 제한을 초과하면 데이터 API가 오류를 반환하고 요청을 처리하지 않습니다. 이 4MiB 제한에는 요청의 HTTP 헤더와 JSON 표기법의 크기가 포함됩니다. 따라서 포함할 수 있는 파라미터 세트의 수는 SQL 문의 크기 및 각 파라미터 세트의 크기와 같은 요인의 조합에 따라 달라집니다.

응답 크기 제한은 1MiB입니다. 호출이 1MiB를 초과하는 응답 데이터를 반환하면 호출이 종료됩니다.

Aurora Serverless v1의 경우 초당 최대 요청 수는 1,000개입니다. 지원되는 다른 모든 데이터베이스의 경우 제한이 없습니다.

예를 들어, 다음 CLI 명령은 파라미터 세트를 이용해 데이터 배열에 대해 배치 SQL 문을 실행합니다.

Linux, macOS, Unix:


aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" \
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"

Windows의 경우:


aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" ^
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"

참고

--parameter-sets 옵션에 줄바꿈을 포함하지 마십시오.

SQL 트랜잭션 커밋

aws rds-data commit-transaction CLI 명령을 사용하여 aws rds-data begin-transaction으로 시작한 SQL 트랜잭션을 종료하고 변경 사항을 커밋할 수 있습니다.

일반 옵션 외에 다음 옵션을 지정하십시오.

--transaction-id (필수) – begin-transaction CLI 명령을 사용하여 시작된 트랜잭션의 식별자. 종료하고 커밋할 트랜잭션의 트랜잭션 ID를 지정하십시오.

예를 들어 다음 CLI 명령은 SQL 트랜잭션을 끝내고 변경 내용을 커밋합니다.

Linux, macOS, Unix:


aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

Windows의 경우:


aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

다음은 이 응답의 예입니다.


{
    "transactionStatus": "Transaction Committed"
}

SQL 트랜잭션 롤백

aws rds-data rollback-transaction CLI 명령을 사용하여 aws rds-data begin-transaction으로 시작한 SQL 트랜잭션을 롤백할 수 있습니다. 트랜잭션을 롤백하면 변경 내용이 취소됩니다.

중요

트랜잭션 ID가 만기되었다면 트랜잭션이 자동으로 롤백된 것입니다. 이 경우 만기된 트랜잭션 ID를 지정하는 aws rds-data rollback-transaction 명령이 오류를 반환합니다.

일반 옵션 외에 다음 옵션을 지정하십시오.

--transaction-id (필수) – begin-transaction CLI 명령을 사용하여 시작된 트랜잭션의 식별자. 롤백하려는 트랜잭션의 트랜잭션 ID를 지정하십시오.

예를 들어 다음 AWS CLI 명령은 SQL 트랜잭션을 롤백합니다.

Linux, macOS, Unix:


aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

Windows의 경우:


aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

다음은 이 응답의 예입니다.


{
    "transactionStatus": "Rollback Complete"
    }

Python 애플리케이션에서 RDS 데이터 API 호출

Python 애플리케이션에서 RDS 데이터 API(데이터 API)를 호출할 수 있습니다.

다음 예제에서는 AWS SDK for Python(Boto)을 사용합니다. Boto에 대한 자세한 내용은 AWS SDK for Python(Boto 3) 설명서를 참조하세요.

주제

SQL 쿼리 실행
DML SQL 문 실행
SQL 트랜잭션 실행

SQL 쿼리 실행

SELECT 문을 실행하고 Python 애플리케이션으로 결과를 가져올 수 있습니다.

다음 예는 SQL 쿼리를 실행합니다.


import boto3

rdsData = boto3.client('rds-data')

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

response1 = rdsData.execute_statement(
            resourceArn = cluster_arn,
            secretArn = secret_arn,
            database = 'mydb',
            sql = 'select * from employees limit 3')

print (response1['records'])
[
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'ROSALEZ'
        },
        {
            'stringValue': 'ALEJANDRO'
        },
        {
            'stringValue': '2016-02-15 04:34:33.0'
        }
    ],
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'DOE'
        },
        {
            'stringValue': 'JANE'
        },
        {
            'stringValue': '2014-05-09 04:34:33.0'
        }
    ],
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'STILES'
        },
        {
            'stringValue': 'JOHN'
        },
        {
            'stringValue': '2017-09-20 04:34:33.0'
        }
    ]
]

DML SQL 문 실행

데이터 조작 언어(DML) 문을 실행하여 데이터베이스의 데이터를 삽입, 업데이트 또는 삭제할 수 있습니다. DML 문에 파라미터를 사용할 수도 있습니다.

중요

호출이 transactionID 파라미터를 포함하지 않아서 트랜잭션의 일부가 아닌 경우 호출 결과는 자동으로 커밋됩니다.

다음 예제는 insert SQL 문을 실행하고 파라미터를 사용합니다.


import boto3

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

rdsData = boto3.client('rds-data')


param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO'}}
paramSet = [param1, param2]

response2 = rdsData.execute_statement(resourceArn=cluster_arn,
                                      secretArn=secret_arn,
                                      database='mydb',
                                      sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)',
                                      parameters = paramSet)

print (response2["numberOfRecordsUpdated"])

SQL 트랜잭션 실행

SQL 트랜잭션을 시작하고 하나 이상의 SQL 문을 실행한 다음, 변경 사항을 Python 애플리케이션으로 커밋할 수 있습니다.

중요

3분 안에 트랜잭션 ID를 사용하는 호출이 없는 경우 트랜잭션 시간이 초과됩니다. 커밋되기 전에 트랜잭션 시간이 초과되면 자동으로 롤백됩니다.

트랜잭션 ID를 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.

다음 예에서는 테이블에 행을 삽입하는 SQL 트랜잭션을 실행합니다.


import boto3

rdsData = boto3.client('rds-data')

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

tr = rdsData.begin_transaction(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     database = 'mydb')

response3 = rdsData.execute_statement(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     database = 'mydb',
     sql = 'insert into employees(first_name, last_name) values('XIULAN', 'WANG')',
     transactionId = tr['transactionId'])

cr = rdsData.commit_transaction(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     transactionId = tr['transactionId'])

cr['transactionStatus']
'Transaction Committed'

response3['numberOfRecordsUpdated']
1

참고

데이터 정의 언어(DDL) 문을 실행하는 경우 호출 시간이 초과된 후에도 문을 계속 실행하는 것이 좋습니다. DDL 문 실행이 끝나기 전에 종료되면 오류가 발생하고 데이터 구조가 손상될 수 있습니다. 호출 시간이 초과된 후 문을 계속 실행하려면 continueAfterTimeout 파라미터를 true로 설정하십시오.

Java 애플리케이션에서 RDS 데이터 API 호출

Java 애플리케이션에서 RDS 데이터 API(데이터 API)를 호출할 수 있습니다.

다음 예제는 AWS SDK for Java를 사용합니다. 자세한 내용은 AWS SDK for Java 개발자 안내서를 참조하십시오.

주제

SQL 쿼리 실행
SQL 트랜잭션 실행
일괄 SQL 작업 실행

SQL 쿼리 실행

SELECT 문을 실행하고 Java 애플리케이션으로 결과를 가져올 수 있습니다.

다음 예는 SQL 쿼리를 실행합니다.


package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;

import java.util.List;

public class FetchResultsExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
    AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    ExecuteStatementRequest request = new ExecuteStatementRequest()
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withDatabase("mydb")
            .withSql("select * from mytable");

    ExecuteStatementResult result = rdsData.executeStatement(request);

    for (List<Field> fields: result.getRecords()) {
      String stringValue = fields.get(0).getStringValue();
      long numberValue = fields.get(1).getLongValue();

      System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
    }
  }
}

SQL 트랜잭션 실행

SQL 트랜잭션을 시작하고 하나 이상의 SQL 문을 실행한 다음, 변경 사항을 Java 애플리케이션으로 커밋할 수 있습니다.

중요

3분 안에 트랜잭션 ID를 사용하는 호출이 없는 경우 트랜잭션 시간이 초과됩니다. 커밋되기 전에 트랜잭션 시간이 초과되면 자동으로 롤백됩니다.

트랜잭션 ID를 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.

다음 예는 SQL 트랜잭션을 실행합니다.


package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BeginTransactionRequest;
import com.amazonaws.services.rdsdata.model.BeginTransactionResult;
import com.amazonaws.services.rdsdata.model.CommitTransactionRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;

public class TransactionExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
    AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    BeginTransactionRequest beginTransactionRequest = new BeginTransactionRequest()
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withDatabase("mydb");
    BeginTransactionResult beginTransactionResult = rdsData.beginTransaction(beginTransactionRequest);
    String transactionId = beginTransactionResult.getTransactionId();

    ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest()
            .withTransactionId(transactionId)
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withSql("INSERT INTO test_table VALUES ('hello world!')");
    rdsData.executeStatement(executeStatementRequest);

    CommitTransactionRequest commitTransactionRequest = new CommitTransactionRequest()
            .withTransactionId(transactionId)
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN);
    rdsData.commitTransaction(commitTransactionRequest);
  }
}

참고

일괄 SQL 작업 실행

Java 애플리케이션을 사용하여 데이터 배열에 대해 대량 삽입 및 업데이트 작업을 실행할 수 있습니다. 파라미터 세트의 배열을 사용하여 DML 문을 실행할 수 있습니다.

중요

트랜잭션 ID를 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.

다음 예제에서는 대량 삽입 작업을 실행합니다.


package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;

import java.util.Arrays;

public class BatchExecuteExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
      AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
            .withDatabase("test")
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withSql("INSERT INTO test_table2 VALUES (:string, :number)")
            .withParameterSets(Arrays.asList(
                    Arrays.asList(
                            new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
                            new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
                    ),
                    Arrays.asList(
                            new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
                            new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
                    )
            ));

    rdsData.batchExecuteStatement(request);
  }
}

RDS 데이터 API용 Java 클라이언트 라이브러리 사용

RDS 데이터 API(데이터 API)용 Java 클라이언트 라이브러리를 다운로드하여 사용할 수 있습니다. 이 Java 클라이언트 라이브러리는 데이터 API를 사용할 수 있는 다른 방법을 제공합니다. 이 라이브러리를 사용하면 클라이언트 측 클래스를 데이터 API 요청 및 응답에 매핑할 수 있습니다. 이러한 매핑 지원을 통해 Date, Time, BigDecimal 등 일부 특정 Java 유형과 쉽게 통합할 수 있습니다.

데이터 API용 Java 클라이언트 라이브러리 다운로드

Data API Java 클라이언트 라이브러리는 다음 위치의 GitHub에서 오픈 소스로 제공됩니다.

https://github.com/awslabs/rds-data-api-client-library-java

소스 파일에서 라이브러리를 수동으로 빌드할 수 있지만 모범 사례는 Apache Maven 종속성 관리를 사용해 라이브러리를 사용하는 것입니다. Maven POM 파일에 다음 종속성을 추가하세요.

AWS SDK 2.x와 호환되는 버전 2.x의 경우 다음을 사용하세요.


<dependency>
   <groupId>software.amazon.rdsdata</groupId>
   <artifactId>rds-data-api-client-library-java</artifactId>
   <version>2.0.0</version>
</dependency>

AWS SDK 1.x와 호환되는 버전 1.x의 경우 다음을 사용하세요.


<dependency>
    <groupId>software.amazon.rdsdata</groupId>
    <artifactId>rds-data-api-client-library-java</artifactId>
    <version>1.0.8</version>
</dependency>

Java 클라이언트 라이브러리 예시

아래에는 데이터 API Java 클라이언트 라이브러리 사용에 관한 몇 가지 일반적인 예시가 나와 있습니다. 이 예시에서는 accounts와 accountId이라는 두 개의 열이 있는 name라는 테이블이 있다고 가정합니다. 또한 다음과 같은 데이터 전송 객체(DTO)도 있습니다.


public class Account {
    int accountId;
    String name;
    // getters and setters omitted
}

클라이언트 라이브러리를 통해 DTO를 입력 파라미터로 전달할 수 있습니다. 다음 예시에서는 고객 DTO가 입력 파라미터 세트로 매핑되는 방식을 보여줍니다.


var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParamSets(account1, account2)
         .execute();

어떤 경우에는 입력 파라미터인 간단한 값으로 작업하는 것이 더 쉽습니다. 다음 구문을 사용하면 이러한 작업이 가능합니다.


client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParameter("accountId", 3)
         .withParameter("name", "Zhang")
         .execute();

다음은 입력 파라미터인 간단한 값으로 작업하는 또 다른 예시입니다.



client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
         .execute();

클라이언트 라이브러리에서는 결과가 반환될 때 DTO에 대한 자동 매핑을 제공합니다. 다음 예시에서는 결과가 DTO에 매핑되는 방식을 보여줍니다.


List<Account> result = client.forSql("SELECT * FROM accounts")
          .execute()
          .mapToList(Account.class);

Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
          .execute()
          .mapToSingle(Account.class);

대부분의 경우 데이터베이스 결과 집합에는 단일 값만 포함됩니다. 이러한 결과 검색을 단순화하기 위해 클라이언트 라이브러리는 다음 API를 제공합니다.


int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
          .execute()
          .singleValue(Integer.class);

참고

mapToList 함수는 SQL 결과 집합을 사용자 정의 객체 목록으로 변환합니다. Java 클라이언트 라이브러리에 대한 ExecuteStatement 호출에 이 .withFormatRecordsAs(RecordsFormatType.JSON) 문을 사용할 수 없습니다. 동일한 용도로 사용되기 때문입니다. 자세한 내용은 JSON 형식의 쿼리 결과 처리 섹션을 참조하세요.

JSON 형식의 쿼리 결과 처리

ExecuteStatement 작업을 호출할 때 쿼리 결과를 JSON 형식의 문자열로 반환하도록 선택할 수 있습니다. 이렇게 하면 프로그래밍 언어의 JSON 구문 분석 기능을 사용하여 결과 집합을 해석하고 형식을 다시 지정할 수 있습니다. 그러면 결과 집합을 반복하고 각 열 값을 해석하는 추가 코드를 작성하지 않아도 됩니다.

결과 집합을 JSON 형식으로 요청하려면 선택적으로 formatRecordsAs 파라미터를 JSON 값과 함께 전달합니다. JSON 형식의 결과 집합이 ExecuteStatementResponse 구조의 formattedRecords 필드에 반환됩니다.

BatchExecuteStatement 작업은 결과 집합을 반환하지 않습니다. 따라서 JSON 옵션은 해당 작업에 적용되지 않습니다.

JSON 해시 구조에서 키를 사용자 정의하려면 결과 집합에서 열 별칭을 정의합니다. SQL 쿼리의 열 목록에 있는 AS 절을 사용하면 됩니다.

JSON 기능을 사용하여 결과 집합을 더 쉽게 읽도록 하고 내용을 언어별 프레임워크에 매핑할 수 있습니다. ASCII로 인코딩된 결과 집합의 볼륨이 기본 표현보다 크기 때문에 많은 수의 행이나 큰 열 값을 반환하여 애플리케이션에서 사용할 수 있는 것보다 많은 메모리를 사용하는 쿼리에 기본 표현을 선택할 수 있습니다.

주제

JSON 형식의 쿼리 결과 검색
데이터 유형 매핑
문제 해결
예제

JSON 형식의 쿼리 결과 검색

결과 집합을 JSON 문자열로 수신하려면 ExecuteStatement 호출에 .withFormatRecordsAs(RecordsFormatType.JSON)을 포함하세요. 반환 값은 formattedRecords 필드에 JSON 문자열로 반환됩니다. 이 경우 columnMetadata는 null입니다. 열 레이블은 각 행을 나타내는 객체의 키입니다. 이 열 이름은 결과 집합의 각 행에서 반복됩니다. 열 값은 따옴표로 묶인 문자열, 숫자 값 또는 true, false 또는 null을 나타내는 특수 값입니다. 길이 제약 조건 및 숫자 및 문자열의 정확한 유형과 같은 열 메타데이터는 JSON 응답에 보존되지 않습니다.

.withFormatRecordsAs() 호출을 생략하거나 NONE의 파라미터를 지정하는 경우 결과 집합은 Records 및 columnMetadata 필드를 사용하여 이진 형식으로 반환됩니다.

데이터 유형 매핑

결과 집합의 SQL 값은 더 작은 JSON 유형 집합에 매핑됩니다. 값은 JSON에서 문자열, 숫자 및 true, false 및 null과 같은 특수 상수로 표시됩니다. 프로그래밍 언어에 적합하도록 강한 타이핑 또는 약한 타이핑을 사용하여 이 값을 애플리케이션에서 변수로 변환할 수 있습니다.

JDBC 데이터 유형	JSON 데이터 유형
`INTEGER`, `TINYINT`, `SMALLINT`, `BIGINT`	기본적으로 숫자입니다. `LongReturnType` 옵션이 `STRING`으로 설정되어 있으면 문자열입니다.
`FLOAT`, `REAL`, `DOUBLE`	숫자
`DECIMAL`	기본적으로 문자열입니다. `DecimalReturnType` 옵션이 `DOUBLE_OR_LONG`으로 설정되어 있으면 숫자입니다.
`STRING`	문자열
`BOOLEAN`, `BIT`	부울
`BLOB`, `BINARY`, `VARBINARY`, `LONGVARBINARY`	base64 인코딩의 문자열입니다.
`CLOB`	String
`ARRAY`	배열
`NULL`	`null`
다른 형식(날짜 및 시간과 관련된 형식 포함)	String

문제 해결

JSON 응답은 10MB로 제한됩니다. 응답이 이 한도보다 크면 프로그램에서 BadRequestException 오류를 받습니다. 이런 경우 다음 기법 중 하나를 사용하여 오류를 해결할 수 있습니다.

결과 집합에서 행의 수를 줄입니다. LIMIT 절을 추가하면 됩니다. LIMIT 및 OFFSET 절이 있는 여러 쿼리를 제출하여 큰 결과 집합을 여러 개의 작은 결과 집합으로 나눌 수 있습니다.

결과 집합에 애플리케이션 로직별로 필터링된 행이 포함되어 있는 경우 WHERE 절에 조건을 더 추가하여 결과 집합에서 해당 행을 제거할 수 있습니다.
결과 집합에서 열의 수를 줄입니다. 쿼리의 선택 목록에서 항목을 제거하면 됩니다.
쿼리에서 열 별칭을 사용하여 열 레이블을 줄입니다. 각 열 이름은 결과 집합의 각 행에 대한 JSON 문자열에서 반복됩니다. 따라서 열 이름이 길고 행이 많은 쿼리 결과는 크기 제한을 초과할 수 있습니다. 특히 복잡한 표현식에 열 별칭을 사용하면 JSON 문자열에서 전체 표현식이 반복되는 것을 방지할 수 있습니다.
SQL을 사용하면 열 별칭을 사용하여 동일한 이름의 열이 두 개 이상 있는 결과 집합을 생성할 수 있지만 JSON에서는 중복 키 이름이 허용되지 않습니다. 결과 집합을 JSON 형식으로 요청하고 둘 이상의 열의 이름이 같은 경우 RDS Data API에서 오류를 반환합니다. 따라서 모든 열 레이블의 이름이 고유하도록 해야 합니다.

예제

다음 Java 예제는 응답이 JSON 형식의 문자열인 ExecuteStatement를 호출한 후 결과 집합을 해석하는 방법을 보여줍니다. databaseName, secretStoreArn 및 clusterArn 파라미터를 적절한 값으로 대체합니다.

다음 Java 예제에서는 결과 집합에서 소수 값을 반환하는 쿼리를 보여줍니다. assertThat 호출은 응답 필드에 JSON 결과 집합에 대한 규칙을 기반으로 예상되는 속성이 있는지 테스트합니다.

이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.


create table test_simplified_json (a float);
insert into test_simplified_json values(10.0);


public void JSON_result_set_demo() {
    var sql = "select * from test_simplified_json";
    var request = new ExecuteStatementRequest()
      .withDatabase(databaseName)
      .withSecretArn(secretStoreArn)
      .withResourceArn(clusterArn)
      .withSql(sql)
      .withFormatRecordsAs(RecordsFormatType.JSON);
    var result = rdsdataClient.executeStatement(request);
}

이전 프로그램의 formattedRecords 필드 값은 다음과 같습니다.


[{"a":10.0}]

JSON 결과 집합이 있기 때문에 응답의 Records 및 ColumnMetadata 필드는 모두 Null입니다.

다음 Java 예제에서는 결과 집합에서 정수 값을 반환하는 쿼리를 보여줍니다. 예제는 getFormattedRecords를 호출하여 JSON 형식의 문자열만 반환하고 비어 있거나 Null인 다른 응답 필드는 무시합니다. 이 예제에서는 결과를 레코드 목록을 나타내는 구조로 역직렬화합니다. 각 레코드에는 이름이 결과 집합의 열 별칭에 해당하는 필드가 있습니다. 이 기법은 결과 집합을 구문 분석하는 코드를 단순화합니다. 애플리케이션에서 결과 집합의 행과 열을 반복하여 각 값을 적절한 유형으로 변환할 필요가 없습니다.

이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.


create table test_simplified_json (a int);
insert into test_simplified_json values(17);


public void JSON_deserialization_demo() {
    var sql = "select * from test_simplified_json";
    var request = new ExecuteStatementRequest()
      .withDatabase(databaseName)
      .withSecretArn(secretStoreArn)
      .withResourceArn(clusterArn)
      .withSql(sql)
      .withFormatRecordsAs(RecordsFormatType.JSON);
    var result = rdsdataClient.executeStatement(request)
      .getFormattedRecords();

/* Turn the result set into a Java object, a list of records.
   Each record has a field 'a' corresponding to the column
   labelled 'a' in the result set. */
    private static class Record { public int a; }
    var recordsList = new ObjectMapper().readValue(
        response, new TypeReference<List<Record>>() {
        });
}

이전 프로그램의 formattedRecords 필드 값은 다음과 같습니다.


[{"a":17}]

결과 행 0의 a 열을 검색하려면 애플리케이션은 recordsList.get(0).a를 참조합니다.

반대로 다음 Java 예제에서는 JSON 형식을 사용하지 않을 때 결과 집합을 포함하는 데이터 구조를 구성하는 데 필요한 코드 종류를 보여줍니다. 이 경우 결과 집합의 각 행에는 단일 사용자에 대한 정보가 포함된 필드가 포함됩니다. 결과 집합을 나타내는 데이터 구조를 구축하려면 행을 반복해야 합니다. 각 행에 대해 코드는 각 필드의 값을 검색하고 적절한 형식 변환을 수행하며 행을 나타내는 객체의 해당 필드에 결과를 할당합니다. 그런 다음 코드는 각 사용자를 나타내는 객체를 전체 결과 집합을 나타내는 데이터 구조에 추가합니다. 결과 집합에서 필드를 재정렬, 추가 또는 제거하도록 쿼리가 변경된 경우 애플리케이션 코드도 변경해야 합니다.


/* Verbose result-parsing code that doesn't use the JSON result set format */
for (var row: response.getRecords()) {
    var user = User.builder()
      .userId(row.get(0).getLongValue())
      .firstName(row.get(1).getStringValue())
      .lastName(row.get(2).getStringValue())
      .dob(Instant.parse(row.get(3).getStringValue()))
      .build();
    result.add(user);
  }

다음 샘플 값은 열, 열 별칭 및 열 데이터 유형이 서로 다른 결과 집합에 대한 formattedRecords 필드의 값을 보여줍니다.

결과 집합에 여러 행이 포함된 경우 각 행은 배열 요소인 객체로 표시됩니다. 결과 집합의 각 열은 객체 내에서 키가 됩니다. 키는 결과 집합의 각 행에서 반복됩니다. 따라서 여러 행과 열로 구성된 결과 집합의 경우 전체 응답의 길이 제한을 초과하지 않도록 짧은 열 별칭을 정의해야 할 수 있습니다.

이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.


create table sample_names (id int, name varchar(128));
insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");


[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"},
{"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]

결과 집합의 열이 표현식으로 정의된 경우 표현식의 텍스트가 JSON 키가 됩니다. 따라서 일반적으로 쿼리의 선택 목록에서 각 표현식에 대한 설명 열 별칭을 정의하는 것이 편리합니다. 예를 들어, 다음 쿼리는 선택 목록에 함수 호출 및 산술 연산과 같은 표현식을 포함합니다.


select count(*), max(id), 4+7 from sample_names;

이러한 표현식은 키로 JSON 결과 집합을 통해 전달됩니다.


[{"count(*)":5,"max(id)":4,"4+7":11}]

설명 레이블이 있는 AS 열을 추가하면 JSON 결과 집합에서 키를 보다 간단하게 해석할 수 있습니다.


select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;

수정된 SQL 쿼리의 경우, AS 절에 의해 정의된 열 레이블이 키 이름으로 사용됩니다.


[{"rows":5,"largest_id":4,"addition_result":11}]

JSON 문자열의 각 키 값 쌍의 값은 따옴표로 묶인 문자열일 수 있습니다. 문자열에는 유니코드 문자가 포함될 수 있습니다. 문자열에 이스케이프 시퀀스가 포함되어 있거나 " 또는 \문자가 포함되어 있는 경우 이러한 문자 앞에는 백슬래시 이스케이프 문자가 있습니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다. 예를 들어 string_with_escape_sequences 결과에는 특수 문자 백스페이스, 줄 바꿈, 캐리지 리턴, 탭, 양식 피드 및 \가 포함됩니다.


[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}]

JSON 문자열의 각 키 값 쌍의 값은 숫자를 나타낼 수도 있습니다. 숫자는 정수, 부동 소수점 값, 음수 값 또는 지수 표기법으로 표현되는 값일 수 있습니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다.


[{"integer_value":17}]
[{"float_value":10.0}]
[{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}]
[{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}]

부울 값과 Null 값은 따옴표 없는 특수 키워드 true, false 및 null로 표현됩니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다.


[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}]

BLOB 유형의 값을 선택하면 결과가 JSON 문자열에서 base64로 인코딩된 값으로 표시됩니다. 값을 원래 표현으로 다시 변환하려면 애플리케이션의 언어로 적절한 디코딩 기능을 사용할 수 있습니다. 예를 들어 Java에서는 Base64.getDecoder().decode() 함수를 호출합니다. 다음 샘플 출력은 hello world의 BLOB 값을 선택하고 결과 집합을 JSON 문자열로 반환한 것을 보여줍니다.


[{"blob_column":"aGVsbG8gd29ybGQ="}]

다음 Python 예제는 Python execute_statement 함수에 대한 호출의 결과에서 값에 액세스하는 방법을 보여줍니다. 결과 집합은 필드 response['formattedRecords']의 문자열 값입니다. 이 코드는 json.loads 함수를 호출하여 JSON 문자열을 데이터 구조로 변환합니다. 그러면 결과 집합의 각 행은 데이터 구조 내의 목록 요소이며 각 행 내에서 이름으로 결과 집합의 각 필드를 참조할 수 있습니다.


import json

result = json.loads(response['formattedRecords'])
print (result[0]["id"])

다음 JavaScript 예제는 JavaScript executeStatement 함수에 대한 호출의 결과에서 값에 액세스하는 방법을 보여줍니다. 결과 집합은 필드 response.formattedRecords의 문자열 값입니다. 이 코드는 JSON.parse 함수를 호출하여 JSON 문자열을 데이터 구조로 변환합니다. 그러면 결과 집합의 각 행은 데이터 구조 내의 배열 요소이며 각 행 내에서 이름으로 결과 집합의 각 필드를 참조할 수 있습니다.


<script>
    const result = JSON.parse(response.formattedRecords);
    document.getElementById("display").innerHTML = result[0].id;
</script>

RDS 데이터 API 문제 해결

공통 오류 메시지를 소개하는 다음 섹션부터는 RDS 데이터 API(데이터 API)를 사용하면서 발생하는 문제를 해결하는 데 유용합니다.

주제

트랜잭션 <transaction_ID>을 찾을 수 없습니다
쿼리 패킷이 너무 큽니다
데이터베이스 응답이 크기 제한을 초과했습니다
HttpEndpoint가 클러스터 <cluster_ID>에서 활성화되지 않았습니다

트랜잭션 <transaction_ID>을 찾을 수 없습니다

위 오류 메시지는 데이터 API 호출 시 지정한 트랜잭션 ID를 찾을 수 없다는 것을 의미합니다. 이러한 문제가 발생하는 원인이 오류 메시지에 추가되며, 다음 중 한 가지로 표시됩니다.

트랜잭션이 만료될 수 있습니다.

각 트랜잭션 호출은 지난 호출 이후 3분 이내에 실행되어야 합니다.

지정된 트랜잭션 ID가 BeginTransaction 호출에 의해 생성되지 않았을 수도 있습니다. 호출 시 유효한 트랜잭션 ID를 지정해야 합니다.
하나의 이전 호출로 인해 트랜잭션이 종료되었습니다.

CommitTransaction 또는 RollbackTransaction 호출에 의해 트랜잭션이 이미 종료되었습니다.
이전 호출의 오류로 인해 트랜잭션이 중단되었습니다.

이전 호출에서 예외가 발생했는지 확인합니다.

트랜잭션 실행에 대한 자세한 내용은 RDS 데이터 API 호출 단원을 참조하세요.

쿼리 패킷이 너무 큽니다

위 오류 메시지는 행마다 반환되는 결과 집합이 너무 크다는 것을 의미합니다. 데이터 API는 데이터베이스에서 반환되는 결과 집합에서 각 행의 크기를 64KB로 제한합니다.

이 문제를 해결하려면 결과 집합의 각 행마다 크기를 64KB 이하로 유지해야 합니다.

데이터베이스 응답이 크기 제한을 초과했습니다

위 오류 메시지는 데이터베이스에서 반환되는 결과 집합의 크기가 너무 크다는 것을 의미합니다. Data API는 데이터베이스에서 반환되는 결과 집합의 크기를 1MiB로 제한합니다.

이러한 문제를 해결하려면 데이터 API 호출 시 반환되는 데이터 크기를 1MiB 이하로 유지해야 합니다. 반환해야 하는 결과 집합의 크기가 1MiB보다 크면 쿼리에서 다수의 ExecuteStatement 호출을 LIMIT 절과 함께 사용할 수 있습니다.

LIMIT 절에 대한 자세한 내용은 MySQL 설명서에서 SELECT 구문을 참조하세요.

HttpEndpoint가 클러스터 <cluster_ID>에서 활성화되지 않았습니다

이 문제의 잠재적인 원인은 다음과 같습니다.

Aurora DB 클러스터는 데이터 API를 지원하지 않습니다. 예를 들어, Aurora MySQL의 경우 데이터 API는 Aurora Serverless v1에서만 사용할 수 있습니다. RDS 데이터 API가 지원하는 DB 클러스터 유형에 대한 자세한 내용은 리전 및 버전 사용 가능 여부 섹션을 참조하세요.
Aurora DB 클러스터에서 데이터 API가 활성화되어 있지 않습니다. Aurora DB 클러스터에서 데이터 API를 사용하려면 DB 클러스터에서 데이터 API를 먼저 활성화해야 합니다. 데이터 API 활성화에 대한 자세한 내용은 RDS 데이터 API 활성화 섹션을 참조하세요.
데이터 API가 활성화된 후 DB 클러스터의 이름이 바뀌었습니다. 이 경우 해당 클러스터에 대한 데이터 API를 끄고 다시 활성화하세요.
지정한 ARN이 클러스터의 ARN과 정확하게 일치하지 않습니다. 다른 소스에서 반환되었거나 프로그램 논리로 구성된 ARN이 클러스터의 ARN과 정확히 일치하는지 확인합니다. 예를 들어 사용하는 ARN에서 모든 영문자의 대소문자가 올바른지 확인하세요.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

Aurora Serverless v1 및 Aurora 데이터베이스 엔진 버전

AWS CloudTrail을 사용하여 RDS 데이터 API 호출 로깅

RDS 데이터 API 사용

주제

리전 및 버전 사용 가능 여부

참고

RDS 데이터 API의 제한

Serverless v2 및 프로비저닝과 RDS 데이터 API의 비교 및 Aurora Serverless v1

RDS 데이터 API에 대한 액세스 권한 부여

태그 기반 권한 부여 작업

참고

AWS Secrets Manager에 데이터베이스 자격 증명 저장

보안 암호에 DB 클러스터 자격 증명을 저장하려면

RDS 데이터 API 활성화

참고

주제

데이터베이스를 생성할 때 RDS 데이터 API 활성화

기존 데이터베이스에서 RDS 데이터 API 활성화

주제

데이터 API 활성화 또는 비활성화(Aurora PostgreSQL Serverless v2 및 프로비저닝)

데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)

RDS 데이터 API(AWS PrivateLink)에 대한 Amazon VPC 엔드포인트 생성

데이터 API에 대한 Amazon VPC 엔드포인트를 생성하려면

RDS 데이터 API 호출

참고

참고

참고

AWS CLI를 사용하여 RDS 데이터 API 호출

참고

주제

SQL 트랜잭션 시작

중요

SQL 문 실행

중요

참고

중요

참고

데이터 배열에서 일괄 SQL 문 실행

중요

작은 정보

참고

참고

SQL 트랜잭션 커밋

SQL 트랜잭션 롤백

중요

Python 애플리케이션에서 RDS 데이터 API 호출

주제

SQL 쿼리 실행

DML SQL 문 실행

중요

SQL 트랜잭션 실행

중요

참고

Java 애플리케이션에서 RDS 데이터 API 호출

주제

SQL 쿼리 실행

SQL 트랜잭션 실행

중요

참고

일괄 SQL 작업 실행

중요

RDS 데이터 API용 Java 클라이언트 라이브러리 사용

데이터 API용 Java 클라이언트 라이브러리 다운로드

Java 클라이언트 라이브러리 예시

참고

JSON 형식의 쿼리 결과 처리

주제

JSON 형식의 쿼리 결과 검색

데이터 유형 매핑

문제 해결

예제

RDS 데이터 API 문제 해결

주제

트랜잭션 <transaction_ID>을 찾을 수 없습니다

쿼리 패킷이 너무 큽니다

데이터베이스 응답이 크기 제한을 초과했습니다

HttpEndpoint가 클러스터 <cluster_ID>에서 활성화되지 않았습니다