PAYLOAD1 | PAYLOAD2 | PAYLOAD3
```
出力では、次のようになります。
+ 余分なレスポンスヘッダーが返されない場合、`headers`、`multiValueHeaders`、`cookies`、および `statusCode` キーは指定されません。
+ `headers` キーには、単一値のヘッダーのみを含めることができます。
+ 出力では、ヘッダーに `Transfer-Encoding: chunked` または `Content-length: number` が含まれていることが想定されます。関数がこれらのヘッダーのいずれかを返さない場合、API Gateway はレスポンスヘッダーに `Transfer-Encoding: chunked` を追加します。
+ `multiValueHeaders` キーには、複数値のヘッダーや単一値のヘッダーを含めることができます。`multiValueHeaders` キーを使用して、単一値のヘッダーを含めて、すべてのヘッダーを指定することができます。
+ `headers` と `multiValueHeaders` の両方の値を指定した場合、API Gateway はそれらを単一のリストにマージします。同じキーと値のペアが両方で指定された場合にのみ、`multiValueHeaders` の値が、マージされたリストに表示されます。
+ メタデータは有効な JSON である必要があります。`headers`、`multiValueHeaders`、`cookies`、および `statusCode` キーのみがサポートされます。
+ メタデータ JSON の後に区切り記号を指定する必要があります。区切り記号は 8 null バイトで、ストリームデータの最初の 16KB 以内に出現する必要があります。
+ API Gateway では、メソッドレスポンスペイロードに特定の形式は必要ありません。
関数 URL を使用して Lambda 関数をストリーミングする場合は、これらの要件を満たすように Lambda 関数の入力と出力を変更する必要があります。
Lambda 関数の出力がこの形式の要件に準拠していない場合でも、API Gateway は Lambda 関数を呼び出す可能性があります。次の表は、API Gateway でサポートされている API 統合リクエスト設定と Lambda 関数コードの組み合わせを示しています。これには、バッファリングされたレスポンス転送モードでサポートされている組み合わせが含まれます。
| レスポンス転送モード | 関数コードが必要な形式に準拠している | Lambda 呼び出し API | API Gateway でサポートされている |
| --- | --- | --- | --- |
| ストリーム | あり | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | はい。API Gateway はレスポンスをストリーミングします。 |
| ストリーム | 不可 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | いいえ。API Gateway は Lambda 関数を呼び出し、500 のエラーレスポンスを返します。 |
| ストリーム | あり | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | いいえ。API Gateway はこの統合設定をサポートしていません。 |
| ストリーム | 不可 | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | いいえ。API Gateway はこの統合設定をサポートしていません。 |
| バッファ済み | あり | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | いいえ。API Gateway はこの統合設定をサポートしていません。 |
| バッファ済み | 不可 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | いいえ。API Gateway はこの統合設定をサポートしていません。 |
| バッファ済み | あり | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway は HTTP ヘッダーとステータスコードを返しますが、レスポンス本文は返しません。 |
| バッファ済み | 不可 | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | はい。これは Lambda プロキシ統合です。詳細については、「[Lambda プロキシ統合](set-up-lambda-proxy-integrations.md)」を参照してください。 |
# API Gateway で Lambda プロキシとペイロードレスポンスストリーミングを設定する
レスポンスペイロードストリーミングを設定するときは、リソースの統合リクエストで転送モードを指定します。これらの設定は、統合リクエストで設定して、統合レスポンスの前と最中に API Gateway がどのように動作するかを制御します。
## レスポンスストリーミングの Lambda 関数の例
Lambda 関数は [レスポンスストリーミング用の Lambda プロキシ統合形式](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format) に準拠している必要があります。レスポンスストリーミングをテストするには、3 つのサンプル Lambda 関数のいずれかを使用することをお勧めします。Lambda 関数を作成するときは、必ず以下を実行してください。
+ 関数に適切なタイムアウトを指定します。レスポンスストリーミングについて学習するには、少なくとも 1 分のタイムアウトを設定することをお勧めします。本番稼働用リソースを作成するときは、Lambda 関数のタイムアウトがリクエストサイクル全体をカバーしていることを確認してください。詳細については、「[Lambda 関数のタイムアウトを設定する](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)」を参照してください。
+ 最新の Node.js ランタイムを使用します。
+ Lambda レスポンスストリーミングが利用可能なリージョンを使用します。
------
#### [ Using HttpResponseStream.from ]
次のコード例では、パイプラインメソッドを使用せずに、`awslambda.HttpResponseStream()` メソッドを使用して JSON メタデータオブジェクトとペイロードをクライアントにストリーミングします。区切り記号を作成する必要はありません。詳細については、「[レスポンスストリーミング対応 Lambda 関数の記述](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html)」を参照してください。
```
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
"statusCode": 200,
"headers": {
"x-foo": "bar"
},
"multiValueHeaders": {
"x-mv1": ["hello", "world"],
"Set-Cookie": ["c1=blue", "c2=red"]
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("First payload ");
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("Final payload");
responseStream.end();
});
```
------
#### [ Using the pipeline method ]
Lambda では、レスポンスストリーミングが有効な関数を記述するときに、ネイティブ Node.js ランタイムが提供する `awslambda.streamifyResponse()` デコレータと `pipeline()` メソッドを使用することをお勧めします。パイプラインメソッドを使用する場合、区切り記号を作成する必要はありません。Lambda がこれを行います。詳細については、「[レスポンスストリーミング対応 Lambda 関数の記述](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html)」を参照してください。
次のコード例では、JSON メタデータオブジェクトと 3 つのペイロードをクライアントにストリーミングします。
```
import { pipeline } from 'node:stream/promises';
import { Readable } from 'node:stream';
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
statusCode: 200,
headers: {
"Content-Type": "text/plain",
"X-Custom-Header": "Example-Custom-Header"
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
const dataStream = Readable.from(async function* () {
yield "FIRST payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "SECOND payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "THIRD payload\n";
await new Promise(r => setTimeout(r, 1000));
}());
await pipeline(dataStream, responseStream);
}
);
```
------
#### [ Without using the pipeline method ]
次のコード例では、`awslambda.HttpResponseStream()` メソッドを使用せずに、JSON メタデータオブジェクトと 3 つのペイロードをクライアントにストリーミングします。`awslambda.HttpResponseStream()` メソッドを使用しない場合は、メタデータとペイロードの間に 8 null バイトの区切り記号を含める必要があります。
```
export const handler = awslambda.streamifyResponse(async (event, response, ctx) => {
response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}');
response.write("\x00".repeat(8)); // DELIMITER
await new Promise(r => setTimeout(r, 1000));
response.write("FIRST payload");
await new Promise(r => setTimeout(r, 1000));
response.write("SECOND payload");
await new Promise(r => setTimeout(r, 1000));
response.write("FINAL payload");
response.end();
});
```
------
## ペイロードレスポンスストリーミングとの Lambda プロキシ統合を作成する
次の手順は、ペイロードレスポンスストリーミングで Lambda プロキシ統合を作成する方法を示しています。Lambda 関数の例を使用するか、独自の関数を作成します。
------
#### [ AWS マネジメントコンソール ]
**ペイロードレスポンスストリーミングで Lambda プロキシ統合を作成するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. **[リソースの作成]** を選択します。
1. **[リソース名]** に **streaming** と入力します。
1. **[リソースの作成]** を選択します。
1. **[/streaming]** リソースを選択した状態で、**[メソッドを作成]** を選択します。
1. **[メソッドタイプ]** で、**[任意]** を選択します。
1. **[統合タイプ]** で、**[Lambda]** を選択します。
1. **[Lambda プロキシ統合]** を選択します。
1. **[レスポンス転送モード]** で、**[ストリーム]** を選択します。
1. **[Lambda 関数]** で、Lambda 関数の名前を選択します。
API Gateway コンソールは、[InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API を自動的に使用して Lambda 関数を呼び出します。お客様は、レスポンスのストリーミングが有効な Lambda 関数を記述する責任があります。例については、[レスポンスストリーミングの Lambda 関数の例](#response-streaming-lambda-example)を参照してください。
1. **[メソッドの作成]** を選択します。
メソッドを作成したら、API をデプロイします。
**API をデプロイするには**
1. [**API のデプロイ**] を選択します。
1. **[ステージ]** で **[新規ステージ]** を選択します。
1. [**Stage name (ステージ名)**] に **prod** と入力します。
1. (オプション) **[説明]** に説明を入力します。
1. **[デプロイ]** をクリックします。
------
#### [ AWS CLI ]
次の手順では、`responseTransferMode` を `STREAM` に設定して新しい API をインポートする方法を示します。既存の統合 API があり、`responseTransferMode` を変更する場合は、「[Lambda プロキシ統合のレスポンス転送モードを更新する](#response-streaming-lambda-update)」を参照してください。
**ペイロードレスポンスストリーミングを使用して新しい API を作成するには**
1. 以下の Open API ファイルをコピーし、`ResponseStreamDemoSwagger.yaml` として保存します。このファイルでは、`responseTransferMode` は `STREAM` に設定され、統合 URI は `arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations` に設定されます。
`my-function` の関数名をストリーミング対応関数に置き換え、認証情報を、`apigateway` サービスが Lambda 関数を呼び出すことを許可するポリシーを持つ IAM ロールに置き換えます。
```
openapi: "3.0.1"
info:
title: "ResponseStreamingDemo"
version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
variables:
basePath:
default: "prod"
paths:
/lambda:
get:
x-amazon-apigateway-integration:
httpMethod: "POST"
uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations"
type: "aws_proxy"
timeoutInMillis: 90000
responseTransferMode: "STREAM"
credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role"
```
認証情報の IAM ロールを指定する代わりに、Lambda の `add-permission` コマンドを使用してリソースベースのアクセス許可を追加できます。
1. 次の `import-rest-api` コマンドを使用して、OpenAPI 定義をインポートします。
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. 次の `create-deployment` コマンドを使用して、新しい API をステージにデプロイします。
```
aws apigateway create-deployment \
--rest-api-id a1b2c2 \
--stage-name prod \
--region us-west-1
```
------
### Lambda プロキシ統合のレスポンス転送モードを更新する
次の手順は、Lambda プロキシ統合のレスポンス転送モードを更新する方法を示しています。レスポンス転送モードをストリーミングに変更する場合は、レスポンスストリーミングの要件に準拠するように Lambda 関数を更新します。Lambda 関数の例を使用するか、独自の関数を作成します。
------
#### [ AWS マネジメントコンソール ]
**Lambda プロキシ統合のレスポンス転送モードを更新するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メソッドを選択します。
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[レスポンス転送モード]** で、**[ストリーム]** を選択します。
1. **[Lambda 関数]** で、Lambda 関数の名前を選択します。
1. **[保存]** を選択します。
メソッドを更新したら、API をデプロイします。
**API をデプロイするには**
1. [**API のデプロイ**] を選択します。
1. **[ステージ]** で **[新規ステージ]** を選択します。
1. [**Stage name (ステージ名)**] に **prod** と入力します。
1. (オプション) **[説明]** に説明を入力します。
1. **[デプロイ]** をクリックします。
------
#### [ AWS CLI ]
1. Lambda 関数を更新してストリーミングを有効にします。
1. 次の AWS CLI コマンドを使用して、統合 URI と統合のレスポンス転送モードを更新します。
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method ANY \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \
--region us-west-1
```
1. 変更を有効にするには、API を再デプロイします。
------
# API Gateway でのレスポンスストリーミングに関する問題のトラブルシューティング
次のトラブルシューティングガイダンスは、レスポンスストリーミングを試用する API の問題を解決するのに役立ちます。
## 一般的なトラブルシューティング
[TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html) またはコンソールのテストタブを使用して、ストリームレスポンスをテストできます。以下の考慮事項は、レスポンスストリーミングでのテスト呼び出しの使用に影響する可能性があります。
+ メソッドをテストすると、API Gateway はストリーミングされたレスポンスペイロードをバッファリングします。次のいずれかの条件が満たされると、API Gateway はバッファリングされたペイロードを含む 1 回限りのレスポンスを返します。
+ リクエストが完了しました
+ 35 秒経過
+ 1 MB を超えるレスポンスペイロードがバッファされています
+ メソッドが HTTP レスポンスステータスとすべてのヘッダーを返すまでに 35 秒以上経過した場合、TestInvokeMethod で返されるレスポンスステータスは 0 になります。
+ API Gateway は実行ログを生成しません。
API をデプロイしたら、curl コマンドを使用してストリームレスポンスをテストできます。出力にプロトコルレスポンスヘッダーを含めるには、`-i` オプションを使用することをお勧めします。到着時にレスポンスデータを表示するには、curl オプション `--no-buffer` を使用します。
## cURL エラーのトラブルシューティング
統合をテストしていて、`curl: (18) transfer closed with outstanding read data remaining` エラーが表示される場合は、統合のタイムアウトが十分に長いことを確認してください。Lambda 関数を使用している場合は、Lambda 関数のレスポンスタイムアウトを更新する必要があります。詳細については、「[Lambda 関数のタイムアウトを設定する](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)」を参照してください。
## アクセスログ記録を使用したトラブルシューティング
REST API ステージのアクセスログを使用して、レスポンスストリームのログ記録とトラブルシューティングを行うことができます。既存の変数に加えて、次のアクセスログ変数を使用できます。
`$context.integration.responseTransferMode`
統合のレスポンス転送モード。`BUFFERED` または `STREAMED` のいずれかとなります。
`$context.integration.timeToAllHeaders`
API Gateway が統合接続を確立してから、クライアントからすべての統合レスポンスヘッダーを受信するまでの時間。
`$context.integration.timeToFirstContent`
API Gateway が統合接続を確立してから、最初のコンテンツバイトを受信するまでの時間。
`$context.integration.latency`-または-`$context.integrationLatency`
API Gateway が統合接続を確立してから統合レスポンスストリームが完了するまでの時間。
次の図は、これらのアクセスログ変数がレスポンスストリームのさまざまなコンポーネントをどのように表しているかを示しています。
![\[API Gateway でのレスポンスストリーミングのアクセスログ変数\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/response-streaming-figure.png)
アクセスログの詳細については、「[API Gateway で REST API の CloudWatch ログ記録を設定する](set-up-logging.md)」を参照してください。X-Ray を使用してレスポンスストリームをモニタリングすることもできます。詳細については、「[API Gateway で X-Ray を使用して REST API へのユーザーリクエストをトレースする](apigateway-xray.md)」を参照してください。
# API Gateway での REST API のプライベート統合
プライベートな統合を使用して、VPC 内にある HTTP/HTTPS リソースを公開し、VPC 外のクライアントがアクセスできるようにします。これにより、プライベート VPC リソースへのアクセスが VPC の境界を超えて拡張されます。API Gateway がサポートするいずれかの[認可方法](apigateway-control-access-to-api.md)を使用して、API へのアクセスを制御できます。
プライベート統合を作成するには、まず VPC リンクを作成する必要があります。API Gateway は、REST API 用の VPC リンク V2 をサポートしています。VPC リンク V2 を使用すると、Network Load Balancer を使用せずに REST API を Application Load Balancer に接続するプライベート統合を作成できます。Application Load Balancer を使用すると、Amazon ECS コンテナベースのアプリケーションやその他の多くのバックエンドに接続できます。VPC リンク V1 はレガシー統合タイプと見なされます。API Gateway でサポートされていますが、新しい VPC リンク V1 を作成しないことをお勧めします。
## 考慮事項
以下の考慮事項は、プライベート統合の使用に影響する可能性があります。
+ すべてのリソースは、同じ AWS アカウントによって所有されている必要があります。これには、ロードバランサー、VPC リンク、REST API が含まれます。
+ デフォルトでは、プライベート統合トラフィックは HTTP プロトコルを使用します。HTTPS を使用するには、`https://example.com:443/test` などの安全なサーバー名を含む [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri) を指定します。
+ プライベート統合では、API Gateway はバックエンドリソースへのリクエストに API エンドポイントの[ステージ](set-up-stages.md)部分を含めます。例えば、API の `test` ステージをリクエストすると、API Gateway はプライベート統合へのリクエストに `test/path` を含めます。バックエンドリソースへのリクエストからステージ名を削除するには、[パラメータのマッピング](rest-api-parameter-mapping.md)を使用して、`$context.requestOverride.path` 変数の上書きを作成します。
+ AWS Cloud Map とのプライベート統合はサポートされていません。
**Topics**
+ [
## 考慮事項
](#private-integrations-considerations)
+ [
# API Gateway で VPC リンク V2 を設定する
](apigateway-vpc-links-v2.md)
+ [
# プライベート統合の設定
](set-up-private-integration.md)
+ [
# VPC リンク V1 を使用したプライベート統合 (レガシー)
](vpc-links-v1.md)
# API Gateway で VPC リンク V2 を設定する
VPC リンクを使用すると、Application Load Balancer または Amazon ECS コンテナベースのアプリケーションなどの、API ルートを VPC 内のプライベートリソースに接続するプライベート統合を作成できます。プライベート統合は、VPC リンク V2 を使用して、API Gateway と、対象となる VPC リソース間の接続をカプセル化します。異なるリソースと API 間で VPC リンクを再利用できます。
VPC リンクを作成すると、API Gateway はアカウントの VPC リンク V2 用の [Elastic Network Interface](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) を作成および管理します。このプロセスには数分かかることがあります。VPC リンク V2 を使用する準備ができたら、状態は `PENDING` から `AVAILABLE` に移行します。
**注記**
VPC リンク経由で 60 日間トラフィックが送信されない場合は、`INACTIVE` になります。VPC リンクが `INACTIVE` 状態の場合、API Gateway は VPC リンクのネットワークインターフェイスをすべて削除します。これにより、VPC リンクに依存する API リクエストが失敗します。API リクエストが再開すると、API Gateway はネットワークインターフェイスを再プロビジョニングします。ネットワークインターフェイスを作成し、VPC リンクを再度アクティブ化するには、数分かかることがあります。VPC リンクステータスを使用して、VPC リンクの状態を監視できます。
## AWS CLI を使用して VPC リンク V2 を作成する
VPC リンク V2 を作成するには、関連するすべてのリソースが同じ AWS アカウントによって所有されている必要があります。次の [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html) コマンドは、VPC リンクを作成します。
```
aws apigatewayv2 create-vpc-link --name MyVpcLink \
--subnet-ids subnet-aaaa subnet-bbbb \
--security-group-ids sg1234 sg5678
```
**注記**
VPC リンク V2 は変更できません。VPC リンク V2 を作成した後は、そのサブネットやセキュリティグループを変更することはできません。
## AWS CLI を使用して VPC リンク V2 を削除する
次の [delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html) コマンドは、VPC リンクを削除します。
```
aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123
```
## リージョン別の利用可能性
VPC リンク V2 は、次のリージョンとアベイラビリティーゾーンでサポートされています。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/apigateway-vpc-links-v2.html)
# プライベート統合の設定
Application Load Balancer または Network Load Balancer とのプライベート統合を作成するには、HTTP プロキシ統合を作成し、使用する [VPC リンク V2](apigateway-vpc-links-v2.md) を指定して、Network Load Balancer または Application Load Balancer の ARN を指定します。デフォルトでは、プライベート統合トラフィックは HTTP プロトコルを使用します。HTTPS を使用するには、`https://example.com:443/test` などの安全なサーバー名を含む [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri) を指定します。プライベート統合で REST API を作成する方法の完全なチュートリアルについては、「[チュートリアル: プライベート統合を使用して REST API を作成する](getting-started-with-private-integration.md)」を参照してください。
## プライベート統合の作成
以下の手順は、VPC リンク V2 を使用してロードバランサーに接続するプライベート統合を作成する方法を示しています。
------
#### [ AWS マネジメントコンソール ]
プライベート統合を作成する方法のチュートリアルについては、「[チュートリアル: プライベート統合を使用して REST API を作成する](getting-started-with-private-integration.md)」を参照してください。
------
#### [ AWS CLI ]
次の [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) コマンドは、VPC リンク V2 を使用してロードバランサーに接続するプライベート統合を作成します。
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id bbb111
```
接続 ID を直接指定する代わりに、ステージ変数を使用できます。API をステージにデプロイするときは、VPC リンク V2 ID を設定します。次の [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) コマンドは、VPC リンク V2 ID のステージ変数を使用してプライベート統合を作成します。
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkV2Id}"
```
ステージ変数表現 (\$1\$1stageVariables.vpcLinkV2Id\$1) を二重引用符で囲み、\$1 文字をエスケープします。
------
#### [ OpenAPI ]
API の OpenAPI ファイルをインポートすることで、プライベート統合を使用して API を設定することができます。これらの設定は、HTTP 統合を使用する API の OpenAPI 定義と似ていますが、次のような例外があります。
+ `connectionType` を明示的に `VPC_LINK` に設定する必要があります。
+ `connectionId` を `VpcLinkV2` の ID または `VpcLinkV2` の ID を参照するステージ変数に明示的に設定する必要があります。
+ プライベート統合の `uri` パラメータは、VPC 内の HTTP/HTTPS エンドポイントを指しますが、代わりに統合リクエストの `Host` ヘッダーを設定するために使用されます。
+ VPC 内の HTTPS エンドポイントとのプライベート統合における `uri` パラメータは、記載されているドメイン名を VPC エンドポイントにインストールされている証明書内のドメイン名と照合するために使用されます。
ステージ変数を使用して `VpcLinkV2` ID を参照することができます。または、ID 値を `connectionId` に直接割り当てることもできます。
次の JSON 形式の OpenAPI ファイルは、ステージ変数 (`${stageVariables.vpcLinkIdV2}`) によって参照された VPC リンクが設定された API の例を示しています。
```
{
"swagger": "2.0",
"info": {
"version": "2017-11-17T04:40:23Z",
"title": "MyApiWithVpcLinkV2"
},
"host": "abcdef123.execute-api.us-west-2.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "https://example.com:443/path",
"passthroughBehavior": "when_no_match",
"connectionType": "VPC_LINK",
"connectionId": "${stageVariables.vpcLinkV2Id}",
"integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011",
"httpMethod": "GET",
"type": "http_proxy"
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## プライベート統合の更新
次の例では、プライベート統合の VPC リンク V2 を更新します。
------
#### [ AWS マネジメントコンソール ]
**プライベート統合を更新するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. プライベート統合で REST API を選択します。
1. プライベート統合を使用するリソースとメソッドを選択します。
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. プライベート統合の設定を編集できます。現在 VPC リンク V1 を使用している場合は、VPC リンクを VPC リンク V2 に変更できます。
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
------
#### [ AWS CLI ]
次の [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) コマンドは、VPC リンク V2 を使用するようにプライベート統合を更新します。
```
aws apigateway update-integration \
--rest-api-id a1b2c3d4e5 \
--resource-id a1b2c3 \
--http-method GET \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]"
```
------
# VPC リンク V1 を使用したプライベート統合 (レガシー)
**注記**
プライベート統合の次の実装では、VPC リンク V1 を使用します。VPC リンク V1 はレガシーリソースです。[REST API には VPC リンク V2](apigateway-vpc-links-v2.md) を使用することをお勧めします。
プライベート統合を作成するには、まず Network Load Balancer を作成する必要があります。Network Load Balancer には、VPC 内のリソースにリクエストをルーティングする[リスナー](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html)が必要です。API の可用性を高めるには、Network Load Balancer が、AWS リージョン内の複数のアベイラビリティーゾーンにあるリソースにトラフィックをルーティングするようにします。その後、API と Network Load Balancer を接続するために使用する VPC リンクを作成します。VPC リンクを作成したら、プライベート統合を作成して、VPC リンクと Network Load Balancer を介して API から VPC 内のリソースにトラフィックをルーティングします。Network Load Balancer と API は、同じ AWS アカウントによって所有されている必要があります。
**Topics**
+ [
# API Gateway のプライベート統合の Network Load Balancer を設定する (レガシー)
](set-up-nlb-for-vpclink-using-console.md)
+ [
# VPC リンクを作成するためのアクセス許可を API Gateway に付与する (レガシー)
](grant-permissions-to-create-vpclink.md)
+ [
# AWS CLI を使用してプライベート統合で API Gateway API をセットアップする (レガシー)
](set-up-api-with-vpclink-cli.md)
+ [
# プライベート統合用の API Gateway アカウント (レガシー)
](set-up-api-with-vpclink-accounts.md)
# API Gateway のプライベート統合の Network Load Balancer を設定する (レガシー)
**注記**
プライベート統合の次の実装では、VPC リンク V1 を使用します。VPC リンク V1 はレガシーリソースです。[REST API には VPC リンク V2](apigateway-vpc-links-v2.md) を使用することをお勧めします。
次の手順では、Amazon EC2 コンソールを使用して API Gateway のプライベート統合用に Network Load Balancer (NLB) を設定するステップを説明し、各ステップの詳細な手順の参照を提供します。
各 VPC にリソースがあり、1 つの NLB と 1 つ VPCLink 設定するだけで済みます。NLB は、NLB あたり複数の[リスナー](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html)と[ターゲットグループ](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html)をサポートしています。各サービスを NLB の特定のリスナーとして設定でき、単一の VPCLink を使用して NLB に接続できます。API Gateway でプライベート統合を作成するときに、各サービスに割り当てられた特定のポートを使用して、各サービスを定義します。詳細については、「[チュートリアル: プライベート統合を使用して REST API を作成する](getting-started-with-private-integration.md)」を参照してください。Network Load Balancer と API は、同じ AWS アカウントによって所有されている必要があります。
**API Gateway コンソールを使用してプライベート統合用の Network Load Balancer を作成するには**
1. AWS マネジメントコンソール にサインインし、Amazon EC2 コンソール ([https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)) を開きます。
1. Amazon EC2 インスタンスでウェブサーバーを設定します。設定例については、「[Amazon Linux 2 への LAMP ウェブサーバーのインストール](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html)」を参照してください。
1. Network Load Balancer を作成し、ターゲットグループに EC2 インスタンスを登録し、ターゲットグループを Network Load Balancer のリスナーに追加します。詳細については、「[Network Load Balancer の使用開始](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html)」の手順に従います。
1. Network Load Balancer を作成したら、次の操作を行います。
1. Network Load Balancer の ARN をメモします。API を Network Load Balancer の背後にある VPC リソースと統合するために、API Gateway に VPC リンクを作成する際にそれが必要になります。
1. PrivateLink のセキュリティグループ評価をオフにします。
+ コンソールを使用して PrivateLink トラフィックのセキュリティグループ評価をオフにするには、**[セキュリティ]** タブ、**[編集]** の順に選択します。**[セキュリティ設定]** で、**[PrivateLink トラフィックにインバウンドルールを適用する]** をオフにします。
+ 次の [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html) コマンドを使用して、PrivateLink トラフィックのセキュリティグループの評価をオフにします。
```
aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \
--security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off
```
**注記**
API Gateway CIDR は予告なしに変更されることがありますので、依存関係を追加しないでください。
# VPC リンクを作成するためのアクセス許可を API Gateway に付与する (レガシー)
**注記**
プライベート統合の次の実装では、VPC リンク V1 を使用します。VPC リンク V1 はレガシーリソースです。[REST API には VPC リンク V2](apigateway-vpc-links-v2.md) を使用することをお勧めします。
VPC リンクを作成および維持するためのアカウント内のユーザーは、VPC エンドポイントサービス設定の作成、削除、および表示、VPC エンドポイントサービスのアクセス許可の変更、およびロードバランサーの検証の権限を持っている必要があります。このような権限を付与するには、次のステップを使用します。
**VPC リンクを作成、更新、削除するためのアクセス許可を付与するには**
1. 次のような IAM ポリシーを作成します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST",
"apigateway:GET",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/vpclinks",
"arn:aws:apigateway:us-east-1::/vpclinks/*"
]
},
{
"Effect": "Allow",
"Action": [
"elasticloadbalancing:DescribeLoadBalancers"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpointServiceConfiguration",
"ec2:DeleteVpcEndpointServiceConfigurations",
"ec2:DescribeVpcEndpointServiceConfigurations",
"ec2:ModifyVpcEndpointServicePermissions"
],
"Resource": "*"
}
]
}
```
------
VPC リンクのタグ付けを有効にする場合は、タグ付けオペレーションを許可してください。詳細については、「[タグ付けオペレーションを許可する](apigateway-tagging-iam-policy.md#allow-tagging)」を参照してください。
1. IAM ロールを作成または選択し、前述のポリシーをロールにアタッチします。
1. 自分または VPC リンクを作成しているアカウントのユーザーに IAM ロールを割り当てます。
# AWS CLI を使用してプライベート統合で API Gateway API をセットアップする (レガシー)
**注記**
プライベート統合の次の実装では、VPC リンク V1 を使用します。VPC リンク V1 はレガシーリソースです。[REST API には VPC リンク V2](apigateway-vpc-links-v2.md) を使用することをお勧めします。
次のチュートリアルでは、AWS CLI を使用して VPC リンクとプライベート統合を作成する方法を示します。以下の前提条件を満たす必要があります。
+ ターゲットとして VPC ソースを使用して Network Load Balancer を作成し、設定する必要があります。詳細については、「[API Gateway のプライベート統合の Network Load Balancer を設定する (レガシー)](set-up-nlb-for-vpclink-using-console.md)」を参照してください。これは API と同じ AWS アカウントに存在する必要があります。VPC リンクを作成するには、Network Load Balancer ARN が必要です。
+ `VpcLink` を作成および管理するには、API で `VpcLink` を作成するためのアクセス許可が必要です。`VpcLink` を使用するアクセス許可は必要ありません。詳細については、「[VPC リンクを作成するためのアクセス許可を API Gateway に付与する (レガシー)](grant-permissions-to-create-vpclink.md)」を参照してください。
**AWS CLI を使用して、プライベート統合で API を設定するには**
1. 次の [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html) コマンドを使用して、指定した Network Load Balancer をターゲットとする `VpcLink` を作成します。
```
aws apigateway create-vpc-link \
--name my-test-vpc-link \
--target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef
```
このコマンドの出力は、リクエストの受信を確認し、作成中の `VpcLink` のステータス `PENDING` を示します。
```
{
"status": "PENDING",
"targetArns": [
"arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef"
],
"id": "gim7c3",
"name": "my-test-vpc-link"
}
```
API Gateway が `VpcLink` の作成を完了するまでに 2〜4 分かかります。操作が正常に終了すると、`status` は `AVAILABLE` になります。作成した VPC リンクを確認するには、次の [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html) コマンドを使用できます。
```
aws apigateway get-vpc-link --vpc-link-id gim7c3
```
操作が失敗した場合、エラーメッセージを含む `FAILED` と共に `statusMessage` ステータスが表示されます。たとえば、すでに VPC エンドポイントに関連付けられている Network Load Balancer を使用して `VpcLink` を作成しようとすると、`statusMessage` プロパティで次のように表示されます。
```
"NLB is already associated with another VPC Endpoint Service"
```
`VpcLink` が正常に作成された後は、API を作成し、`VpcLink` を通じて VPC リソースと統合することができます。
新しく作成した `VpcLink` の `id` 値をメモしておきます。この出力例では、`gim7c3` です。プライベート統合を設定する際にそれが必要になります。
1. 次の [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) コマンドを使用して、API Gateway [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースを作成します。
```
aws apigateway create-rest-api --name 'My VPC Link Test'
```
返された結果の `RestApi` の `id` 値と `RestApi` の `rootResourceId` 値をメモしておきます。API でさらにオペレーションを実行するには、この値が必要です。
次に、ルートリソース (`/`) に `GET` メソッドのみを持つ API を作成し、そのメソッドを `VpcLink` と統合します。
1. 次の [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) コマンドを使用して、`GET /` メソッドを作成します。
```
aws apigateway put-method \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--authorization-type "NONE"
```
`VpcLink` とのプロキシ統合を使用しない場合は、少なくとも `200` ステータスコードのメソッドレスポンスも設定する必要があります。ここでは、プロキシ統合を使用します。
1. `GET /` メソッドを作成したら、統合を設定します。プライベート統合の場合は、`connection-id` パラメータを使用して `VpcLink` ID を指定します。ステージ変数を使用するか、`VpcLink` ID を直接入力できます。`uri` パラメータは、エンドポイントへのルーティングリクエストには使用されませんが、`Host` ヘッダーの設定および証明書の検証に使用されます。
------
#### [ Use the VPC link ID ]
次の [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) コマンドを使用して、統合で `VpcLink` ID を直接参照します。
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id gim7c3
```
------
#### [ Use a stage variable ]
次の [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) コマンドを使用して、ステージ変数で VPC リンク ID を参照します。API をステージにデプロイするときは、VPC リンク ID を設定します。
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkId}"
```
ステージ変数表現 (`${stageVariables.vpcLinkId}`) を二重引用符で囲み、`$` 文字をエスケープします。
------
いつでも統合を更新して `connection-id` を変更することもできます。次の [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) コマンドを使用して、統合を更新します。
```
aws apigateway update-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]'
```
文字列化された JSON リストを `patch-operations` パラメータ値として使用するようにしてください。
プライベートプロキシ統合を使用したため、API はデプロイとテスト実行の準備ができました。
1. ステージ変数を使用して `connection-id` を定義した場合は、API をデプロイしてテストする必要があります。次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドを使用して、ステージ変数を含めて API をデプロイします。
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name test \
--variables vpcLinkId=gim7c3
```
`asf9d7` などの別の `VpcLink` ID でステージ変数を更新するには、次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドを使用します。
```
aws apigateway update-stage \
--rest-api-id abcdef123 \
--stage-name test \
--patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'
```
`VpcLink` ID リテラルを使用して `connection-id` プロパティをハードコーディングする場合は、API をデプロイしてテストする必要はありません。[test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html) コマンドを使用して、デプロイ前に API をテストします。
1. 次のコマンドを使用して API を呼び出します。
```
curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test
```
または、ウェブブラウザに API の invoke-URL を入力して結果を表示することもできます。
# プライベート統合用の API Gateway アカウント (レガシー)
次のリージョン固有の API Gateway アカウント ID は、`AllowedPrincipals` の作成時に `VpcLink` として VPC エンドポイントサービスに自動的に追加されます。
| **リージョン** | **アカウント ID** |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
# API Gateway での REST API の Mock 統合
Amazon API Gateway は、API メソッドのモック統合をサポートしています。この機能により、API デベロッパーはバックエンドを統合することなく、API Gateway から直接 API レスポンスを生成できます。API 開発者がこの機能を使用すると、プロジェクト開発の完了前に、API を操作する必要がある他の依存チームのブロックを解除できます。また、この機能を活用して、API の概要や API へのナビゲーションを提供できる API のランディングページをプロビジョニングすることができます。そのようなランディングページの例として、「」で説明されている API 例のルートリソースで、GET メソッドの統合リクエストとレスポンスを参照してください[チュートリアル: サンプルをインポートして REST API を作成する](api-gateway-create-api-from-example.md)
API デベロッパーは、API Gateway がモック統合リクエストにどのように応答するかを決定します。そのため、特定のステータスコードとレスポンスを関連付ける、メソッドの統合リクエストと統合レスポンスを設定します。モック統合で `200` レスポンスを返すメソッドの場合は、以下を返すように統合リクエストボディマッピングテンプレートを設定します。
```
{"statusCode": 200}
```
次のようなボディマッピングテンプレートを持つように `200` 統合レスポンスを設定します。
```
{
"statusCode": 200,
"message": "Go ahead without me."
}
```
同様に、メソッドがたとえば `500` エラーレスポンスを返す場合は、統合リクエストボディマッピングテンプレートを設定して以下を返します。
```
{"statusCode": 500}
```
たとえば、次のマッピングテンプレートを使用して `500` 統合レスポンスを設定します。
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
あるいは、統合リクエストマッピングテンプレートを定義せずに、モック統合のメソッドがデフォルトの統合レスポンスを返すこともできます。デフォルトの統合レスポンスは、未定義の [**HTTP status regex (HTTP ステータスの正規表現)**] を持つレスポンスです。適切なパススルー動作が設定されていることを確認します。
**注記**
モック統合は、大規模なレスポンステンプレートをサポートするためのものではありません。お客様のユースケースにモック統合が必要な場合は、代わりに Lambda 統合を使用することを検討してください。
統合リクエストマッピングテンプレートを使用して、アプリケーションロジックを挿入して、特定の条件に基づいて返すモック統合レスポンスを決定することができます。たとえば、受信リクエストに対して `scope` クエリパラメータを使用して、成功レスポンスまたはエラーレスポンスを返すかどうかを判断できます。
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
このように、モック統合の方法では、エラーレスポンスを伴う他のタイプの呼び出しを拒否しながら、内部呼び出しを通過させることができます。
このセクションでは、API Gateway コンソールを使用して、API メソッドのモック統合を有効にする方法を説明します。
**Topics**
+ [
# API Gateway コンソールを使用したモック統合の有効化
](how-to-mock-integration-console.md)
# API Gateway コンソールを使用したモック統合の有効化
メソッドが API Gateway で使用可能であることが必要です。「[チュートリアル: HTTP 非プロキシ統合を使用して REST API を作成する](api-gateway-create-api-step-by-step.md)」の手順に従います。
1. API リソースを選択し、**[メソッドを作成]** を選択します。
メソッドを作成するには、次の操作を行います。
1. **[メソッドタイプ]** で、メソッドを選択します。
1. **[統合タイプ]** で、**[Mock]** を選択します。
1. **[メソッドの作成]** を選択します。
1. **[メソッドリクエスト]** タブの **[メソッドリクエストの設定]** で、**[編集]** を選択します。
1. **[URL クエリ文字列パラメータ]** を選択します。**[クエリ文字列を追加]** を選択し、**[名前]** に「**scope**」と入力します。このクエリパラメータは、呼び出し元が内部かどうかを決定します。
1. **[保存]** を選択します。
1. **[メソッドレスポンス]** タブで **[レスポンスを作成]** を選択し、次の操作を行います。
1. **[HTTP ステータス]** に「**500**」と入力します。
1. **[保存]** を選択します。
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[マッピングテンプレート]** を選択し、次の操作を行います。
1. [**マッピングテンプレートの追加**] を選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
1. **[保存]** を選択します。
1. **[統合レスポンス]** タブの **[デフォルト - レスポンス]** で、**[編集]** を選択します。
1. **[マッピングテンプレート]** を選択し、次の操作を行います。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
{
"statusCode": 200,
"message": "Go ahead without me"
}
```
1. **[保存]** を選択します。
1. **[レスポンスの作成]** を選択します。
500 レスポンスを作成するには、次の操作を行います。
1. [**HTTP status regex (HTTP ステータスの正規表現)**]に「**5\$1d\$12\$1**」と入力します。
1. **[メソッドレスポンスのステータス]** で、[**500**] を選択します。
1. **[保存]** を選択します。
1. **[5\$1d\$12\$1 - レスポンス]** で、**[編集]** を選択します。
1. **[マッピングテンプレート]**、**[マッピングテンプレートの追加]** の順に選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
1. **[保存]** を選択します。
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。Mock 統合をテストするには、次の操作を行います。
1. **[クエリ文字列]** に「`scope=internal`」と入力します。[**Test (テスト)**] を選択します。テストの結果が表示されます。
```
Request: /?scope=internal
Status: 200
Latency: 26 ms
Response Body
{
"statusCode": 200,
"message": "Go ahead without me"
}
Response Headers
{"Content-Type":"application/json"}
```
1. `scope=public` に「`Query strings`」と入力するか、空白のままにします。[**Test (テスト)**] を選択します。テストの結果が表示されます。
```
Request: /
Status: 500
Latency: 16 ms
Response Body
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
Response Headers
{"Content-Type":"application/json"}
```
また、メソッドレスポンスにヘッダーを追加してから、統合レスポンスでヘッダーマッピングを設定することによって、モック統合レスポンスでヘッダーを返すこともできます。実際に、これは API Gateway コンソールで CORS の必要なヘッダーを返すことによって CORS サポートを有効にする方法です。
# API Gateway での REST API のリクエスト検証
統合リクエストを進める前に API リクエストの基本的な検証を実行するよう API Gateway を設定できます。検証に失敗した場合、API Gateway はすぐにリクエストに失敗して、400 個のエラーレスポンスを発信者に返し、CloudWatch Logs で検証結果を発行します。これによりバックエンドへの不必要な呼び出すが減少します。さらに重要な点として、アプリケーション固有の検証作業に集中することができます。リクエスト本文を検証するには、必要なリクエストパラメータが有効で null でないことを確認するか、より複雑なデータ検証用のモデルスキーマを指定します。
**Topics**
+ [
## API Gateway における基本的なリクエストの検証の概要
](#api-gateway-request-validation-basic-definitions)
+ [
# REST API のデータモデル
](models-mappings-models.md)
+ [
# API Gateway で基本的なリクエストの検証を設定する
](api-gateway-request-validation-set-up.md)
+ [
# 基本的なリクエスト検証を含むサンプル API の AWS CloudFormation テンプレート
](api-gateway-request-validation-sample-cloudformation.md)
## API Gateway における基本的なリクエストの検証の概要
基本的なリクエストの検証は API Gateway で処理できるため、ユーザーはバックエンドでのアプリケーション固有の検証に集中できます。検証のために、API Gateway は以下の条件のどちらかまたは両方を確認します。
+ 受信リクエストの URI、クエリ文字列、ヘッダーに必要なリクエストパラメータが含まれており、空白ではない。API Gateway はパラメータの存在のみをチェックし、タイプまたは形式はチェックしません。
+ 該当するリクエストペイロードが、特定のコンテンツタイプのためのメソッドの[設定済みの JSON スキーマ](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04)リクエストに準拠している。一致するコンテンツタイプが見つからない場合、リクエストの検証は実行されません。コンテンツタイプを問わず同じモデルを使用するには、データモデルのコンテンツタイプを `$default` に設定します。
検証を有効にするには、[リクエストの検証](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)により検証ルールを指定し、この検証を API の[リクエストの検証のマップ](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)に追加し、検証を個々の API メソッドに割り当てます。
**注記**
リクエスト本文の検証と[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)は、2 つの異なるトピックです。リクエストペイロードと一致するモデルスキーマがない場合、元のペイロードをパススルーするかブロックするかを選択できます。詳細については、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
# REST API のデータモデル
API Gateway では、モデルはペイロードのデータ構造を定義します。API Gateway では、[JSON スキーマのドラフト 4](https://tools.ietf.org/html/draft-zyp-json-schema-04) を使用してモデルを定義します。次の JSON オブジェクトは、PetStore の例のサンプルデータです。
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
データには、ペットの `id`、`type`、`price` が含まれています。このデータのモデルにより、以下のことが可能になります。
+ 基本的なリクエストの検証を使用する。
+ データ変換用のマッピングテンプレートを作成する。
+ SDK を生成するときに、ユーザー定義データ型 (UDT) を作成する。
![\[PetStore API の JSON データモデルの例。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/how-to-validate-requests.png)
このモデルの内容は以下のとおりです。
1. `$schema` オブジェクトは、有効な JSON スキーマのバージョン識別子を表します。このスキーマは JSON スキーマのドラフト v4 です。
1. `title` オブジェクトは、人間が読めるモデルの識別子です。このタイトルは `PetStoreModel` です。
1. `required` 検証キーワードには、基本的なリクエストの検証用の `type` と `price` が必要です。
1. モデルの `properties` は、`id`、`type`、`price` です。各オブジェクトには、モデルに記述されているプロパティがあります。
1. オブジェクト `type` は、値として `dog`、`cat`、`fish` のいずれかのみを持つことができます。
1. オブジェクト `price` は数値で、`minimum` が 25、`maximum` が 500 に制限されます。
## PetStore モデル
```
1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3 "title": "PetStoreModel",
4 "type" : "object",
5 "required" : [ "price", "type" ],
6 "properties" : {
7 "id" : {
8 "type" : "integer"
9 },
10 "type" : {
11 "type" : "string",
12 "enum" : [ "dog", "cat", "fish" ]
13 },
14 "price" : {
15 "type" : "number",
16 "minimum" : 25.0,
17 "maximum" : 500.0
18 }
19 }
20 }
```
このモデルの内容は以下のとおりです。
1. 2 行目で、`$schema` オブジェクトは有効な JSON スキーマのバージョン識別子を表します。このスキーマは JSON スキーマのドラフト v4 です。
1. 3 行目で、`title` オブジェクトは、人間が読めるモデルの識別子です。このタイトルは `PetStoreModel` です。
1. 5 行目で、`required` 検証キーワードには、基本的なリクエストの検証用の `type` と `price` が必要です。
1. 6～17 行目で、モデルの `properties` は `id`、`type`、`price` です。各オブジェクトには、モデルに記述されているプロパティがあります。
1. 12 行目で、オブジェクト `type` は値として `dog`、`cat`、`fish` のいずれかのみを持つことができます。
1. 14～17 行目で、オブジェクト `price` は数値で、`minimum` が 25、`maximum` が 500 に制限されます。
## より複雑なモデルの作成
`$ref` プリミティブを使用すると、より長いモデルの再利用可能な定義を作成できます。例えば、`price` オブジェクトを記述する `definitions` セクションで、`Price` という定義を作成できます。`$ref` の値は `Price` 定義です。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReUsableRef",
"required" : ["price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "#/definitions/Price"
}
},
"definitions" : {
"Price": {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
外部モデルファイルで定義された別のモデルスキーマを参照することもできます。`$ref` プロパティの値をモデルの場所に設定します。次の例では、`Price` モデルは API `a1234` の `PetStorePrice` モデルに定義されています。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStorePrice",
"type": "number",
"minimum": 25,
"maximum": 500
}
```
より長いモデルは `PetStorePrice` モデルを参照できます。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReusableRefAPI",
"required" : [ "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
}
}
}
```
## 出力データモデルを使用する
データを変換する場合、統合レスポンスでペイロードモデルを定義できます。ペイロードモデルは SDK を生成するときに使用できます。Java、Objective-C、Swift などの厳密に型指定された言語では、オブジェクトはユーザー定義データ型 (UDT) に対応します。SDK の生成時にデータモデルで UDT を指定すると、API Gateway は UDT を作成します。データ変換の詳細については、「[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md)」を参照してください。
以下は、統合レスポンスからの出力データの例です。
```
{
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
}
```
次の例は、出力データを記述するペイロードモデルです。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetStoreOutputModel",
"type" : "object",
"required" : [ "description", "askingPrice" ],
"properties" : {
"description" : {
"type" : "string"
},
"askingPrice" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
このモデルでは、SDK を呼び出し、`PetStoreOutputModel[i].description` プロパティと `PetStoreOutputModel[i].askingPrice` プロパティを読み取ることで、`description` と `askingPrice` のプロパティ値を取得できます。モデルが指定されていない場合、API Gateway は空のモデルを使用してデフォルト UDT を作成します。
## 次のステップ
+ このセクションでは、このトピックで紹介した概念について理解を深めるために役立つリソースを紹介します。
以下のリクエストの検証チュートリアルを参考にしてください。
+ [API Gateway コンソールを使用してリクエストの検証を設定する](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console)
+ [AWS CLI を使用して基本的なリクエストの検証を設定する](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli)
+ [OpenAPI 定義を使用して基本的なリクエストの検証を設定する](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger)
+ データ変換とマッピングテンプレートの詳細については、「[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md)」を参照してください。
# API Gateway で基本的なリクエストの検証を設定する
このセクションでは、コンソール、AWS CLI、OpenAPI 定義を使用して API Gateway のリクエストの検証を設定する方法を示します。
**Topics**
+ [
## API Gateway コンソールを使用してリクエストの検証を設定する
](#api-gateway-request-validation-setup-in-console)
+ [
## AWS CLI を使用して基本的なリクエストの検証を設定する
](#api-gateway-request-validation-setup-cli)
+ [
## OpenAPI 定義を使用して基本的なリクエストの検証を設定する
](#api-gateway-request-validation-setup-importing-swagger)
## API Gateway コンソールを使用してリクエストの検証を設定する
API Gateway コンソールで API リクエストの 3 つの検証から 1 つを選択して、リクエストを検証できます。
+ **本体の検証**。
+ **クエリ文字列パラメータとヘッダーの検証**。
+ **本文、クエリ文字列パラメータ、ヘッダーの検証**。
上記のいずれかの検証を API メソッドに適用すると、API Gateway コンソールは検証を API の [RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) マップに追加します。
このチュートリアルに従うには、CloudFormation テンプレートを使用して不完全な API Gateway API を作成します。この API には、`GET` メソッドと `POST` メソッドを持つ `/validator` リソースがあります。どちらのメソッドも `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP エンドポイントと統合されています。次の 2 種類のリクエストの検証を設定します。
+ `GET` メソッドでは、URL クエリ文字列パラメータに対するリクエストの検証を設定します。
+ `POST` メソッドでは、リクエスト本文に対するリクエストの検証を設定します。
これにより、特定の API コールのみを API にパススルーできます。
[CloudFormation のアプリケーション作成テンプレート](samples/request-validation-tutorial-console.zip)をダウンロードして解凍します。このテンプレートを使用して不完全な API を作成します。残りのステップは API Gateway コンソールで完了します。
**CloudFormation スタックを作成するには**
1. [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) で CloudFormation コンソール を開きます。
1. [**スタックの作成**] を選択し、[**With new resources (standard) 新しいリソースを使用 (標準)**] を選択します。
1. [**Specify template (テンプレートの指定)**] で、[**Upload a template file (テンプレートファイルのアップロード)**] を選択します。
1. ダウンロードしたテンプレートを選択します。
1. [**Next (次へ)**] を選択します。
1. [**Stack name**] (スタックの名前) で、**request-validation-tutorial-console** と入力し、[**Next**] (次へ) を選択します。
1. [**Configure stack options**] (スタックオプションの設定) で、[**Next**] (次へ) を選択します。
1. [**Capabilities**] (機能) で、CloudFormation がアカウントに IAM リソースを作成できることを承認します。
1. **[次へ]** を選択し、**[送信]** を選択します。
CloudFormation は、テンプレートで指定されたリソースをプロビジョニングします。リソースのプロビジョニングには数分かかることがあります。CloudFormation スタックのステータスが **CREATE\$1COMPLETE** の場合は、次のステップに進む準備ができています。
**新しく作成した API を選択するには**
1. 新しく作成した **request-validation-tutorial-console** スタックを選択します。
1. **[リソース]** をクリックします。
1. **[物理 ID]** で API を選択します。このリンクを使用して API Gateway コンソールに移動します。
`GET` メソッドと `POST` メソッドを変更する前に、モデルを作成する必要があります。
**モデルを作成するには**
1. 受信リクエストの本文でリクエストの検証を使用するには、モデルが必要です。モデルを作成するには、メインナビゲーションペインで **[モデル]** を選択します。
1. **[モデルの作成]** を選択します。
1. **[Name]** (名前) には **PetStoreModel** を入力します。
1. **[コンテンツタイプ]** として、「**application/json**」と入力します。一致するコンテンツタイプが見つからない場合、リクエストの検証は実行されません。コンテンツタイプに関係なく同じモデルを使用するには、「**\$1default**」と入力します。
1. **[説明]** に、モデルの説明として「**My PetStore Model**」と入力します。
1. **[モデルスキーマ]** で、次のモデルをコードエディタに貼り付け、**[作成]** を選択します。
```
{
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
これらのモデルの詳細については、「[REST API のデータモデル](models-mappings-models.md)」を参照してください。
**`GET` メソッドのリクエスト検証を設定するには**
1. メインナビゲーションペインで **[リソース]**、**[GET]** メソッドの順に選択します。
1. **[メソッドリクエスト]** タブの **[メソッドリクエスト設定]** で、**[編集]** を選択します。
1. **[リクエストの検証]** で、**[クエリ文字列パラメータおよびヘッダーを検証]** を選択します。
1. **[URL クエリ文字列パラメータ]** で、次の操作を行います。
1. [**クエリ文字列の追加**] を選択します。
1. **[Name]** (名前) には **petType** を入力します。
1. **[必須]** をオンにします。
1. **[キャッシュ]** はオフのままにします。
1. **[保存]** を選択します。
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[URL クエリ文字列パラメータ]** で、次の操作を行います。
1. [**クエリ文字列の追加**] を選択します。
1. **[Name]** (名前) には **petType** を入力します。
1. **[マッピング元]** として「**method.request.querystring.petType**」と入力します。これは、**petType** をペットの種類にマッピングします。
データマッピングの詳細については、[データマッピングチュートリアル](set-up-data-transformations-in-api-gateway.md#mapping-example-console)を参照してください。
1. **[キャッシュ]** はオフのままにします。
1. **[保存]** を選択します。
**`GET` メソッドのリクエスト検証をテストするには**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[クエリ文字列]** に「**petType=dog**」と入力し、**[テスト]** を選択します。
1. メソッドテストが `200 OK` と犬のリストを返します。
この出力データを変換する方法については、[データマッピングチュートリアル](set-up-data-transformations-in-api-gateway.md#mapping-example-console)を参照してください。
1. **petType=dog** を削除して **[テスト]** を選択します。
1. メソッドテストは、`400` エラーを返し、次のエラーメッセージを表示します。
```
{
"message": "Missing required request parameters: [petType]"
}
```
**`POST` メソッドのリクエスト検証を設定するには**
1. メインナビゲーションペインで、**[ステージ]**、**[POST]** メソッドの順に選択します。
1. **[メソッドリクエスト]** タブの **[メソッドリクエスト設定]** で、**[編集]** を選択します。
1. **[リクエストの検証]** で **[本文を検証]** を選択します。
1. **[リクエスト本文]** で、**[モデルを追加]** を選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。一致するコンテンツタイプが見つからない場合、リクエストの検証は実行されません。コンテンツタイプに関係なく同じモデルを使用するには、「`$default`」と入力します。
**[モデル]** で、**PetStoreModel** を選択します。
1. **[保存]** を選択します。
**`POST` メソッドのリクエスト検証をテストするには**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[リクエスト本文]** で、次の内容をコードエディタに貼り付けます。
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 400
}
```
**[テスト]** を選択します。
1. メソッドテストは、`200 OK` と成功メッセージを返します。
1. **[リクエスト本文]** で、次の内容をコードエディタに貼り付けます。
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 4000
}
```
**[テスト]** を選択します。
1. メソッドテストは、`400` エラーを返し、次のエラーメッセージを表示します。
```
{
"message": "Invalid request body"
}
```
テストログの一番下に、無効なリクエスト本文の理由が表示されます。この場合、ペットの価格はモデルに指定されている上限を超えていました。
**CloudFormation スタックを削除するには**
1. CloudFormation コンソール ([https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)) を開きます。
1. CloudFormation スタックを選択します。
1. [**Delete**] (削除) を選択し、選択を確定します。
### 次のステップ
+ 出力データを変換して、より多くのデータマッピングを実行する方法については、[データマッピングチュートリアル](set-up-data-transformations-in-api-gateway.md#mapping-example-console)を参照してください。
+ [AWS CLI を使用して基本的なリクエストの検証を設定する](#api-gateway-request-validation-setup-cli)チュートリアルに従い、AWS CLI を使用して同様の手順を実行します。
## AWS CLI を使用して基本的なリクエストの検証を設定する
AWS CLI を使用してリクエストの検証を設定するための検証を作成できます。このチュートリアルに従うには、CloudFormation テンプレートを使用して不完全な API Gateway API を作成します。
**注記**
これはコンソールチュートリアルと同じ CloudFormation テンプレートではありません。
事前に公開されている `/validator` リソースを使用して `GET` メソッドと `POST` メソッドを作成します。どちらのメソッドも `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP エンドポイントと統合されます。次の 2 つのリクエストの検証を設定します。
+ `GET` メソッドでは、`params-only` 検証を作成して URL クエリ文字列パラメータを検証します。
+ `POST` メソッドでは、`body-only` 検証を作成してリクエスト本文を検証します。
これにより、特定の API コールのみを API にパススルーできます。
**CloudFormation スタックを作成するには**
[CloudFormation のアプリケーション作成テンプレート](samples/request-validation-tutorial-cli.zip)をダウンロードして解凍します。
次のチュートリアルを完了するには、[AWS Command Line Interface (AWS CLI) バージョン 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) が必要です。
コマンドが長い場合は、エスケープ文字 (`\`) を使用してコマンドを複数行に分割します。
**注記**
Windows では、一般的に使用する Bash CLI コマンドの一部 (`zip` など) が、オペレーティングシステムの組み込みターミナルでサポートされていません。Ubuntu および Bash の Windows 統合バージョンを取得するには、[Windows Subsystem for Linux をインストール](https://learn.microsoft.com/en-us/windows/wsl/install)します。このガイドの CLI コマンドの例では、Linux フォーマットを使用しています。Windows CLI を使用している場合、インライン JSON ドキュメントを含むコマンドを再フォーマットする必要があります。
1. 次のコマンドを使用して CloudFormation スタックを作成します。
```
aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation は、テンプレートで指定されたリソースをプロビジョニングします。リソースのプロビジョニングには数分かかることがあります。次のコマンドを使用して CloudFormation スタックのステータスを確認します。
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli
```
1. CloudFormation スタックのステータスが `StackStatus: "CREATE_COMPLETE"` になったら、次のコマンドを使用して関連する出力値を取得し、以後のステップで使用します。
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
出力値は以下のとおりです。
+ ApiId。API の ID です。このチュートリアルの場合、API ID は `abc123` です。
+ ResourceId。`GET` メソッドと `POST` メソッドが公開されている検証リソースの ID です。このチュートリアルの場合、リソース ID は `efg456` です。
**リクエストの検証を作成してモデルをインポートするには**
1. AWS CLI でリクエストの検証を行うには、検証が必要です。リクエストパラメータのみを検証する検証を作成するには、次のコマンドを使用します。
```
aws apigateway create-request-validator --rest-api-id abc123 \
--no-validate-request-body \
--validate-request-parameters \
--name params-only
```
`params-only` 検証の ID をメモしておきます。
1. リクエスト本文のみを検証する検証を作成するには、次のコマンドを使用します。
```
aws apigateway create-request-validator --rest-api-id abc123 \
--validate-request-body \
--no-validate-request-parameters \
--name body-only
```
`body-only` 検証の ID をメモしておきます。
1. 受信リクエストの本文でリクエストの検証を行うには、モデルが必要です。モデルをインポートするには、以下のコマンドを使用します。
```
aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}'
```
一致するコンテンツタイプが見つからない場合、リクエストの検証は実行されません。コンテンツタイプに関係なく同じモデルを使用するには、キーとして `$default` を指定します。
**`GET` メソッドと `POST` メソッドを作成するには**
1. 次のコマンドを使用して、`GET` HTTP メソッドを `/validate` リソースに追加します。このコマンドは、`GET` メソッドを作成して、`params-only` 検証を追加し、必要に応じてクエリ文字列 `petType` を設定します。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--authorization-type "NONE" \
--request-validator-id aaa111 \
--request-parameters "method.request.querystring.petType=true"
```
次のコマンドを使用し、`POST` HTTP メソッドを `/validate` リソースに追加します。このコマンドは、`POST` メソッドを作成して、`body-only` 検証を追加し、モデルを本文専用の検証にアタッチします。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
--request-validator-id bbb222 \
--request-models 'application/json'=PetStoreModel
```
1. 次のコマンドを使用して、`GET /validate` メソッドの `200 OK` レスポンスを設定します。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200
```
次のコマンドを使用して、`POST /validate` メソッドの `200 OK` レスポンスを設定します。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 次のコマンドを使用して、`GET /validation` メソッドの指定された HTTP エンドポイントを `Integration` に設定します。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--type HTTP \
--integration-http-method GET \
--request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
次のコマンドを使用して、`POST /validation` メソッドの指定された HTTP エンドポイントを `Integration` に設定します。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
1. 次のコマンドを使用して、`GET /validation` メソッドの統合レスポンスを設定します。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456\
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
次のコマンドを使用して、`POST /validation` メソッドの統合レスポンスを設定します。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern ""
```
**API をテストするには**
1. クエリ文字列に対するリクエストの検証を実行する `GET` メソッドをテストするには、次のコマンドを使用します。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--path-with-query-string '/validate?petType=dog'
```
結果として、`200 OK` と犬のリストが返されます。
1. 次のコマンドを使用して、クエリ文字列 `petType` を含めずにテストします。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
結果として `400` エラーが返されます。
1. リクエスト本文に対するリクエストの検証を実行する `POST` メソッドをテストするには、次のコマンドを使用します。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'
```
結果として、`200 OK` と成功メッセージが返されます。
1. 次のコマンドを実行し、無効な本文を使用してテストします。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }'
```
犬の価格がモデルで定義されている最大価格を超えているため、結果として `400` エラーが返されます。
**CloudFormation スタックを削除するには**
+ CloudFormation リソースを削除するには、次のコマンドを使用します。
```
aws cloudformation delete-stack --stack-name request-validation-tutorial-cli
```
## OpenAPI 定義を使用して基本的なリクエストの検証を設定する
API レベルでリクエストの検証を宣言するには、[x-amazon-apigateway-request-validators オブジェクト](api-gateway-swagger-extensions-request-validators.md) マップ内の [x-amazon-apigateway-request-validators.requestValidator オブジェクト](api-gateway-swagger-extensions-request-validators.requestValidator.md) オブジェクトのセットを指定して、リクエストのどの部分を検証するかを選択します。OpenAPI 定義の例では、次の 2 つの検証があります。
+ `all` 検証では、本文 (`RequestBodyModel` データモデルを使用) とパラメータの両方を検証します。
`RequestBodyModel` データモデルでは、入力 JSON オブジェクトに `name`、`type`、`price` の各プロパティを含める必要があります。`name` プロパティは任意の文字列にすることができ、`type` は指定された列挙フィールド (`["dog", "cat", "fish"]`) のいずれかでなければなりません。また、`price` は 25 から 500 の範囲にする必要があります。`id` パラメータは必須ではありません。
+ `param-only` 検証では、パラメータのみを検証します。
API のすべてのメソッドでリクエストの検証を有効にするには、OpenAPI 定義の API レベルで [x-amazon-apigateway-request-validator プロパティ](api-gateway-swagger-extensions-request-validator.md) プロパティを指定します。OpenAPI 定義の例の場合、`all` 検証は、オーバーライドされない限り、すべての API メソッドで使用されます。モデルを使用して本文を検証する際、一致するコンテンツタイプが見つからない場合、リクエストの検証は実行されません。コンテンツタイプに関係なく同じモデルを使用するには、キーとして `$default` を指定します。
個々のメソッドでリクエストの検証を有効にするには、メソッドレベルで `x-amazon-apigateway-request-validator` プロパティを指定します。OpenAPI 定義の例の場合、`param-only` 検証は `GET` メソッドの `all` 検証を上書きします。
OpenAPI のサンプルを API Gateway にインポートするには、[リージョン API を API Gateway にインポートする](import-export-api-endpoints.md) または [エッジ最適化 API を API Gateway にインポートする](import-edge-optimized-api.md) に対する次の手順を参照してください。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ReqValidators Sample",
"version" : "1.0.0"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "/v1"
}
}
} ],
"paths" : {
"/validation" : {
"get" : {
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RequestBodyModel"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"RequestBodyModel" : {
"required" : [ "name", "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"maximum" : 500.0,
"minimum" : 25.0,
"type" : "number"
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Error"
}
},
"Error" : {
"type" : "object"
}
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "1.0.0",
"title" : "ReqValidators Sample"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/validation" : {
"get" : {
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"consumes" : [ "application/json" ],
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"type" : "string"
}, {
"in" : "body",
"name" : "RequestBodyModel",
"required" : true,
"schema" : {
"$ref" : "#/definitions/RequestBodyModel"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"definitions" : {
"RequestBodyModel" : {
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Error"
}
},
"Error" : {
"type" : "object"
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
# 基本的なリクエスト検証を含むサンプル API の AWS CloudFormation テンプレート
以下の CloudFormation テンプレート定義の例は、リクエストの検証が有効なサンプル API を定義します。API は、[PetStore API](http://petstore-demo-endpoint.execute-api.com/petstore/pets) のサブセットです。`POST` メソッドを開示し、ペットを `pets` コレクションおよび `GET` メソッドに追加して、指定されたタイプによりペットのクエリを実行します。
宣言されているリクエスト検証は 2 つあります。
**`GETValidator`**
この検証は、`GET` メソッドで有効になります。この検証により、必須のクエリパラメータ (`q1`) が受信リクエストに含まれており、空白でないことを API Gateway が確認できるようになります。
**`POSTValidator`**
この検証は、`POST` メソッドで有効になります。これにより、API Gateway は、コンテンツタイプが `application/json` のとき、ペイロードリクエスト形式が指定された `RequestBodyModel` に準拠していることを検証できます。一致するコンテンツタイプが見つからない場合、リクエストの検証は実行されません。コンテンツタイプに関係なく同じモデルを使用するには、`$default` を指定します。`RequestBodyModel` にはペット ID を定義する追加のモデル `RequestBodyModelId` が含まれています。
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: ReqValidatorsSample
RequestBodyModelId:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModelId
properties:
id:
type: integer
RequestBodyModel:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet type, name, price, and ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModel
required:
- price
- name
- type
type: object
properties:
id:
"$ref": !Sub
- 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}'
- Api: !Ref Api
RequestBodyModelId: !Ref RequestBodyModelId
price:
type: number
minimum: 25
maximum: 500
name:
type: string
type:
type: string
enum:
- "dog"
- "cat"
- "fish"
GETValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: params-only
RestApiId: !Ref Api
ValidateRequestBody: False
ValidateRequestParameters: True
POSTValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: body-only
RestApiId: !Ref Api
ValidateRequestBody: True
ValidateRequestParameters: False
ValidationResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'validation'
ValidationMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: GET
AuthorizationType: NONE
RequestValidatorId: !Ref GETValidator
RequestParameters:
method.request.querystring.q1: true
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ValidationMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: POST
AuthorizationType: NONE
RequestValidatorId: !Ref POSTValidator
RequestModels:
application/json : !Ref RequestBodyModel
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: POST
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- ValidationMethodGet
- RequestBodyModel
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# API Gateway での REST API のデータ変換
**注記**
このセクションでは、非プロキシ統合で使用する関数について説明します。ただし、可能な場合は、REST API ではプロキシ統合を使用することをお勧めします。プロキシ統合にも合理化された統合設定があり、既存の設定を破棄することなくバックエンドで拡張できます。詳細については、「[API Gateway API 統合タイプの選択](api-gateway-api-integration-types.md)」を参照してください。
非プロキシ統合を使用する場合、API Gateway の 2 つの関数を使用して、メソッドリクエストと統合レスポンスを変換できます。統合リクエストのペイロードとは異なるペイロード形式を使用している場合は、メソッドリクエストを変換できます。メソッドレスポンスで返す必要がある形式とは異なるペイロード形式が返された場合、統合レスポンスを変換できます。リクエストのライフサイクルに関する詳細は、「[REST API のリソース例](rest-api-develop.md#rest-api-develop-example)」を参照してください。
次の例は、ヘッダー `"x-version:beta"` の場合、`x-version` ヘッダーパラメータが `app-version` ヘッダーパラメータに変換されるデータ変換を説明しています。`x-version` から `app-version` へのデータ変換は、統合リクエストで行われます。これにより、統合エンドポイントは変換されたヘッダーパラメータ値を受け取ります。統合エンドポイントがステータスコードを返すと、メソッドレスポンスの前にステータスコードが `200` から `204` に変換されます。
![\[API Gateway データ変換の図\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/develop-non-proxy.png)
データ変換を作成するには、以下の関数を使用できます。
**パラメータのマッピング**
パラメータマッピングで変更できるのは、統合リクエストの URL パスパラメータ、URL クエリ文字列パラメータ、または HTTP ヘッダー値です。統合リクエストペイロードは変更できません。HTTP レスポンスヘッダー値も変更できます。パラメータマッピングを使用して、Cross-Origin Resource Sharing(CORS) の静的ヘッダー値を作成します。
パラメータマッピングは、プロキシ統合と非プロキシ統合の統合リクエストでは使用できますが、統合レスポンスでは、非プロキシ統合を使用する必要があります。パラメータマッピングでは、[Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) でのスクリプトは必要ありません。詳細については、「[API Gateway の REST API パラメータマッピング](rest-api-parameter-mapping.md)」を参照してください。
**テンプレート変換のマッピング**
マッピングテンプレート変換では、マッピングテンプレートを使用して、URL パス パラメータ、URL クエリ文字列パラメータ、HTTP ヘッダー、統合リクエストまたは統合レスポンスの本文をマッピングします。*マッピングテンプレート*は、[JSONPath 式](https://goessner.net/articles/JsonPath/)を使用して [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) で表現され、`Content-type` ヘッダーに基づいてペイロードに適用されるスクリプトです。
マッピングテンプレートでは、以下を実行できます。
+ Amazon DynamoDB や Lambda 関数などの AWS のサービス、または HTTP エンドポイントとの統合を使用して送信するデータを選択します。詳細については、「[チュートリアル: AWS サービスへの統合のための統合リクエストとレスポンスを変更する](set-up-data-transformations-in-api-gateway.md)」を参照してください。
+ API の統合リクエストと統合レスポンスパラメータを条件付きで上書きし、新しいヘッダー値を作成して、ステータスコードを上書きします。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。
統合リクエスト本文に一致するマッピングテンプレートがない `Content-type` ヘッダーがある場合の API の動作を指定することもできます。これは、統合パススルーの動作と呼ばれます。詳細については、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
## パラメータマッピングとマッピングテンプレート変換のどちらかを選択する
可能であれば、データの変換にはパラメータマッピングの使用をお勧めします。API で本文を変更する必要がある場合、または受信統合リクエストまたは統合レスポンスに基づいて条件付き上書きと変更を実行する必要がある場合に、プロキシ統合を使用できないときは、マッピングテンプレート変換を使用します。
# API Gateway の REST API パラメータマッピング
**注記**
HTTP API を使用している場合は、「[API Gateway で HTTP API の API リクエストとレスポンスを変換する](http-api-parameter-mapping.md)」を参照してください。
パラメータマッピングでは、リクエストまたはレスポンスパラメータをマッピングします。パラメータのマッピングには、パラメータマッピング式または静的な値を使用できます。マッピング式のリストについては、「[API Gateway での REST API パラメータマッピングのソースのリファレンス](rest-api-parameter-mapping-sources.md)」を参照してください。パラメータマッピングは、プロキシ統合と非プロキシ統合の統合リクエストでは使用できますが、統合レスポンスでは、非プロキシ統合を使用する必要があります。
例えば、メソッドリクエストヘッダーパラメータ `puppies` を統合リクエストヘッダーパラメータ `DogsAge0` にマッピングできます。その後、クライアントが API にヘッダー `puppies:true` を送信すると、統合リクエストはリクエストヘッダー `DogsAge0:true` を統合エンドポイントに送信します。次の図は、この例のリクエストライフサイクルを説明しています。
![\[リクエストの API Gateway パラメータマッピングの例の図\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
API Gateway を使用してこの例を作成するには、「[例 1: メソッドリクエストパラメータを統合リクエストパラメータにマッピングする](request-response-data-mappings.md#request-response-data-mappings-example-1)」を参照してください。
別の例としては、統合レスポンスヘッダーパラメータ `kittens` をメソッドレスポンスヘッダーパラメータ `CatsAge0` にマッピングすることもできます。その後、統合エンドポイントが `kittens:false` を返すと、クライアントはヘッダー `CatsAge0:false` を受け取ります。次の図は、この例のリクエストライフサイクルを説明しています。
![\[レスポンスの API Gateway パラメータマッピングの例の図\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [
# API Gateway での REST API パラメータマッピングの例
](request-response-data-mappings.md)
+ [
# API Gateway での REST API パラメータマッピングのソースのリファレンス
](rest-api-parameter-mapping-sources.md)
# API Gateway での REST API パラメータマッピングの例
次の例は、API Gateway コンソール、OpenAPI、CloudFormation テンプレートを使用して、パラメータマッピング式を作成する方法を説明しています。パラメータマッピングを使用して必要な CORS ヘッダーを作成する方法の例については、「[API Gateway での REST API の CORS](how-to-cors.md)」を参照してください。
## 例 1: メソッドリクエストパラメータを統合リクエストパラメータにマッピングする
次の例では、メソッドリクエストヘッダーパラメータ `puppies` を統合リクエストヘッダーパラメータ `DogsAge0` にマッピングします。
------
#### [ AWS マネジメントコンソール ]
**メソッドリクエストパラメータをマッピングするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メソッドを選択します。
メソッドには非プロキシ統合が必要です。
1. **[メソッドリクエストの設定]** で、**[編集]** をクリックします。
1. **[HTTP リクエストヘッダー]** を選択します。
1. [**ヘッダーの追加**] を選択します。
1. **[Name]** (名前) には **puppies** を入力します。
1. **[保存]** を選択します。
1. **[統合リクエスト]** タブを選択し、**[統合リクエストの設定]** で、**[編集]** を選択します。
AWS マネジメントコンソール は自動的に `method.request.header.puppies ` から `puppies` にパラメータマッピングを追加します。ただし、**[名前]** を統合エンドポイントで想定されるリクエストヘッダーパラメータと一致するように変更する必要があります。
1. **[Name]** (名前) には **DogsAge0** を入力します。
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
次の手順では、パラメータマッピングが正常に完了したかを確認する方法を説明します。
**(オプション) パラメータマッピングをテストする**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. [ヘッダー] には、**puppies:true** と入力します。
1. **[テスト]** を選択します。
1. **[ログ]** では結果が以下のようになります。
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
リクエストヘッダーパラメータが、`puppies` から `DogsAge0` に変更されました。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## 例 2: 複数のメソッドリクエストパラメータを別々の統合リクエストパラメータにマッピングする
次の例では、複数値メソッドリクエストクエリ文字列パラメータ `methodRequestQueryParam` を統合リクエストクエリ文字列パラメータ `integrationQueryParam` にマッピングして、メソッドリクエストヘッダーパラメータ `methodRequestHeaderParam` を統合リクエストパスパラメータ `integrationPathParam` にマッピングします。
------
#### [ AWS マネジメントコンソール ]
**複数のメソッドリクエストパラメータをマッピングするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メソッドを選択します。
メソッドには非プロキシ統合が必要です。
1. **[メソッドリクエストの設定]** で、**[編集]** をクリックします。
1. **[URL クエリ文字列パラメータ]** を選択します。
1. [**クエリ文字列の追加**] を選択します。
1. **[Name]** (名前) には **methodRequestQueryParam** を入力します。
1. **[HTTP リクエストヘッダー]** を選択します。
1. [**ヘッダーの追加**] を選択します。
1. **[Name]** (名前) には **methodRequestHeaderParam** を入力します。
1. **[保存]** を選択します。
1. **[統合リクエスト]** タブを選択し、**[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[URL パスパラメータ]** を選択します。
1. **[パスパラメータを追加]** を選択します。
1. **[Name]** (名前) には **integrationPathParam** を入力します。
1. **[マッピング元]** として「**method.request.header.methodRequestHeaderParam**」と入力します。
これにより、メソッドリクエストで指定したメソッドリクエストヘッダーが新しい統合リクエストパスパラメータにマッピングされます。
1. **[URL クエリ文字列パラメータ]** を選択します。
1. [**クエリ文字列の追加**] を選択します。
1. **[Name]** (名前) には **integrationQueryParam** を入力します。
1. **[マッピング元]** として「**method.request.multivaluequerystring.methodRequestQueryParam**」と入力します。
これにより、複数値クエリ文字列パラメータが新しい単一値統合リクエストクエリ文字列パラメータにマッピングされます。
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
次の OpenAPI 定義は、HTTP 統合のために以下のパラメータマッピングを作成します。
+ `methodRequestHeaderParam` という名前のメソッドリクエストのヘッダーから、`integrationPathParam` という名前の統合リクエストパスパラメータへのマッピング
+ `methodRequestQueryParam` という名前の複数値のメソッドリクエストから、`integrationQueryParam` という名前の統合リクエストのクエリ文字列へのマッピング
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、HTTP 統合のために以下のパラメータマッピングを作成します。
+ `methodRequestHeaderParam` という名前のメソッドリクエストのヘッダーから、`integrationPathParam` という名前の統合リクエストパスパラメータへのマッピング
+ `methodRequestQueryParam` という名前の複数値のメソッドリクエストから、`integrationQueryParam` という名前の統合リクエストのクエリ文字列へのマッピング
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 例 3: JSON リクエスト本文のフィールドを統合リクエストパラメータにマッピングする
統合リクエストのパラメータは、[JSONPath 式](http://goessner.net/articles/JsonPath/index.html#e2) を使用して JSON リクエスト本文のフィールドからマッピングすることもできます。次の例では、メソッドリクエスト本文を `body-header` という名前の統合リクエストヘッダーにマッピングし、JSON 式で表されるリクエスト本文の一部を `pet-price` という名前の統合リクエストヘッダーにマッピングします。
この例をテストするには、次のような料金カテゴリを含む入力を指定します。
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS マネジメントコンソール ]
**複数のメソッドリクエストパラメータをマッピングするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. `POST` メソッド、`PUT` メソッド、`PATCH` メソッド、または `ANY` メソッドのいずれかを選択します。
メソッドには非プロキシ統合が必要です。
1. **[統合リクエストの設定]**で、**[編集]** を選択します。
1. **[URLリクエストヘッダーのパラメータ]** をクリックします。
1. **[リクエストヘッダーのパラメータを追加]** をクリックします。
1. **[Name]** (名前) には **body-header** を入力します。
1. **[マッピング元]** として「**method.request.body**」と入力します。
これにより、メソッドリクエスト本文が新しい統合リクエストヘッダーにマッピングされます。
1. **[リクエストヘッダーのパラメータを追加]** をクリックします。
1. **[Name]** (名前) には **pet-price** を入力します。
1. **[マッピング元]** として「** method.request.body[0].price**」と入力します。
これにより、メソッドリクエスト本文の一部が新しい統合リクエストヘッダーにマッピングされます。
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、JSON リクエスト本文の複数のフィールドから統合リクエストパラメータをマッピングします。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 例 4: 統合レスポンスをメソッドレスポンスにマッピングする
統合レスポンスをメソッドレスポンスにマップすることもできます。次の例では、統合レスポンス本文を `location` という名前のメソッドレスポンスヘッダーにマッピングし、統合レスポンスヘッダー `x-app-id` をメソッドレスポンスヘッダー `id` にマッピングして、複数値の統合レスポンスヘッダー `item` をメソッドレスポンスヘッダー `items` にマッピングします。
------
#### [ AWS マネジメントコンソール ]
**統合レスポンスをマッピングするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メソッドを選択します。
メソッドには非プロキシ統合が必要です。
1. **[メソッドレスポンス]** タブを選択して、**[レスポンス 200]** で **[編集]** を選択します。
1. **[ヘッダー名]** では、**[ヘッダーを追加]** を選択します。
1. **id**、**item**、**location** という名前の 3 つのヘッダーを作成します。
1. **[保存]** を選択します。
1. **[統合レスポンス]** タブをクリックして、**[デフォルト - レスポンス]** で、**[編集]** をクリックします。
1. **[ヘッダーのマッピング]** で、以下を入力します。
1. **[ID]** には **integration.response.header.x-app-id** と入力する
1. **[項目]** には **integration.response.multivalueheader.item** と入力する
1. **[場所]** には **integration.response.body.redirect.url** と入力する
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、統合レスポンスをメソッドレスポンスにマッピングします。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# API Gateway での REST API パラメータマッピングのソースのリファレンス
パラメータマッピングを作成する際は、変更するメソッドリクエストまたは統合レスポンスパラメータを指定して、これらのパラメータを変更する方法を指定します。
次の表は、マッピングできるメソッドリクエストパラメータと、マッピングを作成する式をまとめています。これらの式での *name* はメソッドリクエストパラメータ名です。例えば、リクエストヘッダーパラメータ `puppies` をマッピングするには、`method.request.header.puppies` という式を使用します。式は、正規表現 `'^[a-zA-Z0-9._$-]+$]'` と一致する必要があります。プロキシ統合と非プロキシ統合の統合リクエストでは、パラメータマッピングを使用できます。
| **マッピングされたデータソース** | **マッピング式** |
| --- | --- |
| メソッドリクエストのパス | method.request.path.name |
| メソッドリクエストのクエリ文字列 | method.request.querystring.name |
| 複数値メソッドリクエストのクエリ文字列 | method.request.multivaluequerystring.name |
| メソッドリクエストのヘッダー | method.request.header.name |
| 複数値メソッドリクエストのヘッダー | method.request.multivalueheader.name |
| メソッドリクエストボディ | method.request.body |
| メソッドリクエストボディ (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* はリクエスト本文の JSON フィールドの JSONPath 式です。詳細については、「[JSONPath 式](http://goessner.net/articles/JsonPath/index.html#e2)」を参照してください。 |
| ステージ変数 | stageVariables.name |
| コンテキスト変数 | `context.name` 名前は、[サポートされるコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)のいずれかである必要があります。 |
| 静的な値 | `'static_value'`. *STATIC\$1VALUE* はリテラル文字列で、単一引用符のペアで囲まれている必要があります。例えば、`'https://www.example.com'`。 |
次の表は、マッピングできる統合レスポンスパラメータと、マッピングを作成する式をまとめています。これらの式での *name* はメ統合レスポンスパラメータ名です。メソッドレスポンスヘッダーは、任意の統合レスポンスヘッダーまたは統合レスポンス本文、\$1context 変数、または静的な値からマップできます。統合レスポンスでパラメータマッピングを使用するには、非プロキシ統合を使用する必要があります。
| マッピングされたデータソース | マッピング式 |
| --- | --- |
| 統合レスポンスのヘッダー | integration.response.header.name |
| 統合レスポンスのヘッダー | integration.response.multivalueheader.name |
| 統合レスポンスの本文 | integration.response.body |
| 統合レスポンスの本文 (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* はレスポンス本文の JSON フィールドの JSONPath 式です。詳細については、「[JSONPath 式](http://goessner.net/articles/JsonPath/index.html#e2)」を参照してください。 |
| ステージ変数 | stageVariables.name |
| コンテキスト変数 | `context.name` 名前は、[サポートされるコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)のいずれかである必要があります。 |
| 静的な値 | ` 'static_value'` *STATIC\$1VALUE* はリテラル文字列で、単一引用符のペアで囲まれている必要があります。例えば、`'https://www.example.com'`。 |
# API Gateway での REST API のテンプレート変換のマッピング
マッピングテンプレート変換では、統合リクエストまたは統合レスポンスの変更にマッピングテンプレートを使用します。*マッピングテンプレート*は、[Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) で表現されるスクリプトであり、`Content-type` ヘッダーに基づいて [JSONPath](https://goessner.net/articles/JsonPath/) を使用してペイロードに適用されます。マッピングテンプレート変換を使用する場合は、マッピングテンプレートを使います。このセクションでは、マッピングテンプレートに関連する概念的な情報を説明します。
次の図は、PetStore 統合エンドポイントと統合されている `POST /pets` リソースのリクエストライフサイクルを説明しています。この API では、ユーザーはペットに関するデータを送信し、統合エンドポイントはペットの譲渡料金を返します。このリクエストライフサイクルでは、マッピングテンプレート変換が、リクエスト本文を統合エンドポイントにフィルタリングして、統合エンドポイントからレスポンス本文をフィルタリングします。
![\[リクエストライフサイクルの例\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/mapping-template-transforms.png)
以下のセクションでは、リクエストレスポンスのライフサイクルについて説明します。
## メソッドリクエストと統合リクエスト
前の例で、これがメソッドリクエストに送信されたリクエスト本文である場合:
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
このリクエスト本文は、統合エンドポイントで使用される適切な形式ではないため、API Gateway はマッピングテンプレート変換を実行します。API Gateway は、Content-Type `application/json` 用に定義されたマッピングテンプレートがあるため、マッピングテンプレート変換のみを実行します。Content-Type のマッピングテンプレートを定義しない場合、デフォルトでは、API Gateway は統合リクエストを介して統合エンドポイントに本文を渡します。この動作を変更するには、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
次のマッピングテンプレートは、統合エンドポイントに送信される前に、統合リクエストのメソッドリクエストデータを変換します。
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. `$inputRoot` 変数は、前のセクションにおける元の JSON データのルートオブジェクトです。ディレクティブは `#` 記号で始まります。
1. `dog` は、ユーザーの `id` と文字列値を連結したものです。
1. `Age` はメソッドリクエスト本文からのものです。
次に、以下の出力が統合エンドポイントに転送されます。
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## 統合レスポンスとメソッドレスポンス
統合エンドポイントへのリクエストが正常に完了すると、エンドポイントは API Gateway の統合レスポンスにレスポンスを送信します。以下は、統合エンドポイントからの出力データの例です。
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
メソッドレスポンスは、統合レスポンスが返すペイロードとは異なるペイロードを想定しています。API Gateway はマッピングテンプレート変換を実行します。API Gateway は、Content-Type `application/json` 用に定義されたマッピングテンプレートがあるため、マッピングテンプレート変換のみを実行します。Content-Type のマッピングテンプレートを定義しない場合、デフォルトでは、API Gateway は統合レスポンスを介してメソッドレスポンスに本文を渡します。この動作を変更するには、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
以下の出力は、メソッドレスポンスに送信されます。
```
{"adoptionFee": 19.95}
```
これで、マッピングテンプレート変換の例は完了です。可能であれば、データの変換には、マッピングテンプレート変換を使用する代わりに、プロキシ統合を使用することをお勧めします。詳細については、「[API Gateway API 統合タイプの選択](api-gateway-api-integration-types.md)」を参照してください。
# API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作
メソッドリクエストにペイロードがあり、`Content-Type` ヘッダーにマッピングテンプレートが定義されていない場合は、クライアントが提供するリクエストペイロードを変換せずに統合リクエストを介してバックエンドに渡すことができます。このプロセスは統合パススルーと呼ばれます。
受信リクエストの実際のパススルー動作は、この設定によって決まります。3 つのオプションがあります。
**リクエストした Content-Type ヘッダーと一致するテンプレートがない場合**
メソッドリクエストのコンテンツタイプが、マッピングテンプレートと関連付けられたコンテンツタイプに一致しない場合に、統合リクエストをパススルーしてメソッドリクエスト本文を変換せずにバックエンドに渡す場合は、このオプションを選択します。
API Gateway API を呼び出すときは、[[統合]](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) の `passthroughBehavior` プロパティの値として `WHEN_NO_MATCH` を設定して、このオプションを選択します。
**テンプレートが定義されていない場合 (推奨)**
統合リクエストでマッピングテンプレートが定義されていないときに、統合リクエストをパススルーしてメソッドリクエスト本文を変換せずにバックエンドに渡す場合は、このオプションを選択します。このオプションを選択した際にテンプレートが定義されている場合、定義されたマッピングテンプレートのいずれにも一致しないペイロードとコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。
API Gateway API を呼び出すときは、[[統合]](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) の `passthroughBehavior` プロパティの値として `WHEN_NO_TEMPLATES` を設定して、このオプションを選択します。
**なし**
統合リクエストでマッピングテンプレートが定義されていないときに、統合リクエストをパススルーしてメソッドリクエストボディを変換せずにバックエンドに渡さない場合は、このオプションを選択します。このオプションを選択したときにテンプレートが定義されている場合、マッピングされていないコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。
API Gateway API を呼び出すときは、[[統合]](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) の `passthroughBehavior` プロパティの値として `NEVER` を設定して、このオプションを選択します。
次の例では、可能なパススルー動作について説明します。
例 1: `application/json` コンテンツタイプで 1 つのマッピングテンプレートが統合リクエストで定義されている。
| Content-type | パススルーのオプション | 行動 |
| --- | --- | --- |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1MATCH | リクエストペイロードはテンプレートを使用して変換されます。 |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1TEMPLATES | リクエストペイロードはテンプレートを使用して変換されます。 |
| なし API Gateway のデフォルトは `application/json` | NEVER | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/json | WHEN\$1NO\$1MATCH | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/json | WHEN\$1NO\$1TEMPLATES | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/json | NEVER | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/xml | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/xml | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
例 2: `application/xml` コンテンツタイプで 1 つのマッピングテンプレートが統合リクエストで定義されている。
| Content-type | パススルーのオプション | 行動 |
| --- | --- | --- |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1TEMPLATES | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| なし API Gateway のデフォルトは `application/json` | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/json | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/json | WHEN\$1NO\$1TEMPLATES | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/json | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/xml | WHEN\$1NO\$1MATCH | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/xml | NEVER | リクエストペイロードはテンプレートを使用して変換されます。 |
例 3: 統合リクエストで定義されているマッピングテンプレートがない
| Content-type | パススルーのオプション | 行動 |
| --- | --- | --- |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1TEMPLATES | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| なし API Gateway のデフォルトは `application/json` | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/json | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/json | WHEN\$1NO\$1TEMPLATES | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/json | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/xml | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/xml | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
# 追加の API Gateway での REST API マッピングテンプレート例
次の例は、マッピングテンプレートを使用して統合リクエストと統合レスポンスデータを変換する API Gateway のフォトアルバム API を説明しています。この例では、データモデルを使用して、メソッドリクエストと統合レスポンスのペイロードも定義しています。データモデルの詳細については、「[REST API のデータモデル](models-mappings-models.md)」を参照してください。
## メソッドリクエストと統合リクエスト
以下は、メソッドリクエスト本文を定義するモデルです。この入力モデルでは、発信者が 1 ページの写真をアップロードする必要があり、ページごとに最低 10 枚の写真が必要です。この入力モデルを使用して SDK を生成したり、API のリクエストの検証に使用したりできます。リクエストの検証の使用中に、メソッドリクエスト本文がモデルのデータ構造に準拠していない場合、API Gateway はリクエストを失敗にします。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
以下は、上記のデータモデルのデータ構造に準拠するメソッドリクエスト本文の例です。
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
この例では、クライアントが上記のメソッドリクエスト本文を送信すると、このマッピングテンプレートは統合エンドポイントに必要な形式と一致するようにペイロードを変換します。
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
次の例は、変換からの出力データです。
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
このデータは統合リクエストに送信されてから、統合エンドポイントに送信されます。
## 統合レスポンスとメソッドレスポンス
以下は、統合エンドポイントからの写真データの出力モデルの例です。このモデルはメソッドレスポンスモデルに使用できます。これは、API 用に厳密に型指定した SDK を生成するときに必要です。これにより、出力が Java や Objective-C の適切なクラスにキャストされます。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
統合エンドポイントは、このモデルのデータ構造に準拠するレスポンスで応答しない場合があります。例えば、統合レスポンスは次のようになります。
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
次のマッピングテンプレートの例では、統合レスポンスデータをメソッドレスポンスで想定される形式に変換します。
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
次の例は、変換からの出力データです。
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
このデータはメソッドレスポンスに送信されてから、クライアントに送信されます。
# API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする
マッピングテンプレート変換を使用して、任意のタイプのリクエストパラメータ、レスポンスヘッダー、またはレスポンスステータスコードを上書きできます。マッピングテンプレートを使用して、以下を実行できます。
+ 多対 1 のパラメータマッピングを実行する
+ 標準 API Gateway マッピングが適用された適用された後にパラメータをオーバーライドする
+ 本文の内容やその他のパラメータ値に基づいて条件付きでパラメータをマッピングする
+ プログラムで新しいパラメータを作成する
+ 統合エンドポイントから返されたステータスコードをオーバーライドする
オーバーライドは最終的なものです。オーバーライドは各パラメータに一度だけ適用できます。同じパラメータを複数回オーバーライドしようとすると、API Gateway から `5XX` レスポンスが返されます。テンプレート全体で同じパラメータを複数回オーバーライドする必要がある場合は、変数を作成してテンプレートの終了時にオーバーライドを適用することをお勧めします。テンプレートはテンプレート全体が解析された後にのみ適用されます。
## 例 1: 統合本文に基づいてステータスコードを上書きする
次の例では、[サンプル API](api-gateway-create-api-from-example.md) を使用して、統合レスポンス本文に基づいてステータスコードを上書きします。
------
#### [ AWS マネジメントコンソール ]
**統合レスポンス本文に基づいてステータスコードを上書きするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. [**API の作成**] を選択します。
1. **[REST API]** では、**[構築]** を選択します。
1. **[API の詳細]** では、**[API の例]** を選択します。
1. **[API の作成]** を選択します。
API Gateway は、サンプルのペットストア API を作成します。ペットに関する情報を取得するには、`GET /pets/{petId}` の API メソッドリクエストを使用します。ここで、`{petId}` は、ペットの ID 番号に対応するパスパラメータです。
この例では、エラー状態が検出された場合、`GET` メソッドのレスポンスコードを `400` に上書きします。
1. **[リソース]** ツリーで、`/{petId}` の下の `GET` メソッドを選択します。
1. まず、API の現在の実装をテストします。
**[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[petId]** に「**-1**」と入力し、**[テスト]** を選択します。
**[レスポンス本文]** は、次のとおりの範囲外エラーを示します。
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
さらに、**[ログ]** の最後の行は `Method completed with status: 200` で終わります。
統合は正常に完了しましたが、エラーが発生しました。次に、統合本文に基づいてステータスコードを上書きします。
1. **[統合レスポンス]** タブの **[デフォルト - レスポンス]** で、**[編集]** を選択します。
1. **[マッピングテンプレート]** を選択します。
1. [**マッピングテンプレートの追加**] を選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
このマッピングテンプレートは、統合レスポンスに `error` 文字列が含まれている場合、`$context.responseOverride.status` 変数を使用してステータスコードを `400` に上書きします。
1. **[保存]** を選択します。
1. **[テスト]** タブを選択します。
1. **[petId]** に「**-1**」と入力します。
1. 結果として、[**Response Body (レスポンス本文)**] は範囲外エラーを示します。
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
ただし、**[ログ]** の最後の行は、`Method completed with status: 400` で終わるようになりました。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、`GET pets/{petId}` リソースを作成して、統合本文に基づいてステータスコードを上書きします。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## 例 2: リクエストヘッダーを上書きして新しいヘッダーを作成する
次の例では、[サンプル API](api-gateway-create-api-from-example.md) を使用してリクエストヘッダーを上書きして、新しいヘッダーを作成します。
------
#### [ AWS マネジメントコンソール ]
**新しいヘッダーを作成してメソッドのリクエストヘッダーを上書きするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. 前のチュートリアルで作成した API の例を選択します。API の名前は **[PetStore]** であるはずです。
1. **[リソース]** ツリーで、`/pet` の下の `GET` メソッドを選択します。
1. **[メソッドリクエスト]** タブの **[メソッドリクエストの設定]** で、**[編集]** を選択します。
1. **[HTTP リクエストヘッダー]** を選択した後、**[ヘッダーの追加]** を選択します。
1. **[Name]** (名前) には **header1** を入力します。
1. **[ヘッダーを追加]** を選択し、**header2** という名前の 2 つ目のヘッダーを作成します。
1. **[保存]** を選択します。
次に、マッピングテンプレートを使用して、これらのヘッダーを単一のヘッダー値に結合します。
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[リクエスト本文のパススルー]** で、**[テンプレートが定義されていない場合 (推奨)]** を選択します。
1. **[マッピングテンプレート]** を選択し、次の操作を行います。
1. [**マッピングテンプレートの追加**] を選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
このマッピングテンプレートは、`header1` を文字列 `pets` で上書きし、`header1` と `header2` を組み合わせた `$header3Value` という名前の複数値ヘッダーを作成します。
1. **[保存]** を選択します。
1. **[テスト]** タブを選択します。
1. **[ヘッダー]** で、次のコードをコピーします。
```
header1:header1Val
header2:header2Val
```
1. [**Test (テスト)**] を選択します。
**[ログ]** には次のとおり、このテキストを含むエントリが表示されるはずです。
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、リソース `GET pets` を作成し、リクエストヘッダーを上書きして新しいヘッダーを作成します。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
マッピングテンプレートの上書きを使用するには、マッピングテンプレートで以下の `$context` 変数のいずれかを使用します。`$context` 変数のリストについては、「[データ変換のコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)」を参照してください。
# チュートリアル: AWS サービスへの統合のための統合リクエストとレスポンスを変更する
次のチュートリアルでは、マッピングテンプレート変換を使用して、コンソールと AWS CLI で統合リクエストとレスポンスを変換するためのマッピングテンプレートを設定する方法を説明します。
**Topics**
+ [
## API Gateway コンソールを使用してデータ変換を設定する
](#mapping-example-console)
+ [
## AWS CLI を使用してデータ変換を設定する
](#mapping-example-cli)
+ [
## 完成したデータ変換の CloudFormation テンプレート
](#api-gateway-data-transformations-full-cfn-stack)
## API Gateway コンソールを使用してデータ変換を設定する
このチュートリアルでは、.zip ファイル ([data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip)) を使用して不完全な API と DynamoDB テーブルを作成します。この不完全な API には、`GET` メソッドと `POST` メソッドを持つ `/pets` リソースがあります。
+ `GET` メソッドは `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP エンドポイントからデータを取得します。出力データは、[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換されます。
+ `POST` メソッドを使用すると、ユーザーはマッピングテンプレートを使用して Amazon DynamoDB テーブルにペット情報を `POST` できます。
[CloudFormation のアプリケーション作成テンプレート](samples/data-transformation-tutorial-console.zip)をダウンロードして解凍します。このテンプレートを使用して、ペット情報と不完全な API を投稿するための DynamoDB テーブルを作成します。残りのステップは API Gateway コンソールで完了します。
**CloudFormation スタックを作成するには**
1. [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) で CloudFormation コンソール を開きます。
1. [**スタックの作成**] を選択し、[**With new resources (standard) 新しいリソースを使用 (標準)**] を選択します。
1. [**Specify template (テンプレートの指定)**] で、[**Upload a template file (テンプレートファイルのアップロード)**] を選択します。
1. ダウンロードしたテンプレートを選択します。
1. [**Next (次へ)**] を選択します。
1. [**Stack name**] (スタックの名前) で、**data-transformation-tutorial-console** と入力し、[**Next**] (次へ) を選択します。
1. [**Configure stack options**] (スタックオプションの設定) で、[**Next**] (次へ) を選択します。
1. [**Capabilities**] (機能) で、CloudFormation がアカウントに IAM リソースを作成できることを承認します。
1. **[次へ]** を選択し、**[送信]** を選択します。
CloudFormation は、テンプレートで指定されたリソースをプロビジョニングします。リソースのプロビジョニングには数分かかることがあります。CloudFormation スタックのステータスが **CREATE\$1COMPLETE** の場合は、次のステップに進む準備ができています。
**`GET` 統合レスポンスをテストするには**
1. **data-transformation-tutorial-console** の CloudFormation スタックの **[リソース]** タブで、API の物理 ID を選択します。
1. メインナビゲーションペインで **[リソース]**、**[GET]** メソッドの順に選択します。
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
テストの出力には、次の内容が表示されます。
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
この出力を [API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換します。
**`GET` 統合レスポンスを変換するには**
1. **[統合レスポンス]** タブを選択します。
現在、マッピングテンプレートは定義されていないため、統合レスポンスは変換されません。
1. **[デフォルト - レスポンス]** で **[編集]** を選択します。
1. **[マッピングテンプレート]** を選択し、次の操作を行います。
1. [**マッピングテンプレートの追加**] を選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
**[保存]** を選択します。
**`GET` 統合レスポンスをテストするには**
+ **[テスト]** タブ、**[テスト]** の順に選択します。
テストの出力に、変換されたレスポンスが表示されます。
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**`POST` メソッドからの入力データを変換するには**
1. **[POST]** メソッドを選択します。
1. **[統合リクエスト]** タブを選択し、**[統合リクエストの設定]** で、**[編集]** を選択します。
CloudFormation テンプレートでは、いくつかの統合リクエストフィールドが入力されています。
+ 統合タイプは AWS のサービスです。
+ AWS のサービスは DynamoDB です。
+ HTTP メソッドは `POST` です。
+ アクションは `PutItem` です。
+ API Gateway が DynamoDB テーブルに項目を入力できるようにする実行ロールは `data-transformation-tutorial-console-APIGatewayRole` です。CloudFormation は、API Gateway が DynamoDB とやり取りするための最小限のアクセス許可を持つように、このロールを作成済みです。
DynamoDB テーブルの名前は未指定です。次の手順に従って名前を指定します。
1. **[リクエスト本文のパススルー]** で、**[なし]** を選択します。
つまり、API はマッピングテンプレートを持たない Content-Type のデータを拒否します。
1. **[マッピングテンプレート]** を選択します。
1. **[コンテンツタイプ]** は `application/json` に設定されます。つまり、application/json 以外のコンテンツタイプは API によって拒否されます。統合パススルーの動作の詳細については、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
1. テキストエディタに次のコードを入力します。
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
このテンプレートでは、テーブルを `data-transformation-tutorial-console-ddb` として指定し、項目を `id`、`type`、`price` として設定します。項目は、`POST` メソッドの本体から取得されます。データモデルを使用してマッピングテンプレートを作成することもできます。詳細については、「[API Gateway での REST API のリクエスト検証](api-gateway-method-request-validation.md)」を参照してください。
1. **[保存]** ボタンを選択し、マッピングテンプレートを保存します。
**`POST` メソッドからメソッドと統合レスポンスを追加するには**
CloudFormation は、空白のメソッドと統合レスポンスを作成済みです。このレスポンスを編集して詳細情報を入力します。レスポンスの編集方法の詳細については、「[API Gateway での REST API パラメータマッピングの例](request-response-data-mappings.md)」を参照してください。
1. **[統合レスポンス]** タブの **[デフォルト - レスポンス]** で、**[編集]** を選択します。
1. **[マッピングテンプレート]**、**[マッピングテンプレートの追加]** の順に選択します。
1. **[コンテンツタイプ]** に「**application/json**」と入力します。
1. コードエディタで、次の出力マッピングテンプレートを入力し、出力メッセージを送信します。
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
コンテキスト変数の詳細については、「[データ変換のコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)」を参照してください。
1. **[保存]** ボタンを選択し、マッピングテンプレートを保存します。
**`POST` メソッドをテストする**
**[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. リクエスト本文に、次の例を入力します。
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. **[テスト]** を選択します。
出力に成功メッセージが表示されるはずです。
DynamoDB コンソール ([https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)) を開いて、サンプル項目がテーブルにあることを確認できます。
**CloudFormation スタックを削除するには**
1. CloudFormation コンソール ([https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)) を開きます。
1. CloudFormation スタックを選択します。
1. [**Delete**] (削除) を選択し、選択を確定します。
## AWS CLI を使用してデータ変換を設定する
このチュートリアルでは、.zip ファイル ([data-transformation-tutorial-cli.zip](samples/data-transformation-tutorial-cli.zip)\$1 を使用して不完全な API と DynamoDB テーブルを作成します。この不完全な API には、`http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP エンドポイントと統合された `GET` メソッドを持つ `/pets` リソースがあります。`POST` メソッドを作成して DynamoDB テーブルに接続し、マッピングテンプレートを使用して DynamoDB テーブルにデータを入力します。
+ 出力データは、[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換します。
+ `POST` メソッドを作成し、ユーザーがマッピングテンプレートを使用して Amazon DynamoDB テーブルにペット情報を `POST` できるようにします。
**CloudFormation スタックを作成するには**
[CloudFormation のアプリケーション作成テンプレート](samples/data-transformation-tutorial-cli.zip)をダウンロードして解凍します。
次のチュートリアルを完了するには、[AWS Command Line Interface (AWS CLI) バージョン 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) が必要です。
コマンドが長い場合は、エスケープ文字 (`\`) を使用してコマンドを複数行に分割します。
**注記**
Windows では、一般的に使用する Bash CLI コマンドの一部 (`zip` など) が、オペレーティングシステムの組み込みターミナルでサポートされていません。Ubuntu および Bash の Windows 統合バージョンを取得するには、[Windows Subsystem for Linux をインストール](https://learn.microsoft.com/en-us/windows/wsl/install)します。このガイドの CLI コマンドの例では、Linux フォーマットを使用しています。Windows CLI を使用している場合、インライン JSON ドキュメントを含むコマンドを再フォーマットする必要があります。
1. 次のコマンドを使用して CloudFormation スタックを作成します。
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation は、テンプレートで指定されたリソースをプロビジョニングします。リソースのプロビジョニングには数分かかることがあります。次のコマンドを使用して CloudFormation スタックのステータスを確認します。
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. CloudFormation スタックのステータスが `StackStatus: "CREATE_COMPLETE"` になったら、次のコマンドを使用して関連する出力値を取得し、以後のステップで使用します。
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
出力値は以下のとおりです。
+ ApiRole。API Gateway が DynamoDB テーブルに項目を配置できるようにするロールの名前です。このチュートリアルの場合、ロール名は `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG` です。
+ DDBTableName。DynamoDB テーブルの名前です。このチュートリアルの場合、インスタンス名は `data-transformation-tutorial-cli-ddb` です。
+ ResourceId。`GET` メソッドと `POST` メソッドを公開するペットリソースの ID です。このチュートリアルの場合、リソース ID は `efg456` です。
+ ApiId。API の ID です。このチュートリアルの場合、API の ID は `abc123` です。
**データ変換の前に `GET` メソッドをテストするには**
+ 次のコマンドを使用して、`GET` メソッドをテストします。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
テストの出力には、次の内容が表示されます。
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
この出力を [API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換します。
**`GET` 統合レスポンスを変換するには**
+ 次のコマンドを使用して、`GET` メソッドの統合レスポンスを更新します。*rest-api-id* と *resource-id* を実際の値に置き換えます。
次のコマンドを使用して統合レスポンスを作成します。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**`GET` メソッドをテストするには**
+ 次のコマンドを使用して `GET` メソッドをテストします。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
テストの出力に、変換されたレスポンスが表示されます。
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**`POST` メソッドを作成するには**
1. 次のコマンドを使用して、`/pets` リソースで新しいメソッドを作成します。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
このメソッドを使用すると、CloudFormation スタックで作成した DynamoDB テーブルにペット情報を送信できます。
1. 次のコマンドを使用して、`POST` メソッドで AWS のサービス統合を作成します。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. 次のコマンドを使用して、`POST` メソッドの呼び出しが成功した場合のメソッドレスポンスを作成します。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 次のコマンドを使用して、`POST` メソッドの呼び出しが成功した場合の統合レスポンスを作成します。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**`POST` メソッドをテストするには**
+ 次のコマンドを使用して、`POST` メソッドをテストします。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
出力に、成功のメッセージが表示されます。
**CloudFormation スタックを削除するには**
+ 次のコマンドを使用して CloudFormation リソースを削除します。
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## 完成したデータ変換の CloudFormation テンプレート
次の例は、完成した CloudFormation テンプレートです。これにより、API と、`GET` メソッドと `POST` メソッドを持つ `/pets` リソースを作成します。
+ `GET` メソッドは、`http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP エンドポイントからデータを取得します。出力データは、[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換されます。
+ `POST` メソッドを使用すると、ユーザーはマッピングテンプレートを使用して DynamoDB テーブルにペット情報を `POST` できます。
### CloudFormation テンプレートの例
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# API Gateway のテンプレート変換のマッピングに変数を使用する例
以下の例は、マッピングテンプレートで `$context` 変数、`input` 変数、`util` 変数を使用する方法を説明しています。入力イベントを API Gateway に返すモック統合または Lambda 非プロキシ統合を使用できます。サポートされているデータ変換のすべての変数のリストについては、「[API Gateway のデータ変換の変数](api-gateway-mapping-template-reference.md)」を参照してください。
## 例 1: 統合エンドポイントに複数の `$context` 変数を渡す
次の例は、統合リクエストペイロード内で、受信 `$context` 変数をわずかに異なる名前のバックエンド変数にマッピングするマッピングテンプレートを示しています。
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
変数の 1 つは API キーです。この例では、メソッドが 1 つの API キーを要求することを前提としています。
## 例 2: すべてのリクエストパラメータを JSON ペイロードを介して統合エンドポイントに渡す
次の例では、`path` パラメータ、`querystring` パラメータ、`header` パラメータを含むすべてのリクエストパラメータを JSON ペイロードを介して統合エンドポイントに渡します。
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
リクエストに次の入力パラメータがある場合:
+ `myparam` という名前のパスパラメータ
+ クエリ文字列パラメータ `querystring1=value1,value2`
+ ヘッダー `"header1" : "value1"`
このマッピングテンプレートの出力は、次のようになります。
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## 例 3: メソッドリクエストのサブセクションを統合エンドポイントに渡す
次の例では、入力パラメータ `name` を使用して、パラメータ `name` のみを取得し、入力パラメータ `input.json('$')` を使用してメソッドリクエスト本文全体を取得します。
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
クエリ文字列パラメータ `name=Bella&type=dog` と次の本文を含むリクエストの場合:
```
{
"Price" : "249.99",
"Age": "6"
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
このマッピングテンプレートは、クエリ文字列パラメータ `type=dog` を削除します。
JSON の入力に JavaScript で解析できない文字がエスケープされずに含まれている場合、API Gateway は 400 レスポンスを返すことがあります。JSON の入力を正しく解析できるようにするには、`$util.escapeJavaScript($input.json('$'))` を適用します。
前の例に `$util.escapeJavaScript($input.json('$'))` を適用した結果は次のとおりです。
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
この場合、このマッピングテンプレートの出力は、次のようになります。
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## 例 4: JSONPath 式を使用してメソッドリクエストのサブセクションを統合エンドポイントに渡す
次の例では、JSONPath 式を使用して、リクエスト本文から入力パラメータ `name` と `Age` のみを取得します。
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
クエリ文字列パラメータ `name=Bella&type=dog` と次の本文を含むリクエストの場合:
```
{
"Price" : "249.99",
"Age": "6"
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{
"name" : "Bella",
"body" : "6"
}
```
このマッピングテンプレートは、クエリ文字列パラメータ `type=dog` と `Price` フィールドを本文から削除します。
メソッドリクエストのペイロードに JavaScript で解析できない文字がエスケープされずに含まれている場合、API Gateway は `400` レスポンスを返すことがあります。JSON の入力を正しく解析できるようにするには、`$util.escapeJavaScript()` を適用します。
前の例に `$util.escapeJavaScript($input.json('$.Age'))` を適用した結果は次のとおりです。
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
この場合、このマッピングテンプレートの出力は、次のようになります。
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## 例 5: JSONPath 式を使用してメソッドリクエストに関する情報を統合エンドポイントに渡す
次の例では、`$input.params()`、`$input.path()`、`$input.json()` を使用して、メソッドリクエストに関する情報を統合エンドポイントに送信します。このマッピングテンプレートは、`size()` メソッドを使用してリスト内の要素の数を提供します。
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
パスパラメータ `123` と次の本文を含むリクエストの場合:
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
メソッドリクエストのペイロードに JavaScript で解析できない文字がエスケープされずに含まれている場合、API Gateway は `400` レスポンスを返すことがあります。JSON の入力を正しく解析できるようにするには、`$util.escapeJavaScript()` を適用します。
前の例に `$util.escapeJavaScript($input.json('$.things'))` を適用した結果は次のとおりです。
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# API Gateway のデータ変換の変数
パラメータマッピングを作成する場合、データソースとしてコンテキスト変数を使用できます。マッピングテンプレート変換を作成する場合、[Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) で記述するスクリプトでコンテキスト変数、入力変数、util 変数を使用できます。これらの参照変数を使用するマッピングテンプレートの例については、「[API Gateway のテンプレート変換のマッピングに変数を使用する例](api-gateway-mapping-variable-examples.md)」を参照してください。
アクセスのログ記録の参照変数のリストについては、「[API Gateway のアクセスのログ記録のための変数](api-gateway-variables-for-access-logging.md)」を参照してください。
## データ変換のコンテキスト変数
データ変換には、次の大文字と小文字が区別される `$context` 変数を使用できます。
| パラメータ | 説明 |
| --- | --- |
| \$1context.accountId | API 所有者の AWS アカウント ID。 |
| \$1context.apiId | API Gateway が API に割り当てる識別子。 |
| \$1context.authorizer.claims.property | メソッドの呼び出し側が認証に成功した後に Amazon Cognito ユーザープールから返されるクレームのプロパティ。詳細については、「[Amazon Cognito ユーザープールをオーソライザーとして使用して REST API へのアクセスを制御する](apigateway-integrate-with-cognito.md)」を参照してください。 `$context.authorizer.claims` を呼び出すと NULL が返されます。 |
| \$1context.authorizer.principalId | クライアントにより送信され、API Gateway Lambda オーソライザー (以前のカスタムオーソライザー) から返されたトークンと関連付けられたプリンシパルユーザー ID。詳細については、「[API Gateway Lambda オーソライザーを使用する](apigateway-use-lambda-authorizer.md)」を参照してください。 |
| \$1context.authorizer.property | API Gateway Lambda オーソライザーの関数から返された `context` マップの指定されたキー/値ペアの文字列化された値。たとえば、オーソライザーが次の `context` マップを返すとします。 "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} `$context.authorizer.key` の呼び出しでは `"value"` 文字列が返され、`$context.authorizer.numKey` の呼び出しでは `"1"` 文字列が返され、`$context.authorizer.boolKey` の呼び出しでは `"true"` 文字列が返されます。 *プロパティ* でサポートされる特殊文字は、アンダースコア `(_)` 文字のみです。 詳細については、「[API Gateway Lambda オーソライザーを使用する](apigateway-use-lambda-authorizer.md)」を参照してください。 |
| \$1context.awsEndpointRequestId | AWS エンドポイントのリクエスト ID |
| \$1context.deploymentId | API デプロイの ID。 |
| \$1context.domainName | API の呼び出しに使用された完全ドメイン名。これは、受信 `Host` ヘッダーと同じである必要があります。 |
| \$1context.domainPrefix | `$context.domainName` の 1 つ目のラベル。 |
| \$1context.error.message | API Gateway のエラーメッセージを含む文字列。この変数は、Velocity Template Language エンジン、およびアクセスログ記録では処理されない、[GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 本文マッピングテンプレートの単純な変数の置換でのみ使用できます。詳細については、「[CloudWatch メトリクスを使用して WebSocket API の実行をモニタリングする](apigateway-websocket-api-logging.md)」および「[エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)」を参照してください。 |
| \$1context.error.messageString | \$1context.error.message を引用符で囲んだ値、つまり "\$1context.error.message"。 |
| \$1context.error.responseType | [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) の [type](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)。この変数は、Velocity Template Language エンジン、およびアクセスログ記録では処理されない、[GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 本文マッピングテンプレートの単純な変数の置換でのみ使用できます。詳細については、「[CloudWatch メトリクスを使用して WebSocket API の実行をモニタリングする](apigateway-websocket-api-logging.md)」および「[エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)」を参照してください。 |
| \$1context.error.validationErrorString | 詳細な検証エラーメッセージを含む文字列。 |
| \$1context.extendedRequestId | API Gateway が生成して API リクエストに割り当てる拡張 ID。拡張リクエスト ID には、デバッグとトラブルシューティングに役立つ情報が含まれています。 |
| \$1context.httpMethod | 使用される HTTP メソッドです。有効な値には、`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` および `PUT` があります。 |
| \$1context.identity.accountId | リクエストに関連付けられた AWS アカウント ID です。 |
| \$1context.identity.apiKey | API キーを必要とする API メソッドの場合、この変数はメソッドリクエストに関連付けられている API キーです。API キーを必要としないメソッドの場合、この変数は null になります。詳細については、「[API Gateway での REST API の使用量プランと API キー](api-gateway-api-usage-plans.md)」を参照してください。 |
| \$1context.identity.apiKeyId | API キーを必要とする API リクエストに関連付けられた API キー ID。 |
| \$1context.identity.caller | リクエストに署名した発信者のプリンシパル ID。IAM 認可を使用するリソースでサポートされています。 |
| \$1context.identity.cognitoAuthenticationProvider | リクエスト元の発信者が使用するすべての Amazon Cognito 認証プロバイダーのカンマ区切りのリスト。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。 たとえば、Amazon Cognito ユーザープールのアイデンティティの場合、`cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 利用可能な Amazon Cognito 認証プロバイダーについては、「Amazon Cognito 開発者ガイド」の「[フェデレーティッド ID の使用](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)」を参照してください。** |
| \$1context.identity.cognitoAuthenticationType | リクエストを行う発信者の Amazon Cognito 認証タイプ。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。有効な値は、認証されたアイデンティティ`authenticated`および認証されていないアイデンティティ`unauthenticated`です。 |
| \$1context.identity.cognitoIdentityId | リクエストを行う発信者の Amazon Cognito ID。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。 |
| \$1context.identity.cognitoIdentityPoolId | リクエストを行う発信者の Amazon Cognito ID プール ID。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。 |
| \$1context.identity.principalOrgId | [AWS 組織 ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html)。 |
| \$1context.identity.sourceIp | API Gateway エンドポイントへのリクエストを行う即時 TCP 接続のソース IP アドレス。 |
| \$1context.identity.clientCert.clientCertPem | クライアントが相互 TLS 認証中に提示した PEM エンコードされたクライアント証明書。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.subjectDN | クライアントが提示する証明書のサブジェクトの識別名。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.issuerDN | クライアントが提示する証明書の発行者の識別名。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.serialNumber | 証明書のシリアル番号。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.validity.notBefore | 証明書が無効になる前の日付。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.validity.notAfter | 証明書が無効になった日付。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.vpcId | API Gateway エンドポイントへのリクエストを行う VPC の VPC ID。 |
| \$1context.identity.vpceId | API Gateway エンドポイントへのリクエストを行う VPC エンドポイントの VPC エンドポイント ID。プライベート API がある場合にのみ表示されます。 |
| \$1context.identity.user | リソースアクセスに対して許可されるユーザーのプリンシパル識別子。IAM 認可を使用するリソースでサポートされています。 |
| \$1context.identity.userAgent | API 発信者の [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) ヘッダー。 |
| \$1context.identity.userArn | 認証後に識別された有効ユーザーの Amazon リソースネーム (ARN) です。詳細については、「[https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)」を参照してください。 |
| \$1context.isCanaryRequest | リクエストが canary に送信された場合は `true` を返し、リクエストが canary に送信されなかった場合は `false` を返します。canary が有効になっている場合にのみ表示されます。 |
| \$1context.path | リクエストパス。たとえば、https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child の非プロキシリクエスト URL の場合、\$1context.path 値は /\$1stage\$1/root/child。 |
| \$1context.protocol | HTTP/1.1 などのリクエストプロトコル。 API Gateway API は HTTP/2 リクエストを受け入れることができますが、API Gateway は HTTP/1.1 を使用してバックエンド統合にリクエストを送信します。その結果、クライアントが HTTP/2 を使用するリクエストを送信した場合でも、リクエストプロトコルは HTTP/1.1 として記録されます。 |
| \$1context.requestId | リクエストの ID。クライアントは、このリクエスト ID を上書きできます。API Gateway が生成する一意のリクエスト ID に `$context.extendedRequestId` を使用します。 |
| \$1context.requestOverride.header.header\$1name | リクエストヘッダーオーバーライド。このパラメータが定義されている場合、[**Integration Request (統合リクエスト)**] ペインで定義されている [**HTTP Headers (HTTP ヘッダー)**] の代わりに使用されるヘッダーが含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.requestOverride.path.path\$1name | リクエストパスオーバーライド。このパラメータが定義されている場合、[**Integration Request (統合リクエスト)**] ペインで定義されている [**URL Path Parameters (URL パスパラメータ)**] の代わりに使用されるリクエストパスが含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.requestOverride.querystring.querystring\$1name | リクエストクエリ文字列オーバーライド。このパラメータが定義されている場合、[**Integration Request (統合リクエスト)**] ペインで定義されている [**URL Query String Parameters (URL クエリ文字列パラメータ)**] の代わりに使用されるリクエストクエリ文字列が含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.responseOverride.header.header\$1name | レスポンスヘッダーオーバーライド。このパラメータが定義されている場合、[Integration Response (統合レスポンス)] ペインの [Default mapping (デフォルトのマッピング)] として定義されている [Response header (レスポンスヘッダー)] の代わりに返されるヘッダーが含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.responseOverride.status | レスポンスステータスコードオーバーライド。このパラメータが定義されている場合、[Integration Response (統合レスポンス)] ペインの [Default mapping (デフォルトのマッピング)] として定義されている [Method response status (メソッドレスポンスのステータス)] の代わりに返されるステータスコードが含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 形式の要求時間 (dd/MMM/yyyy:HH:mm:ss \$1-hhmm)。 |
| \$1context.requestTimeEpoch | [エポック](https://en.wikipedia.org/wiki/Unix_time)形式のリクエスト時間 (ミリ秒単位)。 |
| \$1context.resourceId | API Gateway がリソースに割り当てる識別子です。 |
| \$1context.resourcePath | リソースへのパスです。たとえば、`https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` の非プロキシリクエスト URI の場合、`$context.resourcePath` 値は `/root/child`。詳細については、「[チュートリアル: HTTP 非プロキシ統合を使用して REST API を作成する](api-gateway-create-api-step-by-step.md)」を参照してください。 |
| \$1context.stage | API リクエストのデプロイステージ (`Beta`、`Prod` など)。 |
| \$1context.wafResponseCode | [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) から受け取ったレスポンス: `WAF_ALLOW` または `WAF_BLOCK`。ステージがウェブ ACL に関連付けられていない場合は、設定されません。詳細については、「[AWS WAF を使用して API Gateway の REST API を保護する](apigateway-control-access-aws-waf.md)」を参照してください。 |
| \$1context.webaclArn | リクエストを許可するかブロックするかを決定するために使用されるウェブ ACL の完全な ARN。ステージがウェブ ACL に関連付けられていない場合は、設定されません。詳細については、「[AWS WAF を使用して API Gateway の REST API を保護する](apigateway-control-access-aws-waf.md)」を参照してください。 |
## 入力変数
次の大文字と小文字が区別される `$input` 変数を使用して、メソッドリクエストペイロードとメソッドリクエストパラメータを参照できます。以下の機能を使用できます。
| 変数と関数 | 説明 |
| --- | --- |
| \$1input.body | 文字列として raw リクエストペイロードを返します。`$input.body` を使用して、浮動小数点数全体 (`10.00` など) を保持できます。 |
| \$1input.json(x) | この関数は、JSONPath の式を評価し、結果を JSON 文字列で返します。 たとえば `$input.json('$.pets')` は、`pets` 構造を表す JSON 文字列を返します。 JSONPath の詳細については、[JSONPath](https://goessner.net/articles/JsonPath/) または [JSONPath for Java](https://github.com/json-path/JsonPath) を参照してください。 |
| \$1input.params() | すべてのリクエストパラメータのマップを返します。インジェクション攻撃の可能性を避けるため、`$util.escapeJavaScript` を使用して結果をサニタイズすることをお勧めします。リクエストのサニタイズを完全に制御するには、テンプレートなしでプロキシ統合を使用し、統合でリクエストのサニタイズを処理します。 |
| \$1input.params(x) | パラメータ名文字列 `x` が指定された場合に、パス、クエリ文字列、またはヘッダー値から (この順番で検索される) メソッドリクエストパラメータの値を返します。インジェクション攻撃の可能性を避けるため、`$util.escapeJavaScript` を使用してパラメータをサニタイズすることをお勧めします。パラメータのサニタイズを完全に制御するには、テンプレートなしでプロキシ統合を使用し、統合でリクエストのサニタイズを処理します。 |
| \$1input.path(x) | JSONPath 式文字列 (`x`) を受け取り、結果の JSON オブジェクト表現を返します。これにより、[Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) でペイロード要素にネイティブにアクセスして操作できます。 たとえば、式 `$input.path('$.pets')` が次のようにオブジェクトを返すとします。 [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').size()` は を返します。`"3"` JSONPath の詳細については、[JSONPath](https://goessner.net/articles/JsonPath/) または [JSONPath for Java](https://github.com/json-path/JsonPath) を参照してください。 |
## ステージ変数
メソッド統合では、次のステージ変数を ARN と URL のプレースホルダーとして使用できます。詳細については、「[API Gateway で REST API のステージ変数を使用する](stage-variables.md)」を参照してください。
| 構文 | 説明 |
| --- | --- |
| \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'], または \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* はステージ変数名を表します。 |
## Util 変数
マッピングテンプレートのユーティリティ関数を使用するには、次の大文字と小文字が区別される `$util` 変数を使用できます。別に指定されていない限り、デフォルトの文字は UTF-8 に設定されます。
| 関数 | 説明 |
| --- | --- |
| \$1util.escapeJavaScript() | JavaScript 文字列ルールを使用して文字列内の文字をエスケープします。 この関数は、通常の一重引用符 (`'`) をエスケープした一重引用符 (`\'`) に変換します。ただし、エスケープした一重引用符は JSON で有効ではありません。したがって、この関数からの出力を JSON のプロパティで使用する場合、エスケープした一重引用符 (`\'`) を通常の一重引用符 (`'`) に戻す必要があります。これを次の例で示します: "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")" |
| \$1util.parseJson() | "stringified" JSON を受け取り、結果のオブジェクト表現を返します。この関数の結果を使用して、Apache Velocity Template Language (VTL) でペイロード要素にネイティブにアクセスしてこれらの要素を操作できるようになります。たとえば、次のペイロードがあるとします。 {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} さらに、次のマッピングテンプレートを使用するとします。 #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
この場合、次の出力が返されます。 {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | 文字列を「application/x-www-form-urlencoded」形式に変換します。 |
| \$1util.urlDecode() | 「application/x-www-form-urlencoded」文字列をデコードします。 |
| \$1util.base64Encode() | データを base64 エンコードされた文字列にエンコードします。 |
| \$1util.base64Decode() | base64 エンコードされた文字列からデータをデコードします。 |
# API Gateway での REST API のゲートウェイレスポンス
ゲートウェイレスポンスは、API Gateway によって定義されたレスポンスタイプで識別されます。レスポンスは、HTTP ステータスコード、パラメータマッピングで指定される追加のヘッダーのセット、および [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html) 以外のマッピングテンプレートで生成されるペイロードで構成されます。
API Gateway REST API では、ゲートウェイレスポンスは [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) によって表されます。OpenAPI では、`GatewayResponse` インスタンスは [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) 拡張子で記述されます。
ゲートウェイレスポンスを有効にするには、API レベルで[サポートされているレスポンスタイプ](supported-gateway-response-types.md)のゲートウェイレスポンスを設定します。API Gateway からこのタイプのレスポンスが返されるたびに、ゲートウェイレスポンスに定義されているヘッダーマッピングとペイロードマッピングテンプレートに適用されてマッピングされた結果が API 発信者に返されます。
次のセクションでは、API Gateway コンソールと API Gateway REST API を使用してゲートウェイレスポンスを設定する方法を示します。
## エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ
API Gateway は、受信リクエストを処理できない場合、統合バックエンドにリクエストを転送せずにクライアントにエラーレスポンスを返します。デフォルトでは、エラーレスポンスにエラーを説明する短いメッセージが含まれます。たとえば、未定義の API リソースに対してオペレーションを呼び出そうとすると、`{ "message": "Missing Authentication Token" }` というメッセージが含まれたエラーレスポンスが返されます。API Gateway に慣れていないユーザーには、メッセージの意味がわかりにくい場合があります。
一部のエラーレスポンスについては、API デベロッパーがカスタマイズして異なる形式で返すことが API Gateway で許可されています。たとえば、`Missing Authentication Token` の場合は、次の例に示すように、元のレスポンスペイロードにヒントを追加し、考えられる原因を説明できます: `{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`。
API が外部交換と AWS クラウドの間を仲介する場合は、統合リクエストまたは統合レスポンスの VTL マッピングテンプレートを使用して、ペイロードを 1 つの形式から別の形式にマッピングします。ただし、VTL マッピングテンプレートはレスポンスが正常に返される有効なリクエストに対してのみ使用できます。
無効なリクエストに対しては、API Gateway は統合を完全にバイパスしてエラーレスポンスを返します。エラーレスポンスを交換に準拠した形式にするには、カスタマイズを使用する必要があります。カスタマイズは、単純な変数の置換のみをサポートする VTL 以外のマッピングテンプレートでレンダリングされます。
API Gateway で生成されたエラーレスポンスを API Gateway で生成される任意のレスポンスに一般化したものは、*ゲートウェイレスポンス*と呼ばれます。これにより、API Gateway で生成されたレスポンスは統合レスポンスから区別されます。ゲートウェイレスポンスのマッピングテンプレートは、`$context` 変数の値と `$stageVariables` プロパティの値にアクセスできます。また、`method.request.param-position.param-name` 形式のメソッドリクエストのパラメータにもアクセスできます。
`$context` 変数の詳細については、「[データ変換のコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)」を参照してください。の詳細については、「`$stageVariables`」を参照してください。[ステージ変数](api-gateway-mapping-template-reference.md#stagevariables-template-reference)。メソッドリクエストパラメータの詳細については、「[入力変数](api-gateway-mapping-template-reference.md#input-variable-reference)」を参照してください。
**Topics**
+ [
## エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ
](#customize-gateway-responses)
+ [
# API Gateway コンソールを使用して REST API のゲートウェイレスポンスをセットアップする
](set-up-gateway-response-using-the-console.md)
+ [
# API Gateway REST API を使用してゲートウェイレスポンスを設定する
](set-up-gateway-response-using-the-api.md)
+ [
# OpenAPI でゲートウェイレスポンスのカスタマイズを設定する
](set-up-gateway-responses-in-swagger.md)
+ [
# API Gateway でのゲートウェイレスポンスタイプ
](supported-gateway-response-types.md)
# API Gateway コンソールを使用して REST API のゲートウェイレスポンスをセットアップする
次の例は、API Gateway コンソールを使用して REST API のゲートウェイレスポンスをセットアップする方法を示しています。
**API Gateway コンソールを使用してゲートウェイレスポンスをカスタマイズするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メインナビゲーションペインで、**[ゲートウェイレスポンス]** を選択します。
1. レスポンスタイプを選択し、**[編集]** を選択します。このチュートリアルでは、**[認証トークンが見つかりません]** を例として使用します。
1. API Gateway で生成された **[ステータスコード]** を変更し、API の要件を満たす別のステータスコードを返すことができます。この例では、カスタマイズにより、ステータスコードがデフォルト値 (`403`) から `404` に変更されます。これは、見つからないと見なすことができるサポートされていないリソースや無効なリソースをクライアントが呼び出したときに、このエラーメッセージが発生するためです。
1. カスタムヘッダーを返すには、**[レスポンスヘッダー]** で **[ヘッダーの追加]** を選択します。例として、以下のカスタムヘッダーを追加します。
```
Access-Control-Allow-Origin:'a.b.c'
x-request-id:method.request.header.x-amzn-RequestId
x-request-path:method.request.path.petId
x-request-query:method.request.querystring.q
```
前述のヘッダーマッピングで、静的ドメイン名 (`'a.b.c'`) は `Allow-Control-Allow-Origin` ヘッダーにマッピングされて、CORS から API へのアクセスが許可されます。`x-amzn-RequestId` パス変数はレスポンスの `request-id` にマッピングされます。受信リクエストの `petId` パス変数はレスポンスの `request-path` ヘッダーにマッピングされます。元のリクエストの `q` クエリパラメータはレスポンスの `request-query` ヘッダーにマッピングされます。
1. **[レスポンステンプレート]** で、**[コンテンツタイプ]** を `application/json` にしたまま、**[テンプレートの本文]** エディタに次の本文マッピングテンプレートを入力します。
```
{
"message":"$context.error.messageString",
"type": "$context.error.responseType",
"statusCode": "'404'",
"stage": "$context.stage",
"resourcePath": "$context.resourcePath",
"stageVariables.a": "$stageVariables.a"
}
```
この例では、`$context` プロパティと `$stageVariables` プロパティを、ゲートウェイレスポンス本文のプロパティにマッピングする方法を示しています。
1. **[Save changes]** (変更の保存) をクリックします。
1. 新規または既存のステージに API をデプロイします。
該当する API メソッドの呼び出し URL は `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}` であると仮定して、次の CURL コマンドを呼び出してゲートウェイレスポンスをテストします。
```
curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1
```
追加のクエリ文字列パラメータ `q=1` は、API と互換性がないため、指定したゲートウェイレスポンスからエラーが返されます。次のようなゲートウェイレスポンスが返されます。
```
> GET /custErr/pets/5?q=1 HTTP/1.1
Host: o81lxisefl.execute-api.us-east-1.amazonaws.com
User-Agent: curl/7.51.0
Accept: */*
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 334
Connection: keep-alive
Date: Tue, 02 May 2017 03:15:47 GMT
x-amzn-RequestId: 123344566
Access-Control-Allow-Origin: a.b.c
x-amzn-ErrorType: MissingAuthenticationTokenException
header-1: static
x-request-query: 1
x-request-path: 5
X-Cache: Error from cloudfront
Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront)
X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA==
{
"message":"Missing Authentication Token",
"type": MISSING_AUTHENTICATION_TOKEN,
"statusCode": '404',
"stage": custErr,
"resourcePath": /pets/{petId},
"stageVariables.a": a
}
```
前述の例では、API バックエンドが [Pet Store](http://petstore-demo-endpoint.execute-api.com/petstore/pets) であること、さらに API にステージ変数 `a` が定義されていることを前提としています。
# API Gateway REST API を使用してゲートウェイレスポンスを設定する
API Gateway REST API を使用してゲートウェイレスポンスをカスタマイズする前に、API が作成済みで、その識別子を取得済みであることが必要です。API 識別子を取得するには、[restapi:gateway-responses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) リンクリレーションに従い、その結果を確認します。
**API Gateway REST API を使用してゲートウェイレスポンスをカスタマイズするには**
1. [ゲートウェイレスポンス](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)インスタンス全体を上書きするには、[gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html) アクションを呼び出します。URL パスパラメータで目的の [responseType](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) を指定し、リクエストペイロードに [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#statusCode)、[responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters)、および [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseTemplates) マッピングを指定します。
1. `GatewayResponse` インスタンスの一部を更新するには、[gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html) アクションを呼び出します。URL パラメータに `responseType` を指定し、リクエストペイロードに、たとえば `GatewayResponse` や `responseParameters` マッピングなど、必要な個々の `responseTemplates` プロパティを指定します。
# OpenAPI でゲートウェイレスポンスのカスタマイズを設定する
API ルートレベルで `x-amazon-apigateway-gateway-responses` 拡張子を使用し、OpenAPI でゲートウェイレスポンスをカスタマイズできます。次の OpenAPI の定義は、`MISSING_AUTHENTICATION_TOKEN` タイプの [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) をカスタマイズする例を示しています。
```
"x-amazon-apigateway-gateway-responses": {
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.x-request-path": "method.input.params.petId",
"gatewayresponse.header.x-request-query": "method.input.params.q",
"gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'",
"gatewayresponse.header.x-request-header": "method.input.params.Accept"
},
"responseTemplates": {
"application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}"
}
}
```
この例では、カスタマイズによってステータスコードをデフォルト (`403`) から `404` に変更します。また、ゲートウェイレスポンスに 4 つのヘッダーパラメータと、`application/json` メディアタイプの 1 つの本文マッピングテンプレートを追加します。
# API Gateway でのゲートウェイレスポンスタイプ
API Gateway では、API デベロッパーがカスタマイズできる以下のゲートウェイレスポンスを公開しています。
| ゲートウェイレスポンスのタイプ | デフォルトのステータスコード | 説明 |
| --- | --- | --- |
| ACCESS\$1DENIED | 403 | 認可が失敗した場合のゲートウェイレスポンス—たとえば、カスタムまたは Amazon Cognito オーソライザーによってアクセスが拒否された場合などが該当します。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| API\$1CONFIGURATION\$1ERROR | 500 | API 設定が無効な場合のゲートウェイレスポンス — たとえば、無効なエンドポイントアドレスが送信された場合、バイナリサポートが有効になっているときにバイナリデータに対する Base64 デコーディングが失敗した場合、統合レスポンスマッピングがいずれのテンプレートとも一致せず、デフォルトテンプレートも設定されていない場合などが該当します。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_5XX` タイプになります。 |
| AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | カスタムまたは Amazon Cognito オーソライザーへの接続が失敗した場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_5XX` タイプになります。 |
| AUTHORIZER\$1FAILURE | 500 | カスタムまたは Amazon Cognito オーソライザーが発信者の認証に失敗した場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_5XX` タイプになります。 |
| BAD\$1REQUEST\$1PARAMETERS | 400 | 有効になっているリクエストの検証に基づいてリクエストパラメータを検証できない場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| BAD\$1REQUEST\$1BODY | 400 | 有効になっているリクエストの検証に基づいてリクエストボディを検証できない場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| DEFAULT\$14XX | Null | レスポンスタイプが未指定で、ステータスコードが `4XX` のデフォルトのゲートウェイレスポンス。このフォールバックゲートウェイレスポンスのステータスコードを変更すると、他のすべての `4XX` レスポンスのステータスコードが新しい値に変更されます。このステータスコードを null にリセットすると、他のすべての `4XX` レスポンスのステータスコードが元の値に戻ります。 [AWS WAF カスタムレスポンス](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html)は、カスタムゲートウェイレスポンスよりも優先されます。 |
| DEFAULT\$15XX | Null | レスポンスタイプが未指定で、ステータスコードが `5XX` のデフォルトのゲートウェイレスポンス。このフォールバックゲートウェイレスポンスのステータスコードを変更すると、他のすべての `5XX` レスポンスのステータスコードが新しい値に変更されます。このステータスコードを null にリセットすると、他のすべての `5XX` レスポンスのステータスコードが元の値に戻ります。 |
| EXPIRED\$1TOKEN | 403 | AWS 認証トークンの有効期限が切れた場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| INTEGRATION\$1FAILURE | 504 | 統合が失敗した場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_5XX` タイプになります。 |
| INTEGRATION\$1TIMEOUT | 504 | 統合がタイムアウトした場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_5XX` タイプになります。 |
| INVALID\$1API\$1KEY | 403 | API キーを必要としているメソッドに対して無効な API キーが送信された場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| INVALID\$1SIGNATURE | 403 | AWS 署名が無効な場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| MISSING\$1AUTHENTICATION\$1TOKEN | 403 | 認証トークンが見つからない場合のゲートウェイレスポンス。サポートされていない API メソッドやリソースをクライアントが呼び出そうとした場合などが該当します。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| QUOTA\$1EXCEEDED | 429 | 使用量プランのクォータが超過した場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| REQUEST\$1TOO\$1LARGE | 413 | リクエストが大きすぎる場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `HTTP content length exceeded 10485760 bytes` になります。 |
| RESOURCE\$1NOT\$1FOUND | 404 | API リクエストが認証および認可 (API キー認証および認可を除く) に合格した後で、指定されたリソースを API Gateway で見つけることができない場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| THROTTLED | 429 | 使用量プランレベル、メソッドレベル、ステージレベル、またはアカウントレベルのスロットリング制限を超えた場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| UNAUTHORIZED | 401 | カスタムまたは Amazon Cognito オーソライザーが発信者の認証に失敗した場合のゲートウェイレスポンス。 |
| UNSUPPORTED\$1MEDIA\$1TYPE | 415 | 厳格なパススルー動作が有効になっているときに、ペイロードがサポートされていないメディアタイプである場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 |
| WAF\$1FILTERED | 403 | リクエストが AWS WAF によってブロックされた場合のゲートウェイレスポンス。レスポンスタイプが未指定の場合、このレスポンスはデフォルトで `DEFAULT_4XX` タイプになります。 [AWS WAF カスタムレスポンス](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html)は、カスタムゲートウェイレスポンスよりも優先されます。 |
# API Gateway での REST API の CORS
[Cross-origin resource sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) は、ブラウザで実行されているスクリプトから開始されるクロスオリジン HTTP リクエストを制限するブラウザのセキュリティ機能です。詳細については、「[CORS とは](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)」を参照してください。
## CORS サポートを有効にするかどうかを決定する
*クロスオリジン* HTTP リクエストは、以下に対して行われます。
+ 別の*ドメイン* (例: `example.com` から `amazondomains.com` へ)
+ 別の*サブドメイン* (例: `example.com` から `petstore.example.com` へ)
+ 別の*ポート* (例: `example.com` から `example.com:10777` へ)
+ 別の*プロトコル* (例: `https://example.com` から `http://example.com` へ)
API にアクセスできず、`Cross-Origin Request Blocked` を含むエラーメッセージが表示される場合は、CORS を有効にする必要がある場合があります。
クロスオリジン HTTP リクエストは、*シンプルな*リクエスト、および*シンプルではない*リクエストの 2 種類に分類できます。
## シンプルなリクエストの CORS を有効にする
以下の条件がすべて当てはまる場合、HTTP リクエストは*シンプル*です。
+ `GET`、`HEAD`、および `POST` のリクエストのみを許可する API リソースに対して発行されます。
+ それが `POST` メソッドリクエストの場合、`Origin` ヘッダーを含める必要があります。
+ リクエストのペイロードコンテンツタイプが `text/plain`、`multipart/form-data`、または `application/x-www-form-urlencoded` の場合。
+ リクエストにカスタムヘッダーが含まれていません。
+ [シンプルなリクエストに関する Mozilla CORS のドキュメント](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests)に一覧表示されている追加要件。
シンプルなクロスオリジンの `POST` メソッドリクエストの場合、リソースからのレスポンスにはヘッダー `Access-Control-Allow-Origin: '*'` または `Access-Control-Allow-Origin:'origin'` を含める必要があります。
他のすべてのクロスオリジン HTTP リクエストは*シンプルではない*リクエストです。
## シンプルではないリクエストの CORS を有効にする
API のリソースがシンプルではないリクエストを受け取った場合は、統合タイプに応じて追加の CORS サポートを有効にする必要があります。
### 非プロキシ統合の CORS を有効にする
これらの統合の場合、[CORS プロトコル](https://fetch.spec.whatwg.org/#http-cors-protocol)は、実際のリクエストを送信する前に、ブラウザからサーバーにプリフライトリクエストを送信し、サーバーからの承認 (または認証情報のリクエスト) を待つことを要求します。プリフライトリクエストに適切なレスポンスを送信するように API を設定する必要があります。
プリフライトレスポンスを作成するには
1. モック統合の `OPTIONS` メソッドを作成します。
1. 以下のレスポンスヘッダーを 200 メソッドレスポンスに追加します。
+ `Access-Control-Allow-Headers`
+ `Access-Control-Allow-Methods`
+ `Access-Control-Allow-Origin`
1. 統合パススルーの動作を `NEVER` に設定します。この場合、マッピングされていないコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。詳細については、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
1. レスポンスヘッダーの値を入力します。すべてのオリジン、すべてのメソッド、および共通のヘッダーを許可するには、以下のヘッダー値を使用します。
+ `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'`
+ `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'`
+ `Access-Control-Allow-Origin: '*'`
プリフライトリクエストを作成したら、少なくとも 200 個すべてのレスポンスに対して、すべての CORS 対応メソッドの `Access-Control-Allow-Origin: '*'` ヘッダーまたは `Access-Control-Allow-Origin:'origin'` ヘッダーを返す必要があります。
### AWS マネジメントコンソールを使用して非プロキシ統合の CORS を有効にする
AWS マネジメントコンソールを使用して CORS を有効にすることができます。API Gateway は、`OPTIONS` メソッドを作成し、`Access-Control-Allow-Origin` ヘッダーを既存のメソッド統合レスポンスに追加します。これは常に機能するとは限りません。場合によっては、少なくとも 200 個すべてのレスポンスに対して、すべての CORS 対応メソッドの `Access-Control-Allow-Origin` ヘッダーを返すように統合レスポンスを手動で変更する必要があります。
API のバイナリメディアタイプが `*/*` に設定されている場合は、API Gateway が `OPTIONS` メソッドを作成するときに、`contentHandling` を `CONVERT_TO_TEXT` に変更します。
次の [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) コマンドは、統合リクエストの `contentHandling` を `CONVERT_TO_TEXT` に変更します。
```
aws apigateway update-integration \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
次の [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) コマンドは、統合レスポンスの `contentHandling` を `CONVERT_TO_TEXT` に変更します。
```
aws apigateway update-integration-response \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--status-code 200 \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
## プロキシ統合の CORS サポートを有効にする
Lambda プロキシ統合または HTTP プロキシ統合の場合、プロキシ統合は統合レスポンスを返さないため、バックエンドが `Access-Control-Allow-Origin` ヘッダー、`Access-Control-Allow-Methods` ヘッダー、`Access-Control-Allow-Headers` ヘッダーを返す必要があります。
以下の Lambda 関数の例は、必要な CORS ヘッダーを返します。
------
#### [ Node.js ]
```
export const handler = async (event) => {
const response = {
statusCode: 200,
headers: {
"Access-Control-Allow-Headers" : "Content-Type",
"Access-Control-Allow-Origin": "https://www.example.com",
"Access-Control-Allow-Methods": "OPTIONS,POST,GET"
},
body: JSON.stringify('Hello from Lambda!'),
};
return response;
};
```
------
#### [ Python 3 ]
```
import json
def lambda_handler(event, context):
return {
'statusCode': 200,
'headers': {
'Access-Control-Allow-Headers': 'Content-Type',
'Access-Control-Allow-Origin': 'https://www.example.com',
'Access-Control-Allow-Methods': 'OPTIONS,POST,GET'
},
'body': json.dumps('Hello from Lambda!')
}
```
------
**Topics**
+ [
## CORS サポートを有効にするかどうかを決定する
](#apigateway-cors-request-types)
+ [
## シンプルなリクエストの CORS を有効にする
](#apigateway-cors-simple-request)
+ [
## シンプルではないリクエストの CORS を有効にする
](#apigateway-enable-cors-non-simple)
+ [
## プロキシ統合の CORS サポートを有効にする
](#apigateway-enable-cors-proxy)
+ [
# API Gateway コンソールを使用してリソースで CORS を有効にする
](how-to-cors-console.md)
+ [
# API Gateway のインポート API を使用して、リソースで CORS を有効にする
](enable-cors-for-resource-using-swagger-importer-tool.md)
+ [
# API Gateway API の CORS をテストする
](apigateway-test-cors.md)
# API Gateway コンソールを使用してリソースで CORS を有効にする
API Gateway コンソールを使用して、作成した REST API リソース上の 1 つまたはすべてのメソッドに対する CORS サポートを有効にできます。COR サポートを有効にしたら、統合パススルーの動作を `NEVER` に設定します。この場合、マッピングされていないコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。詳細については、[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)を参照してください。
**重要**
リソースには子リソースを含めることができます。リソースおよびそのメソッドに対する CORS サポートを有効にしても、子リソースおよびそのメソッドに対して再帰的に有効になるわけではありません。
**REST API リソースで CORS サポートを有効にするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. APIを選択します。
1. [**リソース**] のリソースを選択します。
1. **[リソースの詳細]** セクションで、**[CORS の有効化]** を選択します。
![\[[リソース] ペインで、[CORS を有効にする] を選択します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png)
1. **[CORS の有効化]** フォームで、以下の操作を行います。
1. (オプション) カスタムゲートウェイレスポンスを作成し、そのレスポンスの CORS サポートを有効にする場合は、ゲートウェイレスポンスを選択します。
1. それぞれのメソッドを選択して CORS サポートを有効にします。`OPTION` メソッドでは CORS が有効になっている必要があります。
`ANY` メソッドの CORS サポートを有効にすると、すべてのメソッドで CORS が有効になります。
1. **[Access-Control-Allow-Headers]** 入力フィールドに、クライアントがリソースの実際のリクエストで送信する必要があるヘッダーのカンマ区切りリストの静的な文字列を入力します。コンソールで提供されたヘッダーのリスト `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` を使用するか、独自のヘッダーを指定します。
1. コンソールで提供された値 `'*'` を [**Access-Control-Allow-Origin**] ヘッダー値として使用してすべてのオリジンからのアクセスリクエストを許可するか、リソースへのアクセスを許可するオリジンを指定します。
1. **[保存]** を選択します。
![\[どのヘッダーを許可するかを選択する\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png)
**重要**
上記の手順をプロキシ統合の `ANY` メソッドに適用すると、適切な CORS ヘッダーは設定されません。代わりに、バックエンドは `Access-Control-Allow-Origin` などの適切な CORS ヘッダーを返す必要があります。
`GET` メソッドで CORS を有効にすると、すでに追加されていない場合は `OPTIONS` メソッドがリソースに追加されます。`200` メソッドの `OPTIONS` レスポンスは、プリフライトハンドシェイクを満たすため 3 つの `Access-Control-Allow-*` ヘッダーを返すよう自動的に設定されます。さらに、実際の (`GET`) メソッドは、デフォルトでその 200 レスポンスで `Access-Control-Allow-Origin` ヘッダーを返すように設定されます。他の種類のレスポンスでは、`Cross-origin access` エラーが発生しないようにする場合、'\$1' または特定のオリジンを使って `Access-Control-Allow-Origin'` ヘッダーを返すよう手動で設定する必要があります。
リソースで CORS サポートを有効にした後、新しい設定を有効にするには API をデプロイまたは再デプロイする必要があります。詳細については、「[デプロイを作成する](set-up-deployments.md#create-deployment)」を参照してください。
**注記**
手順を実行してもリソースで CORS サポートを有効にできない場合は、CORS 設定をサンプルの API `/pets` リソースと比較することをお勧めします。サンプル API の作成方法については、「[チュートリアル: サンプルをインポートして REST API を作成する](api-gateway-create-api-from-example.md)」を参照してください。
# API Gateway のインポート API を使用して、リソースで CORS を有効にする
[API Gateway の API のインポート](api-gateway-import-api.md)を使用している場合、OpenAPI ファイルを使用して CORS サポートをセットアップできます。最初に、必要なヘッダーを返すリソースの、`OPTIONS` メソッドを定義する必要があります。
**注記**
ウェブブラウザは、Access-Control-Allow-Headers ヘッダーおよび Access-Control-Allow-Origin ヘッダーが、CORS リクエストを受け入れる各 API メソッドでセットアップされると想定します。また、一部のブラウザは、同じリソースの `OPTIONS` メソッドに対して HTTP リクエストを行ってから、同じヘッダーを受け取ることを想定します。
## `Options` メソッドの例
次の例では、モック統合の `OPTIONS` メソッドを作成します。
------
#### [ OpenAPI 3.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
tags:
- CORS
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
type: mock
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
```
------
#### [ OpenAPI 2.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
consumes:
- "application/json"
produces:
- "application/json"
tags:
- CORS
x-amazon-apigateway-integration:
type: mock
requestTemplates: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
リソースに `OPTIONS` メソッドを設定したら、CORS リクエストを受け入れる必要がある同じリソースのその他のメソッドに、必要なヘッダーを追加できます。
1. **Access-Control-Allow-Origin** と **Access-Control-Allow-Origin** を応答のタイプに対して宣言します。
------
#### [ OpenAPI 3.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
1. `x-amazon-apigateway-integration` タグで、これらのヘッダーのマッピングを静的な値にセットアップします。
------
#### [ OpenAPI 3.0 ]
```
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
responseTemplates:
application/json: |
{}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
```
------
## API の例
次の例では、`OPTIONS` メソッド、および `GET` メソッドと `HTTP` 統合を含む完全な API を作成します。
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "cors-api"
description: "cors-api"
version: "2024-01-16T18:36:01Z"
servers:
- url: "/{basePath}"
variables:
basePath:
default: "/test"
paths:
/:
get:
operationId: "GetPet"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
components:
schemas:
Empty:
type: "object"
```
------
#### [ OpenAPI 2.0 ]
```
swagger: "2.0"
info:
description: "cors-api"
version: "2024-01-16T18:36:01Z"
title: "cors-api"
basePath: "/test"
schemes:
- "https"
paths:
/:
get:
operationId: "GetPet"
produces:
- "application/json"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
"200":
description: "200 response"
schema:
$ref: "#/definitions/Empty"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Headers:
type: "string"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
definitions:
Empty:
type: "object"
```
------
# API Gateway API の CORS をテストする
API を呼び出し、レスポンスの CORS ヘッダーを確認することで、API の CORS 設定をテストできます。次の `curl` コマンドは、デプロイされた API に OPTIONS リクエストを送信します。
```
curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}
```
```
< HTTP/1.1 200 OK
< Date: Tue, 19 May 2020 00:55:22 GMT
< Content-Type: application/json
< Content-Length: 0
< Connection: keep-alive
< x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token
< x-amz-apigw-id: Abcd=
< Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT
```
レスポンスの `Access-Control-Allow-Origin`、`Access-Control-Allow-Headers`、および `Access-Control-Allow-Methods` ヘッダーは、API が CORS をサポートすることを示しています。詳細については、「[API Gateway での REST API の CORS](how-to-cors.md)」を参照してください。
# API Gateway での REST API のバイナリメディアタイプ
API Gateway では、API リクエストおよびレスポンスにテキストまたはバイナリペイロードがあります。テキストペイロードは `UTF-8` でエンコードされた JSON 文字列です。テキストペイロード以外のすべてはバイナリペイロードです。バイナリペイロードの例には、JPEG ファイル、GZip ファイル、XML ファイルなどがあります。バイナリメディアをサポートするために必要な API 設定は、API がプロキシ統合を使用するか非プロキシ統合を使用するかによって異なります。
ペイロードレスポンスストリーミングとプロキシ統合を使用する場合、バイナリメディアタイプを設定する必要はありません。詳細については、「[API Gateway でプロキシ統合の統合レスポンスをストリーミングする](response-transfer-mode.md)」を参照してください。
## AWS Lambda プロキシ統合
AWS Lambda プロキシ統合のバイナリペイロードを処理するには、関数のレスポンスを base64 でエンコードする必要があります。また、API の [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) を設定する必要があります。API の `binaryMediaTypes` 設定は、API がバイナリデータとして扱うコンテンツタイプのリストです。バイナリメディアタイプの例には、`image/png` または `application/octet-stream` が含まれます。ワイルドカード文字 (`*`) を使用して、複数のメディアタイプを対象にすることができます。
API Gateway は、クライアントからの最初の `Accept` ヘッダーを使用して、レスポンスがバイナリメディアを返すかどうかを判断します。ブラウザからのリクエストなど、`Accept` ヘッダー値の順序を制御できない場合に、バイナリメディアを返すには、API のバイナリメディアタイプを `*/*` に設定します。
サンプルコードについては、「[API Gateway のLambda プロキシ統合からバイナリメディアを返す](lambda-proxy-binary-media.md)」を参照してください。
ペイロードレスポンスストリーミングと Lambda プロキシ統合を使用する場合、バイナリメディアタイプを設定する必要はありません。詳細については、「[API Gateway でペイロードレスポンスストリーミングと Lambda プロキシ統合を設定する](response-transfer-mode-lambda.md)」を参照してください。
## 非プロキシ統合
非プロキシ統合のバイナリペイロードを処理するには、メディアタイプを `RestApi` リソースの [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) リストに追加します。API の `binaryMediaTypes` 設定は、API がバイナリデータとして扱うコンテンツタイプのリストです。[Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) リソースと [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) リソースに [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) プロパティを設定することもできます。`contentHandling` 値は、`CONVERT_TO_BINARY`、`CONVERT_TO_TEXT`、または未定義にすることができます。
**注記**
`MOCK` またはプライベート統合の場合、AWS マネジメントコンソールでは `contentHandling` プロパティの設定はサポートされていません。`contentHandling` プロパティを設定するには、AWS CLI、CloudFormation、または SDK を使用する必要があります。
`contentHandling` 値の内容と、レスポンスの `Content-Type` ヘッダーと受信リクエストの `Accept` ヘッダーのどちらが `binaryMediaTypes` リストのエントリに一致するかどうかに応じて、API Gateway は raw バイナリバイトを base64 でエンコードされた文字列としてエンコードする、base64 でエンコードされた文字列をその raw バイトに戻す、または変更を加えずに本文を渡すことができます。
API Gateway で API のバイナリペイロードをサポートするには、次のように API を設定する必要があります。
+ [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースの `binaryMediaTypes` リストに必要なメディアタイプを追加します。このプロパティと `contentHandling` プロパティが定義されていない場合、ペイロードは UTF-8 でエンコードされた JSON 設定として処理されます。
+ [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) リソースの `contentHandling` プロパティを指定します。
+ リクエストペイロードを base64 でエンコードされた文字列からそのバイナリ BLOB に変換するには、プロパティを `CONVERT_TO_BINARY` に設定します。
+ リクエストペイロードをバイナリ BLOB から base64 でエンコードされた文字列に変換するには、プロパティを `CONVERT_TO_TEXT` に設定します。
+ ペイロードを変更せずにパススルーするには、プロパティを未定義のままにします。バイナリペイロードを変更せずにパススルーするには、`Content-Type` がいずれかの `binaryMediaTypes` エントリに一致し、API で[パススルー動作](integration-passthrough-behaviors.md)が有効になっていることも必要です。
+ [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) リソースの `contentHandling` プロパティを設定します。`contentHandling` プロパティ、クライアントリクエストの `Accept` ヘッダー、API の `binaryMediaTypes` の組み合わせによって、API Gateway がコンテンツタイプの変換を処理する方法が決まります。詳細については、「[API Gateway でのコンテンツタイプの変換](api-gateway-payload-encodings-workflow.md)」を参照してください。
**重要**
リクエストの `Accept` ヘッダーに複数のメディアタイプが含まれている場合、API Gateway は最初の `Accept` メディアタイプのみ受け入れます。`Accept` メディアタイプの順序を制御できず、バイナリコンテンツのメディアタイプがリストの先頭にない場合は、API の `Accept` リストに最初の `binaryMediaTypes` メディアタイプを追加します。API Gateway は、このリスト内のすべてのコンテンツタイプをバイナリとして処理します。
たとえば、ブラウザで `![]()
` 要素を使用して JPEG ファイルを送信するため、ブラウザがリクエストで `Accept:image/webp,image/*,*/*;q=0.8` を送信することがあります。`image/webp` を `binaryMediaTypes` リストに追加することで、エンドポイントは JPEG ファイルをバイナリとして受け取ります。
API Gateway がテキストとバイナリペイロードを処理する方法の詳細については、「[API Gateway でのコンテンツタイプの変換](api-gateway-payload-encodings-workflow.md)」を参照してください。
# API Gateway でのコンテンツタイプの変換
API の `binaryMediaTypes`、クライアントリクエストのヘッダー、統合の `contentHandling` プロパティの組み合わせによって、API Gateway がペイロードをエンコードする方法が決まります。
次の表に、API Gateway がリクエストの `Content-Type` ヘッダーの特定の設定のリクエストペイロード、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースの `binaryMediaTypes` リスト、[Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) リソースの `contentHandling` プロパティ値を変換する方法を示します。
| メソッドリクエストペイロード | リクエスト `Content-Type` ヘッダー | `binaryMediaTypes` | `contentHandling` | 統合リクエストペイロード |
| --- | --- | --- | --- | --- |
| テキストデータ | 任意のデータ型 | 未定義 | 未定義 | UTF8 でエンコードされた文字列 |
| テキストデータ | 任意のデータ型 | 未定義 | CONVERT\$1TO\$1BINARY | Base64 でデコードされたバイナリ BLOB |
| テキストデータ | 任意のデータ型 | 未定義 | CONVERT\$1TO\$1TEXT | UTF8 でエンコードされた文字列 |
| テキストデータ | テキストデータ型 | 一致するメディアタイプで設定 | 未定義 | テキストデータ |
| テキストデータ | テキストデータ型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1BINARY | Base64 でデコードされたバイナリ BLOB |
| テキストデータ | テキストデータ型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1TEXT | テキストデータ |
| バイナリデータ | バイナリデータ型 | 一致するメディアタイプで設定 | 未定義 | バイナリデータ |
| バイナリデータ | バイナリデータ型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1BINARY | バイナリデータ |
| バイナリデータ | バイナリデータ型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1TEXT | Base64 でエンコードされた文字列 |
次の表に、API Gateway がリクエストの `Accept` ヘッダーの特定の設定のレスポンスペイロード、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースの `binaryMediaTypes` リスト、[IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) リソースの `contentHandling` プロパティ値を変換する方法を示します。
**重要**
リクエストの `Accept` ヘッダーに複数のメディアタイプが含まれている場合、API Gateway は最初の `Accept` メディアタイプのみ受け入れます。`Accept` メディアタイプの順序を制御できず、バイナリコンテンツのメディアタイプがリストの先頭にない場合は、API の `Accept` リストに最初の `binaryMediaTypes` メディアタイプを追加します。API Gateway は、このリスト内のすべてのコンテンツタイプをバイナリとして処理します。
たとえば、ブラウザで `![]()
` 要素を使用して JPEG ファイルを送信するため、ブラウザがリクエストで `Accept:image/webp,image/*,*/*;q=0.8` を送信することがあります。`image/webp` を `binaryMediaTypes` リストに追加することで、エンドポイントは JPEG ファイルをバイナリとして受け取ります。
| 統合レスポンスペイロード | リクエスト `Accept` ヘッダー | `binaryMediaTypes` | `contentHandling` | メソッドレスポンスペイロード |
| --- | --- | --- | --- | --- |
| テキストまたはバイナリデータ | テキスト型 | 未定義 | 未定義 | UTF8 でエンコードされた文字列 |
| テキストまたはバイナリデータ | テキスト型 | 未定義 | CONVERT\$1TO\$1BINARY | Base64 でデコードされた BLOB |
| テキストまたはバイナリデータ | テキスト型 | 未定義 | CONVERT\$1TO\$1TEXT | UTF8 でエンコードされた文字列 |
| テキストデータ | テキスト型 | 一致するメディアタイプで設定 | 未定義 | テキストデータ |
| テキストデータ | テキスト型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1BINARY | Base64 でデコードされた BLOB |
| テキストデータ | テキスト型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1TEXT | UTF8 でエンコードされた文字列 |
| テキストデータ | バイナリ型 | 一致するメディアタイプで設定 | 未定義 | Base64 でデコードされた BLOB |
| テキストデータ | バイナリ型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1BINARY | Base64 でデコードされた BLOB |
| テキストデータ | バイナリ型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1TEXT | UTF8 でエンコードされた文字列 |
| バイナリデータ | テキスト型 | 一致するメディアタイプで設定 | 未定義 | Base64 でエンコードされた文字列 |
| バイナリデータ | テキスト型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1BINARY | バイナリデータ |
| バイナリデータ | テキスト型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1TEXT | Base64 でエンコードされた文字列 |
| バイナリデータ | バイナリ型 | 一致するメディアタイプで設定 | 未定義 | バイナリデータ |
| バイナリデータ | バイナリ型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1BINARY | バイナリデータ |
| バイナリデータ | バイナリ型 | 一致するメディアタイプで設定 | CONVERT\$1TO\$1TEXT | Base64 でエンコードされた文字列 |
テキストペイロードをバイナリ BLOB に変換するとき、API Gateway はテキストデータが Base64 でエンコードされた文字列であるとみなし、バイナリデータを Base64 でデコードされた BLOB として出力します。変換に失敗した場合、API 設定エラーを示す `500` レスポンスを返します。そのような変換のマッピングテンプレートは提供しませんが、API で[パススルー動作](integration-passthrough-behaviors.md)を有効にする必要があります。
バイナリペイロードをテキスト文字列に変換した場合、API Gateway は常にバイナリデータに Base64 エンコードを適用します。そのようなペイロードのマッピングテンプレートを定義できますが、サンプルマッピングテンプレートの次の抜粋に示すように、マッピングテンプレート内の Base64 でエンコードされた文字列には `$input.body` を通じてのみアクセスできます。
```
{
"data": "$input.body"
}
```
バイナリペイロードが変更されずに渡されるようにするには、API で[パススルー動作](integration-passthrough-behaviors.md)を有効にする必要があります。
# API Gateway コンソールを使用したバイナリサポートの有効化
このセクションでは、API Gateway コンソールを使用してバイナリサポートを有効にする方法ついて説明します。例として、Amazon S3 と統合された API を使用します。サポートされるメディアタイプを設定するタスクと、ペイロードの処理方法を指定する方法に焦点を当てます。Amazon S3 と統合された API を作成する方法の詳細については、「[チュートリアル: REST API を Amazon S3 のプロキシとして作成する](integrating-api-with-aws-services-s3.md)」を参照してください。
**API Gateway コンソールを使用してバイナリサポートを有効にするには**
1. API のバイナリメディアタイプの設定
1. 新しい API を作成するか、既存の API を選択します。この例では、API に `FileMan` という名前を付けます。
1. プライマリナビゲーションパネルで選択した API で、**[API の設定]** を選択します。
1. **[API の設定]** ペインで、**[バイナリメディアタイプ]** セクションの **[メディアタイプを管理]** を選択します。
1. **[バイナリメディアタイプを追加]** を選択します。
1. 必要なメディアタイプ (例: **image/png**) を入力テキストフィールドに入力します。必要に応じて、このステップを繰り返して他のメディアタイプを追加します。すべてのバイナリメディアタイプをサポートするには、`*/*` を指定します。
1. **[Save changes]** (変更の保存) をクリックします。
1. API メソッドのメッセージペイロードを処理する方法を設定します。
1. API で新しいリソースを作成するか、既存のリソースを選択します。この例では、`/{folder}/{item}` リソースを使用します。
1. リソースで新しいメソッドを作成するか、既存のメソッドを選択します。例として、Amazon S3 で `GET /{folder}/{item}` アクションと統合された `Object GET` メソッドを使用します。
1. **[コンテンツの処理]** で、オプションを選択します。
![\[API Gateway コンソールで GET メソッドをセットアップします。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png)
クライアントとバックエンドが同じバイナリ形式を受け入れるときに本文を変換しない場合は、[**Passthrough (パススルー)**] を選択します。バイナリリクエストペイロードを JSON プロパティとして渡すことがバックエンドで要求される場合などに、バイナリ本文を Base64 でエンコードされた文字列に変換するには、**[テキストに変換]** を選択します。また、クライアントが Base64 でエンコードされた文字列を送信してバックエンドが元のバイナリ形式を要求する場合や、エンドポイントが Base64 でエンコードされた文字列を返してクライアントがバイナリ出力のみ受け入れる場合は、**[バイナリに変換]** を選択します。
1. **[リクエスト本文のパススルー]** で、**[テンプレートが定義されていない場合 (推奨)]** を選択し、リクエスト本文に対するパススルー動作を有効にします。
**[なし]** を選択することもできます。つまり、API はマッピングテンプレートを持たない Content-Type のデータを拒否します。
1. 統合リクエストで、受信リクエストの `Accept` ヘッダーを保持します。これは、`contentHandling` を `passthrough` に設定し、ランタイムにその設定を上書きする場合に行う必要があります。
![\[統合リクエストで Accept ヘッダーを保持します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png)
1. テキストに変換する場合は、Base64 でエンコードされたバイナリデータを必要な形式にするマッピングテンプレートを定義します。
マッピングテンプレートをテキストに変換する例は次のとおりです。
```
{
"operation": "thumbnail",
"base64Image": "$input.body"
}
```
このマッピングテンプレートの形式は、入力のエンドポイント要件によって異なります。
1. **[保存]** を選択します。
# API Gateway REST API を使用したバイナリサポートの有効化
次のタスクは、API Gateway REST API コールを使用してバイナリサポートを有効にする方法を示します。
**Topics**
+ [
## サポートされるバイナリメディアタイプの API への追加と更新
](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [
## リクエストペイロード変換の設定
](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [
## レスポンスペイロード変換の設定
](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [
## バイナリデータをテキストデータに変換する
](#api-gateway-payload-encodings-convert-binary-to-string)
+ [
## テキストデータをバイナリペイロードに変換する
](#api-gateway-payload-encodings-convert-string-to-binary)
+ [
## バイナリペイロードを渡す
](#api-gateway-payload-encodings-pass-binary-as-is)
## サポートされるバイナリメディアタイプの API への追加と更新
API Gateway が新しいバイナリメディアタイプをサポートするようにするには、`binaryMediaTypes` リソースの `RestApi` リストにバイナリメディアタイプを追加する必要があります。たとえば、API Gateway が JPEG イメージを処理するようにするには、`PATCH` リクエストを `RestApi` リソースに送信します。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/image~1jpeg"
}
]
}
```
`image/jpeg` プロパティ値の一部となっている `path` の MIME タイプの指定は、`image~1jpeg` としてエスケープされます。
サポートされるバイナリメディアタイプを更新するには、`binaryMediaTypes` リソースの `RestApi` リストにあるメディアタイプを置き換えるか、削除します。たとえば、バイナリサポートを JPEG ファイルから raw バイトに変更するには、次のように `PATCH` リクエストを `RestApi` リソースに送信します。
```
PATCH /restapis/
{
"patchOperations" : [{
"op" : "replace",
"path" : "/binaryMediaTypes/image~1jpeg",
"value" : "application/octet-stream"
},
{
"op" : "remove",
"path" : "/binaryMediaTypes/image~1jpeg"
}]
}
```
## リクエストペイロード変換の設定
エンドポイントにバイナリ入力が必要な場合、`contentHandling` リソースの `Integration` プロパティを `CONVERT_TO_BINARY` に設定します。これを行うには、次のように `PATCH` リクエストを送信します。
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## レスポンスペイロード変換の設定
クライアントが、エンドポイントから返された Base64 でエンコードされたペイロードの代わりにバイナリ BLOB として結果を受け入れる場合、`contentHandling` リソースの `IntegrationResponse` プロパティを `CONVERT_TO_BINARY` に設定します。これを行うには、次のように `PATCH` リクエストを送信します。
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## バイナリデータをテキストデータに変換する
バイナリデータを API Gateway 経由で、AWS Lambda または Kinesis への入力の JSON プロパティとして送信するには、以下の操作を実行します。
1. `application/octet-stream` の新しいバイナリメディアタイプを API の `binaryMediaTypes` リストに追加することで、API のバイナリペイロードサポートを有効にします。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. `CONVERT_TO_TEXT` リソースの `contentHandling` プロパティで `Integration` を設定し、バイナリデータの Base64 でエンコードされた文字列を JSON プロパティに割り当てるマッピングテンプレートを提供します。次の例では、JSON プロパティが `body` であり、`$input.body` には Base64 でエンコードされた文字列が保持されています。
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_TEXT"
},
{
"op" : "add",
"path" : "/requestTemplates/application~1octet-stream",
"value" : "{\"body\": \"$input.body\"}"
}
]
}
```
## テキストデータをバイナリペイロードに変換する
Lambda 関数がイメージファイルを base64 でエンコードされた文字列として返すとします。API Gateway を通じてこのバイナリ出力をクライアントに渡すには、以下の操作を実行します。
1. `binaryMediaTypes` のバイナリメディアを追加することで API の `application/octet-stream` リストを更新します (まだリストにない場合)。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream",
}]
}
```
1. `contentHandling` リソースの `Integration` プロパティを `CONVERT_TO_BINARY` に設定します。マッピングテンプレートを定義しないでください。マッピングテンプレートを定義しない場合、API Gateway はパススルーテンプレートを呼び出して、Base64 でデコードされたバイナリ BLOB をイメージファイルとしてクライアントに返します。
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}
]
}
```
## バイナリペイロードを渡す
API Gateway を使用して Amazon S3 バケットにイメージを保存するには、以下の操作を実行します。
1. `binaryMediaTypes` のバイナリメディアを追加することで API の `application/octet-stream` リストを更新します (まだリストにない場合)。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. `contentHandling` リソースの `Integration` プロパティで `CONVERT_TO_BINARY` を設定します。マッピングテンプレートを定義せずに、`WHEN_NO_MATCH` を `passthroughBehavior` プロパティとして設定します。これにより、API Gateway はパススルーテンプレートを呼び出すことができます。
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
},
{
"op" : "replace",
"path" : "/passthroughBehaviors",
"value" : "WHEN_NO_MATCH"
}
]
}
```
# API Gateway のコンテンツエンコードのインポートとエクスポート
[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) の `binaryMediaTypes` リストをインポートするには、API の OpenAPI 定義ファイルへの次の API Gateway 拡張を使用します。この拡張は、API 設定のエクスポートにも使用します。
+ [x-amazon-apigateway-binary-media-types のプロパティ](api-gateway-swagger-extensions-binary-media-types.md)
`contentHandling` または `Integration` リソースで `IntegrationResponse` プロパティ値をインポートおよびエクスポートするには、OpenAPI 定義への次の API Gateway 拡張を使用します。
+ [x-amazon-apigateway-integration オブジェクト](api-gateway-swagger-extensions-integration.md)
+ [x-amazon-apigateway-integration.response オブジェクト](api-gateway-swagger-extensions-integration-response.md)
# API Gateway のLambda プロキシ統合からバイナリメディアを返す
[AWS Lambda プロキシ統合](set-up-lambda-proxy-integrations.md)からバイナリメディアを返すには、Lambda 関数からのレスポンスを base64 でエンコードします。また、[API のバイナリメディアタイプを設定](api-gateway-payload-encodings-configure-with-console.md)する必要があります。API のバイナリメディアタイプを設定すると、API はそのコンテンツタイプをバイナリデータとして扱います。ペイロードサイズの上限は 10 MB です。
**注記**
この統合例でウェブブラウザを使用して API を呼び出すには、API のバイナリメディアタイプを `*/*` に設定します 。API Gateway は、クライアントからの最初の `Accept` ヘッダーを使用して、レスポンスがバイナリメディアを返すかどうかを判断します。ブラウザからのリクエストなど、`Accept` ヘッダー値の順序を制御できない場合に、バイナリメディアを返すには、API のバイナリメディアタイプを `*/*` (すべてのコンテンツタイプ) に設定します。
以下のサンプルの Lambda 関数は、Amazon S3 からのバイナリイメージまたはテキストをクライアントに返すことができます。関数のレスポンスには、返されるデータのタイプをクライアントに示す `Content-Type` ヘッダーが含まれています。この関数は、返すデータのタイプに応じて、レスポンスで `isBase64Encoded` プロパティを条件付きで設定します。
------
#### [ Node.js ]
```
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"
const client = new S3Client({region: 'us-east-2'});
export const handler = async (event) => {
var randomint = function(max) {
return Math.floor(Math.random() * max);
}
var number = randomint(2);
if (number == 1){
const input = {
"Bucket" : "bucket-name",
"Key" : "image.png"
}
try {
const command = new GetObjectCommand(input)
const response = await client.send(command);
var str = await response.Body.transformToByteArray();
} catch (err) {
console.error(err);
}
const base64body = Buffer.from(str).toString('base64');
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64body,
'isBase64Encoded': true
}
} else {
return {
'headers': { "Content-Type": "text/html" },
'statusCode': 200,
'body': "This is text
",
}
}
}
```
------
#### [ Python ]
```
import base64
import boto3
import json
import random
s3 = boto3.client('s3')
def lambda_handler(event, context):
number = random.randint(0,1)
if number == 1:
response = s3.get_object(
Bucket='bucket-name',
Key='image.png',
)
image = response['Body'].read()
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64.b64encode(image).decode('utf-8'),
'isBase64Encoded': True
}
else:
return {
'headers': { "Content-type": "text/html" },
'statusCode': 200,
'body': "This is text
",
}
```
------
バイナリメディアタイプの詳細については、「[API Gateway での REST API のバイナリメディアタイプ](api-gateway-payload-encodings.md)」を参照してください。
# API Gateway API を介して Amazon S3 のバイナリファイルにアクセスする
次の例は、Amazon S3 でのイメージのアクセスに使用される OpenAPI ファイル、Amazon S3 からイメージをダウンロードする方法、イメージを Amazon S3 にアップロードする方法を示しています。
**Topics**
+ [
## Amazon S3 でイメージにアクセスするためのサンプル API の OpenAPI ファイル
](#api-gateway-content-encodings-example-image-s3-swagger-file)
+ [
## Amazon S3 からイメージをダウンロードする
](#api-gateway-content-encodings-example-download-image-from-s3)
+ [
## Amazon S3 にイメージをアップロードする
](#api-gateway-content-encodings-example-upload-image-to-s3)
## Amazon S3 でイメージにアクセスするためのサンプル API の OpenAPI ファイル
次の OpenAPI ファイルは、Amazon S3 からのイメージファイルのダウンロードと Amazon S3 へのイメージファイルのアップロードを示すサンプル API を示しています。この API は、指定されたイメージファイルをダウンロードおよびアップロードするための `GET /s3?key={file-name}` メソッドと `PUT /s3?key={file-name}` メソッドを開示します。`GET` メソッドは、200 OK レスポンスにおいて、提供されたマッピングテンプレートに従って、JSON 出力の一部である Base64 でエンコードされた文字列としてイメージファイルを返します。`PUT` メソッドは、入力として raw バイナリ BLOB を受け取り、200 OK レスポンスを空のペイロードで返します。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/s3": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling": "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/s3": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200" }
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling" : "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Amazon S3 からイメージをダウンロードする
イメージファイル (`image.jpg`) を Amazon S3 からバイナリ BLOB としてダウンロードするには
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
正常な応答は次のようになります。
```
200 OK HTTP/1.1
[raw bytes]
```
`Accept` ヘッダーが `application/octet-stream` のバイナリメディアタイプとして設定されており、API のバイナリサポートが有効になっているため、raw バイトが返されます。
または、イメージファイル (`image.jpg`) を、Amazon S3 から、(JSON プロパティとしてフォーマットされた) Base64 でエンコードされた文字列としてダウンロードするには、次の太字の OpenAPI 定義ブロックに示されているように、200 の統合レスポンスにレスポンステンプレートを追加します。
```
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
},
```
イメージファイルをダウンロードするリクエストは、次のようになります。
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
正常なレスポンスは次のようになります。
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## Amazon S3 にイメージをアップロードする
イメージファイル (`image.jpg`) をバイナリ BLOB として Amazon S3 にアップロードするには
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
正常なレスポンスは次のようになります。
```
200 OK HTTP/1.1
```
イメージファイル (`image.jpg`) を Base64 でエンコードされた文字列として Amazon S3 にアップロードするには
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
`Content-Type` ヘッダー値が `application/json` に設定されているため、入力ペイロードは Base64 でエンコードされた文字列でなければならない点に注意してください。正常なレスポンスは次のようになります。
```
200 OK HTTP/1.1
```
# API Gateway API を使用して Lambda のバイナリファイルにアクセスする
次の OpenAPI の例は、API Gateway API を通じて AWS Lambda のバイナリファイルにアクセスする方法を示しています。この API は、指定したイメージファイルをダウンロードおよびアップロードするための `GET /lambda?key={file-name}` メソッドと `PUT /lambda?key={file-name}` メソッドを公開します。`GET` メソッドは、200 OK レスポンスにおいて、提供されたマッピングテンプレートに従って、JSON 出力の一部である Base64 でエンコードされた文字列としてイメージファイルを返します。`PUT` メソッドは、入力として raw バイナリ BLOB を受け取り、200 OK レスポンスを空のペイロードで返します。
API が呼び出す Lambda 関数を作成します。この Lambda 関数は、`application/json` の `Content-Type` ヘッダーを含む文字列を base64 でエンコードして返す必要があります。
**Topics**
+ [
## Lambda でイメージにアクセスするためのサンプル API の OpenAPI ファイル
](#api-gateway-content-encodings-example-image-lambda-swagger-file)
+ [
## Lambda からイメージをダウンロードする
](#api-gateway-content-encodings-example-download-image-from-lambda)
+ [
## Lambda へイメージをアップロードする
](#api-gateway-content-encodings-example-upload-image-to-lambda)
## Lambda でイメージにアクセスするためのサンプル API の OpenAPI ファイル
次の OpenAPI ファイルは、Lambda からのイメージファイルのダウンロードと Lambda へのイメージファイルのアップロードを示す API 例を示しています。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/lambda": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/lambda": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling" : "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Lambda からイメージをダウンロードする
イメージファイル (`image.jpg`) を Lambda からバイナリ BLOB としてダウンロードするには
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
正常なレスポンスは次のようになります。
```
200 OK HTTP/1.1
[raw bytes]
```
イメージファイル (`image.jpg`) を、JSON プロパティとしてフォーマットして base64 でエンコードされた文字列として Lambda からダウンロードするには
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
正常なレスポンスは次のようになります。
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## Lambda へイメージをアップロードする
イメージファイル (`image.jpg`) をバイナリ BLOB として Lambda にアップロードするには
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
正常なレスポンスは次のようになります。
```
200 OK
```
イメージファイル (`image.jpg`) を base64 でエンコードされた文字列として Lambda にアップロードするには
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
正常なレスポンスは次のようになります。
```
200 OK
```
# API Gateway で REST API を呼び出す
デプロイされた API を呼び出すには、API 実行の `execute-api` コンポーネントサービス (API Gateway と呼ばれます) の URL にクライアントがリクエストを送信します。
REST API のベース URL の形式は以下のとおりです。
```
https://api-id.execute-api.region.amazonaws.com/stage/
```
*api\$1id* は API ID、*region* は AWS リージョン、*stage* は API デプロイのステージ名です。
**重要**
API を呼び出す前に、API Gateway でデプロイする必要があります。API をデプロイする手順については、「[API Gateway で REST API をデプロイする](how-to-deploy-api.md)」を参照してください。
**Topics**
+ [
## API の呼び出し URL の取得
](#apigateway-how-to-call-rest-api)
+ [
## API の呼び出し
](#apigateway-call-api)
+ [
# API Gateway コンソールを使用して REST API メソッドをテストする
](how-to-test-method.md)
+ [
# REST API 用に API Gateway で生成された Java SDK を使用する
](how-to-call-apigateway-generated-java-sdk.md)
+ [
# REST API 用に API Gateway で生成された Android SDK を使用する
](how-to-generate-sdk-android.md)
+ [
# REST API 用に API Gateway で生成された JavaScript SDK を使用する
](how-to-generate-sdk-javascript.md)
+ [
# API Gateway によって生成された Ruby SDK を REST API で使用する
](how-to-call-sdk-ruby.md)
+ [
# Objective-C または Swift で REST API 用に API Gateway で生成された iOS SDK を使用する
](how-to-generate-sdk-ios.md)
## API の呼び出し URL の取得
API の呼び出し URL を取得するには、コンソール、AWS CLI、またはエクスポートされた OpenAPI 定義を使用できます。
### コンソールを使用した API の 呼び出し URL の取得
次の手順では、REST API コンソールで API の呼び出し URL を取得する方法を示します。
**REST API コンソールを使用して API の 呼び出し URL を取得するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. デプロイされた API を選択します。
1. メインのナビゲーションペインで、**[ステージ]** を選択します。
1. **[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーします。
この URL は API のルートリソース用です。
![\[REST API を作成すると、コンソールに API の呼び出し URL が表示されます。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png)
1. API で別のリソース用の API の呼び出し URL を取得するには、セカンダリナビゲーションペインでステージを展開し、メソッドを選択します。
1. コピーアイコンを選択して API のリソースレベルの呼び出し URL をコピーします。
![\[REST API のリソースレベルの URL は、ステージのセカンダリナビゲーションペインの下にあります。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/resource-level-invoke-url.png)
#### AWS CLI を使用した API の呼び出し URL の取得
次の手順では、AWS CLI を使用して API の呼び出し URL を取得する方法を示します。
**AWS CLI を使用した API の 呼び出し URL の取得**
1. `rest-api-id` を取得するには、次のコマンドを使用します。このコマンドは、リージョンのすべての `rest-api-id` 値を返します。詳細については、「[get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html)」を参照してください。
```
aws apigateway get-rest-apis
```
1. 例の `rest-api-id` を独自の `rest-api-id`、例の *\$1stage-name\$1* を独自の *\$1stage-name\$1*、*\$1region\$1* を独自のリージョンに置き換えます。
```
https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/
```
##### API のエクスポートされた OpenAPI 定義ファイルを使用した API の呼び出し URL の取得
API のエクスポートされた OpenAPI 定義ファイルの `host` フィールドと `basePath` フィールドを組み合わせてルート URL を構築することもできます。API のエクスポート方法の手順については、「[API Gateway から REST API をエクスポートする](api-gateway-export-api.md)」を参照してください。
## API の呼び出し
デプロイした API は、ブラウザ、curl、または他のアプリケーション ([Postman](https://www.postman.com/) など) を使用して呼び出すことができます。
さらに、API Gateway コンソールを使用して API コールをテストすることもできます。テストでは API Gateway の `TestInvoke` 機能を使用します。これにより、API をデプロイする前に API をテストできます。詳細については、「[API Gateway コンソールを使用して REST API メソッドをテストする](how-to-test-method.md)」を参照してください。
**注記**
呼び出し URL のクエリ文字列パラメーターの値に `%%` を含めることはできません。
### ウェブブラウザを使用した API の呼び出し
API が匿名アクセスを許可する場合は、任意のウェブブラウザを使用して `GET` メソッドを呼び出すことができます。ブラウザのアドレスバーに完全な呼び出し URL を入力します。
他のメソッドや認証が必要な呼び出しについては、ペイロードを指定するか、リクエストに署名する必要があります。HTML ページの裏のスクリプトで、または AWS SDK の 1 つを使用して、クライアントのアプリケーションで処理することができます。
#### curl を使用した API の呼び出し
ターミナルで [curl](https://curl.se/) などのツールを使用して API を呼び出すことができます。次の curl コマンドの例では、API の `prod` ステージの `getUsers` リソースで GET メソッドを呼び出します。
------
#### [ Linux or Macintosh ]
```
curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
------
#### [ Windows ]
```
curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers"
```
------
# API Gateway コンソールを使用して REST API メソッドをテストする
API Gateway コンソールを使用して REST API メソッドをテストします。
**Topics**
+ [
## 前提条件
](#how-to-test-method-prerequisites)
+ [
## API Gateway コンソールを使用してメソッドをテストする
](#how-to-test-method-console)
## 前提条件
+ テストするメソッドの設定を指定する必要があります。「[API Gateway の REST API のメソッド](how-to-method-settings.md)」の手順に従います。
## API Gateway コンソールを使用してメソッドをテストする
**重要**
API Gateway コンソールでメソッドをテストすると、リソースが変更され、元に戻せなくなる場合があります。API Gateway コンソールでメソッドをテストすることは、API Gateway コンソール外でメソッドを呼び出すことと同じです。たとえば、API Gateway コンソールを使用して API リソースを削除するメソッドを呼び出した場合、メソッドの呼び出しが成功すると、API のリソースは削除されます。
**メソッドをテストするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. [**リソース**] ペインで、テストするメソッドを選択します。
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
![\[[テスト] タブを使用して API をテストします。このタブは、[メソッドレスポンス] タブの横にあります。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-test-new-console.png)
表示されたいずれかのボックスに値を入力します (**[クエリ文字列]**、**[ヘッダー]**、**[リクエスト本文]** など)。コンソールには、メソッドリクエストにこれらの値がデフォルトの application/json 形式で含まれています。
指定する必要がある追加オプションについては、API 所有者までお問い合わせください。
1. [**Test (テスト)**] を選択します。次の情報が表示されます。
+ [**リクエスト**]: メソッド用に呼び出されたリソースのパスです。
+ [**ステータス**]: 応答の HTTP ステータスコードです。
+ **[レイテンシー (ミリ秒)]**: 発信者からのリクエストを受信してからレスポンスを返すまでの時間です。
+ **[レスポンス本文]** は HTTP レスポンスの本文です。
+ **[レスポンスヘッダー]** は HTTP レスポンスのヘッダーです。
**ヒント**
マッピングによって、HTTP ステータスコード、応答本文、応答ヘッダーは、Lambda 関数、HTTP プロキシ、または AWS のサービスプロキシから送信されたものと異なる場合があります。
+ [**ログ**] はシミュレートされた Amazon CloudWatch Logs エントリで、このメソッドが API Gateway コンソール外で呼び出された場合は書き込まれています。
**注記**
CloudWatch Logs エントリはシミュレートされていますが、メソッドの呼び出しの結果は現実のものです。
API Gateway コンソールの使用に加えて、AWS CLI、または API Gateway 用の AWS SDK を使用してメソッドの呼び出しをテストすることもできます。AWS CLI を使用してこれを行う方法については、「[test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html)」を参照してください。
# REST API 用に API Gateway で生成された Java SDK を使用する
このセクションでは、[単純な電卓](simple-calc-lambda-api-swagger-definition.md)の API を例として使用し、REST API に対して API Gateway で生成された Java SDK を使用するステップを示します。先に進む前に、「[API Gateway で REST API の SDK を生成する](how-to-generate-sdk.md)」のステップを完了する必要があります。
**API Gateway で生成した Java SDK をインストールして使用するには**
1. ダウンロード済みの API Gateway で生成された .zip ファイルのコンテンツを抽出します。
1. [Apache Maven](https://maven.apache.org/) (バージョン 3.5 以降が必要です) をダウンロードしてインストールします。
1. [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html) をダウンロードしてインストールします。
1. `JAVA_HOME` 環境変数を設定します。
1. 解凍した SDK フォルダ内の pom.xml ファイルに移動します。このフォルダーは、デフォルトでは `generated-code` です。**mvn install** コマンドを実行し、コンパイルされたアーティファクトファイルをローカルの Maven リポジトリにインストールします。これにより、コンパイル済み SDK ライブラリを含む `target` フォルダーが作成されます。
1. 空のディレクトリで次のコマンドを入力し、インストールした SDK ライブラリを使用して API を呼び出すためのクライアントプロジェクトスタブを作成します。
```
mvn -B archetype:generate \
-DarchetypeGroupdId=org.apache.maven.archetypes \
-DgroupId=examples.aws.apig.simpleCalc.sdk.app \
-DartifactId=SimpleCalc-sdkClient
```
**注記**
上のコマンドで区切り記号の `\` は読みやすくするために使用しています。コマンド全体は区切り記号がない単一の行となります。
このコマンドでは、アプリケーションスタブを作成します。アプリケーションスタブには、プロジェクトのルートディレクトリ (上のコマンドの `pom.xml`SimpleCalc-sdkClient`src`) の * ファイルと * フォルダが含まれます。当初は、ソースファイルとして `src/main/java/{package-path}/App.java` と `src/test/java/{package-path}/AppTest.java` の 2 つがあります。この例では、*\$1package-path\$1* は `examples/aws/apig/simpleCalc/sdk/app` です。このパッケージパスは `DarchetypeGroupdId` の値から取得されます。`App.java` ファイルは、クライアントアプリケーションのテンプレートとして使用できます。また、必要に応じて同じフォルダーに他のファイルを追加できます。`AppTest.java` ファイルは、アプリケーションのユニットテストテンプレートとして使用できます。また、必要に応じて同じテストフォルダーに他のテストコードファイルを追加できます。
1. 生成された `pom.xml` ファイルのパッケージ依存関係を以下のように更新し、必要に応じてプロジェクトの `groupId`、`artifactId`、`version`、`name` の各プロパティを置き換えます。
```
4.0.0
examples.aws.apig.simpleCalc.sdk.app
SimpleCalc-sdkClient
jar
1.0-SNAPSHOT
SimpleCalc-sdkClient
http://maven.apache.org
com.amazonaws
aws-java-sdk-core
1.11.94
my-apig-api-examples
simple-calc-sdk
1.0.0
junit
junit
4.12
test
commons-io
commons-io
2.5
org.apache.maven.plugins
maven-compiler-plugin
3.5.1
1.8
1.8
```
**注記**
`aws-java-sdk-core` の依存アーティファクトの新しいバージョンが上記で指定されたバージョン (`1.11.94`) と互換性がない場合は、`` タグを新しいバージョンに更新する必要があります。
1. 次に、SDK の `getABOp(GetABOpRequest req)`、`getApiRoot(GetApiRootRequest req)`、`postApiRoot(PostApiRootRequest req)` の各メソッドを呼び出して、SDK で API を呼び出す方法を示します。これらのメソッドは、`GET /{a}/{b}/{op}`、`GET /?a={x}&b={y}&op={operator}`、`POST /` の各メソッドに対応します。API リクエストのペイロードはそれぞれ `{"a": x, "b": y, "op": "operator"}` です。
次のように `App.java` ファイルを更新します。
```
package examples.aws.apig.simpleCalc.sdk.app;
import java.io.IOException;
import com.amazonaws.opensdk.config.ConnectionConfiguration;
import com.amazonaws.opensdk.config.TimeoutConfiguration;
import examples.aws.apig.simpleCalc.sdk.*;
import examples.aws.apig.simpleCalc.sdk.model.*;
import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*;
public class App
{
SimpleCalcSdk sdkClient;
public App() {
initSdk();
}
// The configuration settings are for illustration purposes and may not be a recommended best practice.
private void initSdk() {
sdkClient = SimpleCalcSdk.builder()
.connectionConfiguration(
new ConnectionConfiguration()
.maxConnections(100)
.connectionMaxIdleMillis(1000))
.timeoutConfiguration(
new TimeoutConfiguration()
.httpRequestTimeout(3000)
.totalExecutionTimeout(10000)
.socketTimeout(2000))
.build();
}
// Calling shutdown is not necessary unless you want to exert explicit control of this resource.
public void shutdown() {
sdkClient.shutdown();
}
// GetABOpResult getABOp(GetABOpRequest getABOpRequest)
public Output getResultWithPathParameters(String x, String y, String operator) {
operator = operator.equals("+") ? "add" : operator;
operator = operator.equals("/") ? "div" : operator;
GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator));
return abopResult.getResult().getOutput();
}
public Output getResultWithQueryParameters(String a, String b, String op) {
GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op));
return rootResult.getResult().getOutput();
}
public Output getResultByPostInputBody(Double x, Double y, String o) {
PostApiRootResult postResult = sdkClient.postApiRoot(
new PostApiRootRequest().input(new Input().a(x).b(y).op(o)));
return postResult.getResult().getOutput();
}
public static void main( String[] args )
{
System.out.println( "Simple calc" );
// to begin
App calc = new App();
// call the SimpleCalc API
Output res = calc.getResultWithPathParameters("1", "2", "-");
System.out.printf("GET /1/2/-: %s\n", res.getC());
// Use the type query parameter
res = calc.getResultWithQueryParameters("1", "2", "+");
System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC());
// Call POST with an Input body.
res = calc.getResultByPostInputBody(1.0, 2.0, "*");
System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC());
}
}
```
上の例で、SDK クライアントをインスタンス化するために使用している設定はサンプルであり、必ずしも推奨されるベストプラクティスではありません。また、`sdkClient.shutdown()` の呼び出しはオプションです。リソースを解放するタイミングを正確に制御する場合などに役立ちます。
Java SDK を使用して API を呼び出すための基本的なパターンを示しました。必要に応じて手順を拡張し、他の API メソッドを呼び出すことができます。
# REST API 用に API Gateway で生成された Android SDK を使用する
このセクションでは、REST API 用に API Gateway で生成された Android SDK を使用するステップを説明します。先に進む前に、「[API Gateway で REST API の SDK を生成する](how-to-generate-sdk.md)」のステップを済ませている必要があります。
**注記**
生成された SDK は、Android 4.4 以前とは互換性がありません。詳細については、「[Amazon API Gateway に関する重要な注意点](api-gateway-known-issues.md)」を参照してください。
**API Gateway で生成された Android SDK をインストールして使用するには**
1. ダウンロード済みの API Gateway で生成された .zip ファイルのコンテンツを抽出します。
1. [Apache Maven](https://maven.apache.org/) をダウンロードしてインストールします (バージョン 3.x を推奨)。
1. [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html) をダウンロードしてインストールします。
1. `JAVA_HOME` 環境変数を設定します。
1. **mvn install** コマンドを実行し、コンパイルされたアーティファクトファイルをローカルの Maven リポジトリにインストールします。これにより、コンパイル済み SDK ライブラリを含む `target` フォルダーが作成されます。
1. `target` フォルダからの SDK ファイル (ファイルの名前は、 `simple-calcsdk-1.0.0.jar`など、SDK の生成時に指定した **Artifact ID** および **Artifact バージョン**に由来するものです) を、`target/lib` フォルダからのその他すべてのライブラリとともに、プロジェクトの `lib` フォルダにコピーします。
Andriod Studio を使用している場合は、クライアントアプリケーションモジュールで `libs` フォルダを作成し、このフォルダ内に必要な .jar ファイルをコピーします。モジュールの gradle ファイルの依存関係セクションに、以下が含まれていることを確認します。
```
compile fileTree(include: ['*.jar'], dir: 'libs')
compile fileTree(include: ['*.jar'], dir: 'app/libs')
```
重複した .jar ファイルが宣言されていないことを確認します。
1. `ApiClientFactory` クラスを使用して、API Gateway で生成された SDK を初期化します。例:
```
ApiClientFactory factory = new ApiClientFactory();
// Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway.
final SimpleCalcClient client = factory.build(SimpleCalcClient.class);
// Invoke a method:
// For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method:
Result output = client.rootGet("1", "2", "+");
// where the Result class of the SDK corresponds to the Result model of the API.
//
// For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request,
Result output = client.aBOpGet(a, b, c);
// where a, b, c can be "1", "2", "add", respectively.
// For the following API method:
// POST /
// host: ...
// Content-Type: application/json
//
// { "a": 1, "b": 2, "op": "+" }
// you can call invoke it by calling the rootPost method of the SDK as follows:
Input body = new Input();
input.a=1;
input.b=2;
input.op="+";
Result output = client.rootPost(body);
// where the Input class of the SDK corresponds to the Input model of the API.
// Parse the result:
// If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as
String result=output.c;
```
1. Amazon Cognito 認証情報プロバイダーを使用して API への呼び出しを認可するには、次の例で示すように API Gateway で生成された SDK を使用して `ApiClientFactory` クラスで AWS 認証情報のセットを渡します。
```
// Use CognitoCachingCredentialsProvider to provide AWS credentials
// for the ApiClientFactory
AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(
context, // activity context
"identityPoolId", // Cognito identity pool id
Regions.US_EAST_1 // region of Cognito identity pool
);
ApiClientFactory factory = new ApiClientFactory()
.credentialsProvider(credentialsProvider);
```
1. API Gateway で生成された SDK で API キーを設定するには、次のようなコードを使用します。
```
ApiClientFactory factory = new ApiClientFactory()
.apiKey("YOUR_API_KEY");
```
# REST API 用に API Gateway で生成された JavaScript SDK を使用する
次の手順は、API Gateway によって生成された JavaScript SDK を使用する方法を示しています。
**注記**
これらの手順は、すでに「[API Gateway で REST API の SDK を生成する](how-to-generate-sdk.md)」の手順を完了していることを前提としています。
**重要**
API に ANY メソッドのみが定義された場合、生成された SDK パッケージに `apigClient.js` ファイルは含まれず、ANY メソッドを自分で定義する必要があります。
**REST API に対して API Gateway で生成された JavaScript SDK をインストールし、開始して呼び出すには**
1. ダウンロード済みの API Gateway で生成された .zip ファイルのコンテンツを抽出します。
1. API Gateway で生成された SDK で呼び出すすべてのメソッドで Cross-Origin Resource Sharing (CORS) を有効にします。手順については、[API Gateway での REST API の CORS](how-to-cors.md) を参照してください。
1. ウェブページで、以下のスクリプトへの参照を含めます。
```
```
1. コードで、API Gateway で生成された SDK を初期化します。次のようなコードを使用します。
```
var apigClient = apigClientFactory.newClient();
```
API Gateway で生成された SDK を AWS 認証情報で初期化するには、次のようなコードを使用します。AWS 認証情報を使用すると、API に対するすべてのリクエストに署名が付与されます。
```
var apigClient = apigClientFactory.newClient({
accessKey: 'ACCESS_KEY',
secretKey: 'SECRET_KEY',
});
```
API Gateway で生成された SDK で API キーを使用するには、次のようなコードを使用し、API キーをパラメータとして `Factory` オブジェクトに渡すことができます。API キーを使用する場合は、`x-api-key` ヘッダーの一部として指定され、API に対するすべてのリクエストに署名が付与されます。これは、各リクエストに適切な CORS Accept ヘッダーを設定する必要があることを意味します。
```
var apigClient = apigClientFactory.newClient({
apiKey: 'API_KEY'
});
```
1. 以下のようなコードを使用して API Gateway で API メソッドを呼び出します。各呼び出しから、成功または失敗のコールバックとともに promise が返されます。
```
var params = {
// This is where any modeled request parameters should be added.
// The key is the parameter name, as it is defined in the API in API Gateway.
param0: '',
param1: ''
};
var body = {
// This is where you define the body of the request,
};
var additionalParams = {
// If there are any unmodeled query parameters or headers that must be
// sent with the request, add them here.
headers: {
param0: '',
param1: ''
},
queryParams: {
param0: '',
param1: ''
}
};
apigClient.methodName(params, body, additionalParams)
.then(function(result){
// Add success callback code here.
}).catch( function(result){
// Add error callback code here.
});
```
ここで、*methodName* は、メソッドリクエストのリソースパスと HTTP 動詞から作成されます。SimpleCalc API の場合、次の API メソッドの SDK メソッド
```
1. GET /?a=...&b=...&op=...
2. POST /
{ "a": ..., "b": ..., "op": ...}
3. GET /{a}/{b}/{op}
```
対応する SDK メソッドは次のとおりです。
```
1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters
2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...}
3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters
```
# API Gateway によって生成された Ruby SDK を REST API で使用する
次の手順は、API Gateway によって生成された Ruby SDK を使用する方法を示しています。
**注記**
これらの手順は、すでに「[API Gateway で REST API の SDK を生成する](how-to-generate-sdk.md)」の手順を完了していることを前提としています。
**REST API に対して API Gateway で生成された Ruby SDK をインストールし、開始して呼び出すには**
1. ダウンロードした Ruby SDK ファイルを解凍します。生成された SDK ソースは、次のように表示されます。
![\[ダウンロードした Ruby SDK ファイルを Ruby モジュールに解凍します\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png)
1. ターミナルウィンドウで次のシェルコマンドを使用して、生成された SDK ソースから Ruby Gem を構築します。
```
# change to /simplecalc-sdk directory
cd simplecalc-sdk
# build the generated gem
gem build simplecalc-sdk.gemspec
```
この後、[**simplecalc-sdk-1.0.0.gem**] が利用可能になります。
1. gem をインストールします。
```
gem install simplecalc-sdk-1.0.0.gem
```
1. クライアントアプリケーションを作成します。アプリで Ruby SDK クライアントをインスタンス化して初期化します。
```
require 'simplecalc-sdk'
client = SimpleCalc::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50
)
```
API に `AWS_IAM` タイプの認可が設定されている場合、初期化中に `accessKey` と `secretKey` を指定して、発信者の AWS 認証情報を含めることができます。
```
require 'pet-sdk'
client = Pet::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50,
access_key_id: 'ACCESS_KEY',
secret_access_key: 'SECRET_KEY'
)
```
1. アプリで SDK を使用して API 呼び出しを行います。
**ヒント**
SDK のメソッド呼び出し規則に精通していない場合は、生成された SDK の `client.rb` フォルダの `lib` ファイルを確認できます。このフォルダには、サポートされている各 API メソッド呼び出しのドキュメントが含まれています。
サポートされているオペレーションを検出するには:
```
# to show supported operations:
puts client.operation_names
```
これにより、`GET /?a={.}&b={.}&op={.}`、`GET /{a}/{b}/{op}`、および `POST /` の API メソッドに対応する次のような表示になります。必要に応じて `{a:"…", b:"…", op:"…"}` 形式のペイロードを加えます。
```
[:get_api_root, :get_ab_op, :post_api_root]
```
`GET /?a=1&b=2&op=+`API メソッドを呼び出すには、以下の Ruby SDK メソッドを呼び出します。
```
resp = client.get_api_root({a:"1", b:"2", op:"+"})
```
`POST /` を使用して、`{a: "1", b: "2", "op": "+"}` API メソッドを呼び出すには、以下の Ruby SDK メソッドを呼び出します。
```
resp = client.post_api_root(input: {a:"1", b:"2", op:"+"})
```
`GET /1/2/+`API メソッドを呼び出すには、以下の Ruby SDK メソッドを呼び出します。
```
resp = client.get_ab_op({a:"1", b:"2", op:"+"})
```
SDK メソッド呼び出しが正常に終了すると次のレスポンスを返します。
```
resp : {
result: {
input: {
a: 1,
b: 2,
op: "+"
},
output: {
c: 3
}
}
}
```
# Objective-C または Swift で REST API 用に API Gateway で生成された iOS SDK を使用する
このチュートリアルでは、Objective-C または Swift アプリケーションにおいて、REST API の API Gateway で生成された iOS SDK を使用して基盤となる API を呼び出す方法について説明します。以下のトピックでは、[SimpleCalc API](simple-calc-lambda-api.md) を例として使います。
+ AWS Mobile SDK の必要なコンポーネントを Xcode プロジェクト内にインストールする方法
+ API のメソッドを呼び出す前に API クライアントオブジェクトを作成する方法
+ API クライアントオブジェクトで対応する SDK メソッドを介して API のメソッドを呼び出す方法
+ SDK の対応するモデルクラスを使用してメソッドの入力を準備し、その結果を解析する方法
**Topics**
+ [
## 生成された iOS SDK (Objective-C) を使用して API を呼び出す
](#how-to-use-sdk-ios-objc)
+ [
## 生成された iOS SDK (Swift) を使用して API を呼び出す
](#how-to-generate-sdk-ios-swift)
## 生成された iOS SDK (Objective-C) を使用して API を呼び出す
次の手順を開始する前に、Objective-C で iOS 用の「[API Gateway で REST API の SDK を生成する](how-to-generate-sdk.md)」のステップを実行し、生成された SDK の .zip ファイルをダウンロードする必要があります。
### API Gateway で生成された AWS Mobile SDK と iOS SDK を Objective-C プロジェクトでインストールする
次の手順では、SDK をインストールする方法を説明します。
**API Gateway で生成された iOS SDK を Objective-C でインストールして使用するには**
1. ダウンロード済みの API Gateway で生成された .zip ファイルのコンテンツを抽出します。[SimpleCalc API](simple-calc-lambda-api.md) を使用して、解凍した SDK フォルダの名前を **sdk\$1objc\$1simple\$1calc** などに変更することもできます。この SDK フォルダーには、`README.md` ファイルと `Podfile` ファイルが含まれています。`README.md` ファイルには、SDK をインストールして使用するための手順が記載されています。このチュートリアルでは、この手順について詳しく説明します。インストールでは、[CocoaPods](https://cocoapods.org) を使用して必要な API Gateway ライブラリとその他の依存する AWS Mobile SDK コンポーネントをインポートします。SDK をアプリケーションの XCode プロジェクト内にインポートするには、`Podfile` を更新する必要があります。解凍した SDK フォルダー内には、API の生成された SDK のソースコードを含む `generated-src` フォルダーもあります。
1. Xcode を起動し、新しい iOS Objective-C プロジェクトを作成します。プロジェクトのターゲットを書き留めておきます。それを `Podfile` に設定する必要があります。
![\[Xcode でターゲットを検索します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png)
1. CocoaPods を使用して AWS Mobile SDK for iOS を Xcode プロジェクト内にインポートするには、以下の操作を行います。
1. ターミナルウィンドウで次のコマンドを実行して、CocoaPods をインストールします。
```
sudo gem install cocoapods
pod setup
```
1. 抽出した SDK フォルダー内にある `Podfile` ファイルを、Xcode プロジェクトファイルがある同じディレクトリ内にコピーします。次のブロックのターゲット名を
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
次のようにプロジェクトのターゲット名に置き換えます。
```
target 'app_objc_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
Xcode プロジェクトに `Podfile` という名前のファイルが既に含まれている場合は、次のコード行を追加します。
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. ターミナルウィンドウを開いて、次のコマンドを実行します。
```
pod install
```
これにより、API Gateway コンポーネント とその他の依存する AWS Mobile SDK コンポーネントがインストールされます。
1. Xcode プロジェクトを閉じて `.xcworkspace` ファイルを開き、Xcode を再起動します。
1. 抽出した SDK の `.h` ディレクトリから、すべての `.m` ファイルと `generated-src` ファイルを Xcode プロジェクト内に追加します。
![\[.h ファイルと .m ファイルは generated-src にあります\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png)
AWS Mobile SDK for iOS Objective-C をプロジェクト内にインポートするために、明示的に AWS Mobile SDK をダウンロードするか、[Carthage](https://github.com/Carthage/Carthage#installing-carthage) を使用する場合は、*README.md* ファイルの手順に従ってください。この 2 つのオプションのうち、必ず 1 つのみを使用して AWS Mobile SDK をインポートしてください。
### API Gateway で生成された iOS SDK を使用して Objective-C オブジェクトで API メソッドを呼び出す
SDK の生成時に、メソッドの入力 (`Input`) と出力 (`Result`) を 2 つのモデルとする [SimpleCalc](simple-calc-lambda-api.md) API のプレフィックスとして `SIMPLE_CALC` を使用すると、結果の API クライアントクラスは `SIMPLE_CALCSimpleCalcClient` となり、対応するデータクラスはそれぞれ `SIMPLE_CALCInput` と `SIMPLE_CALCResult` になります。API のリクエストとレスポンスは、次のように SDK メソッドにマッピングされます。
+ 次の API リクエストは
```
GET /?a=...&b=...&op=...
```
次のような SDK メソッドになります。
```
(AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b
```
`AWSTask.result` モデルをメソッドのレスポンスに追加した場合、`SIMPLE_CALCResult` プロパティのタイプは `Result` です。それ以外の場合、プロパティは `NSDictionary` タイプになります。
+ 次の API リクエストは
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
次のような SDK メソッドになります。
```
(AWSTask *)rootPost:(SIMPLE_CALCInput *)body
```
+ 次の API リクエストは
```
GET /{a}/{b}/{op}
```
次のような SDK メソッドになります。
```
(AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op
```
次の手順では、Objective-C アプリケーションのソースコードで API メソッドを呼び出す方法を説明します。たとえば、`viewDidLoad` ファイルで `ViewController.m` デリゲートの一部として呼び出します。
**API Gateway で生成された iOS SDK を介して API を呼び出すには**
1. API クライアントクラスのヘッダーファイルをインポートして、API クライアントクラスをアプリケーションで呼び出せるようにします。
```
#import "SIMPLE_CALCSimpleCalc.h"
```
`#import` ステートメントにより、2 つのモデルクラスとして `SIMPLE_CALCInput.h` と `SIMPLE_CALCResult.h` もインポートされます。
1. API クライアントクラスをインスタンス化します。
```
SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient];
```
API で Amazon Cognito を使用するには、`defaultClient` メソッドを呼び出して API クライアントオブジェクトを作成する (前の例を参照) 前に、次に示すようにデフォルトの `AWSServiceManager` オブジェクトで `defaultServiceConfiguration` プロパティを設定します。
```
AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id];
AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds];
AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
```
1. `GET /?a=1&b=2&op=+` メソッドを呼び出して、`1+2` を実行します。
```
[[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField1.text = [self handleApiResponse:task];
return nil;
}];
```
ヘルパー関数の `handleApiResponse:task` は、結果を文字列としてフォーマットし、テキストフィールド (`_textField1`) に表示します。
```
- (NSString *)handleApiResponse:(AWSTask *)task {
if (task.error != nil) {
return [NSString stringWithFormat: @"Error: %@", task.error.description];
} else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) {
return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c];
}
return nil;
}
```
結果として `1 + 2 = 3` と表示されます。
1. ペイロードを渡す `POST /` を呼び出して、`1-2` を実行します。
```
SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init];
input.a = [NSNumber numberWithInt:1];
input.b = [NSNumber numberWithInt:2];
input.op = @"-";
[[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField2.text = [self handleApiResponse:task];
return nil;
}];
```
結果として `1 - 2 = -1` と表示されます。
1. `GET /{a}/{b}/{op}` を呼び出して、`1/2` を実行します。
```
[[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField3.text = [self handleApiResponse:task];
return nil;
}];
```
結果として `1 div 2 = 0.5` と表示されます。ここで `div` が `/` の代わりに使用されているのは、バックエンドの[シンプルな Lambda 関数](simple-calc-nodejs-lambda-function.md)では URL エンコードされたパス変数が処理されないためです。
## 生成された iOS SDK (Swift) を使用して API を呼び出す
次の手順を開始する前に、Swift で iOS 用の「[API Gateway で REST API の SDK を生成する](how-to-generate-sdk.md)」のステップを実行し、生成された SDK の .zip ファイルをダウンロードする必要があります。
**Topics**
+ [
### AWS Mobile SDK と API Gateway で生成された SDK を Swift プロジェクトでインストールする
](#use-sdk-ios-swift-install-sdk)
+ [
### API Gateway で生成された iOS SDK を介して Swift プロジェクトで API メソッドを呼び出す
](#use-sdk-ios-swift-call-api)
### AWS Mobile SDK と API Gateway で生成された SDK を Swift プロジェクトでインストールする
次の手順では、SDK をインストールする方法を説明します。
**API Gateway で生成された iOS SDK を Swift にインストールして使用するには**
1. ダウンロード済みの API Gateway で生成された .zip ファイルのコンテンツを抽出します。[SimpleCalc API](simple-calc-lambda-api.md) を使用して、解凍した SDK フォルダの名前を **sdk\$1swift\$1simple\$1calc** などに変更することもできます。この SDK フォルダーには、`README.md` ファイルと `Podfile` ファイルが含まれています。`README.md` ファイルには、SDK をインストールして使用するための手順が記載されています。このチュートリアルでは、この手順について詳しく説明します。インストールでは、[CocoaPods](https://cocoapods.org) を使用して AWS Mobile SDK の必要なコンポーネントをインポートします。SDK を Swift アプリケーションの XCode プロジェクト内にインポートするには、`Podfile` を更新する必要があります。解凍した SDK フォルダー内には、API の生成された SDK のソースコードを含む `generated-src` フォルダーもあります。
1. Xcode を起動し、新しい iOS Swift プロジェクトを作成します。プロジェクトのターゲットを書き留めておきます。それを `Podfile` に設定する必要があります。
![\[Xcode でターゲットを検索します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png)
1. CocoaPods を使用して AWS Mobile SDK の必要なコンポーネントを Xcode プロジェクト内にインポートするには、以下の操作を実行します。
1. ターミナルウィンドウで次のコマンドを実行して CocoaPods をインストールします (まだインストールしていない場合)。
```
sudo gem install cocoapods
pod setup
```
1. 抽出した SDK フォルダー内にある `Podfile` ファイルを、Xcode プロジェクトファイルがある同じディレクトリ内にコピーします。次のブロックのターゲット名を
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
次のようにプロジェクトのターゲット名に置き換えます。
```
target 'app_swift_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
Xcode プロジェクト内の `Podfile` に正しいターゲットが既に設定されている場合は、次のコード行を `do ... end` ループに追加するだけで済みます。
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. ターミナルウィンドウを開き、アプリケーションのディレクトリで次のコマンドを実行します。
```
pod install
```
これにより、API Gateway コンポーネント とその他の依存する AWS Mobile SDK コンポーネントがアプリケーションのプロジェクト内にインストールされます。
1. Xcode プロジェクトを閉じて `*.xcworkspace` ファイルを開き、Xcode を再起動します。
1. 抽出した `.h` ディレクトリから、SDK のヘッダーファイル (`.swift`) と Swift ソースコードファイル (`generated-src`) のすべてを Xcode プロジェクトに追加します。
![\[.h ファイルと .swift ファイルは generated-src にあります。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png)
1. Swift コードプロジェクトから AWS Mobile SDK の Objective-C ライブラリを呼び出せるようにするには、Xcode プロジェクト設定の [`Bridging_Header.h`Swift Compiler - General**] オプションの [**Objective-C Bridging Header**] プロパティで ** ファイルのパスを設定します。
![\[[Swift Compiler - General] で Bridging_Header.h ファイルパスを設定します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png)
**ヒント**
Xcode の検索ボックスに「**bridging**」と入力し、[**Objective-C Bridging Header**] プロパティを見つけます。
1. Xcode プロジェクトを構築し、それが適切に設定されていることを確認してから先に進みます。Xcode で使用している Swift のバージョンが AWS Mobile SDK でサポートされているものより新しい場合は、Swift コンパイラエラーが発生します。この場合は、[**Swift Compiler - Version (Swift コンパイラ - バージョン)**] 設定の [**Use Legacy Swift Language Version**] プロパティを [**Yes**] に設定します。
![\[[Legacy Swift Language Version] プロパティを [Yes] に設定します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png)
Swift で の AWS Mobile SDK for iOS をプロジェクト内にインポートするために、明示的に AWS Mobile SDK をダウンロードするか、[Carthage](https://github.com/Carthage/Carthage#installing-carthage) を使用する場合は、SDK パッケージに含まれている `README.md` ファイルに記載されている手順に従います。この 2 つのオプションのうち、必ず 1 つのみを使用して AWS Mobile SDK をインポートしてください。
### API Gateway で生成された iOS SDK を介して Swift プロジェクトで API メソッドを呼び出す
SDK の生成時に、API のリクエストとレスポンスの入力 (`Input`) と出力 (`Result`) を記述する 2 つのモデルがあるこの [SimpleCalc API](simple-calc-lambda-api.md) のプレフィックスとして `SIMPLE_CALC` を使用すると、結果の API クライアントクラスは `SIMPLE_CALCSimpleCalcClient` となり、対応するデータクラスはそれぞれ `SIMPLE_CALCInput` と `SIMPLE_CALCResult` になります。API のリクエストとレスポンスは、次のように SDK メソッドにマッピングされます。
+ 次の API リクエストは
```
GET /?a=...&b=...&op=...
```
次のような SDK メソッドになります。
```
public func rootGet(op: String?, a: String?, b: String?) -> AWSTask
```
`AWSTask.result` モデルをメソッドのレスポンスに追加した場合、`SIMPLE_CALCResult` プロパティのタイプは `Result` です。それ以外の場合は、`NSDictionary` タイプになります。
+ 次の API リクエストは
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
次のような SDK メソッドになります。
```
public func rootPost(body: SIMPLE_CALCInput) -> AWSTask
```
+ 次の API リクエストは
```
GET /{a}/{b}/{op}
```
次のような SDK メソッドになります。
```
public func aBOpGet(a: String, b: String, op: String) -> AWSTask
```
次の手順では、Swift アプリケーションのソースコードで API メソッドを呼び出す方法を示します。たとえば、`viewDidLoad()` ファイルで `ViewController.m` デリゲートの一部として呼び出します。
**API Gateway で生成された iOS SDK を介して API を呼び出すには**
1. API クライアントクラスをインスタンス化します。
```
let client = SIMPLE_CALCSimpleCalcClient.default()
```
API で Amazon Cognito を使用するには、`default` メソッド (前出) を取得する前にデフォルトの AWS のサービス設定 (後出) を設定します。
```
let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id")
let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider)
AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration
```
1. `GET /?a=1&b=2&op=+` メソッドを呼び出して、`1+2` を実行します。
```
client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
上のヘルパー関数 `self.showResult(task)` は結果またはエラーをコンソールに表示します。次に例を示します。
```
func showResult(task: AWSTask) {
if let error = task.error {
print("Error: \(error)")
} else if let result = task.result {
if result is SIMPLE_CALCResult {
let res = result as! SIMPLE_CALCResult
print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!))
} else if result is NSDictionary {
let res = result as! NSDictionary
print("NSDictionary: \(res)")
}
}
}
```
本稼働アプリケーションでは、結果またはエラーをテキストフィールドに表示できます。結果として `1 + 2 = 3` と表示されます。
1. ペイロードを渡す `POST /` を呼び出して、`1-2` を実行します。
```
let body = SIMPLE_CALCInput()
body.a=1
body.b=2
body.op="-"
client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
結果として `1 - 2 = -1` と表示されます。
1. `GET /{a}/{b}/{op}` を呼び出して、`1/2` を実行します。
```
client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
結果として `1 div 2 = 0.5` と表示されます。ここで `div` が `/` の代わりに使用されているのは、バックエンドの[シンプルな Lambda 関数](simple-calc-nodejs-lambda-function.md)では URL エンコードされたパス変数が処理されないためです。
# API Gateway で OpenAPI を使用して REST API を開発する
API Gateway を使用して、REST API を外部定義ファイルから API Gateway にインポートできます。現在、API Gateway は [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) および [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) 定義ファイルをサポートしています。この例外が「[Amazon API Gateway の REST API に関する重要な注意点](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis)」に記載されています。新しい定義で上書きして API を更新したり、既存の API と定義をマージしたりできます。リクエスト URL で `mode` クエリパラメータを使用して、オプションを指定します。
API Gateway コンソールからサンプル API 機能を使用するチュートリアルについては、「[チュートリアル: サンプルをインポートして REST API を作成する](api-gateway-create-api-from-example.md)」を参照してください。
**Topics**
+ [
# エッジ最適化 API を API Gateway にインポートする
](import-edge-optimized-api.md)
+ [
# リージョン API を API Gateway にインポートする
](import-export-api-endpoints.md)
+ [
# OpenAPI ファイルをインポートして既存の API 定義を更新する
](api-gateway-import-api-update.md)
+ [
# OpenAPI`basePath` プロパティを設定
](api-gateway-import-api-basePath.md)
+ [
# OpenAPI インポート用の AWS 変数
](import-api-aws-variables.md)
+ [
# API Gateway への API のインポートによるエラーと警告
](api-gateway-import-api-errors-warnings.md)
+ [
# API Gateway から REST API をエクスポートする
](api-gateway-export-api.md)
# エッジ最適化 API を API Gateway にインポートする
API OpenAPI 定義ファイルをインポートして、新しいエッジ最適化 API を作成できます。そのためには、OpenAPI ファイルに加えて `EDGE` エンドポイントタイプをインポートオペレーションへの入力として指定します。これは、API Gateway コンソール、AWS CLI、または AWS SDK を使用して行うこともできます。
API Gateway コンソールからサンプル API 機能を使用するチュートリアルについては、「[チュートリアル: サンプルをインポートして REST API を作成する](api-gateway-create-api-from-example.md)」を参照してください。
**Topics**
+ [
## API Gateway コンソールを使用してエッジ最適化 API をインポートする
](#import-edge-optimized-api-with-console)
+ [
## AWS CLI を使用してエッジ最適化 API をインポートする
](#import-edge-optimized-api-with-awscli)
## API Gateway コンソールを使用してエッジ最適化 API をインポートする
API Gateway コンソールを使用してエッジ最適化 API をインポートするには、次の操作を行います。
1. API Gateway コンソール ([https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)) にサインインします。
1. [**API の作成**] を選択します。
1. [**REST API**] で、[**インポート**] を選択します。
1. API OpenAPI 定義をコピーしてコードエディタに貼り付けるか、**[ファイルの選択]** を選択してローカルドライブから OpenAPI ファイルを読み込みます。
1. **[エンドポイントタイプ]** で、**[エッジ最適化]** を選択します。
1. **[API の作成]** を選択して OpenAPI 定義のインポートを開始します。
## AWS CLI を使用してエッジ最適化 API をインポートする
次の [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) コマンドは、OpenAPI 定義ファイルから API をインポートして、新しいエッジ最適化 API を作成します。
```
aws apigateway import-rest-api \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
または、`endpointConfigurationTypes` クエリ文字列パラメータを `EDGE` に明示的に指定します。
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=EDGE \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# リージョン API を API Gateway にインポートする
API のインポート時、API のリージョンのエンドポイント設定を選択できます。API Gateway コンソール、AWS CLI、または AWS SDK を使用できます。
API のエクスポート時、エクスポートされた API 定義に API エンドポイント設定は含まれません。
API Gateway コンソールからサンプル API 機能を使用するチュートリアルについては、「[チュートリアル: サンプルをインポートして REST API を作成する](api-gateway-create-api-from-example.md)」を参照してください。
**Topics**
+ [
## API Gateway コンソールを使用してリージョン API をインポートする
](#import-regional-api-with-console)
+ [
## AWS CLI を使用してリージョン API をインポートする
](#import-regional-api-with-awscli)
## API Gateway コンソールを使用してリージョン API をインポートする
API Gateway コンソールを使用してリージョンのエンドポイントの API をインポートするには、以下の手順を実行します。
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. [**API の作成**] を選択します。
1. [**REST API**] で、[**インポート**] を選択します。
1. API OpenAPI 定義をコピーしてコードエディタに貼り付けるか、**[ファイルの選択]** を選択してローカルドライブから OpenAPI ファイルを読み込みます。
1. **[API エンドポイントタイプ]** で、**[リージョン別]** を選択します。
1. **[API の作成]** を選択して OpenAPI 定義のインポートを開始します。
## AWS CLI を使用してリージョン API をインポートする
次の [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) コマンドは、OpenAPI 定義ファイルをインポートし、エンドポイントタイプをリージョン別に設定します。
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=REGIONAL \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# OpenAPI ファイルをインポートして既存の API 定義を更新する
API 定義をインポートできるのは、エンドポイント設定、ステージおよびステージ変数、または API キーへの参照を変更せずに既存の API を更新する場合のみです。
インポートから更新への操作は、マージまたは上書きという 2 つのモードで行うことができます。
API (`A`) が別の API (`B`) にマージされると、作成された API では、2 つの API で矛盾する定義が共有されていない限り、`A` と `B` の両方の定義が保持されます。矛盾が発生した場合、マージする API (`A`) のメソッド定義によってマージ先の API (`B`) の対応するメソッド定義がオーバーライドされます。たとえば、`B` が `200` および `206` レスポンスを返す次のメソッドを宣言しているとします。
```
GET /a
POST /a
```
`A` は `200` および `400` レスポンスを返す次のメソッドを宣言しています。
```
GET /a
```
`A` が `B` にマージされると、作成される API は次のメソッドを生成します。
```
GET /a
```
`200` レスポンスと `400` レスポンスを返すメソッド。
```
POST /a
```
`200` レスポンスと `206` レスポンスを返すメソッド。
API のマージは、外部の API 定義を複数の小さな部分に分解し、それらの部分の変更を一度に 1 つのみ適用する場合に役立ちます。たとえば、複数のチームが API のさまざまな部分を担当し、異なるレートで変更を可能にする場合です。このモードでは、インポートされた定義で明確に定義されていない既存の API の項目はそのまま残されます。
API (`A`) によって別の API (`B`) がオーバーライドされ、作成される API には API (`A`) の定義が採用されます。API の上書きは、外部の API 定義に、API の完全な定義が含まれているときに役立ちます。このモードでは、インポートされた定義で明確に定義されていない既存の API の項目は削除されます。
API をマージするには、`PUT` リクエストを `https://apigateway..amazonaws.com/restapis/?mode=merge` に送信します。`restapi_id` パスのパラメータ値は、指定された API 定義のマージ先となる API を示します。
次のコードスニペットは、指定された API がすでに API Gateway にあり、JSON の OpenAPI API 定義をペイロードとしてマージする `PUT` リクエストの例を示しています。
```
PUT /restapis/?mode=merge
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
更新オペレーションのマージでは、2 つの完全な API 定義を使用し、それらをマージします。小さい増分変更の場合は、[リソースの更新](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)オペレーションを使用できます。
API をオーバーライドするには、`PUT` リクエストを `https://apigateway..amazonaws.com/restapis/?mode=overwrite` に送信します。`restapi_id` パスパラメータは、指定された API 定義で上書きされる API を示します。
次のコードスニペットは、JSON 形式の OpenAPI 定義のペイロードでリクエストを上書きする例を示しています。
```
PUT /restapis/?mode=overwrite
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
`mode` クエリパラメータを指定しないと、マージが想定されます。
**注記**
`PUT` オペレーションはべき等ですが、アトミックではありません。つまり、処理中にシステムエラーが発生した場合、API は不正な状態になる可能性があります。ただし、オペレーションを正常に繰り返すと、API は最初のオペレーションが成功した場合と同じ最終状態になります。
# OpenAPI`basePath` プロパティを設定
[OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) では、`basePath` プロパティを使用して、`paths` プロパティに定義された各パスに先行する 1 つ以上のパス部分を提供できます。API Gateway にはリソースのパスを表現する複数の方法があるため、API のインポート機能には、インポート中に `basePath` プロパティを解釈するための次のオプションが用意されています。ignore、prepend、および split です。
「[https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/)」では、`basePath` は、最上位のプロパティではありません。代わりに、API Gateway は規則として[サーバー変数](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject)を使用します。API のインポート機能には、インポート中に基本パスを解釈するための同じオプションが用意されています。基本パスは次のように識別されます。
+ API に `basePath` 変数が含まれていない場合、API のインポート機能は `server.url` 文字列を確認して、`"/"` 以外のパスが含まれているかどうかを確認します。含まれている場合は、そのパスが基本パスとして使用されます。
+ API に含まれる `basePath` 変数が 1 つだけの場合、API のインポート機能は `server.url` で参照されていなくても、それを基本パスとして使用します。
+ API に複数の `basePath` 変数が含まれている場合、API のインポート機能は最初の変数のみを基本パスとして使用します。
## Ignore (無視)
OpenAPI ファイルの `basePath` の値が `/a/b/c` で、`paths` プロパティに `/e` および `/f` が含まれる場合に、次の `POST` または `PUT` リクエストがあるとします。
```
POST /restapis?mode=import&basepath=ignore
```
```
PUT /restapis/api_id?basepath=ignore
```
この場合、API で次のリソースが発生します。
+ `/`
+ `/e`
+ `/f`
その効果として、`basePath` を、これが存在しなかったかのように扱い、宣言された API のすべてのリソースは、ホストに対して相対的に提供されます。これを使用できるのは、たとえば、*基本パス*を含まない API マッピングや、本番ステージを参照する*ステージ*値を持つカスタムドメイン名がある場合です。
**注記**
API Gateway は、定義ファイルに明示的に宣言されていない場合でも、自動的にルートリソースを作成します。
指定しない場合、`basePath` はデフォルトで `ignore` を受け取ります。
## Prepend
OpenAPI ファイルの `basePath` の値が `/a/b/c` で、`paths` プロパティに `/e` および `/f` が含まれる場合に、次の `POST` または `PUT` リクエストがあるとします。
```
POST /restapis?mode=import&basepath=prepend
```
```
PUT /restapis/api_id?basepath=prepend
```
この場合、API で次のリソースが発生します。
+ `/`
+ `/a`
+ `/a/b`
+ `/a/b/c`
+ `/a/b/c/e`
+ `/a/b/c/f`
その効果として、(メソッドなしで) 追加のリソースとして `basePath` を処理し、宣言されたリソースセットに追加します。これを使用できるのは、たとえば、さまざまなチームが API パートの異なる部分を担当し、`basePath` が各チームの API 部分のパスの場所を参照できる場合です。
**注記**
API Gateway は、定義に明示的に宣言されていない場合でも、自動的に中間リソースを作成します。
## Split
OpenAPI ファイルの `basePath` の値が `/a/b/c` で、`paths` プロパティに `/e` および `/f` が含まれる場合に、次の `POST` または `PUT` リクエストがあるとします。
```
POST /restapis?mode=import&basepath=split
```
```
PUT /restapis/api_id?basepath=split
```
この場合、API で次のリソースが発生します。
+ `/`
+ `/b`
+ `/b/c`
+ `/b/c/e`
+ `/b/c/f`
その効果として、最上位のパス部分 `/a` を、各リソースのパスの先頭として扱い、API 内で (メソッドなしで) 追加のリソースを作成します。これを使用できるのは、たとえば、`a` が、API の一部として公開するステージ名である場合です。
# OpenAPI インポート用の AWS 変数
OpenAPI 定義では、次の AWS 変数を使用できます。API Gateway は、API のインポート時に変数を解決します。変数を指定するには、`${variable-name}` を使用します。次の表は、使用可能な AWS 変数について説明しています。
| 変数名 | 説明 |
| --- | --- |
| AWS::AccountId | API をインポートする AWS アカウント ID。例: 123456789012。 |
| AWS::Partition | API のインポート先の AWS パーティション。標準の AWS リージョンの場合、パーティションは aws です。 |
| AWS::Region | API のインポート先の AWS リージョン。例: us-east-2。 |
## AWS 変数の例
次の例では、AWS 変数を使用して統合用の AWS Lambda 関数を指定します。
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "tasks-api"
version: "v1.0"
paths:
/:
get:
summary: List tasks
description: Returns a list of tasks
responses:
200:
description: "OK"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Task"
500:
description: "Internal Server Error"
content: {}
x-amazon-apigateway-integration:
uri:
arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
httpMethod: "POST"
contentHandling: "CONVERT_TO_TEXT"
type: "aws_proxy"
components:
schemas:
Task:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
```
------
# API Gateway への API のインポートによるエラーと警告
外部定義ファイルを API Gateway にインポートすると、API Gateway で警告やエラーが発生することがあります。以下のセクションでは、インポート中に発生する可能性のあるエラーと警告について説明します。
## インポート中のエラー
インポート中に、無効な OpenAPI ドキュメントなど、大きな問題に対してエラーが生成される場合があります。エラーは、失敗のレスポンスの例外 (例: `BadRequestException`) として返されます。エラーが発生した場合、新しい API 定義は破棄され、既存の API は変更されません。
## インポート中の警告
インポート中に、モデル参照の不足など、小規模な問題に対して警告が生成される場合があります。警告が発生した場合、リクエスト URL に `failonwarnings=false` クエリ式が追加されている場合、オペレーションは続行します。それ以外の場合、更新はロールバックされます。デフォルトで、`failonwarnings` は `false` に設定されています。このような場合、警告は [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースのフィールドとして返されます。それ以外の場合、警告は例外のメッセージとして返されます。
# API Gateway から REST API をエクスポートする
API Gateway で REST API を作成および設定したら、API Gateway コンソールなどから API Gateway Export API (Amazon API Gateway Control Service の一部です) を使用して、API を OpenAPI ファイルにエクスポートできます。API Gateway Export API を使用するには、API リクエストに署名する必要があります。リクエストの署名の詳細については、「IAM ユーザーガイド」の「[AWS API リクエストの署名](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)」を参照してください。**エクスポートされた OpenAPI 定義ファイルに、API Gateway 統合の拡張機能と、[Postman](https://www.postman.com) 拡張機能を含めるオプションがあります。
**注記**
AWS CLI を使用して API をエクスポートする場合、次の例に示すように extensions パラメータを必ず含めて、`x-amazon-apigateway-request-validator` 拡張子が含まれるようにします。
```
aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json
```
ペイロードが `application/json` 型でない場合、API をエクスポートすることはできません。エクスポートを試みると、JSON 本文モデルが見つからないことを示すエラーレスポンスが返されます。
## REST API をエクスポートするリクエスト
Export API を使用すると、GET リクエストを送信し、URL パスの一部としてエクスポートされる API を指定することにより、既存の REST API をエクスポートします。リクエストの URL は次の形式です。
------
#### [ OpenAPI 3.0 ]
```
https:///restapis//stages//exports/oas30
```
------
#### [ OpenAPI 2.0 ]
```
https:///restapis//stages//exports/swagger
```
------
`extensions` クエリ文字列を追加して、(値 `integration` を使用) API Gateway 拡張を含めるか、(値 `postman` を使用) Postman 拡張を含めるかを指定できます。
さらに、`Accept` ヘッダーを `application/json` または `application/yaml` に設定して、それぞれ JSON 形式または YAML 形式で API 定義の出力を受け取ることができます。
API Gateway Export API を使用して GET リクエストを送信する詳細については、「[GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html)」を参照してください。
**注記**
API でモデルを定義する場合、モデルをエクスポートする API Gateway の "application/json" のコンテンツタイプである必要があります。それ以外の場合、API Gateway は「Only found non-JSON body models for ...」というエラーメッセージとともに例外をスローします。
モデルはプロパティを含むか、特定の JSONSchema 型として定義される必要があります。
## REST API OpenAPI 定義を JSON でダウンロードする
OpenAPI 定義を JSON 形式にして REST API をエクスポートおよびダウンロードするには、以下のようにします。
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/json
```
------
ここで、`` はたとえば `us-east-1` にできます。API Gateway を利用できるすべてのリージョンについては、「[リージョンとエンドポイント](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region)」を参照してください。
## REST API OpenAPI 定義を YAML でダウンロードする
OpenAPI 定義を YAML 形式にして REST API をエクスポートおよびダウンロードするには、以下のようにします。
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## Postman 拡張機能を使用して REST API OpenAPI 定義を JSON でダウンロードする
Postman を使用して OpenAPI 定義を JSON 形式にして REST API をエクスポートおよびダウンロードするには、以下のようにします。
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
## API Gateway 統合を使用して REST API OpenAPI 定義ファイルを YAML でダウンロードする
OpenAPI 定義を YAML 形式にして API Gateway 統合を使用して REST API をエクスポートおよびダウンロードするには、以下のようにします。
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## API Gateway コンソールを使用して REST API をエクスポートする
[REST API をステージにデプロイ](set-up-deployments.md#create-deployment)したら、次に API Gateway コンソールを使用してステージ内の API を OpenAPI ファイルにエクスポートすることができます。
API Gateway コンソールの **[ステージ]** ペインで、**[ステージアクション]**、**[エクスポート]** を選択します。
![\[API Gateway コンソールを使用して REST API をエクスポートする\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/export-new-console.png)
**[API 仕様タイプ]**、**[フォーマット]**、**[拡張機能]** を指定して API の OpenAPI 定義をダウンロードします。