Aurora Serverless の Data API の使用 - Amazon Aurora

Aurora Serverless の Data API の使用

Aurora Serverless DB クラスターにアクセスするには、組み込みの Data API を使用します。この API を使用すると、ウェブサービスベースのアプリケーション(AWS Lambda、AWS AppSync、AWS Cloud9 など)を通じて Aurora Serverless にアクセスできます。これらのアプリケーションの詳細については、AWS LambdaAWS AppSyncAWS Cloud9 を参照してください。

Data API は、DB クラスターへの永続的な接続を必要としません。代わりに、セキュア HTTP エンドポイントおよび AWS SDK との統合を利用できます。エンドポイントを使用して、接続を管理せずに SQL ステートメントを実行することができます。Data API へのすべての呼び出しは同期的です。デフォルトでは、呼び出しは、45 秒以内に処理が完了しないと、タイムアウトになって終了します。continueAfterTimeout パラメータを使用して、呼び出しがタイムアウトした後も SQL ステートメントの実行を続けることができます。

API は、AWS Secrets Manager に保存されているデータベース認証情報を使用するため、API コールに認証情報を渡す必要はありません。API でも、AWS Lambda を安全に使用することができます。Virtual Private Cloud (VPC) 内のリソースにアクセスするように Lambda 関数を設定しなくても、DB クラスターにアクセスすることができます。AWS Secrets Manager の詳細については、AWS Secrets Manager ユーザーガイド の「AWS Secrets Manager とは」を参照してください。

注記

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

Data API の提供状況

Data API は、次の Aurora Serverless DB クラスターにのみ使用できます。

  • MySQL バージョン 5.6 と互換性のある Aurora

  • MySQL バージョン 5.7 と互換性のある Aurora

  • PostgreSQL バージョン 10.7 と互換性がある Aurora

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

リージョン リンク
アジアパシフィック (シンガポール) rds-data.ap-southeast-1.amazonaws.com
アジアパシフィック (シドニー) rds-data.ap-southeast-2.amazonaws.com
アジアパシフィック (東京) rds-data.ap-northeast-1.amazonaws.com
アジアパシフィック (ムンバイ) rds-data.ap-south-1.amazonaws.com
欧州 (フランクフルト) rds-data.eu-central-1.amazonaws.com
欧州 (アイルランド) rds-data.eu-west-1.amazonaws.com
欧州 (ロンドン) rds-data.eu-west-2.amazonaws.com
欧州 (パリ) rds-data.eu-west-3.amazonaws.com
米国東部(バージニア北部) rds-data.us-east-1.amazonaws.com
米国東部 (オハイオ) rds-data.us-east-2.amazonaws.com
米国西部 (北カリフォルニア) rds-data.us-west-1.amazonaws.com
米国西部 (オレゴン) rds-data.us-west-2.amazonaws.com

Data API へのアクセスの承認

ユーザーは Data API へのアクセスが許可されている必要があります。Data API へのユーザーのアクセスを承認するには、事前定義済みの AWS Identity and Access Management (IAM) のポリシーである AmazonRDSDataFullAccess ポリシーをユーザーに追加します。

Data API へのアクセス権を付与する IAM ポリシーを作成することもできます。作成したポリシーは、Data API にアクセスする必要がある各ユーザーに追加します。

次のポリシーでは、Data API にアクセスするための必要最低限のアクセス許可をユーザーに付与します。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "SecretsManagerDbCredentialsAccess", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:PutResourcePolicy", "secretsmanager:PutSecretValue", "secretsmanager:DeleteSecret", "secretsmanager:DescribeSecret", "secretsmanager:TagResource" ], "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*" }, { "Sid": "RDSDataServiceAccess", "Effect": "Allow", "Action": [ "secretsmanager:CreateSecret", "secretsmanager:ListSecrets", "secretsmanager:GetRandomPassword", "tag:GetResources", "rds-data:BatchExecuteStatement", "rds-data:BeginTransaction", "rds-data:CommitTransaction", "rds-data:ExecuteStatement", "rds-data:RollbackTransaction" ], "Resource": "*" } ] }

IAM ポリシーの作成方法については、IAM ユーザーガイド の「IAM ポリシーの作成」を参照してください。

