Data API でデータを使用する Data API の呼び出し時の考慮事項冪等性トークンを使用して SQL ステートメントを実行する

Amazon Redshift Data API の使用

組み込みの Amazon Redshift データ API を使用して、Amazon Redshift データベースにアクセスできます。この API を使用すると、AWS Lambda、Amazon SageMaker ノートブック、AWS Cloud9などのウェブサービスベースのアプリケーションで Amazon Redshift データにアクセスできます。これらのアプリケーションの詳細については、「AWS Lambda」、「Amazon SageMaker」、および「AWS Cloud9」を参照してください。

Data API は、データベースへの永続的な接続を必要としません。代わりに、セキュア HTTP エンドポイントおよび AWS SDK との統合を利用できます。エンドポイントを使用して、接続を管理せずに SQL ステートメントを実行することができます。Data API の呼び出しは非同期です。

Data API では、AWS Secrets Managerに格納された認証情報か、一時的なデータベース認証情報が使用されます。どちらの認証方法でも、API 呼び出しでパスワードを渡す必要はありません。AWS Secrets Manager の詳細については、AWS Secrets Managerユーザーガイドの「AWS Secrets Manager とは」を参照してください。

Data API オペレーションの詳細については、Amazon Redshift Data API のリファレンスを参照してください。

Amazon Redshift Data API の操作

Amazon Redshift データ API を使用する前に、以下の手順を確認してください。

データ API の呼び出し元として承認されているかどうかを確認します。認証の詳細については、「Amazon Redshift Data API へのアクセスの認可」を参照してください。
Secrets Manager から認証情報を使用してデータ API を呼び出すか、一時的に認証情報を使用するかを決定します。詳細については、「Amazon Redshift Data API を呼び出すときのデータベース認証用の認証情報の選択」を参照してください。
認証情報に Secrets Manager を使用する場合は、シークレットを設定します。詳細については、「AWS Secrets Manager へのデータベース認証情報の保存」を参照してください。
Data API を呼び出す際の考慮事項と制限事項を確認してください。詳細については、「Amazon Redshift Data API を呼び出す際の考慮事項」を参照してください。
Data API は、AWS Command Line Interface(AWS CLI) や独自のコードから、または Amazon Redshift コンソールのクエリエディタを使用して呼び出します。AWS CLI からの呼び出しの例については、「Data API の呼び出し」を参照してください。

Amazon Redshift Data API を呼び出す際の考慮事項

Data API を呼び出すときは、以下について検討します。

Amazon Redshift Data API は、Amazon Redshift のプロビジョニング済みクラスターと Redshift Serverless ワークグループのデータベースにアクセスできます。Redshift Data API を利用可能な AWS リージョンの一覧については、Amazon Web Services 全般のリファレンスの「Redshift Data API」のエンドポイントのリストをご覧ください。
クエリの最大期間は 24 時間です。
アクティブなクエリの最大数 (STARTED および SUBMITTED クエリ) は、Amazon Redshift クラスターあたり 200 です。
クエリ結果の最大サイズは 100 MB (gzip 圧縮後) です。100 MB を超えるレスポンスデータが返されると、その呼び出しは終了します。
クエリ結果の最大保持時間は 24 時間です。
クエリステートメントの最大サイズは 100 KB です。
Data API は、次のノードタイプの単一ノードおよび複数ノードのクラスターを照会するために使用できます。
- dc2.large
- dc2.8xlarge
- ds2.xlarge
- ds2.8xlarge
- ra3.xlplus
- ra3.4xlarge
- ra3.16xlarge
クラスターは、Amazon VPC サービスに基づいて Virtual Private Cloud (VPC) で作成する必要があります。
デフォルトでは、ExecuteStatement または BatchExecuteStatement API オペレーションの実行者と同じ IAM ロールまたは IAM アクセス許可を持つユーザーは、CancelStatement、DescribeStatement、GetStatementResult および ListStatements API オペレーションで同じステートメントを操作できます。別のユーザーから同じ SQL ステートメントを操作する場合、そのユーザーは、SQL ステートメントを実行したユーザーの IAM ロールを引き受ける必要があります。ロールを割り当てる方法については、Amazon Redshift Data API へのアクセスの認可を参照してください。
BatchExecuteStatement API オペレーションの Sqls パラメータで SQL ステートメントが単一のトランザクションとして実行されます。これらは、配列の順に従って連続的に実行されます。後続の SQL ステートメントは、配列内の前のステートメントが完了するまで開始されません。SQL ステートメントが失敗した場合、1 つのトランザクションとして実行されるため、すべての作業がロールバックされます。
ExecuteStatement または BatchExecuteStatement API オペレーションで使用されるクライアントトークンの最大保持時間は 8 時間です。
Redshift Data API の各 API には、リクエストのスロットリング前の 1 秒あたりのトランザクション割り当てがあります。クォータについては、「Amazon Redshift Data API のクォータ」を参照してください。リクエスト率がクォータを超えると、HTTP ステータスコード: 400 の ThrottlingException が返されます。スロットリングに対応するには、「AWS SDK とツールリファレンスガイド」の「再試行動作」で説明されている再試行戦略を使用します。AWS SDK によっては、この戦略が HTTP 400 エラー用に自動的に実装されています。
注記
AWS Step Functions では、再試行がデフォルトでは有効になっていません。Step Functions ステートマシンで Redshift データ API を呼び出す場合は、Redshift データ API コールに ClientToken 冪等性パラメータを含める必要があります。この ClientToken の値は、再試行の間も維持する必要があります。次の ExecuteStatement API へのリクエストの例では、States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7) 式は、組み込み関数を使用してステートマシンが実行されるたびに一意となる $$.Execution.Id の UUID 部分を抽出します。詳細については、「AWS Step Functions デベロッパーガイド」の「組み込み関数」を参照してください。
```
{
  "Database": "dev",
  "Sql": "select 1;",
  "ClusterIdentifier": "MyCluster",
  "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```

