リージョンとバージョンの可用性制限事項 Serverless v2 およびプロビジョンド、および Aurora Serverless v1 の比較アクセスの承認 RDS Data API の有効化 Amazon VPC エンドポイントの作成 RDS Data API の呼び出し Java クライアントライブラリの使用 JSON 形式で RDS Data API クエリ結果を処理する Data API の問題のトラブルシューティング

RDS Data API の使用

RDS Data API (Data API) を使用すると、Aurora DB クラスターへのウェブサービスインターフェイスを操作できます。Data API は、DB クラスターへの永続的な接続を必要としません。代わりに、セキュア HTTP エンドポイントおよび AWS SDK との統合を利用できます。エンドポイントを使用して、接続を管理せずに SQL ステートメントを実行することができます。

Data API は AWS Secrets Manager に保存されたデータベース認証情報を使用するため、ユーザーは Data API の呼び出しで認証情報を渡す必要はありません。Secrets Manager に認証情報を保存するには、Secrets Manager を使用する適切なアクセス許可に加えて Data API もユーザーに付与されている必要があります。ユーザー承認の詳細については、RDS Data API へのアクセスの承認を参照してください。

Data API を使用して、Amazon Aurora を他の AWS アプリケーション (AWS Lambda、AWS AppSync、および AWS Cloud9 など) と統合することもできます。Data API では、AWS Lambda をより安全に使用することができます。Virtual Private Cloud (VPC) 内のリソースにアクセスするように Lambda 関数を設定しなくても、DB クラスターにアクセスすることができます。詳細については、「AWS Lambda」、「AWS AppSync」、および「AWS Cloud9」を参照してください。

Data API は、Aurora DB クラスターの作成時に有効にできます。後で設定を変更することもできます。詳細については、「RDS Data API の有効化」を参照してください。

Data API を有効にした後、クエリエディタを使用して、VPC 内の Aurora にアクセスするようにクエリツールを設定しなくても、アドホッククエリを実行することもできます。詳細については、「Aurora クエリエディタの使用」を参照してください。

トピック

リージョンとバージョンの可用性
RDS Data API の制限事項
RDS Data API と Serverless v2 およびプロビジョンド、および Aurora Serverless v1 の比較
RDS Data API へのアクセスの承認
RDS Data API の有効化
RDS Data API の Amazon VPC エンドポイント (AWS PrivateLink) の作成
RDS Data API の呼び出し
RDS Data API 用の Java クライアントライブラリの使用
JSON 形式で RDS Data API クエリ結果を処理する
RDS Data API の問題のトラブルシューティング
AWS CloudTrail での RDS Data API コールのログ記録

リージョンとバージョンの可用性

Data 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 を使用する

注記

現在、Data API は、MySQL エンジンを使用するプロビジョンドまたは Aurora Serverless v2 DB クラスターでは使用できません。

コマンドラインインターフェイスまたは API を使用してデータ API にアクセスするときに FIPS 140-2 検証済みの暗号化モジュールが必要な場合は、FIPS エンドポイントを使用します。利用可能な FIPS エンドポイントの詳細については、「連邦情報処理規格 (FIPS) 140-2」を参照してください。

RDS Data API の制限事項

RDS Data API (Data API) には以下の制限があります。

Data API クエリは、DB クラスターのライターインスタンスでのみ実行できます。ただし、ライターインスタンスは書き込みクエリと読み取りクエリの両方を受け入れることができます。
Aurora グローバルデータベースでは、プライマリ DB クラスターとセカンダリ DB クラスターの両方で Data API を有効にできます。ただし、セカンダリクラスターがプライマリに昇格されるまで、ライターインスタンスはありません。したがって、セカンダリに送信する Data API クエリは失敗します。昇格したセカンダリに使用可能なライターインスタンスが作成されると、その DB インスタンスに対する Data API クエリが成功します。
Performance Insights は、Data API を使用して行ったデータベースクエリのモニタリングをサポートしていません。
Data API は T DB インスタンスクラスではサポートされていません。
PostgreSQL エンジンを使用する Aurora Serverless v2 およびプロビジョニングされた DB クラスターの場合、RDS Data API は一部のデータ型をサポートしていません。サポートされているタイプのリストについては、「RDS Data API と Serverless v2 およびプロビジョンド、および Aurora Serverless v1 の比較」を参照してください。
Aurora PostgreSQL バージョン 14 以降のデータベースでは、Data API はパスワード暗号化のために scram-sha-256 のみをサポートします。
レスポンスサイズの上限は 1 MiB です。1 MiB を超えるレスポンスデータが返されると、その呼び出しは終了します。
Aurora Serverless v1 では、1 秒あたりの最大リクエスト数は 1,000 です。サポートされている他のすべてのデータベースには、制限はありません。
Data API のサイズ制限は、データベースから返る結果セットの 1 行あたり 64 KB です。結果セットの各行が 64 KB 以下であることを確認します。

RDS Data API と Serverless v2 およびプロビジョンド、および Aurora Serverless v1 の比較

RDS Data API の最新の機能強化により、PostgreSQL エンジンの最新バージョンを使用するクラスターで使用できます。これらのクラスターは、Aurora Serverless v2 を使用するように設定するか、db.t4g または db.r6i などのプロビジョニングされたインスタンスクラスを使用するように設定できます。

次の表は、RDS Data API (Data API) と Aurora PostgreSQL Serverless v2 とプロビジョニングされた DB クラスター、および Aurora Serverless v1 DB クラスターの RDS API の違いを示しています。