IAM ポリシーをユーザーに追加する方法については、IAM ユーザーガイド の「IAM ID アクセス許可の追加および削除」を参照してください。

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 DB クラスターの作成」および「Aurora Serverless DB クラスターの変更」を参照してください。

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

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

次の例では、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 値を設定できます。

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

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

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

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

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

  2. AWS Secrets Manager コンソールを使用して、作成したシークレットの詳細を表示するか、AWS CLI の aws secretsmanager describe-secret コマンドを実行します。

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

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

Amazon Virtual Private Cloud (Amazon VPC) を使用すると、Aurora DB クラスターやアプリケーションなどの AWS リソースを仮想プライベートクラウド (VPC) 内に起動できます。AWS PrivateLink は、Amazon 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 マネジメントコンソールにサインインし、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 マネジメントコンソール でリンクを選択して、エンドポイントの詳細を表示します。


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

エンドポイントの [詳細] タブには、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 で DB クラスターに対して SQL ステートメントを実行します。Data API は、AWS SDK でサポートされているプログラミング言語をサポートしています。詳細については、「AWS で構築するツール」を参照してください。

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

FLOAT, REAL, DOUBLE

DOUBLE

DECIMAL

STRING

BOOLEAN, BIT

BOOLEAN

BLOB, BINARY, LONGVARBINARY, VARBINARY

BLOB

CLOB

STRING

その他の型 (日時に関する型も含む)

STRING

DECIMALTIME などの特定のタイプでは、String 値を異なるタイプとしてデータベースに渡す必要があることを Data API に指示するためのヒントが必要になる場合があります。これには、SqlParameter データ型の typeHint に値を含めます。typeHint に指定できる値は以下のとおりです。

  • DECIMAL – 対応する String パラメータ値は、DECIMAL タイプのオブジェクトとしてデータベースに送信されます。

  • TIMESTAMP – 対応する String パラメータ値は、TIMESTAMP タイプのオブジェクトとしてデータベースに送信されます。受け入れられる形式は YYYY-MM-DD HH:MM:SS[.FFF] です。

  • TIME – 対応する String パラメータ値は、TIME タイプのオブジェクトとしてデータベースに送信されます。受け入れられる形式は HH:MM:SS[.FFF] です。

  • DATE – 対応する String パラメータ値は、DATE タイプのオブジェクトとしてデータベースに送信されます。受け入れられる形式は YYYY-MM-DD です。

注記

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

注記

これらの例は完全なものではありません。

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

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

以下の例では、Data API で AWS CLI を使用しています。詳細については、「AWS Command Line Interface の Data API リファレンス」を参照してください。

各例で、DB クラスターの ARN を Aurora Serverless DB クラスターの ARN に置き換えます。また、シークレット ARN を AWS 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 MB です。1 MB を超えるレスポンスデータが返されると、その呼び出しは終了します。

たとえば、次の 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 ステートメント。

  • --transaction-id (オプション) – CLI の begin-transaction コマンドを使用して開始されたトランザクションの識別子。SQL ステートメントを含めるトランザクションのトランザクション ID を指定します。

  • --parameter-set (オプション) – バッチオペレーション用のパラメータセット。

  • --database (オプション) – データベースの名前。

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

注記

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

たとえば、次の 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 を AWS 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 Developer Guide を参照してください。

それぞれの例で、DB クラスターの Amazon リソースネーム(ARN)を Aurora Serverless DB クラスターの ARN に置き換えます。また、シークレット ARN を AWS 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.3</version> </dependency>

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

以下に、Data API Java クライアントライブラリを使用する一般的な例をいくつか示します。これらの例では、accountIdname の 2 つの列を含むテーブル accounts があることを前提としています。また、次のデータ転送オブジェクト(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)") .withParams(account1, account2) .execute();

場合によっては、単純な値を入力パラメータとして使用する方が簡単です。これには、次の構文を使用します。

client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)") .withParam("accountId", 3) .withParam("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 MB です。

この問題を解決するには、Data API への呼び出しで返るデータが 1 MB 以下になるようにします。1 MB を超えるデータを返す必要がある場合は、クエリで 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 の有効化」を参照してください。