Aurora Serverless v1 の Data API の使用 - Amazon Aurora

Aurora Serverless v1 の Data API の使用

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

Data API へのすべての呼び出しは同期的です。デフォルトでは、呼び出しの処理が 45 秒以内に完了していない場合、呼び出しはタイムアウトします。ただし、continueAfterTimeout パラメータを使用して呼び出しがタイムアウトになった場合は、SQL ステートメントの実行を続行できます。例については、「SQL トランザクションの実行」を参照してください。

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

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

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

Data API を有効にすると、Aurora Serverless v1 のクエリエディタも使用できます。詳細については、「Aurora Serverless v1 のクエリエディタの使用」を参照してください。

注記

データ API とクエリエディタは、Aurora Serverless v2 ではサポートされていません。

Data API の可用性

データ API は、特定の Aurora MySQL と Aurora PostgreSQL バージョンのみを使用して Aurora Serverless v1 DB クラスターで有効にできます。詳細については、「Aurora Serverless v1 の Data API」を参照してください。

現在 AWS で Data API が利用可能な Aurora Serverless v1 リージョンを次の表に示します。これらのリージョンで Data API にアクセスするには、HTTPS プロトコルを使用します。

リージョン リンク
米国東部 (オハイオ) rds-data.us-east-2.amazonaws.com
米国東部 (バージニア北部) rds-data.us-east-1.amazonaws.com
米国西部 (北カリフォルニア) rds-data.us-west-1.amazonaws.com
US West (Oregon) rds-data.us-west-2.amazonaws.com
アジアパシフィック (ムンバイ) rds-data.ap-south-1.amazonaws.com
アジアパシフィック (ソウル) rds-data.ap-northeast-2.amazonaws.com
アジアパシフィック (シンガポール) rds-data.ap-southeast-1.amazonaws.com
Asia Pacific (Sydney) rds-data.ap-southeast-2.amazonaws.com
Asia Pacific (Tokyo) rds-data.ap-northeast-1.amazonaws.com
カナダ (中部) rds-data.ca-central-1.amazonaws.com
Europe (Frankfurt) rds-data.eu-central-1.amazonaws.com
Europe (Ireland) rds-data.eu-west-1.amazonaws.com
Europe (London) rds-data.eu-west-2.amazonaws.com
Europe (Paris) rds-data.eu-west-3.amazonaws.com

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

Data API へのアクセスの承認

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

タグベースの承認の操作

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 へのデータベース認証情報の保存

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

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

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

    手順については、AWS Secrets Manager ユーザーガイドの「基本的なシークレットを作成する」を参照してください。

  2. 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アイデンティティ許可の追加および削除を参照してください。

Data API の有効化

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

注記

現在、Aurora Serverless v2 DB インスタンスでデータ API を使用することはできません。

Data API を有効にするには、Aurora Serverless v1 DB クラスターの作成時または変更時に RDS コンソールを使用します。Aurora Serverless v1 DB クラスターの作成時には、RDS コンソールの [Connectivity (接続)] セクションで Data API を有効にします。Aurora Serverless v1 DB クラスターの変更時には、RDS コンソールの [Network & Security (ネットワークとセキュリティ)] セクションで Data API を有効にします。

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


                            コンソールで Aurora Serverless v1 DB クラスターの Data API を有効にする

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

Aurora Serverless v1 CLI コマンドを使用して、AWS DB クラスターを作成または変更する際、--enable-http-endpoint を指定すると Data API が有効になります。

以下の --enable-http-endpoint CLI コマンドを使用して AWS を指定することもできます。

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

Amazon RDS API オペレーションを使用して、Aurora Serverless v1 DB クラスターを作成または変更する際、EnableHttpEndpoint 値を true に設定して、Data API を有効にします。

以下の API オペレーションを使用して EnableHttpEndpoint 値を設定できます。