Amazon Redshift Data API を呼び出すときのデータベース認証用の認証情報の選択

データ API を呼び出すと、一部の API 操作で次のいずれかの認証方法を使用します。各メソッドでは、異なるパラメータの組み合わせが必要です。

AWS Secrets Manager

この方法では、username および password を持つ AWS Secrets Manager が格納されるシークレットの secret-arn を指定します。指定されたシークレットには、指定する database に接続するための認証情報が含まれます。クラスターに接続するときは、データベース名も指定します。クラスター識別子 (dbClusterIdentifier) を指定する場合は、シークレット内に格納されているクラスター識別子と一致する必要があります。サーバーレスワークグループに接続する場合は、データベース名も指定します。詳細については、「AWS Secrets Manager へのデータベース認証情報の保存」を参照してください。

一時的な認証情報

この方法を実行する場合は、次のいずれかのオプションを選択します。

サーバーレスワークグループに接続する場合は、ワークグループ名とデータベース名を指定します。データベースユーザー名は IAM ID から取得されます。例えば、arn:iam::123456789012:user:foo のデータベースユーザー名は IAM:foo です。また、redshift-serverless:GetCredentials オペレーションを呼び出す許可も必要です。
IAM ID としてクラスターに接続するときは、クラスター識別子とデータベース名を指定します。データベースユーザー名は IAM ID から取得されます。例えば、arn:iam::123456789012:user:foo のデータベースユーザー名は IAM:foo です。また、redshift:GetClusterCredentialsWithIAM オペレーションを呼び出す許可も必要です。
データベースユーザーとしてクラスターに接続するときは、クラスター識別子、データベース名、データベースユーザー名を指定します。また、redshift:GetClusterCredentials オペレーションを呼び出す許可も必要です。この方法で接続するときにデータベースグループに参加する方法については、「クラスターへの接続時にデータベースグループに参加する」を参照してください。

また、これらの方法でも、データが配置されている AWS リージョンを特定する region 値を指定できます。

Amazon Redshift データ API を呼び出すときの JDBC データ型のマッピング

次の表は、Data API 呼び出しで指定したデータ型に Java Database Connectivity (JDBC) データ型をマッピングしたものです。

JDBC データ型	Data API のデータ型
`INTEGER, SMALLINT, BIGINT`	`LONG`
`FLOAT, REAL, DOUBLE`	`DOUBLE`
`DECIMAL`	`STRING`
`BOOLEAN, BIT`	`BOOLEAN`
`BLOB, BINARY, LONGVARBINARY, VARBINARY`	`BLOB`
`VARBINARY`	`STRING`
`CLOB`	`STRING`
その他の型 (日時に関する型も含む)	`STRING`

文字列値は Amazon Redshift データベースに渡され、暗黙的にデータベースのデータ型に変換されます。

注記

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

Amazon Redshift Data API を呼び出す際にパラメータを使用した SQL ステートメントを実行する

SQL ステートメントの一部にパラメータを使用して Data API オペレーションを呼び出し、データベースエンジンに送信される SQL テキストを制御できます。名前付きパラメータを使用すると、SQL テキストでハードコーディングすることなく、柔軟な方法でパラメータを渡すことができます。これらは、SQL テキストを再利用し、SQL インジェクションの問題を回避するのに役立ちます。

次の例では、execute-statementAWS CLI コマンドにおける parameters フィールドの名前付きパラメータを示しています。


--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"

名前付きパラメータを使用する際は、次について検討します。

名前付きパラメータは、SQL ステートメントの値の置換にのみ使用できます。
- INSERT INTO mytable VALUES(:val1) など、INSERT ステートメントの値は置換することができます。
  
  名前付きパラメータは任意の順序で指定でき、パラメータは SQL テキストで複数回使用できます。前の例で示したパラメータオプションでは、値 1 および Seattle がテーブル列 id および address に挿入されます。SQL テキストでは、次のように名前付きパラメータを指定します。
```
--sql "insert into mytable values (:id, :address)"
```
- WHERE attr >= :val1、WHERE attr BETWEEN :val1 AND :val2、HAVING COUNT(attr) > :val など、条件句の値は置換することができます。
- SELECT column-name、ORDER BY column-name、または GROUP BY column-name など、SQL ステートメントの列名は置換できません。
  
  例えば、次の SELECT ステートメントは無効な構文なので失敗します。