違い	Aurora PostgreSQL Serverless v2 とプロビジョンド	Aurora Serverless v1
1 秒あたりの最大リクエスト数。	無制限	1,000
RDS API または AWS CLI を使用する既存のデータベースでの Data 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 のイベント	Data API コールからのイベントはデータイベントです。これらのイベントは、デフォルトで証跡で自動的に除外されます。詳細については、「AWS CloudTrail の証跡からの Data API イベントの包含」を参照してください。	Data API コールからのイベントは管理イベントです。これらのイベントは、デフォルトで証跡で自動的に含まれます。詳細については、「AWS CloudTrail の証跡からの Data API イベントの除外 (Aurora Serverless v1 のみ)」を参照してください。
マルチステートメントのサポート	マルチステートメントはサポートされていません。この場合、Data API は `ValidationException: Multistatements aren't supported` をスローします。	Aurora PostgreSQL の場合、マルチステートメントは最初のクエリレスポンスのみを返します。Aurora MySQL では、マルチステートメントはサポートされていません。
BatchExecuteStatement	更新結果で生成されたフィールドオブジェクトは空です。	更新結果で生成されたフィールドオブジェクトには、挿入された値が含まれます。
ExecuteSQL	サポートされていません	廃止済み
ExecuteStatement	`ExecuteStatement` は、多次元配列の列の取得をサポートしていません。この場合、Data API は `UnsupportedResultException` をスローします。 Data API は、ジオメトリ型や金額型など、一部のデータ型をサポートしていません。この場合、Data API は `UnsupportedResultException: The result contains the unsupported data type data_type` をスローします。次のタイプのみがサポートされています。 `BOOL` `BYTEA` `DATE` `CIDR` `DECIMAL`, `NUMERIC` `ENUM` `FLOAT8`, `DOUBLE PRECISION` `INET` `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 Data API へのアクセスの承認

ユーザーは、許可されている場合にのみ RDS Data API (Data API) オペレーションを呼び出すことができます。アクセス許可を定義する AWS Identity and Access Management (IAM) ポリシーをアタッチすることで、Data API を使用するアクセス許可をユーザーに付与できます。IAM ロールを使用している場合は、ポリシーをロールにアタッチすることもできます。AWS 管理ポリシー AmazonRDSDataFullAccess には、Data API のアクセス許可が含まれています。

AmazonRDSDataFullAccess ポリシーには、ユーザーが AWS Secrets Manager からシークレットの値を取得するためのアクセス許可も含まれています。ユーザーは、Secrets Manager を使用して、Data API の呼び出しで使用できるシークレットを保存する必要があります。シークレットを使用すると、ユーザーは Data API の呼び出しでターゲットとするリソースのデータベース認証情報を含める必要がなくなります。Data API は透過的に Secrets Manager を呼び出し、シークレットに対するユーザーのリクエストを許可 (または拒否) します。Data API で使用するシークレットの設定については、「AWS Secrets Manager へのデータベース認証情報の保存」を参照してください。

AmazonRDSDataFullAccess ポリシーは、(Data API を介して) リソースへの完全なアクセスを提供します。リソースの Amazon リソースネーム (ARN) を指定する独自のポリシーを定義することで、スコープを絞り込むことができます。

例えば、次のポリシーは、ARN によって識別される DB クラスターの Data 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 Data API (Data API) と Secrets Manager はどちらも、タグベースの認証をサポートしています。タグは、RDS クラスターなどのリソースに、追加の文字列値を使用してラベル付けするキーと値のペアです。次に例を示します。

environment:production
environment:development

コスト配分、オペレーションサポート、アクセス制御など、さまざまな理由でリソースにタグを適用できます。(リソースにタグがまだないため、タグを適用する場合は、「Amazon RDS リソースにタグを付ける」で詳細を参照してください)。ポリシーステートメントでタグを使用して、これらのタグでラベル付けされた RDS クラスターへのアクセスを制限できます。例として、Aurora DB クラスターには、その環境を本番環境または開発環境として識別するタグが存在する場合があります。

以下の例は、ポリシーステートメントでタグを使用する方法を示しています。このステートメントでは、Data API リクエストで渡されたクラスターとシークレットの両方に environment:production タグが必要です。

ポリシーが適用される方法は次のとおりです。ユーザーが Data API を使用して呼び出しを行うと、リクエストがサービスに送信されます。Data API はまず、リクエストで渡されたクラスター ARN が environment:production でタグ付けされていることを確認します。次に、Secrets Manager を呼び出し、リクエスト内のユーザーのシークレット値を取得します。また、Secrets Manager は environment:production を使用して、ユーザーのシークレットがタグ付け済みかどうかを検証します。その場合、Data API は取得した値をユーザーの DB パスワードに使用します。その値も正しい場合、最後にユーザーに対して Data 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"
                                        ]
                     }
             }
         }
     ]
}

この例は、Data API と Secrets Manager の rds-data および secretsmanager に対する個別のアクションを示しています。ただし、特定のユースケースをサポートするために、さまざまな方法でアクションを組み合わせたり、タグ条件を定義したりできます。詳細については、「Secrets Manager でアイデンティティベースのポリシー (IAM ポリシー) を使用する」を参照してください。

ポリシーの「Condition」要素では、次の項目の中からタグキーを選択できます。

aws:TagKeys
aws:ResourceTag/${TagKey}

リソースタグについてと aws:TagKeys の使用方法の詳細については、「リソースタグを使用した AWS リソースへのアクセスの制御」を参照してください。

注記

Data API と AWS Secrets Manager のどちらもユーザーを承認します。ポリシーで定義されているすべてのアクションに対するアクセス許可を持っていない場合は、AccessDeniedException エラーが発生します。

AWS Secrets Manager へのデータベース認証情報の保存

RDS Data API (Data API) を呼び出すと、Secrets Manager のシークレットを使用して Aurora DB クラスターの認証情報を渡すことができます。この方法で認証情報を渡すには、シークレットの名前またはシークレットの Amazon リソースネーム (ARN) を指定します。

DB クラスター認証情報をシークレットに保存するには

Secrets Manager を使用して Aurora DB クラスターの認証情報が含まれているシークレットを作成します。

手順については、AWS Secrets Managerユーザーガイド の「データベースシークレットを作成する」を参照してください。
Secrets Manager コンソールを使用して、作成したシークレットの詳細を表示するか、AWS CLI の aws secretsmanager describe-secret コマンドを実行します。

シークレットの名前と ARN を書き留めます。これらは、Data API への呼び出しで使用できます。

Secrets Manager の使用の詳細については、AWSSecrets Manager ユーザーガイドを参照してください。

Amazon Aurora が Identity and Access Management をどのように管理するかについては、「 Amazon Aurora で IAM を使用する方法」を参照してください。

IAM ポリシーの作成方法の詳細については、『IAM ユーザーガイド』の「IAM ポリシーの作成」を参照してください。IAM ポリシーをユーザーに追加する方法については、IAM ユーザーガイドの IAMアイデンティティ許可の追加および削除を参照してください。

RDS Data API の有効化

RDS Data API (Data API) を使用するには、Aurora DB クラスター用に有効にする必要があります。Data API の有効化は、DB クラスターの作成時または変更時に行うことができます。

注記

Aurora PostgreSQL の場合、Data API は Aurora Serverless v2、Aurora Serverless v1、およびでプロビジョニングされたデータベースでサポートされています。Aurora MySQL では、Data API は Aurora Serverless v1 データベースでのみサポートされています。

データベースの作成時の RDS Data API の有効化

RDS Data API (Data API) をサポートするデータベースを作成するときに、この機能を有効にできます。次の手順では、AWS Management Console、AWS CLI または RDS API を使用するときにこれを行う方法について説明します。

DB クラスターの作成時に Data API を有効にするには、次のスクリーンショットのように、[データベースの作成] ページの [接続] セクションで [RDS Data API を有効にする] チェックボックスをオンにします。

RDS Data API を使用できる Aurora DB クラスターの作成方法については、以下を参照してください。

Aurora PostgreSQL Serverless v2 とプロビジョンドクラスター – Amazon Aurora DB クラスターの作成
Aurora Serverless v1 – Aurora Serverless v1 DB クラスターの作成の場合

Aurora DB クラスターの作成中に Data API を有効にするには、--enable-http-endpoint オプションを指定して create-db-cluster AWS CLI コマンドを実行します。

次の例では、Data 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 クラスターの作成中に Data API を有効にするには、EnableHttpEndpoint パラメータの値を true に設定して CreateDBCluster オペレーションを使用します。

既存のデータベースでの RDS Data API の有効化

RDS Data API (Data API) をサポートする DB クラスターを変更して、この機能を有効または無効にできます。

トピック

Data API (Aurora PostgreSQL Serverless v2 およびプロビジョンド) の有効化と無効化
Data API の有効化または無効化 (Aurora Serverless v1 のみ)

Data API (Aurora PostgreSQL Serverless v2 およびプロビジョンド) の有効化と無効化

Aurora PostgreSQL Serverless v2 およびプロビジョニングされたデータベースで Data API を有効または無効にするには、次の手順に従います。Aurora Serverless v1 データベースで Data API を有効または無効にするには、「Data API の有効化または無効化 (Aurora Serverless v1 のみ)」の手順を使用します。

Data API を有効または無効にするには、この機能をサポートする DB クラスターの RDS コンソールを使用します。これを行うには、Data API を有効または無効にするデータベースのクラスター詳細ページを開き、[接続とセキュリティ] タブで [RDS Data API] セクションに移動します。このセクションでは、Data API のステータスを表示し、それを有効または無効にできます。

次のスクリーンショットは、[RDS Data API] が有効になっていないことを示しています。

DB クラスターの詳細ページの [接続とセキュリティ] タブの [RDS Data API] セクション。Data API のステータスは無効と表示され、[RDS Data API を有効にする] ボタンが表示されます。

既存のデータベースで Data API を有効または無効にするには、enable-http-endpoint または disable-http-endpoint AWS CLI コマンドを実行し、DB クラスターの ARN を指定します。

次の例では、Data API を有効にします。

Linux、macOS、Unix の場合:


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

Windows の場合:


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

既存のデータベースで Data API を有効または無効にするには、EnableHttpEndpoint オペレーションと DisableHttpEndpoint オペレーションを使用します。

Data API の有効化または無効化 (Aurora Serverless v1 のみ)

Aurora Serverless v1 データベースで Data API を有効または無効にするには、次の手順を使用します。Aurora PostgreSQL Serverless v2 およびプロビジョニングされたデータベースで Data API を有効または無効にするには、Data API (Aurora PostgreSQL Serverless v2 およびプロビジョンド) の有効化と無効化の手順を使用します。

Aurora Serverless v1 DB クラスターの変更時には、RDS コンソールの [接続] セクションで Data API を有効にします。

次のスクリーンショットは、Aurora DB クラスターを変更時に有効になった [Data API] を示しています。

DB クラスターの変更ページの [接続] セクションで、[Data API] チェックボックスが選択されています。

Aurora Serverless v1 DB クラスターを変更する手順については、「Aurora Serverless v1 DB クラスターの変更」を参照してください。

Data API を有効または無効にするには、必要に応じて --enable-http-endpointまたは --no-enable-http-endpoint を使用して modify-db-cluster AWS CLI コマンドを実行します。

次の例では、sample-cluster で Data 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

Data API を有効にするには、ModifyDBCluster オペレーションを使用し、必要に応じて EnableHttpEndpoint の値を true または false に設定します。

RDS Data API の Amazon VPC エンドポイント (AWS PrivateLink) の作成

Amazon VPC を使用すると、Aurora DB クラスターやアプリケーションなどの AWS リソースを Virtual Private Cloud (VPC) 内に起動できます。AWS PrivateLink は、VPC と AWS のサービス間のプライベート接続を、Amazon ネットワーク上で高い安全性とともに提供します。AWS PrivateLink を使用すると、Amazon VPC エンドポイントを作成できます。これにより、Amazon VPC に基づいて、異なるアカウントと VPC のサービスに接続することが可能になります。AWS PrivateLink の詳細については、Amazon Virtual Private Cloud ユーザーガイドの「VPC エンドポイントサービス (AWS PrivateLink)」を参照してください。

Amazon VPC エンドポイントを使用して RDS Data API (Data API) を呼び出すことができます。Amazon VPC エンドポイントを使用することで、パブリック IP アドレスなしで Amazon VPC 内のアプリケーションと AWS ネットワーク内の Data API 間のトラフィックを維持できます。Amazon VPC エンドポイントは、公共のインターネット接続の制限に関連するコンプライアンスおよび規制要件を満たすのに役立ちます。例えば、Amazon VPC エンドポイントを使用する場合、Amazon EC2 インスタンスで実行されているアプリケーションと、それらを含む VPC 内の Data API 間のトラフィックを維持できます。

Amazon VPC エンドポイントを作成したら、アプリケーションでコードや設定を変更せずに、エンドポイントの使用をスタートできます。

Data API に Amazon VPC エンドポイントを作成するには

AWS Management Console にサインインして、Amazon VPC コンソール (https://console.aws.amazon.com/vpc/) を開きます。
[ エンドポイント] を選択し、[エンドポイントの作成] を選択します。
[エンドポイントの作成] ページの [サービスカテゴリ] で [AWS サービス] を選択します。[サービス名] で、[rds-data] を選択します。
[VPC] の場合は、VPC を選択してエンドポイントを作成します。

Data API コールを行うアプリケーションを含む VPC を選択します。
[サブネット] で、アプリケーションを実行している AWS のサービスによって使用される各アベイラビリティーゾーン (AZ) のサブネットを選択します。

Amazon VPC エンドポイントを作成するには、エンドポイントにアクセスできるプライベート IP アドレスの範囲を指定します。これを行うには、各アベイラビリティーゾーンのサブネットを選択します。これにより、VPC エンドポイントは各アベイラビリティーゾーンに固有のプライベート IP アドレス範囲に制限され、各アベイラビリティーゾーンに Amazon VPC エンドポイントが作成されます。
[DNS 名を有効にする] で、[このエンドポイントで有効にする] を選択します。

プライベート DNS は、スタンダードの Data API DNS ホスト名 (https://rds-data.region.amazonaws.com) を、Amazon VPC エンドポイントに固有の DNS ホスト名に関連付けられたプライベート IP アドレスに解決します。その結果、Data API エンドポイント URL を更新するためのコードや設定を変更せずに、AWS CLI または AWS SDK を使用して Data API VPC エンドポイントにアクセスできます。
セキュリティグループで、Amazon VPC エンドポイントに関連付けるセキュリティグループを選択します。

アプリケーションを実行している AWS のサービスへのアクセスを許可するセキュリティグループを選択します。例えば、Amazon EC2 インスタンスでアプリケーションを実行している場合は、Amazon EC2 インスタンスへのアクセスを許可するセキュリティグループを選択します。セキュリティグループを使用すると、VPC 内のリソースから Amazon VPC エンドポイントへのトラフィックを制御できます。
[ポリシー] で [フルアクセス] を選択すると、Amazon VPC 内部の誰でもこのエンドポイントを介して Data API にアクセスできるようになります。または、[カスタム] を選択して、アクセスを制限するポリシーを指定します。

[カスタム] を選択した場合は、ポリシー作成ツールでポリシーを入力します。
[エンドポイントの作成] を選択します。

エンドポイントを作成したら、AWS Management Console でリンクを選択して、エンドポイントの詳細を表示します。

エンドポイントの [Details (詳細)] タブには、Amazon VPC エンドポイントの作成中に生成された DNS ホスト名が表示されます。

スタンダードエンドポイント (rds-data.region.amazonaws.com) または VPC 固有のエンドポイントの 1 つを使用して、Amazon VPC 内の Data API を呼び出すことができます。スタンダード Data API エンドポイントは、自動的に Amazon VPC エンドポイントにルーティングします。このルーティングは、Amazon VPC エンドポイントの作成時にプライベート DNS ホスト名が有効になったために発生します。

Data API コールで Amazon VPC エンドポイントを使用すると、アプリケーションと Data API 間のすべてのトラフィックは、それらを含む Amazon VPC に残ります。Amazon VPC エンドポイントは、任意のタイプの Data API コールに使用できます。Data API を呼び出す方法については、「RDS Data API の呼び出し」を参照してください。

RDS Data API の呼び出し

Aurora DB クラスターで RDS Data API (Data API) を有効にした状態で、Data API または AWS CLI により、Aurora DB クラスターで SQL ステートメントを実行できます。Data API は、AWS SDK でサポートされているプログラミング言語をサポートしています。詳細については、AWS で構築するツールを参照してください。

トピック

Data API オペレーションリファレンス
AWS CLI を使用した RDS Data API の呼び出し
Python アプリケーションからの RDS Data API の呼び出し
Java アプリケーションからの RDS Data API の呼び出し
Data API タイムアウト動作の制御

Data API オペレーションリファレンス

Data API では、以下のオペレーションを使用して、SQL ステートメントを実行することができます。

Data API オペレーション	AWS CLI コマンド	説明
`ExecuteStatement`	`aws rds-data execute-statement`	データベースで SQL ステートメントを実行します。
`BatchExecuteStatement`	`aws rds-data batch-execute-statement`	データの配列に対してバッチ SQL ステートメントを実行して、一括更新オペレーションおよび挿入オペレーションを行います。パラメータセットの配列を使用して、データ操作言語 (DML) ステートメントを実行できます。バッチ SQL ステートメントは、挿入ステートメントと更新ステートメントを個々に実行するよりもパフォーマンスは大幅に向上します。

どちらかの操作を使用して、個々の SQL ステートメントを実行したり、トランザクションを実行したりできます。トランザクションの場合、Data API は次のオペレーションを提供します。

Data API オペレーション	AWS CLI コマンド	説明
`BeginTransaction`	`aws rds-data begin-transaction`	SQL トランザクションをスタートします。
`CommitTransaction`	`aws rds-data commit-transaction`	SQL トランザクションを終了し、変更をコミットします。
`RollbackTransaction`	`aws rds-data rollback-transaction`	トランザクションをロールバックします。

SQL ステートメントを実行し、トランザクションをサポートするためのオペレーションには、以下の共通の Data API パラメータおよび AWS CLI オプションがあります。他のパラメータやオプションをサポートするオペレーションもあります。

Data API オペレーションのパラメータ	AWS CLI コマンドオプション	必須	説明
`resourceArn`	`--resource-arn`	あり	Aurora DB クラスターの Amazon リソースネーム (ARN)。
`secretArn`	`--secret-arn`	あり	DB クラスターへのアクセスを有効にするシークレットの ARN の名前。

パラメータは、Data API の ExecuteStatement および BatchExecuteStatement への呼び出しと、AWS CLI の execute-statement コマンドおよび batch-execute-statement コマンドの実行時に使用できます。パラメータを使用するには、名前と値のペアを SqlParameter データ型で指定します。値は、Field データ型で指定します。次の表は、Data API 呼び出しで指定したデータ型に Java Database Connectivity (JDBC) データ型をマッピングしたものです。

JDBC データ型	Data 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 などの特定のタイプでは、Data 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 タイプのオブジェクトとしてデータベースに送信されます。

注記
現在、Data API はユニバーサル固有識別子 (UUID) の配列をサポートしていません。

注記

Amazon Aurora PostgreSQL の場合、Data API は常に UTC タイムゾーンの Aurora PostgreSQL データ型 TIMESTAMPTZ を返します。

AWS CLI を使用した RDS Data API の呼び出し

RDS Data API (Data API) は、AWS CLI を使用して呼び出すことができます。

以下の例では、Data API で AWS CLI を使用しています。詳細については、AWS CLI reference for the Data API を参照してください。

それぞれの例で、DB クラスターの Amazon リソースネーム (ARN) を Aurora DB クラスターの ARN に置き換えます。また、シークレット ARN を Secrets Manager のシークレットの ARN に置き換え、DB クラスターへのアクセスを許可します。

注記

AWS CLI はレスポンスを JSON でフォーマットできます。

トピック

SQL トランザクションのスタート
SQL ステートメントの実行
データ配列に対するバッチ SQL ステートメントの実行
SQL トランザクションのコミット
SQL トランザクションのロールバック

SQL トランザクションのスタート

SQL トランザクションをスタートするには、CLI の aws rds-data begin-transaction コマンドを使用します。コールによって、トランザクション識別子が返ります。

重要

Data API では、3 分以内にトランザクション ID を使用する呼び出しがないと、トランザクションはタイムアウトします。トランザクションがコミットされる前にタイムアウトした場合、Data API は自動的にロールバックします。

トランザクション内の MySQL データ定義言語 (DDL) ステートメントは、暗黙的なコミットを引き起こします。各 MySQL DDL ステートメントは、execute-statement コマンドに --continue-after-timeout オプションを指定して、個別に実行することをお勧めします。

共通オプションに加えて、--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 ステートメントの実行

SQL ステートメントを実行するには、CLI の aws rds-data execute-statement を使用します。

SQL ステートメントをトランザクションで実行するには、--transaction-id オプションとあわせてトランザクション識別子を指定します。トランザクションをスタートするには、CLI の aws rds-data begin-transaction コマンドを使用します。トランザクションを終了し、コミットするには、CLI の aws rds-data commit-transaction コマンドを使用します。

重要

--transaction-id オプションを指定しない場合、呼び出しによる変更は自動的にコミットされます。

共通オプションに加えて、次のオプションを指定します。

--sql (必須) - DB クラスターで実行する SQL ステートメント。
--transaction-id (オプション) - CLI の begin-transaction コマンドを使用してスタートされたトランザクションの識別子。SQL ステートメントを含めるトランザクションのトランザクション ID を指定します。
--parameters (オプション) - SQL ステートメントのパラメータ。
--include-result-metadata | --no-include-result-metadata (オプション) - 結果にメタデータを含むかどうかを示す値。デフォルト: --no-include-result-metadata。
--database (オプション) - データベースの名前。

--database オプションは、前のリクエストで --sql "use database_name;" を実行した後に SQL ステートメントを実行すると、機能しない場合があります。--sql "use database_name;" ステートメントを実行する代わりに --database オプションを使用することをお勧めします。
--continue-after-timeout | --no-continue-after-timeout (オプション) — 呼び出しが Data API タイムアウト間隔の 45 秒を超えた後もステートメントの実行を継続するかどうかを示す値。デフォルト: --no-continue-after-timeout。

データ定義言語 (DDL) ステートメントでは、エラーやデータ構造の破損の可能性を回避するために、呼び出しがタイムアウトした後もステートメントを実行し続けることをお勧めします。
--format-records-as "JSON"|"NONE" - 結果セットを JSON 文字列としてフォーマットするかどうかを指定するオプションの値です。デフォルト: "NONE"。JSON 結果セットの処理の詳細については、「JSON 形式で RDS Data API クエリ結果を処理する」を参照してください。

DB クラスターは呼び出しに対してレスポンスを返します。

注記

レスポンスサイズの上限は 1 MiB です。1 MiB を超えるレスポンスデータが返されると、その呼び出しは終了します。

Aurora Serverless v1 では、1 秒あたりの最大リクエスト数は 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 ステートメントが終了すると、エラーが発生したり、データ構造が破損したりする恐れがあります。呼び出しが RDS Data API のタイムアウト間隔である 45 秒を超えた後もステートメントの実行を続けるには、--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 ステートメントの実行

データの配列に対してバッチ SQL ステートメントを実行するには、CLI の aws rds-data batch-execute-statement コマンドを使用します。このコマンドを使用して、一括インポートまたは一括更新オペレーションを実行できます。

重要

--transaction-id オプションを指定しない場合、呼び出しによる変更は自動的にコミットされます。

共通オプションに加えて、次のオプションを指定します。

--sql (必須) - DB クラスターで実行する SQL ステートメント。

ヒント
MySQL 互換のステートメントでは、--sql パラメータの末尾にセミコロンを含めないでください。末尾のセミコロンは、構文エラーを引き起こす可能性があります。
--transaction-id (オプション) - CLI の begin-transaction コマンドを使用してスタートされたトランザクションの識別子。SQL ステートメントを含めるトランザクションのトランザクション ID を指定します。
--parameter-set (オプション) - バッチオペレーション用のパラメータセット。
--database (オプション) - データベースの名前。

DB クラスターは、呼び出しに対してレスポンスを返します。

注記

パラメータセットの数に固定された上限はありません。ただし、データ API を介して送信される HTTP リクエストの最大サイズは 4 MiB です。リクエストがこの制限を超えると、データ API はエラーを返し、リクエストを処理しません。この 4 MiB の制限には、リクエスト内の HTTP ヘッダーのサイズと JSON 表記が含まれます。したがって、含めることができるパラメータセットの数は、SQL ステートメントのサイズや各パラメータセットのサイズなどの要素の組み合わせによって異なります。

レスポンスサイズの上限は 1 MiB です。1 MiB を超えるレスポンスデータが返されると、その呼び出しは終了します。

Aurora Serverless v1 では、1 秒あたりの最大リクエスト数は 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 トランザクションのコミット

CLI の aws rds-data commit-transaction コマンドを使用すると、aws rds-data begin-transaction でスタートした SQL トランザクションを終了し、変更をコミットすることができます。

共通オプションに加えて、次のオプションを指定します。

--transaction-id (必須) - CLI の begin-transaction コマンドを使用してスタートされたトランザクションの識別子。終了し、コミットするトランザクションのトランザクション 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 トランザクションのロールバック

CLI の aws rds-data rollback-transaction コマンドを使用すると、aws rds-data begin-transaction でスタートした SQL トランザクションをロールバックすることができます。トランザクションをロールバックすると、変更はキャンセルされます。

重要

トランザクション ID の有効期限が切れている場合、トランザクションは自動的にロールバックされます。この場合、有効期限切れのトランザクション ID を指定する aws rds-data rollback-transaction コマンドによって、エラーが返ります。

共通オプションに加えて、次のオプションを指定します。

--transaction-id (必須) - CLI の begin-transaction コマンドを使用してスタートされたトランザクションの識別子。ロールバックするトランザクションのトランザクション 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 Data API の呼び出し

Python アプリケーションから RDS Data API (Data API) を呼び出すことができます。

以下の例では、AWS SDK for Python (Boto) を使用します。Boto の詳細については、AWS SDK for Python (Boto 3) ドキュメントを参照してください。

トピック

SQL クエリの実行
DML SQL ステートメントの実行
SQL トランザクションの実行

SQL クエリの実行

Python アプリケーションを使用して、SELECT ステートメントを実行し、結果を取得することができます。

以下の例では、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 パラメータが含まれていないため、呼び出しがトランザクションの一部ではない場合、呼び出しによる変更は自動的にコミットされます。

以下の例では、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 トランザクションのスタートから、1 つ以上の 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 ステートメントが終了すると、エラーが発生したり、データ構造が破損したりする恐れがあります。呼び出しが RDS Data API のタイムアウト間隔である 45 秒を超えた後もステートメントの実行を続けるには、continueAfterTimeout パラメータを true に設定します。

Java アプリケーションからの RDS Data API の呼び出し

Java アプリケーションから RDS Data API (Data API) を呼び出すことができます。

以下の例では、AWS SDK for Java を使用します。詳細については、「AWS SDK for Java デベロッパーガイド」を参照してください。

トピック

SQL クエリの実行
SQL トランザクションの実行
SQL のバッチオペレーションを実行する

SQL クエリの実行

Java アプリケーションを使用して、SELECT ステートメントを実行し、結果を取得することができます。

以下の例では、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 トランザクションのスタートから、1 つ以上の SQL ステートメントの実行、Java アプリケーションによる変更のコミットまで行うことができます。

重要

トランザクション 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);
  }
}

Data API タイムアウト動作の制御

Data API へのすべての呼び出しは同期的です。INSERT または CREATE TABLE などの SQL ステートメントを実行する Data API 操作を実行するとします。Data API 呼び出しが正常に返されると、呼び出しが返されたときに SQL 処理は終了します。

デフォルトでは、Data API は操作をキャンセルし、操作が 45 秒以内に処理を完了しなかった場合、タイムアウトエラーを返します。その場合、データは挿入されず、テーブルは作成されません。

Data API を使用して、45 秒以内に完了できない長時間実行操作を実行できます。大きなテーブルに対する一括操作 INSERT や DDL 操作などの操作に 45 秒以上かかることが予想される場合は、ExecuteStatement 操作の continueAfterTimeout パラメータを指定できます。アプリケーションは引き続きタイムアウトエラーを受け取ります。ただし、操作は実行され続け、キャンセルされません。例については、「SQL トランザクションの実行」を参照してください。

プログラミング言語の AWS SDK に API コールまたは HTTP ソケット接続について独自のタイムアウト期間がある場合、そのようなタイムアウト期間がすべて 45 秒以上であることを確認してください。一部の SDK では、タイムアウト期間はデフォルトで 45 秒未満です。SDK 固有またはクライアント固有のタイムアウト期間を少なくとも 1 分に設定することをお勧めします。これにより、アプリケーションがタイムアウトエラーを受け取る可能性を回避しつつ、Data API 操作を正常に完了できます。これにより、操作を再試行するかどうかを確認できます。

例えば、SDK がタイムアウトエラーをアプリケーションに返したが、Data API 操作は Data API タイムアウト間隔内に完了したとします。その場合、操作を再試行すると、重複したデータが挿入されたり、誤った結果が生成される可能性があります。SDK は操作を自動的に再試行して、アプリケーションからのアクションなしで誤ったデータを引き起こす可能性があります。

Java 2 SDK では、タイムアウト間隔が特に重要です。その SDK では、API コールのタイムアウトと HTTP ソケットのタイムアウトはどちらもデフォルトで 30 秒です。これらのタイムアウトをより高い値に設定する例を次に示します。


public RdsDataClient createRdsDataClient() {
    return RdsDataClient.builder()
        .region(Region.US_EAST_1) // Change this to your desired Region
        .overrideConfiguration(createOverrideConfiguration())
        .httpClientBuilder(createHttpClientBuilder())
        .credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
        .build();
}

private static ClientOverrideConfiguration createOverrideConfiguration() {
    return ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofSeconds(60))
        .build();
}
    
private HttpClientBuilder createHttpClientBuilder() {
    return ApacheHttpClient.builder() // Change this to your desired HttpClient
        .socketTimeout(Duration.ofSeconds(60));
}

非同期データクライアントを使用した同等の例を次に示します。


public static RdsDataAsyncClient createRdsDataAsyncClient() {
    return RdsDataAsyncClient.builder()
        .region(Region.US_EAST_1) // Change this to your desired Region
        .overrideConfiguration(createOverrideConfiguration())
        .credentialsProvider(defaultCredentialsProvider())  // Change this to your desired credentials provider
        .build();
}

private static ClientOverrideConfiguration createOverrideConfiguration() {
    return ClientOverrideConfiguration.builder()
        .apiCallAttemptTimeout(Duration.ofSeconds(60))
        .build();
}

private HttpClientBuilder createHttpClientBuilder() {
    return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient
        .readTimeout(Duration.ofSeconds(60));
}

RDS Data API 用の Java クライアントライブラリの使用

RDS Data API (Data API) 用の Java クライアントライブラリをダウンロードして使用できます。この Java クライアントライブラリは、Data API を使用する代替手段を提供します。このライブラリを使用すると、クライアント側のクラスを Data API のリクエストとレスポンスにマッピングできます。このマッピングのサポートにより、Date、Time、BigDecimal などの特定の Java タイプとの統合が容易になります。

Data API 用の Java クライアントライブラリのダウンロード

Data API Java クライアントライブラリは、GitHub の次の場所にあるオープンソースです。

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

ソースファイルからライブラリを手動で構築できますが、ベストプラクティスは、Apache Maven 依存関係管理を使用してライブラリを使用する方法です。Maven POM ファイルに次の依存関係を追加します。

バージョン 2.x (AWS SDK 2.x 互換) では、以下を使用します。


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

バージョン 1.x (AWS SDK 1.x 互換) では、以下を使用します。


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

Java クライアントライブラリの例

以下に、Data API Java クライアントライブラリを使用する一般的な例をいくつか示します。これらの例では、accounts と accountId の 2 つの列を含むテーブル 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();

以下は、入力パラメータとして単純な値を使用するもう 1 つの例です。



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);

多くの場合、データベースの結果セットには 1 つの値しか含まれていません。このような結果の取得を簡素化するために、クライアントライブラリは次の API を提供しています。


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

注記

mapToList 関数は、SQL 結果セットをユーザー定義のオブジェクトリストに変換します。Java クライアントライブラリの ExecuteStatement コールで .withFormatRecordsAs(RecordsFormatType.JSON) ステートメントの使用は、同じ目的を果たすためサポートしていません。詳細については、「JSON 形式で RDS Data API クエリ結果を処理する」を参照してください。

JSON 形式で RDS Data API クエリ結果を処理する

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`	文字列
`ARRAY`	配列
`NULL`	`null`
その他の型 (日時に関する型も含む)	文字列

