Amazon Redshift は、パッチ 198 以降、新しい Python UDF の作成をサポートしなくなります。既存の Python UDF は、2026 年 6 月 30 日まで引き続き機能します。詳細については、[ブログ記事](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)を参照してください。
# Amazon Redshift Data API の使用
Amazon Redshift Data API は、データベースドライバー、接続、ネットワーク設定、データバッファリング、認証情報などを管理する必要がなくなるため、Amazon Redshift データウェアハウスへのアクセスを簡素化します。AWS SDK で Data API オペレーションを使用して SQL ステートメントを実行できます。Data API オペレーションの詳細については、[Amazon Redshift Data API のリファレンス](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)を参照してください。
Data API は、データベースへの永続的な接続を必要としません。代わりに、セキュア HTTP エンドポイントおよび AWS SDK との統合を利用できます。エンドポイントを使用して、接続を管理せずに SQL ステートメントを実行することができます。Data API の呼び出しは非同期です。Data API では、AWS Secrets Manager に格納された認証情報か、一時的なデータベース認証情報を使用できます。どちらの認可方法でも、API 呼び出しでパスワードを渡す必要はありません。AWS Secrets Manager の詳細については、*AWS Secrets Managerユーザーガイド*の「[AWS Secrets Manager とは](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)」を参照してください。認可に AWS IAM アイデンティティセンター を使用することもできます。
Data API を使用すると、AWS Lambda、Amazon SageMaker AI ノートブック、AWS Cloud9 などのウェブサービスベースのアプリケーションで、Amazon Redshift のデータにプログラムによってアクセスできます。これらのアプリケーションの詳細については、「[AWS Lambda](https://aws.amazon.com/lambda/)」、「[Amazon SageMaker AI](https://aws.amazon.com/sagemaker/)」、「[AWS Cloud9](https://aws.amazon.com/cloud9/)」を参照してください。
Data API の詳細については、「*AWS Big Data ブログ*」の「[Get started with the Amazon Redshift Data API](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/)」を参照してください。
## Amazon Redshift Data API の操作
Amazon Redshift データ API を使用する前に、以下の手順を確認してください。
1. データ API の呼び出し元として承認されているかどうかを確認します。認可の詳細については、「[Amazon Redshift Data API へのアクセスの認可](data-api-access.md)」を参照してください。
1. Secrets Manager から認証情報を使用して Data API を呼び出すか、一時的な認証情報を使用するか、または AWS IAM アイデンティティセンター を使用するかを決定します。詳細については、「[Amazon Redshift Data API を呼び出すときのデータベース認証用の認証情報の選択](#data-api-calling-considerations-authentication)」を参照してください。
1. 認証情報に Secrets Manager を使用する場合は、シークレットを設定します。詳細については、「[AWS Secrets Manager へのデータベース認証情報の保存](data-api-secrets.md)」を参照してください。
1. Data API を呼び出す際の考慮事項と制限事項を確認してください。詳細については、「[Amazon Redshift Data API を呼び出す際の考慮事項](#data-api-calling-considerations)」を参照してください。
1. Data API は、AWS Command Line Interface(AWS CLI) や独自のコードから、または Amazon Redshift コンソールのクエリエディタを使用して呼び出します。AWS CLI からの呼び出しの例については、「[Data API の呼び出し](data-api-calling.md)」を参照してください。
## Amazon Redshift Data API を呼び出す際の考慮事項
Data API を呼び出すときは、以下について検討します。
+ Amazon Redshift Data API は、Amazon Redshift のプロビジョニング済みクラスターと Redshift Serverless ワークグループのデータベースにアクセスできます。Redshift Data API を利用可能な AWS リージョン の一覧については、*Amazon Web Services 全般のリファレンス*の「[Redshift Data API](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html)」のエンドポイントのリストをご覧ください。
+ クエリの最大期間は 24 時間です。
+ アクティブなクエリの最大数 (`STARTED` および `SUBMITTED` クエリ) は、Amazon Redshift クラスターあたり 500 です。
+ クエリ結果の最大サイズは 500 MB (gzip 圧縮後) です。500 MB を超えるレスポンスデータが返されると、その呼び出しは終了します。
+ クエリ結果の最大保持時間は 24 時間です。
+ クエリステートメントの最大サイズは 100 KB です。
+ Data API は、次のノードタイプの単一ノードおよび複数ノードのクラスターを照会するために使用できます。
+ dc2.large
+ dc2.8xlarge
+ ra3.large
+ ra3.xlplus
+ ra3.4xlarge
+ ra3.16xlarge
+ クラスターは、Amazon VPC サービスに基づいて Virtual Private Cloud (VPC) で作成する必要があります。
+ デフォルトでは、`ExecuteStatement` または `BatchExecuteStatement` API オペレーションの実行者と同じ IAM ロールを持つユーザーは `CancelStatement`、`DescribeStatement`、`GetStatementResult`、`GetStatementResultV2`、および `ListStatements` API オペレーションで同じステートメントを操作できます。別のユーザーから同じ SQL ステートメントを操作する場合、そのユーザーは、SQL ステートメントを実行したユーザーの IAM ロールを引き受ける必要があります。ロールを割り当てる方法については、[Amazon Redshift Data API へのアクセスの認可](data-api-access.md)を参照してください。
+ `BatchExecuteStatement` API オペレーションの `Sqls` パラメータで SQL ステートメントが単一のトランザクションとして実行されます。これらは、配列の順に従って連続的に実行されます。後続の SQL ステートメントは、配列内の前のステートメントが完了するまで開始されません。SQL ステートメントが失敗した場合、1 つのトランザクションとして実行されるため、すべての作業がロールバックされます。
+ `ExecuteStatement` または `BatchExecuteStatement` API オペレーションで使用されるクライアントトークンの最大保持時間は 8 時間です。
+ Amazon Redshift でプロビジョニングされたクラスターと Redshift Serverless ワークグループがカスタマーマネージドキーを使用して暗号化されている場合、Redshift は Redshift Data API がオペレーションにキーを使用できるようにする許可を作成します。詳細については、 [Amazon Redshift Data API で AWS KMS を使用する](data-api-kms.md) を参照してください。
+ Redshift Data API の各 API には、リクエストのスロットリング前の 1 秒あたりのトランザクション割り当てがあります。クォータについては、「[Amazon Redshift Data API のクォータ](amazon-redshift-limits.md#data-api-quotas-account)」を参照してください。リクエスト率がクォータを超えると、HTTP ステータスコード: 400 の `ThrottlingException` が返されます。スロットリングに対応するには、「**AWS SDK とツールリファレンスガイド」の「[再試行動作](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)」で説明されている再試行戦略を使用します。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 デベロッパーガイド」の「[組み込み関数](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html)」を参照してください。
```
{
"Database": "dev",
"Sql": "select 1;",
"ClusterIdentifier": "MyCluster",
"ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```
## Amazon Redshift Data API を呼び出すときのデータベース認証用の認証情報の選択
データ API を呼び出すと、一部の API 操作で次のいずれかの認証方法を使用します。各メソッドでは、異なるパラメータの組み合わせが必要です。
**AWS IAM アイデンティティセンター**
Data API は、AWS IAM アイデンティティセンター に登録されたシングルサインオンユーザーでアクセスできます。IAM アイデンティティセンターの設定手順については、「[信頼できる ID の伝播で Data API を使用する](data-api-trusted-identity-propagation.md)」を参照してください。
**AWS Secrets Manager**
この方法では、`username` および `password` を持つ AWS Secrets Manager が格納されるシークレットの `secret-arn` を指定します。指定されたシークレットには、指定する `database` に接続するための認証情報が含まれます。クラスターに接続するときは、データベース名も指定します。クラスター識別子 (`dbClusterIdentifier`) を指定する場合は、シークレット内に格納されているクラスター識別子と一致する必要があります。サーバーレスワークグループに接続する場合は、データベース名も指定します。詳細については、「[AWS Secrets Manager へのデータベース認証情報の保存](data-api-secrets.md)」を参照してください。
またこの方法では、データが配置されている AWS リージョン を特定する `region` 値も指定できます。
**一時的な認証情報**
この方法を実行する場合は、次のいずれかのオプションを選択します。
+ サーバーレスワークグループに接続する場合は、ワークグループ名とデータベース名を指定します。データベースユーザー名は 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` オペレーションを呼び出す許可も必要です。この方法で接続するときにデータベースグループに参加する方法については、「[クラスターへの接続時にデータベースグループに参加する](data-api-dbgroups.md)」を参照してください。
またこの方法では、データが配置されている 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` | `BLOB` |
| `VARBINARY` | `STRING` |
| `CLOB` | `STRING` |
| その他の型 (日時に関する型も含む) | `STRING` |
文字列値は Amazon Redshift データベースに渡され、暗黙的にデータベースのデータ型に変換されます。
**注記**
現在、Data API はユニバーサル固有識別子 (UUID) の配列をサポートしていません。
## Amazon Redshift Data API を呼び出す際にパラメータを使用した SQL ステートメントを実行する
SQL ステートメントの一部にパラメータを使用して Data API オペレーションを呼び出し、データベースエンジンに送信される SQL テキストを制御できます。名前付きパラメータを使用すると、SQL テキストでハードコーディングすることなく、柔軟な方法でパラメータを渡すことができます。これらは、SQL テキストを再利用し、SQL インジェクションの問題を回避するのに役立ちます。
次の例では、`execute-statement`AWS 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 \$1"FROM\$1"\$1n Position: 12)。
+ `COUNT(column-name)`、`AVG(column-name)`、または `SUM(column-name)` などの集計関数では、列名を置換できません。
+ JOIN 句の列名は置換できません。
+ SQL が実行されると、データは暗黙的にデータ型にキャストされます。データ型のキャストのついての詳細は、*Amazon Redshift データベースデベロッパーガイド*の「[データ型](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)」を参照してください。
+ 値を 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 の例](logging-with-cloudtrail.md#data-api-cloudtrail)」を参照してください。
次の `execute-statement` AWS CLI コマンドは、冪等性のオプション `client-token` パラメータを示しています。
```
aws redshift-data execute-statement
--secret-arn 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 シリーズ応答コード | 再試行しないでください | 次のうち、リクエストに問題があります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/redshift/latest/mgmt/data-api.html) リクエストに状態の変更処理中のリソースが含まれている場合、リクエストを再試行すると成功する可能性があります。 |
| 500 シリーズ応答コード | 再試行 | このエラーは AWS サーバー側の問題によって発生し、通常は一時的なものです。適切なバックオフ戦略でリクエストを繰り返してください。 |
Amazon Redshift 応答コードの詳細については、「*Amazon Redshift API リファレンス*」から「[一般的なエラー](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html)」を参照してください。
## Amazon Redshift Data API を呼び出す際にセッションの再利用によって SQL ステートメントを実行する
API リクエストを実行して SQL ステートメントを実行すると、通常、SQL が実行されているセッションは SQL の完了時に終了します。指定された秒数だけセッションをアクティブにするために、Data API `ExecuteStatement` および `BatchExecuteStatement` オペレーションにはオプションの `SessionKeepAliveSeconds` パラメータがあります。`SessionId` レスポンスフィールドにはセッションのアイデンティティが含まれており、後続の `ExecuteStatement` および `BatchExecuteStatement` オペレーションで使用できます。それ以降の呼び出しでは、別の `SessionKeepAliveSeconds` を指定してアイドルタイムアウト時間を変更できます。`SessionKeepAliveSeconds` が変更されていない場合、最初のアイドルタイムアウト設定は残ります。セッションの再利用を使用する場合は、次の点を考慮してください。
+ `SessionKeepAliveSeconds` の最大値は 24 時間です。
+ セッションは最大 24 時間持続します。24 時間後、セッションは強制的に閉じられ、進行中のクエリは終了します。
+ Amazon Redshift クラスターまたは Redshift Serverless ワークグループあたりのセッションの最大数は 500 です。
+ セッションごとに 1 つのクエリしか実行できません。同じセッションで次のクエリを実行するには、クエリが完了するまで待つ必要があります。つまり、指定されたセッションでクエリを並行して実行することはできません。
+ Data API は、特定のセッションのクエリをキューに入れることはできません。
`ExecuteStatement` および `BatchExecuteStatement` オペレーションの呼び出しで使用される `SessionId` を取得するには、`DescribeStatement` および `ListStatements` オペレーションを呼び出します。
次の例は、`SessionKeepAliveSeconds` および `SessionId` パラメータを使用してセッションを存続させ、再利用する方法を示しています。まず、オプションの `session-keep-alive-seconds` パラメータを `2` に設定して `execute-statement` AWS CLI コマンドを呼び出します。
```
aws redshift-data execute-statement
--session-keep-alive-seconds 2
--sql "select 1"
--database dev
--workgroup-name mywg
```
応答にはセッションの識別子が含まれます。
```
{
"WorkgroupName": "mywg",
"CreatedAt": 1703022996.436,
"Database": "dev",
"DbUser": "awsuser",
"Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
"SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}
```
次に、最初の呼び出しから返された `SessionId` を使用して `execute-statement` AWS CLI コマンドを呼び出します。オプションで、`session-keep-alive-seconds` パラメータを `10` に設定してアイドルタイムアウト値を変更します。
```
aws redshift-data execute-statement
--sql "select 1"
--session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
--session-keep-alive-seconds 10
```
## SQL ステートメントの結果を取得する
結果の形式に応じて異なる Data API オペレーションを使用して、SQL 結果を取得します。`ExecuteStatement` および `BatchExecuteStatement` オペレーションを呼び出すときに、結果の形式を JSON と CSV のどちらにするかを指定できます。未指定の場合は、デフォルトで JSON になります。JSON 形式で結果を取得するには、`GetStatementResult` オペレーションを使用します。CSV 形式で結果を取得するには、`GetStatementResultV2` オペレーションを使用します。
JSON 形式で返される結果は、各列に関するメタデータを含むレコードです。各レコードは JSON 形式です。例えば、`GetStatementResult` からのレスポンスは次のようになります。
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"longValue": 1
}
]
],
"TotalNumRows":
}
```
CSV 形式で返される結果は、各列に関するメタデータを含むレコードです。結果は 1 MB のチャンクで返され、各チャンクには任意の数の行が CSV 形式で含まれます。各リクエストは、最大 15 MB 分の結果を返します。結果が 15 MB を上回る場合は、結果の取得を続行できるように、次のページトークンが返されます。例えば、`GetStatementResultV2` からのレスポンスは次のようになります。
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk
},
{
"CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk
}
...
]
],
"ResultFormat" : "CSV",
"TotalNumRows":
}
```
# Amazon Redshift Data API へのアクセスの認可
ユーザーは Data API へのアクセスが許可されている必要があります。事前定義済みの AWS Identity and Access Management (IAM) ポリシーである管理ポリシーをユーザーに追加して、ユーザーに Data API へのアクセスを許可できます。ベストプラクティスとして、アクセス許可ポリシーを IAM ロールにアタッチし、それを必要に応じてユーザーやグループに割り当てることをお勧めします。詳細については、「[Amazon Redshift での Identity and Access Management](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)」を参照してください。マネージドポリシーによって許可および拒否されるアクセス許可を確認するには、IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) 参照してください。
# IAM 許可の設定
Amazon Redshift は、`AmazonRedshiftDataFullAccess`マネージドポリシーを提供します。このポリシーは、Amazon Redshift Data API オペレーションへのフルアクセスを提供します。このポリシーでは、Amazon Redshift クラスターまたは Redshift Serverless ワークグループの認証とアクセスに必要な特定の Amazon Redshift、AWS Secrets Manager、IAM API オペレーションへのスコープ付きアクセスも許可されます。
特定のリソースへのアクセスを許可する独自の IAM ポリシーを作成することもできます。ポリシーを作成するには、`AmazonRedshiftDataFullAccess`ポリシーを開始テンプレートとして使用します。作成したポリシーは、Data API にアクセスする必要がある各ユーザーに追加します。
ユーザーに関連付けられた IAM ポリシーの以下の要件を考慮してください。
+ AWS Secrets Manager を使用して認証する場合、ポリシーでは `secretsmanager:GetSecretValue` アクションの使用が許可され、キー `RedshiftDataFullAccess` でタグ付けされたシークレットを取得できることを確認します。
+ 一時的な認証情報を使用してクラスターに対して認証する場合、ポリシーでは、クラスター内の任意のデータベースのデータベースユーザー名 `redshift_data_api_user` に対する `redshift:GetClusterCredentials` アクションの使用が許可されることを確認します。このユーザー名は、データベースにすでに作成されている必要があります。
+ 一時的な認証情報を使用してサーバーレスワークグループへの認証を行う場合は、ポリシーで `redshift-serverless:GetCredentials` キーでタグ付けされたワークグループを取得するための `RedshiftDataFullAccess` アクションの使用が許可されていることを確認します。データベースユーザーが、ソース AWS Identity and Access Management (IAM) ID に対して 1:1 にマップされています。例えば、ユーザー sample\$1user はデータベースユーザー `IAM:sample_user` にマップされ、IAM ロール sample\$1role は `IAMR:sample_role` にマップされます。IAM ID の詳細については、「IAM ユーザーガイド」の「[IAM ID (ユーザー、ユーザーグループ、ロール)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html)」を参照してください。
+ IAM アクション `redshift-data:GetStatementResult` は、`GetStatementResult` および `GetStatementResultV2` API オペレーションの両方へのアクセスを許可します。
次のリンクから、*IAM ユーザーガイド*で AWS Identity and Access Management についての詳細情報をご覧いただけます。
+ IAM ロールの作成については、「[IAM ロールの作成](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)」を参照してください。
+ IAM ポリシーの作成については、「[IAM ポリシーの作成](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)」を参照してください。
+ IAM ポリシーをユーザーに追加する方法については、「[IAM ID のアクセス許可の追加および削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)」を参照してください。
## 別のアカウントが所有するクラスターでクエリを実行する
別のアカウントが所有するクラスターでクエリを実行するには、呼び出すアカウントで Data API がロールを引き受けることができる IAM ロールを所有アカウントより提供してもらう必要があります。例えば、アカウント A がアクセスする必要のあるクラスターを、アカウント B が所有しているとします。アカウント B は、AWS マネージドポリシーの `AmazonRedshiftDataFullAccess` をアカウント B の IAM ロールにアタッチできます。次に、アカウント B は、次のような信頼ポリシーを使用してアカウント A を信頼します: ``
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/someRoleA"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
最後に、アカウント A の IAM ロールでアカウント B の IAM ロールを引き受けることができなければなりません。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/someRoleB"
}
}
```
------
## AWS アカウント 内のリソースを Amazon Redshift Serverless ワークグループおよび Amazon Redshift クラスターに制限する IAM ロールを指定します。
アイデンティティベースのポリシーでリソース ARN を指定して、AWS アカウントの Redshift Serverless ワークグループと Amazon Redshift クラスターへのアクセスを制御できます。この例では、指定した AWS アカウントのワークグループとクラスターのみに対して Data API へのアクセスを許可するポリシーを作成する方法を示します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "redshift-data:*",
"Resource": [
"arn:aws:redshift:us-east-1:111122223333:workgroup/*",
"arn:aws:redshift:us-east-1:111122223333:cluster:*"
]
}
]
}
```
------
## SQL ステートメント情報へのアクセスをステートメント所有者のみに制限する IAM ポリシーを設定する
デフォルトでは、Amazon Redshift Data API は、`ExecuteStatement` および `BatchExecuteStatement` を呼び出すときに使用される IAM ロールを SQL ステートメントの所有者として扱います。ロールを引き受けることが許可されているユーザーは、結果を含む SQL ステートメントに関する情報にアクセスできます。特定の所有者との IAM ロールセッションへの SQL ステートメント情報アクセスを制限するには、条件 `redshift-data:statement-owner-iam-userid: "${aws:userid}"` を追加します。次の IAM ポリシーは、アクセスを制限します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:statement-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
`statement-owner-iam-userid` 条件は `CancelStatement`、`DescribeStatement`、`GetStatementResult`、および `ListStatements` で使用することができます。詳細については、「[Amazon Redshift Data API で定義されるアクション](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)」を参照してください。
## SQL 結果へのアクセスをセッション所有者のみに制限する IAM ポリシーを設定する
デフォルトでは、Amazon Redshift Data API は、`ExecuteStatement` と `BatchExecuteStatement` を呼び出すときに使用される IAM ロールを、SQL ステートメントを実行するデータベースセッションの所有者として扱います。ロールを引き受けることが許可されているユーザーは、データベースセッションにクエリを送信できます。特定の所有者との IAM ロールセッションへのセッションアクセスを制限するには、条件 ` redshift-data:session-owner-iam-userid: "${aws:userid}"` を追加します。次の IAM ポリシーは、アクセスを制限します。
次の IAM ポリシーでは、セッション所有者のみがステートメントの結果を取得できます。条件 `session-owner-iam-userid` は、指定された `userid` へのリソースアクセスを制限するために使用されます。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:ExecuteStatement",
"redshift-data:BatchExecuteStatement"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:session-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
`ExecuteStatement` および `BatchExecuteStatement` で `session-owner-iam-userid` 条件を使用することができます。詳細については、「[Amazon Redshift Data API で定義されるアクション](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)」を参照してください。
# AWS Secrets Manager へのデータベース認証情報の保存
Data API を呼び出すと、AWS Secrets Manager のシークレットを使用してクラスターまたはサーバーレスワークグループの認証情報を渡すことができます。この方法で認証情報を渡すには、シークレットの名前またはシークレットの Amazon リソースネーム (ARN) を指定します。
Secrets Manager で認証情報を保存するには、`SecretManagerReadWrite`マネージドポリシー権限が必要です。最小のアクセス許可についての詳細は、*AWS Secrets Managerユーザーガイド*の「[Creating and Managing Secrets with AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)」を参照してください。
**Amazon Redshift クラスターのシークレットに認証情報を保存するには**
1. AWS Secrets Manager コンソールを使用して、クラスターの認証情報が含まれるシークレットを作成します。
+ [**Store a new secret (新しいシークレットを保存する)**] を選択する場合は、[**Credentials for Redshift cluster (Redshift クラスターの認証情報)**]を選択します。
+ **[User name]** (ユーザー名) (データベースユーザー)、**[Password]** (パスワード)、および **[DB cluster]** (DB クラスター) (クラスター識別子) の値をシークレットに保存します。
+ キー `RedshiftDataFullAccess` でシークレットにタグを付けます。AWS マネージドポリシーの `AmazonRedshiftDataFullAccess` は、キー `RedshiftDataFullAccess` でタグ付けされたシークレットに対してのみアクション `secretsmanager:GetSecretValue` を許可します。
手順については、*AWS Secrets Managerユーザーガイド* の「[Creating a Basic Secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)」を参照してください。
1. AWS Secrets Manager コンソールを使用して、作成したシークレットの詳細を表示するか、`aws secretsmanager describe-secret`の AWS CLI コマンドを実行します。
シークレットの名前と ARN を書き留めます。これらは、Data API への呼び出しで使用できます。
**サーバーレスワークグループのシークレットに認証情報を保存するには**
1. サーバーレスワークグループの認証情報を含むシークレットを保存するには、AWS Secrets Manager AWS CLI コマンドを使用します。
+ ファイルにシークレットを作成します。例: `mycreds.json` という名前の JSON ファイル。ファイルで [**ユーザー名**] (データベースユーザー) と [**パスワード**] の値を指定します。
```
{
"username": "myusername",
"password": "mypassword"
}
```
+ 値をシークレットに保存し、シークレットに `RedshiftDataFullAccess` キーでタグを付けます。
```
aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json
```
出力は以下のようになります。
```
{
"ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf",
"Name": "MyRedshiftSecret",
"VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE"
}
```
詳細については、*AWS Secrets Manager ユーザーガイド*の「[AWS CLI を使用したベーシックシークレットの作成](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api)」を参照してください。
1. AWS Secrets Manager コンソールを使用して、作成したシークレットの詳細を表示するか、`aws secretsmanager describe-secret`の AWS CLI コマンドを実行します。
シークレットの名前と ARN を書き留めます。これらは、Data API への呼び出しで使用できます。
# Data API に Amazon VPC エンドポイント (AWS PrivateLink) を作成する
Amazon Virtual Private Cloud (Amazon VPC) を使用すると、Amazon Redshift クラスターやアプリケーションなどの AWS リソースを仮想プライベートクラウド (VPC) 内に起動できます。AWS PrivateLink は、仮想プライベートクラウド (VPC) と AWS サービス間のプライベートな接続を Amazon ネットワーク上で安全に提供します。AWS PrivateLink を使用すると、VPC エンドポイントを作成できます。これにより、Amazon VPC に基づいて、異なるアカウントや VPC のサービスに接続できます。AWS PrivateLink の詳細については、*Amazon Virtual Private Cloud ユーザーガイド*の「[VPC エンドポイントサービス (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html)」を参照してください。
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/](https://console.aws.amazon.com/vpc/)) を開きます。
1. [** エンドポイント**] を選択し、[**エンドポイントの作成**] を選択します。
1. [**エンドポイントの作成**] ページの [**サービスカテゴリ**] で [**AWS サービス**] を選択します。を使用する場合[**サービス名**] で、[**redshift Data**(`com.amazonaws.region.redshift-data`)]。
1. [**VPC**] の場合は、VPC を選択してエンドポイントを作成します。
Data API コールを行うアプリケーションを含む VPC を選択します。
1. [**サブネット**] で、アプリケーションを実行している AWS のサービスによって使用される各アベイラビリティーゾーン (AZ) のサブネットを選択します。
Amazon VPC エンドポイントを作成するには、エンドポイントにアクセスできるプライベート IP アドレスの範囲を指定します。これを行うには、各アベイラビリティーゾーンのサブネットを選択します。これにより、VPC エンドポイントは各アベイラビリティーゾーンに固有のプライベート IP アドレス範囲に制限され、各アベイラビリティーゾーンに Amazon VPC エンドポイントが作成されます。
1. [**DNS 名を有効にする**] で、[**このエンドポイントで有効にする**] を選択します。
プライベート DNS は、標準の Data API DNS ホスト名 (`https://redshift-data.region.amazonaws.com`) を、Amazon VPC エンドポイントに固有の DNS ホスト名に関連付けられたプライベート IP アドレスに解決します。その結果、Data API エンドポイント URL を更新するためのコードや設定を変更せずに、AWS CLIまたは AWS SDK を使用して Data API VPC エンドポイントにアクセスできます。
1. **セキュリティグループ**で、Amazon VPC エンドポイントに関連付けるセキュリティグループを選択します。
アプリケーションを実行している AWS のサービスへのアクセスを許可するセキュリティグループを選択します。例えば、Amazon EC2 インスタンスでアプリケーションを実行している場合は、Amazon EC2 インスタンスへのアクセスを許可するセキュリティグループを選択します。セキュリティグループを使用すると、VPC 内のリソースから Amazon VPC エンドポイントへのトラフィックを制御できます。
1. [**Create endpoint (エンドポイントの作成)**] を選択します。
エンドポイントを作成したら、AWS マネジメントコンソールでリンクを選択して、エンドポイントの詳細を表示します。
エンドポイントの [**Details (詳細)**] タブには、Amazon VPC エンドポイントの作成中に生成された DNS ホスト名が表示されます。
標準エンドポイント (`redshift-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 を呼び出す方法については、「[Amazon Redshift Data API を呼び出す際の考慮事項](data-api.md#data-api-calling-considerations)」を参照してください。
# クラスターへの接続時にデータベースグループに参加する
データベースグループは、データベースユーザーのコレクションです。データベース権限はグループに付与できます。管理者は、SQL を Data API で実行するときに、これらのデータベースグループを考慮に入れて IAM ロールを設定できます。データベースグループの詳細については、「Amazon Redshift データベース開発者ガイド」の「[グループ](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html)」を参照してください。**
Data API がクラスターに接続したときに、呼び出しで指定したデータベースユーザーがデータベースグループに参加するように、Data API 呼び出し元の IAM ロールを設定できます。この機能は、プロビジョニングされたクラスターに接続する場合にのみサポートされます。Redshift Serverless ワークグループに接続する場合はサポートされません。Data API の呼び出し元の IAM ロールでは、`redshift:JoinGroup` アクションも許可する必要があります。
これを設定するには、IAM ロールにタグを追加します。呼び出し元の IAM ロールの管理者は、キー `RedshiftDbGroups` およびデータベースグループのリストのキー値を使用してタグを追加します。値は、コロン (:) で区切られたデータベースグループの名前のリストで、全長は最大 256 文字です。データベースグループは、接続されたデータベースで事前に定義しておく必要があります。指定したグループがデータベースに見つからない場合、そのグループは無視されます。例えば、データベースグループ `accounting` および `retail` の場合、キー値は `accounting:retail` です。タグのキーおよび値のペア `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}` は、Data API への呼び出しで、どのデータベースグループが指定のデータベースユーザーに関連付けられているかを Data API で判断するために使用します。
**データベースグループに参加するには**
1. AWS マネジメントコンソール にサインインして、IAM コンソール [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) を開きます。
1. コンソールのナビゲーションペインで、**ロール** を選択し、編集するロールの名前を選択します。
1. **[タグ]** タブ、**[タグを管理]** の順に選択します。
1. **[タグを追加]** を選択し、キー **RedshiftDbGroups** と値 (*database-groups-colon-separated* のリスト) を追加します。
1. **[Save changes]** (変更の保存) をクリックします。
これで、この IAM ロールがアタッチされた IAM プリンシパルから Data API を呼び出すと、指定したデータベースユーザーが IAM ロールに指定されたデータベースグループに参加します。
IAM ロールや IAM ユーザーなど、プリンシパルにタグをアタッチする方法については、「*IAM ユーザーガイド*」の「[IAM リソースのタグ付け](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)」を参照してください。
# 信頼できる ID の伝播で Data API を使用する
Amazon Redshift アカウント管理者は、Amazon Redshift クラスターまたはワークグループを AWS IAM アイデンティティセンター と統合できます。これにより、シングルサインオンで Amazon Redshift へのワークフォースアクセスを管理できます。詳細については、「[Amazon Redshift での AWS IAM アイデンティティセンターの統合の設定](redshift-iam-access-control-idp-connect-console.md)」を参照してください。Amazon Redshift Data API は、IAM アイデンティティセンターのユーザー ID を Amazon Redshift クラスターまたはワークグループ、および AWS Lake Formation などの他の サービスに連鎖的に伝播することをサポートしています。「[Access AWS services programmatically using trusted identity propagation](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/)」の手順に従って、Data API を使用した設定およびクエリを実行することができます。
ID 拡張 IAM ロールセッションから IAM アイデンティティセンターのユーザー ID を使用して Data API を呼び出す場合、結果のステートメントとステートメントの結果には、同じ IAM アイデンティティセンターユーザーを使用してのみアクセスできます。例えば、次の AWS CLI コマンドは `execute-statement` オペレーションを呼び出して、信頼できる ID の伝播で SQL コマンドを実行します。
```
aws redshift-data execute-statement
--sql "select current_user;"
--cluster-id mycluster
--database dev
```
次の AWS CLI コマンドは、`batch-execute-statement` オペレーションを呼び出して 2 つの SQL コマンドを実行します。
```
aws redshift-data batch-execute-statement
--sqls "select current_user;" "select current_date;"
--cluster-id mycluster
--database dev
```
ID 拡張 IAM ロールセッションによって送信された `cancel-statement`、`describe-statement`、`get-statement-result`、および `get-statement-result-v2` のステートメントにアクセスするには、IAM アイデンティティセンターのユーザーと IAM ロールが、`execute-statment` または `batch-execute-statement` の実行に使用される認証情報と一致する必要があります。例えば、次の AWS CLI コマンドは SQL ステートメントの結果を取得します。
```
aws redshift-data get-statement-result
--id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
ステートメントを一覧表示するには、割り当てられている Amazon Redshift IAM アイデンティティセンターアプリケーションのみに IAM アイデンティティセンターのユーザーがアクセスできるように、`cluster-identifier` または `workgroup-name` パラメータを指定する必要があります。例えば、次の AWS CLI コマンドは、特定のクラスターのステートメントを一覧表示します。
```
aws redshift-data list-statements
--cluster-identifier mycluster
```
信頼できる ID の伝播を使用して、クラスターまたはワークグループ内のデータベースオブジェクトにアクセスする Data API オペレーションを呼び出すこともできます。これには `list-databases`、`list-schemas`、`list-tables`、および `describe-table` オペレーションが含まれます。
IAM アイデンティティセンターのユーザーによって行われた API コールは、AWS CloudTrail で追跡できます。CloudTrail イベントの `onBehalfOf` セクションには、IAM アイデンティティセンターのユーザー ID と ID ストア ARN が表示されます。次の例は、IAM アイデンティティセンターのユーザー ID `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` と ID ストア ARN `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2` を含む `onBehalfOf` セクションを表示している CloudTrail イベントのスニペットを示しています。
```
{
"eventVersion":"1.10",
"userIdentity":{
"type":"AssumedRole",
...
},
"onBehalfOf":{
"userId":"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"identityStoreArn":"arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2"
}
},
"eventTime":"2025-01-13T04:46:27Z",
"eventSource":"redshift-data.amazonaws.com",
"eventName":"ExecuteStatement",
"awsRegion":"us-east-1"
}
```
次の SQL コマンドを実行して、IAM アイデンティティセンターのユーザーが送信したクエリを確認できます。この例では、アイデンティティセンターに登録されている E メールは `username@example.com` です。
```
SELECT
h.query_id,
h.database_name,
h.status,
h.query_text,
u.usename,
h.start_time,
h.end_time
FROM
sys_query_history h
LEFT JOIN
pg_user u
ON
h.user_id = u.usesysid
where u.usename='awsidc:username@example.com'
ORDER BY
h.start_time DESC;
```
# Data API の呼び出し
Data API または AWS CLI を呼び出して、クラスターまたはサーバーレスワークグループで SQL ステートメントを実行できます。SQL ステートメントを実行する主なオペレーションは、*Amazon Redshift Data API リファレンス*の [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) と [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html) です。Data API は、AWSSDK でサポートされているプログラミング言語をサポートしています。詳細については、「[AWS での構築ツール](https://aws.amazon.com/tools/)」を参照してください。
Data API を呼び出すコードの例については、*GitHub* の「[Getting Started with Redshift Data API](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api)」を参照してください。このリポジトリには、Amazon EC2、AWS Glue Data Catalog または Amazon SageMaker ランタイムからの Amazon Redshift データへのアクセスに AWS Lambda を使用する例があります。プログラミング言語の例としては、Python、Go、Java、Javascript があります。
Data API は、AWS CLIを使用して呼び出すことができます。
次の例では、AWS CLIを使用して Data API を呼び出します。例を実行するには、環境に合わせてパラメータ値を編集します。多くの例では、クラスターに対して実行するため、`cluster-identifier` が指定されています。サーバーレスワークグループに対して実行する場合は、代わりに `workgroup-name` を指定します。これらの例は、データ API 操作の一部を示しています。詳細については、*AWS CLIコマンドリファレンス*を参照してください。
次の例のコマンドは分割され、読みやすい形式になっています。すべてのパラメータとレスポンスがすべての例で表示されるとは限りません。完全なリクエスト構文、リクエストパラメータ、レスポンス構文、レスポンス要素の API 定義については、「[Amazon Redshift Data API リファレンス](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)」を参照してください。
# SQL ステートメントを Amazon Redshift データウェアハウスに渡す
このページの例は、SQL ステートメントをデータウェアハウスに渡すさまざまな方法について説明しています。
## SQL ステートメントを実行する
SQL ステートメントを実行するには、`aws redshift-data execute-statement` AWS CLI コマンドを使用します。
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、結果を取得する識別子を返します。この例では、AWS Secrets Managerの認証方法を使用します。
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
```
次は、レスポンスの例です。
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、結果を取得する識別子を返します。この例では、一時的な認証情報認証方法を使用します。
```
aws redshift-data execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sql "select * from stl_query limit 1"
```
次は、レスポンスの例です。
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
次の AWS CLI コマンドは、サーバーレスワークグループに対して SQL ステートメントを実行し、結果を取得する識別子を返します。この例では、一時的な認証情報認証方法を使用します。
```
aws redshift-data execute-statement
--database dev
--workgroup-name myworkgroup
--sql "select 1;"
```
次は、レスポンスの例です。
```
{
"CreatedAt": "2022-02-11T06:25:28.748000+00:00",
"Database": "dev",
"DbUser": "IAMR:RoleName",
"Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e",
"WorkgroupName": "myworkgroup"
}
```
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、結果を取得する識別子を返します。この例では、AWS Secrets Manager 認証方法と冪等性トークンを使用しています。
```
aws redshift-data execute-statement
--secret-arn 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
```
次は、レスポンスの例です。
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
## パラメータを使用して SQL ステートメントを実行する
SQL ステートメントを実行するには、`aws redshift-data execute-statement` AWS CLI コマンドを使用します。
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、結果を取得する識別子を返します。この例では、AWS Secrets Managerの認証方法を使用します。SQL テキストには、名前付きパラメータ `distance` があります。この場合、述部で使用される距離は `5` です。SELECT ステートメントでは、列名の名前付きパラメータは述部でのみ使用できます。SQL ステートメントの名前付きパラメータの値は、`parameters`オプションで指定できます。
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance"
--parameters "[{\"name\": \"distance\", \"value\": \"5\"}]"
--database dev
```
次は、レスポンスの例です。
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
次の例では、サンプルデータベースの `EVENT` テーブルを使用します。詳細については、*Amazon Redshift データベースデベロッパーガイド*の「[EVENT テーブル](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html)」を参照してください。
まだデータベースに `EVENT` テーブルにない場合、Data API を使用して次のように作成できます。
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "create table event( eventid integer not null distkey,
venueid smallint not null,
catid smallint not null,
dateid smallint not null sortkey,
eventname varchar(200),
starttime timestamp)"
```
次のコマンドは、1 つの行を `EVENT` テーブルに挿入します。
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)"
--parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"},
{\"name\": \"catid\", \"value\": \"1\"},
{\"name\": \"dateid\", \"value\": \"1\"},
{\"name\": \"eventname\", \"value\": \"event 1\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"}]"
```
次のコマンドは、2 つ目の行を `EVENT` テーブルに挿入します。この例は以下を示します。
+ `id` という名前のパラメータは SQL テキストで 4 回使用されます。
+ 暗黙的な型変換は、パラメータ `starttime` を挿入する際に自動的に適用されます。
+ `venueid` 列は、SMALLINT データ型にタイプキャストされます。
+ DATE データ型を表す文字列は、TIMESTAMP データ型に暗黙的に変換されます。
+ コメントは SQL テキスト内で使用できます。
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/"
--parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"},
{\"name\": \"id\", \"value\": \"2\"}]"
```
次に、挿入された 2 つの行を示します。
```
eventid | venueid | catid | dateid | eventname | starttime
---------+---------+-------+--------+-----------+---------------------
1 | 1 | 1 | 1 | event 1 | 2022-02-22 00:00:00
2 | 2 | 2 | 2 | event 2 | 2022-02-22 00:00:00
```
次のコマンドでは、WHERE 句で名前付きパラメータを使用して、`eventid`が `1` である行を取得します。
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "select * from event where eventid=:id"
--parameters "[{\"name\": \"id\", \"value\": \"1\"}]"
```
次のコマンドを実行して、前の SQL ステートメントの SQL 結果を取得します。
```
aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a
```
これにより次の結果が示されます。
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"stringValue": "event 1"
},
{
"stringValue": "2022-02-22 00:00:00.0"
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "eventid",
"length": 0,
"name": "eventid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "venueid",
"length": 0,
"name": "venueid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "catid",
"length": 0,
"name": "catid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "dateid",
"length": 0,
"name": "dateid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "eventname",
"length": 0,
"name": "eventname",
"nullable": 1,
"precision": 200,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "varchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 1,
"precision": 29,
"scale": 6,
"schemaName": "public",
"tableName": "event",
"typeName": "timestamp"
}
],
"TotalNumRows": 1
}
```
## 複数の SQL ステートメントを実行する
1 つのコマンドで複数の SQL ステートメントを実行するには、`aws redshift-data batch-execute-statement`AWS CLI コマンドを実行します。
次の AWS CLI コマンドは、クラスターに対して 3 つの SQL ステートメントを実行し、結果を取得する識別子を返します。この例では、一時的な認証情報認証方法を使用します。
```
aws redshift-data batch-execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sqls "set timezone to BST" "select * from mytable" "select * from another_table"
```
次は、レスポンスの例です。
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
# SQL ステートメントに関するメタデータを一覧表示する
`aws redshift-data list-statements` AWS CLI コマンドを使用して、SQL ステートメントに関するメタデータを一覧表示します。このコマンドの実行の承認は、呼び出し元の IAM アクセス許可に基づいています。
次の AWS CLI コマンドは、実行された SQL ステートメントを示しています。
```
aws redshift-data list-statements
--status ALL
```
次は、レスポンスの例です。
```
{
"Statements": [
{
"CreatedAt": 1598306924.632,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
},
{
"CreatedAt": 1598311717.437,
"Id": "e0ebd578-58b3-46cc-8e52-8163fd7e01aa",
"QueryString": "select * from stl_query limit 1",
"Status": "FAILED",
"UpdatedAt": 1598311719.008
},
{
"CreatedAt": 1598313683.65,
"Id": "c361d4f7-8c53-4343-8c45-6b2b1166330c",
"QueryString": "select * from stl_query limit 1",
"Status": "ABORTED",
"UpdatedAt": 1598313685.495
},
{
"CreatedAt": 1598306653.333,
"Id": "a512b7bd-98c7-45d5-985b-a715f3cfde7f",
"QueryString": "select 1",
"Status": "FINISHED",
"UpdatedAt": 1598306653.992
}
]
}
```
# SQL ステートメントに関するメタデータの記述を取得する
SQL ステートメントのメタデータの記述を取得するには、`aws redshift-data describe-statement` AWS CLI コマンドを使用します。このコマンドの実行の承認は、呼び出し元の IAM アクセス許可に基づいています。
次の AWS CLI コマンドは、SQL ステートメントを記述します。
```
aws redshift-data describe-statement
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
次は、レスポンスの例です。
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Duration": 1095981511,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"RedshiftPid": 20859,
"RedshiftQueryId": 48879,
"ResultRows": 1,
"ResultSize": 4489,
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
}
```
次に、複数の SQL ステートメントで `batch-execute-statement` コマンドを実行した後の `describe-statement` レスポンスの例を示します。
```
{
"ClusterIdentifier": "mayo",
"CreatedAt": 1623979777.126,
"Duration": 6591877,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652",
"RedshiftPid": 31459,
"RedshiftQueryId": 0,
"ResultRows": 2,
"ResultSize": 22,
"Status": "FINISHED",
"SubStatements": [
{
"CreatedAt": 1623979777.274,
"Duration": 3396637,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:1",
"QueryString": "select 1;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979777.903
},
{
"CreatedAt": 1623979777.274,
"Duration": 3195240,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2",
"QueryString": "select 2;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979778.076
}
],
"UpdatedAt": 1623979778.183
}
```
# SQL ステートメントの結果を取得する
実行された SQL ステートメントの結果を取得するには、`redshift-data get-statement-result` または `redshift-data get-statement-result-v2` AWS CLI コマンドを使用します。`get-statement-result` の結果は JSON 形式です。`get-statement-result-v2` の結果は CSV 形式です。レスポンスで受け取った `Id` を、`execute-statement`または`batch-execute-statement` に提供できます。`batch-execute-statement` によって実行された SQL ステートメントの `Id` 値は、`describe-statement` の結果で取得できます。この値には、`b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2` のように、コロンとシーケンス番号が末尾に付きます。`batch-execute-statement` で複数の SQL ステートメントを実行する場合、各 SQL ステートメントには `describe-statement` に示されているような `Id` 値があります。このコマンドの実行の承認は、呼び出し元の IAM アクセス許可に基づいています。
次のステートメントは、`execute-statement` によって実行された SQL ステートメントの結果を返します。`ResultFormat` はデフォルトで `JSON` に設定されます。結果を取得するには、`get-statement-result` オペレーションを呼び出します。
```
aws redshift-data get-statement-result
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
次のステートメントは、`batch-execute-statement`によって実行された 2 番目の SQL ステートメントの結果を返します。
```
aws redshift-data get-statement-result
--id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2
```
以下は、`get-statement-result` への呼び出しに対するレスポンスの例です。SQL 結果は、レスポンスの `Records` キーに JSON 形式で返されます。
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "userid",
"length": 0,
"name": "userid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "query",
"length": 0,
"name": "query",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "label",
"length": 0,
"name": "label",
"nullable": 0,
"precision": 320,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "xid",
"length": 0,
"name": "xid",
"nullable": 0,
"precision": 19,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int8"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "pid",
"length": 0,
"name": "pid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "database",
"length": 0,
"name": "database",
"nullable": 0,
"precision": 32,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "querytxt",
"length": 0,
"name": "querytxt",
"nullable": 0,
"precision": 4000,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "endtime",
"length": 0,
"name": "endtime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"type": 93,
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "aborted",
"length": 0,
"name": "aborted",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "insert_pristine",
"length": 0,
"name": "insert_pristine",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "concurrency_scaling_status",
"length": 0,
"name": "concurrency_scaling_status",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
}
],
"Records": [
[
{
"longValue": 1
},
{
"longValue": 3
},
{
"stringValue": "health"
},
{
"longValue": 1023
},
{
"longValue": 15279
},
{
"stringValue": "dev"
},
{
"stringValue": "select system_status from stv_gui_status;"
},
{
"stringValue": "2020-08-21 17:33:51.88712"
},
{
"stringValue": "2020-08-21 17:33:52.974306"
},
{
"longValue": 0
},
{
"longValue": 0
},
{
"longValue": 6
}
]
],
"TotalNumRows": 1
}
```
次の例は、`execute-statement` によって実行され、結果を JSON 形式で返す SQL ステートメントを示しています。テーブル `testingtable` には整数列が 3 つ (col1、col2、col3) あり、3 つの行に値 (1、2、3)、(4、5、6)、および (7、8、9) が含まれています。
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format JSON
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
以下は、`get-statement-result` への呼び出しに対するレスポンスの例です。SQL 結果は、レスポンスの `Records` キーに JSON 形式で返されます。
```
aws redshift-data get-statement-result
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 2
},
{
"longValue": 3
}
],
[
{
"longValue": 4
},
{
"longValue": 5
},
{
"longValue": 6
}
],
[
{
"longValue": 7
},
{
"longValue": 8
},
{
"longValue": 9
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3
}
```
次の例は、`execute-statement` によって実行され、結果を CSV 形式で返す SQL ステートメントを示しています。テーブル `testingtable` には整数列が 3 つ (col1、col2、col3) あり、3 つの行に値 (1、2、3)、(4、5、6)、および (7、8、9) が含まれています。
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format CSV
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
以下は、`get-statement-result-v2` への呼び出しに対するレスポンスの例です。SQL 結果は、レスポンスの `Records` キーに CSV 形式で返されます。行はキャリッジリターンと改行 (\$1r\$1n) で区切られます。`Records` で返される最初の行は列ヘッダーです。CSV 形式で返される結果は 1 MB 単位で返され、各チャンクには最大 1MB 分の任意の数の行が含まれます。
```
aws redshift-data get-statement-result-v2
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
{
"CSVRecords": "col1,col2,col3\r\n1,2,3\r\n4,5,6\r\n7,8,9\r\n"
}
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3,
"ResultFormat": "csv"
}
```
# テーブルの説明
`aws redshift-data describe-table` AWS CLI コマンドを使用して、テーブルを説明するメタデータを取得します。
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、テーブルを記述するメタデータを返します。この例では、AWS Secrets Managerの認証方法を使用します。
```
aws redshift-data describe-table
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
```
次は、レスポンスの例です。
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
次の AWS CLI コマンドは、テーブルを記述するクラスターに対して SQL ステートメントを実行します。この例では、一時的な認証情報認証方法を使用します。
```
aws redshift-data describe-table
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
```
次は、レスポンスの例です。
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_supported",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_verified_by",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "comments",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
# クラスター内のデータベースの一覧表示
`aws redshift-data list-databases` AWS CLI コマンドを使用して、クラスター内のデータベースを一覧表示します。
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、データベースを一覧表示します。この例では、AWS Secrets Managerの認証方法を使用します。
```
aws redshift-data list-databases
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
次は、レスポンスの例です。
```
{
"Databases": [
"dev"
]
}
```
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、データベースを一覧表示します。この例では、一時的な認証情報認証方法を使用します。
```
aws redshift-data list-databases
--db-user myuser
--cluster-identifier mycluster-test
--database dev
```
次は、レスポンスの例です。
```
{
"Databases": [
"dev"
]
}
```
# データベース内のスキーマの一覧表示
`aws redshift-data list-schemas` AWS CLI コマンドを使用して、データベース内のスキーマを一覧表示します。
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、データベース内のスキーマを一覧表示します。この例では、AWS Secrets Managerの認証方法を使用します。
```
aws redshift-data list-schemas
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
次は、レスポンスの例です。
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、データベース内のスキーマを一覧表示します。この例では、一時的な認証情報認証方法を使用します。
```
aws redshift-data list-schemas
--db-user mysuser
--cluster-identifier mycluster-test
--database dev
```
次は、レスポンスの例です。
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
# データベース内のテーブルの一覧表示
`aws redshift-data list-tables` AWS CLI コマンドを使用して、データベース内のテーブルを一覧表示します。
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、データベース内のテーブルを一覧表示します。この例では、AWS Secrets Managerの認証方法を使用します。
```
aws redshift-data list-tables
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
次は、レスポンスの例です。
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
}
```
次の AWS CLI コマンドは、クラスターに対して SQL ステートメントを実行し、データベース内のテーブルを一覧表示します。この例では、一時的な認証情報認証方法を使用します。
```
aws redshift-data list-tables
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
次は、レスポンスの例です。
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
]
}
```
# Amazon Redshift Data API のトラブルシューティングに関する問題
Data API に関する問題のトラブルシューティングには、「一般的なエラーメッセージ」というタイトルの以下のセクションを使用します。
**Topics**
+ [クエリのパケットが大きすぎる](#data-api-troubleshooting-packet-too-large)
+ [データベース応答がサイズ制限を超えている](#data-api-troubleshooting-response-size-too-large)
## クエリのパケットが大きすぎる
クエリのパケットが大きすぎることを示すエラーが表示された場合は、通常、ローに対して返される結果セットが大きすぎます。Data API のサイズ制限は、データベースから返る結果セットの 1 行あたり 64 KB です。
この問題を解決するには、結果セットの各行が 64 KB 以下であることを確認します。
## データベース応答がサイズ制限を超えている
データベース応答がサイズ制限を超えていることを示すエラーが表示される場合、通常、データベースから返る結果セットのサイズが大きすぎます。Data API の制限は、データベースより返る結果セットで 500 MB です。
この問題を解決するには、Data API への呼び出しで返るデータが 500 MB 以下になるようにします。500 MB を超えるデータを返す必要がある場合は、クエリで `LIMIT` 句を使用して、複数のステートメント呼び出しを行います。
# Amazon EventBridge を使用した Amazon Redshift Data API オペレーションのスケジューリング
選択したイベントを照合し、ターゲットにルーティングしてアクションを実行するためのルールを作成できます。ルールを使用して、あらかじめ決められたスケジュールに従ってアクションを実行することもできます。詳細については、[Amazon EventBridge ユーザーガイド](https://docs.aws.amazon.com/eventbridge/latest/userguide/)を参照してください。
EventBridge でデータ API オペレーションをスケジュールするには、関連付けられた IAM ロールが CloudWatch Events (events.amazonaws.com) のプリンシパルを信頼する必要があります。このロールには、管理対象ポリシー `AmazonEventBridgeFullAccess` に相当するものがアタッチされている必要があります。また、Data API によって管理される `AmazonRedshiftDataFullAccess` ポリシー権限も必要です。IAM コンソールで、これらのアクセス許可を持つ IAM ロールを作成できます。IAM コンソールでロールを作成するときは、CloudWatch Events 用に AWS サービスの信頼できるエンティティを選択します。EventBridge ターゲットの `RoleArn` JSON 値に IAM ロールを指定します。IAM ロールの作成の詳細については、*IAM ユーザーガイド*の「[AWS のサービス用ロールの作成 (コンソール)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console)」を参照してください。
Amazon EventBridge で作成するルールの `name` は、`RedshiftDataParameters` の `StatementName` と一致する必要があります。
以下の例は、単一または複数の SQL ステートメントを使用し、データウェアハウスとして Amazon Redshift クラスターまたは Amazon Redshift Serverless ワークグループを使用して EventBridge ルールを作成するバリエーションを示しています。
## 単一 SQL ステートメントとクラスターによる呼び出し
次の例では、AWS CLI を使用して、Amazon Redshift クラスターに対する 1 つの SQL ステートメントの実行に使用する EventBridge ルールを作成します。
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
次に、ルールで指定されたスケジュールで実行する EventBridge ターゲットが作成されます。
```
aws events put-targets
--cli-input-json file://data.json
```
入力 data.json ファイルは次のとおりです。`Sql` JSON キーは、単一 SQL ステートメントがあることを示しています。`Arn` JSON 値にはクラスター識別子が含まれます。`RoleArn` JSON 値には、前述のように SQL を実行するために使用される IAM ロールが含まれます。
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"DbUser": "root",
"Sql": "select 1;",
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## 単一 SQL ステートメントおよびワークグループによる呼び出し
次の例では、AWS CLI を使用して、Amazon Redshift Serverless ワークグループに対する 1 つの SQL ステートメントの実行に使用する EventBridge ルールを作成します。
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
次に、ルールで指定されたスケジュールで実行する EventBridge ターゲットが作成されます。
```
aws events put-targets
--cli-input-json file://data.json
```
入力 data.json ファイルは次のとおりです。`Sql` JSON キーは、単一 SQL ステートメントがあることを示しています。`Arn` JSON 値にはワークグループ名が含まれます。`RoleArn` JSON 値には、前述のように SQL を実行するために使用される IAM ロールが含まれます。
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sql": "select 1;",
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
## 複数の SQL ステートメントおよびクラスターによる呼び出し
次の例では、AWS CLI を使用して、Amazon Redshift クラスターに対する複数の SQL ステートメントの実行に使用する EventBridge ルールを作成します。
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
次に、ルールで指定されたスケジュールで実行する EventBridge ターゲットが作成されます。
```
aws events put-targets
--cli-input-json file://data.json
```
入力 data.json ファイルは次のとおりです。`Sqls` JSON キーは、複数の SQL ステートメントがあることを示しています。`Arn` JSON 値にはクラスター識別子が含まれます。`RoleArn` JSON 値には、前述のように SQL を実行するために使用される IAM ロールが含まれます。
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## 複数の SQL ステートメントおよびワークグループによる呼び出し
次の例では、AWS CLI を使用して、Amazon Redshift Serverless ワークグループに対する複数の SQL ステートメントの実行に使用する EventBridge ルールを作成します。
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
次に、ルールで指定されたスケジュールで実行する EventBridge ターゲットが作成されます。
```
aws events put-targets
--cli-input-json file://data.json
```
入力 data.json ファイルは次のとおりです。`Sqls` JSON キーは、複数の SQL ステートメントがあることを示しています。`Arn` JSON 値にはワークグループ名が含まれます。`RoleArn` JSON 値には、前述のように SQL を実行するために使用される IAM ロールが含まれます。
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
# データ API のモニタリング
モニタリングは、Data API およびその他の AWS ソリューションの信頼性、可用性、およびパフォーマンスを維持する上で重要な部分です。Data API を監視したり、問題が発生したときに報告したり、必要に応じて自動アクションを実行するため、AWSには次のモニタリングツールが用意されています。
+ Amazon EventBridge を使用して、AWSのサービスを自動化し、アプリケーションの可用性の問題やリソースの変更などのシステムイベントに自動的に対応できます。AWS サービスからのイベントは、ほぼリアルタイムで EventBridge に配信されます。簡単なルールを記述して、注目するイベントと、イベントがルールに一致した場合に自動的に実行するアクションを指定できます。詳細については、[Amazon EventBridge ユーザーガイド](https://docs.aws.amazon.com/eventbridge/latest/userguide/)を参照してください。
+ AWS CloudTrail は、AWSアカウントにより、またはそのアカウントに代わって行われた API コールや関連イベントを取得し、指定した Amazon S3 バケットにログファイルを配信します。AWS を呼び出したユーザーとアカウント、呼び出し元の IP アドレス、および呼び出し日時を特定できます。Amazon Redshift と AWS CloudTrail の統合の詳細については、「[CloudTrail によるログ記録](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html)」を参照してください。CloudTrail の詳細については、「[AWS CloudTrail ユーザーガイド](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)」を参照してください。
**Topics**
+ [Amazon EventBridge での Amazon Redshift データ API のイベントのモニタリング](data-api-monitoring-events.md)
# Amazon EventBridge での Amazon Redshift データ API のイベントのモニタリング
お客様独自のアプリケーション、Software as a Service (SaaS) アプリケーション、AWSサービスからのリアルタイムデータのストリームを配信する EventBridge で、Data API イベントをモニタリングできます。EventBridge では、データは AWS Lambda や Amazon SNS などのターゲットにルーティングされます。これらのイベントは、CloudWatch Events に表示されるイベントと同じで、AWSリソースの変更を記述するシステムイベントのストリームをほぼリアルタイムで配信します。イベントは、Amazon Redshift データベースを含むアカウントに送信されます。例えば、別のアカウントでロールを引き受ける場合、イベントはそのアカウントに送信されます。詳細については、*Amazon EventBridge ユーザーガイド*の「[Amazon EventBridge events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)」を参照してください。
データ API イベントは、`ExecuteStatement`または `BatchExecuteStatement` API オペレーションが `WithEvent` オプションを `true` に設定するときに送信されます。`state` フィールドには次のいずれかの値が含まれます。
+ ABORTED – クエリの実行がユーザーによって停止されました。
+ FAILED – クエリの実行に失敗しました。
+ FINISHED – クエリの実行が終了しました。
イベントは保証に基づいて配信されます。詳細については、*Amazon EventBridge ユーザーガイド*の「[Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)」を参照してください。
## データ API 終了イベントの例
以下の例は、`ExecuteStatement`API オペレーションが終了したときの Data API のイベントを示しています。この例では、`test.testtable`という名前のステートメントの実行が終了しました。
```
{
"version": "0",
"id": "18e7079c-dd4b-dd64-caf9-e2a31640dab0",
"detail-type": "Redshift Data Statement Status Change",
"source": "aws.redshift-data",
"account": "123456789012",
"time": "2020-10-01T21:14:26Z",
"region": "us-east-1",
"resources": [
"arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster-1"
],
"detail": {
"principal": "arn:aws:iam::123456789012:user/myuser",
"statementName": "test.testtable",
"statementId": "dd2e1ec9-2ee3-49a0-819f-905fa7d75a4a",
"redshiftQueryId": -1,
"state": "FINISHED",
"rows": 1,
"expireAt": 1601673265
}
}
```
# Amazon Redshift Data API で AWS KMS を使用する
Amazon Redshift クラスターまたは Redshift Serverless ワークグループをカスタマーマネージドキーで暗号化すると、Amazon Redshift Data API は同じカスタマーマネージドキーを使用してクエリと結果を保存および暗号化します。
Data API は、デフォルトでデータを暗号化して、クエリテキストやクエリ結果などの機密情報を保護します。この保護には、AWS が所有する AWS KMS 暗号化キーを使用します。
保管中のデータをデフォルトで暗号化して、機密データの保護に伴う運用上のオーバーヘッドと複雑な作業を軽減します。このアプローチにより、厳格な暗号化のコンプライアンスと規制要件に対応する安全なアプリケーションを構築できます。
## AWS KMS での権限の使用
Data API でカスタマーマネージドキーを使用するには権限が必要です。
カスタマーマネージドキーで暗号化されたクラスターに対して `ExecuteStatement` または `BatchExecuteStatement` を呼び出すと、Amazon Redshift は AWS KMS に [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) リクエストを送信してユーザーに代わって権限を作成します。AWS KMS は権限を使用して、アカウント内の KMS キーへのアクセス権を Data API に付与します。
DATA API では、以下のオペレーションでカスタマーマネージドキーを使用するのに権限が必要です。
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) リクエストを AWS KMS に送信して、カスタマーマネージドキーを使用してクエリメタデータを暗号化する。
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) リクエストを AWS KMS に送信して、カスタマーマネージドキーで暗号化されたデータキーを生成する。
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) リクエストを AWS KMS に送信して、暗号化されたデータキーを復号して、データを暗号化できるようにする。
権限へのアクセス許可の取り消し、またはカスタマーマネージドキーへの Amazon Redshift のアクセス許可の削除は、いつでも実行できます。これを行うと、DATA API はカスタマーマネージドキーによって暗号化されたデータにアクセスできなくなり、そのデータに依存しているオペレーションが影響を受けます。例えば、権限の取り消し後にクエリ結果を取得したり、クエリのステータスを追跡しようとすると、Data API は `AccessDeniedException` を返します。
## カスタマーマネージドキーの KMS キーポリシー
キーポリシーは、カスタマーマネージドキーへのアクセスを制御します。すべてのカスタマーマネージドキーには、キーポリシーが 1 つだけ必要です。このポリシーには、そのキーを使用できるユーザーとその使用方法を決定するステートメントが含まれています。キーポリシーは、カスタマーマネージドキーの作成時に指定できます。詳細については、「*AWS Key Management Service デベロッパーガイド*」の「[カスタマーマネージドキー](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key)」を参照してください。
Data API でカスタマーマネージドキーを使用するには、まず Amazon Redshift へのアクセスを許可する必要があります。キーポリシーで次の API オペレーションを許可する必要があります。
+ `kms:CreateGrant` - カスタマーマネージドキーに許可を追加します。この権限は、指定された AWS KMS キーへのアクセスを制御します。これにより、必要な許可オペレーションに対し Amazon Redshift がアクセスできるようにします。詳細については、「[AWS KMS での権限の使用](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations)」を参照してください。
以下は、キーポリシーの例です。
```
"Statement":[
{
"Sid":"Allow access to principals authorized to use Amazon Redshift",
"Effect":"Allow",
"Principal":{
"AWS":"*"
},
"Action":[
"kms:DescribeKey",
"kms:CreateGrant"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"kms:ViaService":"redshift.amazonaws.com",
"kms:CallerAccount":"111122223333"
}
}
},
{
"Sid":"AllowKeyAdministratorsAccess",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole"
},
"Action":"kms:*",
"Resource":"*"
},
{
"Sid":"AllowKeyUseForExampleRole",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleUserRole"
},
"Action":[
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource":"*"
}
]
```
## データ API 暗号化コンテキスト
暗号化コンテキストとは、データに関する追加のコンテキスト情報を含む、(オプションの) キーと値のペアのセットです。AWS KMS は、暗号化コンテキストを追加の認証済みデータとして使用し、認証付き暗号化をサポートします。データの暗号化リクエストに暗号化コンテキストを組み込むと、AWS KMS は暗号化コンテキストを暗号化後のデータにバインドします。データを復号するには、そのリクエストに同じ暗号化コンテキストを含める必要があります。
Data API は、プロビジョニングされたクラスターのすべての AWS KMS 暗号化オペレーションで同じ 3 つの暗号化コンテキストのキーと値のペアを使用します。
+ `aws:redshift:arn` – クラスターの Amazon リソースネーム (ARN) (文字列)
+ `aws:redshift:createtime` – クラスターの作成をリクエストしたときのタイムスタンプ
+ `serviceName` – `RedshiftDataAPI`
```
"EncryptionContextSubset": {
"aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster",
"aws:redshift:createtime": "20250815T0000Z",
"serviceName": "RedshiftDataAPI",
}
```
Data API は、サーバーレスワークグループのすべての AWS KMS 暗号化オペレーションで 2 つの暗号化コンテキストのキーと値のペアを使用します。
+ `aws:redshift-serverless:arn` – 名前空間の Amazon リソースネーム (ARN)
+ `serviceName` – RedshiftDataAPI
```
"EncryptionContextSubset": {
"aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012",
"serviceName": "RedshiftDataAPI"
}
```
暗号化の詳細については、「[AWS KMS の暗号化の詳細の概要](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html)」を参照してください。Amazon Redshift と AWS KMS 統合の詳細については、「[Amazon Redshift が AWS KMS を使用する方法](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html)」を参照してください。