Data API (AWS PrivateLink) 用に Amazon VPC エンドポイントを作成する

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 エンドポイントを使用して 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 エンドポイントを作成するには

  1. AWS Management Console にサインインして、Amazon VPC コンソール (https://console.aws.amazon.com/vpc/) を開きます。

  2. [ エンドポイント] を選択し、[エンドポイントの作成] を選択します。

  3. [エンドポイントの作成] ページの [サービスカテゴリ] で [AWS サービス] を選択します。[サービス名] で、[rds-data] を選択します。

    
                            Data API の Amazon VPC エンドポイントを作成する
  4. [VPC] の場合は、VPC を選択してエンドポイントを作成します。

    Data API コールを行うアプリケーションを含む VPC を選択します。

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

    
                            Amazon VPC エンドポイントのサブネットを選択する

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

  6. [DNS 名を有効にする] で、[このエンドポイントで有効にする] を選択します。

    
                            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 エンドポイントにアクセスできます。

  7. セキュリティグループで、Amazon VPC エンドポイントに関連付けるセキュリティグループを選択します。

    アプリケーションを実行している AWS のサービスへのアクセスを許可するセキュリティグループを選択します。例えば、Amazon EC2 インスタンスでアプリケーションを実行している場合は、Amazon EC2 インスタンスへのアクセスを許可するセキュリティグループを選択します。セキュリティグループを使用すると、VPC 内のリソースから Amazon VPC エンドポイントへのトラフィックを制御できます。

  8. [ポリシー] で [フルアクセス] を選択すると、Amazon VPC 内部の誰でもこのエンドポイントを介して Data API にアクセスできるようになります。または、[カスタム] を選択して、アクセスを制限するポリシーを指定します。

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

  9. [Create endpoint] (エンドポイントの作成) を選択します。

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


                    Amazon VPC エンドポイントの詳細へのリンク

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


                    Amazon VPC エンドポイントの詳細へのリンク

スタンダードエンドポイント (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 を呼び出す方法については、「Data API の呼び出し」を参照してください。

Data API の呼び出し

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

注記

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

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 ステートメントを実行したり、トランザクションを実行したりできます。トランザクションの場合、データ 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 Serverless v1 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 での作業時に発生する可能性のある事態を避けるために、これを行うことをお勧めします。

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

注記

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

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

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

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

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

注記

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

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

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

重要

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

トランザクション内のデータ定義言語 (DDL) ステートメントは、暗黙的なコミットを引き起こします。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 (オプション) - データベースの名前。

  • --continue-after-timeout | --no-continue-after-timeout (オプション) - 呼び出しのタイムアウト後、ステートメントの実行を継続するかどうかを示す値。デフォルト: --no-continue-after-timeout

    データ定義言語 (DDL) ステートメントでは、エラーやデータ構造の破損の可能性を回避するために、呼び出しがタイムアウトした後もステートメントを実行し続けることをお勧めします。

  • --format-records-as "JSON"|"NONE" - 結果セットを JSON 文字列としてフォーマットするかどうかを指定するオプションの値です。デフォルト: "NONE"。JSON 結果セットの処理の詳細については、「JSON 形式でクエリ結果を処理する」を参照してください。

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

注記

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

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 ステートメントが終了すると、エラーが発生したり、データ構造が破損したりする恐れがあります。呼び出しがタイムアウトした後もステートメントの実行を続けるには、--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 コマンドを使用します。このコマンドを使用して、一括インポートまたは一括更新オペレーションを実行できます。

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

重要

--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 を超えるレスポンスデータが返されると、その呼び出しは終了します。

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 アプリケーションから Data API を呼び出す

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

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

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

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 ステートメントが終了すると、エラーが発生したり、データ構造が破損したりする恐れがあります。呼び出しがタイムアウトした後もステートメントの実行を続けるには、continueAfterTimeout パラメータを true に設定します。

Java アプリケーションから Data API を呼び出す

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

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

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

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 アプリケーションによる変更のコミットまで行うことができます。

重要

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); } }
注記

データ定義言語 (DDL) ステートメントを実行する場合は、呼び出しがタイムアウトした後もステートメントを実行し続けることをお勧めします。実行が終了する前に DDL ステートメントが終了すると、エラーが発生したり、データ構造が破損したりする恐れがあります。呼び出しがタイムアウトした後もステートメントの実行を続けるには、continueAfterTimeout パラメータを true に設定します。

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 用の Java クライアントライブラリの使用

Data API 用の Java クライアントライブラリをダウンロードして使用できます。この Java クライアントライブラリは、Data API を使用する代替手段を提供します。このライブラリを使用すると、クライアント側のクラスを Data API のリクエストとレスポンスにマッピングできます。このマッピングのサポートにより、DateTimeBigDecimal などの特定の 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 クライアントライブラリを使用する一般的な例をいくつか示します。これらの例では、accountsaccountId の 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 形式でクエリ結果を処理する」を参照してください。

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

ExecuteStatement オペレーションを呼び出す場合、クエリ結果を JSON 形式の文字列として返すように選択できます。これにより、プログラミング言語の JSON 解析機能を使用して結果セットを解釈し、再フォーマットできます。そうすることで、結果セットをループして各列の値を解釈するために、余分なコードを記述せずに済むようになります。

JSON 形式で結果セットをリクエストするには、オプションの formatRecordsAs パラメータに JSON の値を渡します。JSON 形式の結果セットは、ExecuteStatementResponse 構造の formattedRecords に返されます。