トラブルシューティング

JSON レスポンスは 10 メガバイトに制限されています。レスポンスがこの制限よりも大きい場合、プログラムには BadRequestException エラーが返されます。この場合、以下のいずれかの方法でエラーを解決できます。

結果セットの行数を減らします。これを行うには、LIMIT 句を追加します。LIMIT と OFFSET の句を持つ複数のクエリを送信することで、大きな結果セットを複数の小さな結果セットに分割できます。

アプリケーションロジックによって、結果セットにフィルタリングされた行が含まれている場合は、WHERE 句にさらに条件を追加することで、結果セットから該当の行を削除できます。
結果セットの列数を減らします。これを行うには、クエリの選択リストから項目を削除します。
クエリで列エイリアスを使用することにより、列ラベルを短くします。各列名は、結果セット内の各行に対して JSON 文字列で繰り返されます。そのため、長い列名と多くの行を含むクエリ結果の場合、サイズ制限を超える可能性があります。特に、複雑な式には列のエイリアスを使用して、JSON 文字列で式全体が繰り返されないようにします。
SQL では、列のエイリアスを使用して同じ名前の列を複数持つ結果セットを作成できますが、JSON ではキー名の重複は許可されません。JSON 形式で結果セットをリクエストし、複数の列が同じ名前の場合、RDS データ API はエラーを返します。そのため、すべての列のラベルに一意の名前があることを確認します。