```
--sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"
```
  構文エラーのあるステートメントを記述 (describe-statement オペレーション) した場合、返される QueryString はパラメータ ("QueryString": "SELECT :colname, FROM event") の列名を置換せず、エラーが報告されます (ERROR: syntax error at or near \"FROM\"\n Position: 12)。
- COUNT(column-name)、AVG(column-name)、または SUM(column-name) などの集計関数では、列名を置換できません。
- JOIN 句の列名は置換できません。
SQL が実行されると、データは暗黙的にデータ型にキャストされます。データ型のキャストのついての詳細は、Amazon Redshift データベースデベロッパーガイドの「データ型」を参照してください。
値を NULL に設定することはできません。データ API では、これはリテラル文字列 NULL として解釈されます。次の例では、idがリテラル文字列 null に置き換えられます。SQL NULL 値ではありません。
```
--parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
```
長さにゼロの値を設定することはできません。Data API の SQL ステートメントが失敗します。次の例では、idの長さをゼロの値に設定しようとしているため、SQL ステートメントは失敗します。
```
--parameters "[{\"name\": \"id\", \"value\": \"\"}]"
```
パラメータを使用して、SQL ステートメントにテーブル名を設定することはできません。Data API では、JDBC PreparedStatement のルールに従います。
describe-statement オペレーションの出力により、SQL ステートメントのクエリパラメータが返されます。
パラメータを使用した SQL ステートメントをサポートするのは、execute-statementオペレーションのみです。

Amazon Redshift Data API を呼び出す際に冪等性トークンで SQL ステートメントを実行する

変異する API リクエストを行うと、通常、リクエストはオペレーションの非同期ワークフローが完了する前に結果を返します。リクエストが既に結果を返している場合でも、操作が完了する前にタイムアウトしたり、その他のサーバーの問題が発生したりすることもあります。これにより、リクエストが成功したかどうかを判断するのが難しくなり、操作を正常に完了するために複数回の再試行が行われることがあります。ただし、元のリクエストとその後の再試行が成功すると、操作は複数回完了します。つまり、意図したよりも多くのリソースを更新する可能性があります。

冪等性とは、API リクエストが 1 回だけ完了することを保証するものです。冪等性リクエストでは、元のリクエストが正常に完了した場合、その後の再試行は追加のアクションを実行せずに正しく完了します。データ API ExecuteStatement と BatchExecuteStatement オペレーションには、オプションの ClientToken 冪等性パラメータがあります。ClientToken は 8 時間後に期限切れになります。

重要

AWS SDK から ExecuteStatement および BatchExecuteStatement オペレーションを呼び出すと、再試行時に使用するクライアントトークンが自動的に生成されます。この場合、ExecuteStatement および BatchExecuteStatement オペレーションで client-token パラメータを使用することはお勧めしません。CloudTrail のログを表示すると ClientToken を確認できます。CloudTrail ログの例については、「Amazon Redshift Data API の例」を参照してください。

次の execute-statement AWS CLI コマンドは、冪等性のオプション client-token パラメータを示しています。



aws redshift-data execute-statement 
    --region us-west-2 
    --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn 
    --cluster-identifier mycluster-test 
    --sql "select * from stl_query limit 1" 
    --database dev 
    --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1

次の表は、冪等性 API リクエストに対して返される一般的な応答と、再試行の推奨事項を示しています。

レスポンス	推奨事項	コメント
200 (OK)	再試行しないでください	元のリクエストは正しく完了しています。それ以降に再試行しても正常に戻ります。
400 シリーズ応答コード	再試行しないでください	次のうち、リクエストに問題があります。無効なパラメータまたはパラメータの組み合わせが含まれています。権限のないアクションまたはリソースを使用しています。状態の変更処理中のリソースを使用しています。リクエストに状態の変更処理中のリソースが含まれている場合、リクエストを再試行すると成功する可能性があります。
500 シリーズ応答コード	再試行	このエラーは AWS サーバー側の問題によって発生し、通常は一時的なものです。適切なバックオフ戦略でリクエストを繰り返してください。

レスポンス

推奨事項

200 (OK)

再試行しないでください

元のリクエストは正しく完了しています。それ以降に再試行しても正常に戻ります。

400 シリーズ応答コード

再試行しないでください

次のうち、リクエストに問題があります。

無効なパラメータまたはパラメータの組み合わせが含まれています。
権限のないアクションまたはリソースを使用しています。
状態の変更処理中のリソースを使用しています。

リクエストに状態の変更処理中のリソースが含まれている場合、リクエストを再試行すると成功する可能性があります。

500 シリーズ応答コード

再試行

このエラーは AWS サーバー側の問題によって発生し、通常は一時的なものです。適切なバックオフ戦略でリクエストを繰り返してください。

Amazon Redshift 応答コードの詳細については、「Amazon Redshift API リファレンス」から「一般的なエラー」を参照してください。

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

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

ドキュメントの表記規則

JDBC フェッチサイズパラメータの設定

アクセスの承認