BatchExecuteStatement アクションは結果セットを返しません。したがって、JSON オプションはそのアクションには適用されません。

JSON ハッシュ構造のキーをカスタマイズするには、結果セットにカラムのエイリアスを定義します。SQL クエリの列リスト内で AS 句を指定することで定義できます。

JSON 機能を使用することで、結果セットが読みやすくなり、その内容を言語固有のフレームワークにマッピングしやすくなります。ASCII でエンコードされた結果セットのボリュームはデフォルトの表記よりも大きいため、大きな行または列値を返すクエリではアプリケーションで使用可能なメモリよりも多くのメモリを消費することになり、この場合はデフォルトの表記を選択する方が良いでしょう。

JSON 形式でクエリ結果を取得する

結果セットを JSON 文字列として受け取るには、ExecuteStatement の呼び出しに .withFormatRecordsAs(RecordsFormatType.JSON) を含めます。戻り値は、formattedRecords フィールドに JSON 文字列として戻ります。この場合、columnMetadatanull です。列ラベルは、各行を表すオブジェクトのキーです。これらの列名は、結果セットの行ごとに繰り返されます。列値は引用符で囲まれた文字列、数値、または truefalsenull を表す特殊な値です。長さの制約、数値、文字列の正確な型などの列のメタデータは、JSON レスポンスでは保持されません。

.withFormatRecordsAs() 呼び出しを省略、または NONE のパラメータを指定した場合、結果セットは RecordscolumnMetadata のフィールドを使用してバイナリ形式で返されます。

データ型のマッピング

結果セットの SQL 値は、より小さい JSON 型のセットにマッピングされます。値は JSON で文字列、数値、および truefalsenull などの特殊な定数で表現されます。これらの値は、プログラミング言語に適した強い型付けまたは弱い型付けを使用して、アプリケーション内の変数に変換できます。

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 句を追加します。LIMITOFFSET の句を持つ複数のクエリを送信することで、大きな結果セットを複数の小さな結果セットに分割できます。

    アプリケーションロジックによって、結果セットにフィルタリングされた行が含まれている場合は、WHERE 句にさらに条件を追加することで、結果セットから該当の行を削除できます。

  • 結果セットの列数を減らします。これを行うには、クエリの選択リストから項目を削除します。

  • クエリで列エイリアスを使用することにより、列ラベルを短くします。各列名は、結果セット内の各行に対して JSON 文字列で繰り返されます。そのため、長い列名と多くの行を含むクエリ結果の場合、サイズ制限を超える可能性があります。特に、複雑な式には列のエイリアスを使用して、JSON 文字列で式全体が繰り返されないようにします。

  • SQL では、列のエイリアスを使用して同じ名前の列を複数持つ結果セットを作成できますが、JSON ではキー名の重複は許可されません。JSON 形式で結果セットをリクエストし、複数の列が同じ名前の場合、RDS データ API はエラーを返します。そのため、すべての列のラベルに一意の名前があることを確認します。

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

以下の 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 結果セットが存在するため、レスポンスの RecordsColumnMetadata フィールドは両方とも 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 値は、引用符で囲まれていない特殊キーワード truefalsenull で表されます。以下に、可能性のある 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>

Data API の問題のトラブルシューティング

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

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

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

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

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

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

  • 前回の呼び出しで、トランザクションが終了しました。

    トランザクションは、お客様の CommitTransaction または RollbackTransaction コールによってすでに終了しています。

  • 前回の呼び出しのエラーにより、トランザクションが中断されました。

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

トランザクションの実行については、「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> に対して有効になっていない

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

  • Data API が Aurora Serverless v1 DB クラスターに対して有効になっていません。Aurora Serverless v1 DB クラスターで Data API を使用するには、DB クラスターに対して Data API が有効になっている必要があります。Data API を有効にする方法については、「Data API の有効化」を参照してください。

  • Data API が有効になった後、DB クラスターの名前が変更されました。この場合は、クラスターの データ API を一度オフにしてから、再度有効にします。

  • 指定された ARN がクラスターの ARN と正確に一致しません。別のソースから返された ARN、またはプログラムロジックによって構築された ARN が、クラスターの ARN と正確に一致していることを確認します。例えば、使用する ARN は、アルファベットの大文字と小文字がすべて一致しているかを確認します。

DB クラスターに対して Data API が有効になっていない場合は有効にします。Aurora Serverless v1 クラスターであることを確認します。現在、Aurora Serverless v2 で データ API を使用することはできません。

DB クラスターに対して Data API が有効になってから DBクラスターの名前が変更された場合は、Data API を無効にしてから再度有効にします。

Data API を有効にする方法については、「Data API の有効化」を参照してください。