例

以下の Java の例では、レスポンスを JSON 形式の文字列として ExecuteStatement を呼び出し、結果セットを解釈する方法を示しています。databaseName、secretStoreArn、clusterArn パラメータを適切な値に置き換えます。

以下の Java の例では、結果セットに 10 進数の値を返すクエリを示しています。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 形式を使用しない場合に、結果セットを保持するデータ構造を構築するために必要なコードの種類を示しています。この場合、結果セットの各行には 1 人のユーザーに関する情報を含むフィールドが含まれています。結果セットを表すデータ構造を構築するには、行をループする必要があります。各行について、コードによって各フィールドの値を取得して、適切な型変換を実行し、その行を表すオブジェクト内の対応するフィールドに結果を代入します。次に、各ユーザーを表すオブジェクトを、結果セット全体を表すデータ構造に追加します。クエリの結果セット内でフィールドの並べ替え、追加、削除などで変更があった場合、アプリケーションコードも変更する必要があります。


/* 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 文字列の各キーバリューペアの値は、引用符で囲まれた文字列にできます。文字列には Unicode 文字が含まれている場合があります。文字列にエスケープシーケンスが含まれている場合、または " や \ 文字の場合、それらの文字の前にバックスラッシュ (エスケープ) 文字が付きます。以下に、可能性のある 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 タイプの値を選択した場合、結果は base64 でエンコードされた値として JSON 文字列で表されます。値を元の表現に戻すには、アプリケーションの言語で適切なデコード関数を使用できます。例えば、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 Data API の問題のトラブルシューティング

RDS Data API (Data API) に関する問題のトラブルシューティングには、「一般的なエラーメッセージ」というタイトルの以下のセクションを使用します。

トピック

トランザクション <transaction_ID> が見つかりません
クエリのパケットが大きすぎる
データベース応答がサイズ制限を超えている
HttpEndpoint がクラスター <cluster_ID> に対して有効になっていない

トランザクション <transaction_ID> が見つかりません

この場合、Data API 呼び出しで指定されたトランザクション ID は見つかりませんでした。この問題の原因は、エラーメッセージに追加されますが、次のいずれかであることが考えられます。

トランザクションの有効期限が切れている可能性があります。

各トランザクションの呼び出しが、前のトランザクション呼び出しから 3 分以内に実行されることを確認します。

指定されたトランザクション ID が、BeginTransaction コールによって作成されていない可能性もあります。呼び出しに有効なトランザクション ID があることを確認します。
前回の呼び出しで、トランザクションが終了しました。

トランザクションは、お客様の CommitTransaction または RollbackTransaction コールによってすでに終了しています。
前回の呼び出しのエラーにより、トランザクションが中断されました。

以前の呼び出しで例外が発生したかどうかを確認します。

トランザクションの実行については、「RDS Data API の呼び出し」を参照してください。

クエリのパケットが大きすぎる

この場合、1 行に対して返った結果セットが大きすぎます。Data API のサイズ制限は、データベースから返る結果セットの 1 行あたり 64 KB です。

この問題を解決するには、結果セットの各行が 64 KB 以下であることを確認します。

データベース応答がサイズ制限を超えている

この場合、データベースから返る結果セットのサイズが大きすぎます。Data API の制限は、データベースから返る結果セットの 1 MiB です。

この問題を解決するには、Data API への呼び出しで返るデータが 1 MiB 以下になるようにします。1 MiB を超えるデータを返す必要がある場合は、クエリでLIMIT句を使用して、ExecuteStatement呼び出しを複数回行います。

LIMIT 句の詳細については、MySQL ドキュメントの「SELECT 構文」を参照してください。

HttpEndpoint がクラスター <cluster_ID> に対して有効になっていない

この問題の原因として考えられるものとして、以下の項目を確認してください。

Aurora DB クラスターは Data API をサポートしていません。例えば、Aurora MySQL の場合、Data API は Aurora Serverless v1 でのみ使用できます。RDS Data API がサポートする DB クラスターのタイプについては、「リージョンとバージョンの可用性」を参照してください。
Data API が Aurora DB クラスターに対して有効になっていません。Aurora DB クラスターで Data API を使用するには、DB クラスターに対して Data API が有効になっている必要があります。Data API を有効にする方法については、「RDS Data API の有効化」を参照してください。
Data API が有効になった後、DB クラスターの名前が変更されました。この場合は、クラスターのデータ API を一度オフにしてから、再度有効にします。
指定された ARN がクラスターの ARN と正確に一致しません。別のソースから返された ARN、またはプログラムロジックによって構築された ARN が、クラスターの ARN と正確に一致していることを確認します。例えば、使用する ARN は、アルファベットの大文字と小文字がすべて一致しているかを確認します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Aurora Serverless v1 とAurora データベースエンジンのバージョン

AWS CloudTrail での RDS Data API コールのログ記録