Aurora Serverless の Data API の使用 - Amazon Aurora

Aurora Serverless の Data API の使用

Aurora Serverless の Data API を使用すると、Aurora Serverless 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 を他の 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 クラスターの作成時に有効にできます。後で設定を変更することもできます。詳細については、「Data API の有効化」を参照してください。

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

Data API の可用性

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

現在 AWS で Data API が利用可能な Aurora Serverless リージョンを次の表に示します。これらのリージョンで 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 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 の使用の詳細については、AWSAWS Secrets Manager ユーザーガイドを参照してください。

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

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

Data API の有効化

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

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

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


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

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

Aurora Serverless 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 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 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 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 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) ステートメントでは、エラーやデータ構造の破損の可能性を回避するために、呼び出しがタイムアウトした後もステートメントを実行し続けることをお勧めします。

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 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 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ファイルに次の依存関係を追加します。

<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>1.0.5</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);

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

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

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

この場合、Data API 呼び出しで指定されたトランザクション ID は見つかりませんでした。通常、この問題の原因は、以下のいずれかであることが考えられます。

  • 指定されたトランザクション ID は、BeginTransaction コールで作成されなかった。

  • 指定されたトランザクション ID は有効期限切れです。

    3 分以内にそのトランザクション ID を使用するコールがない場合、トランザクションは期限切れになります。

この問題を解決するには、呼び出しに有効なトランザクション ID があることを確認します。また、各トランザクションの呼び出しが、最後のトランザクション呼び出しから 3 分以内に実行されることを確認します。

トランザクションの実行については、「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 DB クラスターに対して有効になっていません。Aurora Serverless DB クラスターで Data API を使用するには、DB クラスターに対して Data API が有効になっている必要があります。

  • Data API が有効になった後、DB クラスターの名前が変更されました。

DB クラスターに対して Data API が有効になっていない場合は有効にします。

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

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