# API Gateway で HTTP API を開発する
このセクションでは、API Gateway API の開発中に必要な API Gateway 機能について詳しく説明します。
API Gateway API の開発中、API の特性をいくつか決定することになります。これらの特性は API のユースケースによって異なります。たとえば、API を特定のクライアントのみが呼び出せるようにしたり、すべてのユーザーが利用できるようにしたりできます。API コールで Lambda 関数の実行、データベースクエリの作成やアプリケーションの呼び出しができます。
**Topics**
+ [HTTP API を作成する](#http-api-examples)
+ [API Gateway で HTTP API のルートを作成する](http-api-develop-routes.md)
+ [API Gateway の HTTP API の IP アドレスタイプ](http-api-ip-address-type.md)
+ [API Gateway で HTTP API へのアクセスを制御および管理する](http-api-access-control.md)
+ [API Gateway で HTTP API の統合を作成する](http-api-develop-integrations.md)
+ [API Gateway で HTTP API の CORS を設定する](http-api-cors.md)
+ [API Gateway で HTTP API の API リクエストとレスポンスを変換する](http-api-parameter-mapping.md)
+ [API Gateway で HTTP API の OpenAPI 定義を使用する](http-api-open-api.md)
## HTTP API を作成する
機能する API を作成するには、少なくとも 1 つのルート、統合、ステージ、およびデプロイが必要です。
次の例は、AWS Lambda または HTTP 統合、ルート、および変更を自動的にデプロイするように設定されたデフォルトステージを持つ API を作成する方法を示しています。
このガイドは、ユーザーが既に API Gateway と Lambda に関する知識を持っていることを前提としています。より詳細なガイドについては、「[API Gateway の使用を開始する](getting-started.md)」を参照してください。
**Topics**
+ [を使用して HTTP API を作成するAWS マネジメントコンソール](#apigateway-http-api-create.console)
+ [AWS CLI を使用して HTTP API を作成する](#http-api-examples.cli.quick-create)
### を使用して HTTP API を作成するAWS マネジメントコンソール
1. [API Gateway コンソール](https://console.aws.amazon.com/apigateway)を開きます。
1. [**Create API**] を選択します。
1. [**HTTP API**] で、[**Build (ビルド)**] を選択します。
1. [**統合の追加**] を選択し、AWS Lambda 関数を選択するか、HTTP エンドポイントを入力します。
1. [**Name (名前)**] に、API の名前を指定します。
1. [**Review and create**] を選択します。
1. [**Create**] を選択します。
これで、API を呼び出す準備ができました。API をテストするには、呼び出し URL をブラウザに入力するか、Curl を使用します。
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
### AWS CLI を使用して HTTP API を作成する
クイック作成を使用して、Lambda または HTTP 統合、デフォルトのキャッチオールルート、変更を自動的にデプロイするように設定されたデフォルトステージを持つ API を作成できます。次の [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) コマンドは、クイック作成を使用して、バックエンドの Lambda 関数と統合する API を作成します。
**注記**
Lambda 統合を呼び出すには、必要なアクセス許可が API Gateway に必要です。リソースベースのポリシーまたは IAM ロールを使用して、Lambda 関数を呼び出す API Gateway のアクセス許可を付与できます。詳細については、[AWS Lambda デベロッパーガイド](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html)の「*AWS Lambda のアクセス許可*」を参照してください。
**Example**
```
aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-east-2:123456789012:function:function-name
```
これで、API を呼び出す準備ができました。API をテストするには、呼び出し URL をブラウザに入力するか、Curl を使用します。
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
# API Gateway で HTTP API のルートを作成する
ルートは、直接の受信 API リクエストをバックエンドリソースにルーティングします。ルートは、HTTP メソッドとリソースパスという 2 つの部分で構成されます (例: `GET /pets`)。ルートに特定の HTTP メソッドを定義できます。または、`ANY` メソッドを使用して、リソースに対して定義していないすべてのメソッドを一致させることができます。他のどのルートとも一致しないリクエストのキャッチオールとして機能する `$default` ルートを作成できます。
**注記**
API Gateway は、URL エンコードされたリクエストパラメータをデコードしてからバックエンド統合に渡します。
## パス変数の操作
HTTP API ルートでパス変数を使用できます。
たとえば、`GET /pets/{petID}` ルートは、クライアントが `GET` に送信する `https://api-id.execute-api.us-east-2.amazonaws.com/pets/6` リクエストをキャッチします。
*greedy パス変数*は、ルートのすべての子リソースをキャッチします。greedy パス変数を作成するには、変数名に `+` を追加します (例: `{proxy+}`)。greedy パス変数は、リソースパスの末尾にある必要があります。
## クエリ文字列パラメータの操作
デフォルトでは、API Gateway は HTTP API へのリクエストにクエリ文字列パラメータが含まれている場合、バックエンド統合にクエリ文字列パラメータを送信します。
たとえば、クライアントが `https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog` にリクエストを送信すると、クエリ文字列パラメータ `?id=4&type=dog` が統合に送信されます。
## `$default` ルートの操作
`$default` ルートは、API 内の他のルートと明示的に一致しないリクエストをキャッチします。
`$default` ルートがリクエストを受信すると、API Gateway は完全なリクエストパスを統合に送信します。たとえば、`$default` ルートのみを持つ API を作成し、`ANY` メソッドで `https://petstore-demo-endpoint.execute-api.com` HTTP エンドポイントと統合できます。`https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout` にリクエストを送信すると、API Gateway は `https://petstore-demo-endpoint.execute-api.com/store/checkout` にリクエストを送信します。
HTTP 統合の詳細については、「[HTTP API の HTTP プロキシ統合を作成する](http-api-develop-integrations-http.md)」を参照してください。
## API リクエストのルーティング
クライアントが API リクエストを送信すると、API Gateway はまずリクエストをルーティングする[ステージ](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-stages.html)を決定します。リクエストがステージと明示的に一致する場合、API Gateway はそのステージにリクエストを送信します。リクエストに完全に一致するステージがない場合、API Gateway はリクエストを `$default` ステージに送信します。`$default` ステージがない場合、API は `{"message":"Not Found"}` を返し、CloudWatch ログを生成しません。
ステージを選択した後、API Gateway はルートを選択します。API Gateway は、次の優先順位を使用して、最も具体的な一致を持つルートを選択します。
1. ルートとメソッドの完全一致。
1. greedy パス変数 (`{proxy+}`)を持つルートとメソッドを一致させます。
1. `$default` ルート。
リクエストに一致するルートがない場合、API Gateway は `{"message":"Not Found"}` をクライアントに返します。
たとえば、`$default` ステージがある API と、次のルート例を考えてみます。
1. `GET /pets/dog/1`
1. `GET /pets/dog/{id}`
1. `GET /pets/{proxy+}`
1. `ANY /{proxy+}`
1. `$default`
次の表は、API Gateway がリクエストをルート例にルーティングする方法をまとめたものです。
| リクエスト | 選択されたルート | 説明 |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1` | `GET /pets/dog/1` | リクエストはこの静的ルートに完全に一致します。 |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2` | `GET /pets/dog/{id}` | リクエストはこのルートに完全に一致します。 |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1` | `GET /pets/{proxy+}` | リクエストがルートに完全に一致していません。`GET` メソッドと greedy パス変数を持つルートは、このリクエストをキャッチします。 |
| `POST https://api-id.execute-api.region.amazonaws.com/test/5` | `ANY /{proxy+}` | `ANY` メソッドは、ルートに対して定義していないすべてのメソッドに一致します。greedy パス変数を持つルートの優先順位は、`$default` ルートよりも高くなります。 |
# API Gateway の HTTP API の IP アドレスタイプ
API を作成する際、API を呼び出すことができる IP アドレスのタイプを指定します。IPv4 を選択して IPv4 アドレスを解決し、API を呼び出すことができます。デュアルスタックを選択すると、API の呼び出しを IPv4 アドレスと IPv6 アドレスの両方に許可できます。IP アドレスタイプをデュアルスタックに設定して、IP スペースの枯渇の問題を軽減したり、セキュリティ体制を強化したりすることもできます。デュアルスタック IP アドレスタイプの利点の詳細については、「[IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)」を参照してください。
## IP アドレスタイプに関する考慮事項
以下の考慮事項は、IP アドレスタイプの使用に影響する可能性があります。
+ HTTP API のデフォルトの IP アドレスタイプは IPv4 です。
+ 既存の API の IP アドレスタイプを IPv4 からデュアルスタックに変更する場合、API へのアクセスを制御するポリシーが IPv6 呼び出しを考慮して更新されていることを確認します。IP アドレスタイプを変更すると、変更はすぐに有効になります。
+ API は、その API とは異なる IP アドレスタイプのカスタムドメイン名にマッピングできます。デフォルトの API エンドポイントを無効にすると、発信者が API を呼び出す方法が影響を受ける可能性があります。
## HTTP API の IP アドレスタイプを変更する
IP アドレスタイプは、API の設定を更新して、変更できます。API の設定は、AWS マネジメントコンソール、AWS CLI、CloudFormation、または AWS SDK を使用して、更新できます。API の IP アドレスタイプを変更した場合、API を再デプロイしなくても変更が有効になります。
------
#### [ AWS マネジメントコンソール ]
**HTTP API の IP アドレスタイプを変更するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. HTTP API を選択します。
1. **[API の設定]** で、**[編集]** を選択します。
1. [IP アドレスタイプ] で、**[IPv4]** または **[デュアルスタック]** を選択します。
1. **[保存]** を選択します。
API の設定の変更はすぐに有効になります。
------
#### [ AWS CLI ]
次の [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) コマンドは、IP アドレスタイプがデュアルスタックになるように API を更新します。
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
出力は次のようになります。
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-HTTP-API",
"ProtocolType": "HTTP",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# API Gateway で HTTP API へのアクセスを制御および管理する
API Gateway は HTTP API へのアクセスを制御し管理する複数のメカニズムをサポートしています。
+ **Lambda オーソライザー**は、Lambda 関数を使用して API へのアクセスを制御します。詳細については、「[AWS Lambda オーソライザーを使用して HTTP API へのアクセスを制御する](http-api-lambda-authorizer.md)」を参照してください。
+ **JWT オーソライザー**は、JSON ウェブトークンを使用して API へのアクセスをコントロールします。詳細については、「[API Gateway の JWT オーソライザーを使用して HTTP API へのアクセスを制御する](http-api-jwt-authorizer.md)」を参照してください。
+ **標準の AWS IAM ロールとポリシー**は、柔軟で堅牢なアクセス制御を提供します。IAM ロールとポリシーを使用して、どのユーザーが API を呼び出すことができるだけでなく、作成および管理することもできるかをコントロールできます。詳細については、「[API Gateway の IAM 認可を使用して HTTP API へのアクセスを制御する](http-api-access-control-iam.md)」を参照してください。
セキュリティ体制を向上させるには、HTTP API のすべてのルートにオーソライザーを設定することをお勧めします。これは、さまざまなコンプライアンスフレームワークに準拠するために必要になる場合があります。詳細については、*AWS Security Hub ユーザーガイド*の「[Amazon API Gateway のコントロール](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)」を参照してください。
# AWS Lambda オーソライザーを使用して HTTP API へのアクセスを制御する
Lambda オーソライザーを使用し、Lambda 関数を使用して HTTP API へのアクセスを制御します。次に、クライアントが API を呼び出すと、API Gateway が Lambda 関数を呼び出します。API Gateway は、Lambda 関数からのレスポンスを使用して、クライアントが API にアクセスできるかどうかを判断します。
## ペイロード形式バージョン
オーソライザーの’ペイロード形式バージョンでは、API Gateway が Lambda 認証に送信するデータの形式と、API Gateway が Lambda からのレスポンスをどのように解釈するかを指定します。ペイロード形式バージョンを指定しない場合、AWS マネジメントコンソール はデフォルトで最新バージョンを使用します。AWS CLI、CloudFormation、または SDK を使用して Lambda オーソライザーを作成する場合は、`authorizerPayloadFormatVersion` を指定する必要があります。サポートされる値は `1.0` と `2.0` です。
REST APIとの互換性が必要な場合は、バージョン `1.0` を使用してください。
次の例は、各ペイロード形式バージョンの構造を示しています。
------
#### [ 2.0 ]
```
{
"version": "2.0",
"type": "REQUEST",
"routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": ["user1", "123"],
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": ["cookie1", "cookie2"],
"headers": {
"header1": "value1",
"header2": "value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "IP",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"pathParameters": { "parameter1": "value1" },
"stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" }
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": "user1,123",
"authorizationToken": "user1,123",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"HeaderAuth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "..."
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "...",
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "abcdef123"
}
}
```
------
## Lambda オーソライザーのレスポンス形式
ペイロード形式バージョンによって、Lambda 関数から返す必要のあるレスポンスの構造も決まります。
### Lambda 関数レスポンス形式 1.0
`1.0` 形式バージョンを選択した場合、Lambda オーソライザーは API ルートへのアクセスを許可または拒否する IAM ポリシーを返す必要があります。ポリシーでは、標準の IAM ポリシー構文を使用できます。IAM ポリシーの例については、「[API を呼び出すためのアクセスの制御](api-gateway-control-access-using-iam-policies-to-invoke-api.md)」を参照してください。`$context.authorizer.property` を使用して、コンテキストプロパティを Lambda 統合に渡したり、ログにアクセスしたりできます。`context` オブジェクトはオプションです。`claims` は予約されたプレースホルダーであり、コンテキストオブジェクトとしては使用できません。詳細については[HTTP API アクセスログをカスタマイズする](http-api-logging-variables.md)を参照してください。
**Example**
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
### Lambda 関数レスポンス形式 2.0
`2.0` 形式バージョンを選択した場合は、Lambda 関数から、ブール値を返すか、標準の IAM ポリシー構文を使用する IAM ポリシーを返すことができます。ブール値を返すには、オーソライザーの簡易レスポンスを有効にします。以下の例では、Lambda 関数から返すようにコーディングする必要のある形式を示しています。`context` オブジェクトはオプションです。`$context.authorizer.property` を使用して、コンテキストプロパティを Lambda 統合に渡したり、ログにアクセスしたりできます。詳細については、「[HTTP API アクセスログをカスタマイズする](http-api-logging-variables.md)」を参照してください。
------
#### [ Simple response ]
```
{
"isAuthorized": true/false,
"context": {
"exampleKey": "exampleValue"
}
}
```
------
#### [ IAM policy ]
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
------
## Lambda オーソライザー関数の例
以下のサンプルの Node.js Lambda 関数では、`2.0` ペイロード形式バージョンの場合に Lambda 関数から返す必要のあるレスポンスの形式を示しています。
------
#### [ Simple response - Node.js ]
```
export const handler = async(event) => {
let response = {
"isAuthorized": false,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
if (event.headers.authorization === "secretToken") {
console.log("allowed");
response = {
"isAuthorized": true,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
}
return response;
};
```
------
#### [ Simple response - Python ]
```
import json
def lambda_handler(event, context):
response = {
"isAuthorized": False,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
"isAuthorized": True,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
#### [ IAM policy - Node.js ]
```
export const handler = async(event) => {
if (event.headers.authorization == "secretToken") {
console.log("allowed");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
else {
console.log("denied");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
};
```
------
#### [ IAM policy - Python ]
```
import json
def lambda_handler(event, context):
response = {
# The principal user identification associated with the token sent by
# the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
# The principal user identification associated with the token
# sent by the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
## ID ソース
オプションで、Lambda オーソライザーの ID ソースを指定できます。ID ソースは、リクエストを認可するために必要なデータの場所を指定します。例えば、ヘッダーまたはクエリ文字列の値を ID ソースとして指定できます。ID ソースを指定する場合、クライアントはそれらのソースをリクエストに含める必要があります。クライアントのリクエストに ID ソースが含まれていない場合、API Gateway は Lambda オーソライザーを呼び出さず、クライアントは `401` エラーを受け取ります。
次の表は、Lambda オーソライザーでサポートされている ID ソースを示しています。
| **タイプ** | **例** | **注意事項** |
| --- | --- | --- |
| ヘッダー値 | \$1request.header.name | ヘッダー名では大文字と小文字は区別されません。 |
| クエリ文字列値 | \$1request.querystring.name | クエリ文字列名では大文字と小文字が区別されます。 |
| コンテキスト変数 | \$1context.variableName | サポートされている[コンテキスト変数](http-api-logging-variables.md)の値。 |
| ステージ変数 | \$1stageVariables.variableName | [ステージ変数](http-api-stages.stage-variables.md)の値。 |
Lambda 関数から直接 ` {"errorMessage" : "Unauthorized"}` を返し、クライアントに `401` エラーを返すこともできます。Lambda 関数からクライアントに直接 `401` エラーを返す場合は、Lambda オーソライザーの作成時に ID ソースを指定しないでください。
## オーソライザーのレスポンスのキャッシュ
[authorizerResultTtlInSeconds](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers.html#apis-apiid-authorizers-prop-createauthorizerinput-authorizerresultttlinseconds) を指定することで、Lambda オーソライザーのキャッシュを有効にすることができます。オーソライザーのキャッシュが有効になっていると、API Gateway はオーソライザーの ID ソースをキャッシュキーとして使用します。クライアントが設定済みの TTL 内の ID ソースで同じパラメータを指定した場合、API Gateway は、Lambda 関数を呼び出すのではなく、キャッシュされたオーソライザーの結果を使用します。
キャッシュを有効にするには、オーソライザーに 1 つ以上の ID ソースが必要です。
オーソライザーの簡易レスポンスを有効にすると、オーソライザーのレスポンスは、キャッシュされた ID ソース値に一致するすべての API リクエストを完全に許可するか、拒否するかになります。より詳細なアクセス許可が必要な場合は、簡易レスポンスを無効にし、IAM ポリシーが返されるようにします。オーソライザーによっては、IAM ポリシーが複数のアクセスを制御する必要がある場合があります。
デフォルトでは、API Gateway は、オーソライザーを使用する API のすべてのルートに対して、キャッシュされたオーソライザーのレスポンスを使用します。ルートごとにレスポンスをキャッシュするには、オーソライザーの ID ソースに `$context.routeKey` を追加します。
## Lambda オーソライザーの作成
Lambda オーソライザーを作成するときは、API Gateway で使用する Lambda 関数を指定します。関数のリソースポリシーまたは IAM ロールを使用して Lambda 関数を呼び出すには、API Gateway のアクセス許可を付与する必要があります。次の [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) コマンドは、Lambda オーソライザーを作成します。
```
aws apigatewayv2 create-authorizer \
--api-id abcdef123 \
--authorizer-type REQUEST \
--identity-source '$request.header.Authorization' \
--name lambda-authorizer \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \
--authorizer-payload-format-version '2.0' \
--enable-simple-responses
```
次の [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) コマンドは、API Gateway に Lambda 関数を呼び出すためのアクセス許可を付与するように、その関数のリソースポリシーを更新します。API Gateway に関数を呼び出すアクセス許可がない場合、クライアントは `500 Internal Server Error` を受け取ります。
```
aws lambda add-permission \
--function-name my-authorizer-function \
--statement-id apigateway-invoke-permissions-abc123 \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id"
```
オーソライザーを作成し、呼び出すアクセス許可を API Gateway に付与したら、オーソライザーを使用するようにルートを更新します。次の [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) コマンドは、Lambda オーソライザーをルートに追加します。Lambda オーソライザーがポリシーキャッシュを使用している場合は、追加ルートのアクセスを制御するようにポリシーを更新してください。
```
aws apigatewayv2 update-route \
--api-id abcdef123 \
--route-id abc123 \
--authorization-type CUSTOM \
--authorizer-id def123
```
## Lambda オーソライザーのトラブルシューティング
API Gateway が Lambda オーソライザーを呼び出せない場合、または Lambda オーソライザーが無効な形式のレスポンスを返す場合、クライアントは `500 Internal Server Error` を受け取ります。
エラーのトラブルシューティングを行うには、API ステージの[アクセスログを有効にします](http-api-logging.md)。ログ形式に `$context.authorizer.error` ログ記録変数を含めます。
API Gateway に関数を呼び出すアクセス許可がないことがログに示されている場合は、関数のリソースポリシーを更新するか、IAM ロールを提供して API Gateway にオーソライザーを呼び出すアクセス許可を付与します。
Lambda 関数が無効なレスポンスを返すことがログに示されている場合は、Lambda 関数が[必要な形式](#http-api-lambda-authorizer.payload-format-response)でレスポンスを返すことを確認してください。
# API Gateway の JWT オーソライザーを使用して HTTP API へのアクセスを制御する
[OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) および [OAuth 2.0](https://oauth.net/2/) フレームワークの一部として JSON ウェブトークン (JWT) を使用して、API へのクライアントアクセスを制限できます。
API のルートに JWT オーソライザーを設定する場合、API Gateway はクライアントが API リクエストとともに送信する JWT を検証します。API Gateway は、トークンの検証、およびオプションでトークン内のスコープに基づいてリクエストを許可または拒否します。ルートのスコープを設定する場合、ルートのスコープを 1 つ以上、トークンに含める必要があります。
API の各ルートに個別のオーソライザーを設定することも、複数のルートに同じオーソライザーを使用することもできます。
**注記**
JWT アクセストークンを OpenID Connect ID トークンなど他のタイプの JWT と区別する標準的なメカニズムはありません。API 認可に ID トークンが必要でない限り、認可スコープを要求するようにルートを設定することをお勧めします。また、JWT アクセストークンを発行するときにのみ ID プロバイダーが使用する発行者または対象者を要求するように JWT オーソライザーを設定することもできます。
## JWT オーソライザーによる API リクエストの承認
API Gateway は、次の一般的なワークフローを使用して、JWT オーソライザーを使用するように設定されたルートへの要求を承認します。
1. [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource) でトークンを確認します。`identitySource` には、トークンのみを含めるか、`Bearer` のプレフィックスが付いたトークンのみを含めることができます。
1. トークンをデコードします。
1. 発行者の `jwks_uri` から取得したパブリックキーを使用して、トークンのアルゴリズムと署名を確認します。現在、RSA ベースのアルゴリズムのみがサポートされています。API Gateway は、パブリックキーを 2 時間キャッシュできます。ベストプラクティスとして、キーをローテーションするときは、古いキーと新しいキーの両方が有効な猶予期間を設けてください。
1. クレームを検証します。API Gateway は、次のトークンクレームを評価します。
+ [https://datatracker.ietf.org/doc/html/rfc7517#section-4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5) – トークンには、トークンに署名した `jwks_uri` のキーと一致するヘッダークレームが必要です。
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) – オーソライザーに設定された [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) と一致する必要があります。
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) または `client_id` – オーソライザーに設定された [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) エントリの 1 つと一致する必要があります。API Gateway は、`aud` が存在しない場合にのみ、`client_id` を検証します。`aud` と `client_id` の両方が存在する場合、API Gateway は `aud` を評価します。
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) – UTC の現在時刻より後にする必要があります。
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) – UTC の現在時刻より前にする必要があります。
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) – UTC の現在時刻より前にする必要があります。
+ [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) または `scp` – トークンには、ルートの [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes) のスコープを少なくとも 1 つ含める必要があります。
これらのいずれかの手順が失敗した場合、API Gateway は API リクエストを拒否します。
API Gateway は JWT を検証した後、トークン内のクレームを API ルートの統合に渡します。JWT クレームには、Lambda 関数などのバックエンドリソースがアクセスできます。例えば、JWT に ID クレーム `emailID` が含まれている場合、`$event.requestContext.authorizer.jwt.claims.emailID` で Lambda 統合に使用できます。API Gateway が Lambda 統合に送信するペイロードの詳細については、「[API Gateway で HTTP API の AWS Lambda プロキシ統合を作成する](http-api-develop-integrations-lambda.md)」を参照してください。
## JWT オーソライザーを作成する
JWT オーソライザーを作成する前に、クライアントアプリケーションを ID プロバイダーに登録する必要があります。また、HTTP API を作成しておく必要があります。HTTP API の作成例については、「[HTTP API を作成する](http-api-develop.md#http-api-examples)」を参照してください。
### コンソールを使用して JWT オーソライザーを作成する
次の手順は、コンソールを使用して JWT オーソライザーを作成する方法を示しています。
**コンソールを使用して JWT オーソライザーを作成するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. HTTP API を選択します。
1. メインナビゲーションペインで、**[認可]** を選択します。
1. **[オーソライザーを管理]** タブを選択します。
1. **[作成]** を選択します。
1. **[オーソライザーのタイプ]** で、**[JWT]** を選択します。
1. JWT オーソライザーを設定し、トークンのソースを定義する **ID ソース**を指定します。
1. **[作成]** を選択します。
#### AWS CLI を使用して JWT オーソライザーを作成する
次の [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) コマンドは、JWT オーソライザーを作成します。`jwt-configuration` には、ID プロバイダーの `Audience` と `Issuer` を指定します。Amazon Cognito を ID プロバイダーとして使用する場合、`IssuerUrl` は `https://cognito-idp.us-east-2.amazonaws.com/userPoolID` です。
```
aws apigatewayv2 create-authorizer \
--name authorizer-name \
--api-id api-id \
--authorizer-type JWT \
--identity-source '$request.header.Authorization' \
--jwt-configuration Audience=audience,Issuer=IssuerUrl
```
##### AWS CloudFormation を使用して JWT オーソライザーを作成する
次の CloudFormation テンプレートでは、Amazon Cognito を ID プロバイダーとして使用する JWT オーソライザーで HTTP API を作成します。
CloudFormation テンプレートの出力は、クライアントがサインアップ/サインインして JWT を受け取ることができる、Amazon Cognito がホストする UI の URL です。クライアントは、サインインすると、URL のアクセストークンにより、HTTP API にリダイレクトされます。アクセストークンを使用して API を呼び出すには、URL の `#` を `?` に変更し、トークンをクエリ文字列パラメータとして使用します。
##### CloudFormation テンプレートの例
```
AWSTemplateFormatVersion: '2010-09-09'
Description: |
Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer
and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can
sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token
in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter.
Resources:
MyAPI:
Type: AWS::ApiGatewayV2::Api
Properties:
Description: Example HTTP API
Name: api-with-auth
ProtocolType: HTTP
Target: !GetAtt MyLambdaFunction.Arn
DefaultRouteOverrides:
Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides
Properties:
ApiId: !Ref MyAPI
Route:
AuthorizationType: JWT
AuthorizerId: !Ref JWTAuthorizer
JWTAuthorizer:
Type: AWS::ApiGatewayV2::Authorizer
Properties:
ApiId: !Ref MyAPI
AuthorizerType: JWT
IdentitySource:
- '$request.querystring.access_token'
JwtConfiguration:
Audience:
- !Ref AppClient
Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
Name: test-jwt-authorizer
MyLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Runtime: nodejs18.x
Role: !GetAtt FunctionExecutionRole.Arn
Handler: index.handler
Code:
ZipFile: |
exports.handler = async (event) => {
const response = {
statusCode: 200,
body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'),
};
return response;
};
APIInvokeLambdaPermission:
Type: AWS::Lambda::Permission
Properties:
FunctionName: !Ref MyLambdaFunction
Action: lambda:InvokeFunction
Principal: apigateway.amazonaws.com
SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default
FunctionExecutionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Service:
- lambda.amazonaws.com
Action:
- 'sts:AssumeRole'
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
UserPool:
Type: AWS::Cognito::UserPool
Properties:
UserPoolName: http-api-user-pool
AutoVerifiedAttributes:
- email
Schema:
- Name: name
AttributeDataType: String
Mutable: true
Required: true
- Name: email
AttributeDataType: String
Mutable: false
Required: true
AppClient:
Type: AWS::Cognito::UserPoolClient
Properties:
AllowedOAuthFlows:
- implicit
AllowedOAuthScopes:
- aws.cognito.signin.user.admin
- email
- openid
- profile
AllowedOAuthFlowsUserPoolClient: true
ClientName: api-app-client
CallbackURLs:
- !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
ExplicitAuthFlows:
- ALLOW_USER_PASSWORD_AUTH
- ALLOW_REFRESH_TOKEN_AUTH
UserPoolId: !Ref UserPool
SupportedIdentityProviders:
- COGNITO
HostedUI:
Type: AWS::Cognito::UserPoolDomain
Properties:
Domain: !Join
- '-'
- - !Ref MyAPI
- !Ref AppClient
UserPoolId: !Ref UserPool
Outputs:
SignupURL:
Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
```
## JWT オーソライザーを使用するようにルートを更新する
JWT オーソライザーを使用するようにルートを更新するには、コンソール、AWS CLI、または AWS SDK を使用できます。
### コンソールを使用して、JWT オーソライザーを使用するようにルートを更新する
次の手順では、コンソールを使用して、JWT オーソライザーを使用するようにルートを更新する方法を示します。
**コンソールを使用して JWT オーソライザーを作成するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. HTTP API を選択します。
1. メインナビゲーションペインで、**[認可]** を選択します。
1. メソッドを選択し、ドロップダウンメニューからオーソライザーを選択して、**[オーソライザーをアタッチ]** を選択します。
#### AWS CLI を使用して、JWT オーソライザーを使用するようにルートを更新する
次の [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) コマンドは、JWT オーソライザーを使用するようにルートを更新します。
```
aws apigatewayv2 update-route \
--api-id api-id \
--route-id route-id \
--authorization-type JWT \
--authorizer-id authorizer-id \
--authorization-scopes user.email
```
# API Gateway の IAM 認可を使用して HTTP API へのアクセスを制御する
HTTP API ルートに対して IAM 認可を有効にできます。IAM 認可が有効な場合、クライアントは [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) を使用して、AWS 認証情報でリクエストに署名する必要があります。API Gateway は、クライアントがルートに対する `execute-api` アクセス許可を持っている場合にのみ、API ルートを呼び出します。
HTTP API に対する IAM 認可は、[REST API](api-gateway-control-access-using-iam-policies-to-invoke-api.md) に対する認可と同様です。
**注記**
リソースポリシーは、現在 HTTP API 向けにサポートされていません。
API を呼び出すアクセス許可をクライアントに付与する IAM ポリシーの例については、「[API を呼び出すためのアクセスの制御](api-gateway-control-access-using-iam-policies-to-invoke-api.md)」を参照してください。
## ルートに対する IAM 認可を有効にする
次の [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) コマンドは、HTTP API ルートの IAM 認可を有効にします。
```
aws apigatewayv2 update-route \
--api-id abc123 \
--route-id abcdef \
--authorization-type AWS_IAM
```
# API Gateway で HTTP API の統合を作成する
*統合*は、ルートをバックエンドリソースに接続します。HTTP API は、Lambda プロキシ、AWS のサービス、および HTTP プロキシの統合をサポートします。たとえば、API の `POST` ルートへの `/signup` リクエストを設定して、お客様のサインアップを処理する Lambda 関数と統合できます。
**Topics**
+ [API Gateway で HTTP API の AWS Lambda プロキシ統合を作成する](http-api-develop-integrations-lambda.md)
+ [HTTP API の HTTP プロキシ統合を作成する](http-api-develop-integrations-http.md)
+ [API Gateway で HTTP API の AWS のサービス統合を作成する](http-api-develop-integrations-aws-services.md)
+ [API Gateway で HTTP API のプライベート統合を作成する](http-api-develop-integrations-private.md)
# API Gateway で HTTP API の AWS Lambda プロキシ統合を作成する
Lambda プロキシ統合を使用すると、API ルートを Lambda 関数と統合できます。クライアントが API を呼び出すと、API Gateway はリクエストを Lambda 関数に送信し、関数のレスポンスをクライアントに返します。HTTP API の作成例については、「[HTTP API を作成する](http-api-develop.md#http-api-examples)」を参照してください。
## ペイロード形式バージョン
ペイロード形式バージョンは、API Gateway が Lambda 統合に送信するイベントの形式と、API Gateway が Lambda からのレスポンスをどのように解釈するかを指定します。ペイロード形式バージョンを指定しない場合、AWS マネジメントコンソール はデフォルトで最新バージョンを使用します。AWS CLI、CloudFormation、SDK を使用して Lambda 統合を作成する場合は、`payloadFormatVersion` を指定する必要があります。サポートされる値は `1.0` と `2.0` です。
`payloadFormatVersion` を設定する方法の詳細については、「[create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html)」を参照してください。既存の統合の `payloadFormatVersion` を確認する方法の詳細については、「[get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html)」を参照してください。
### ペイロード形式の相違点
次のリストは、ペイロード形式の `1.0` バージョンと `2.0` バージョンの違いを示しています。
+ Format `2.0` には `multiValueHeaders` または `multiValueQueryStringParameters` フィールドがありません。重複するヘッダーはコンマで結合され、`headers` フィールドに含められます。重複するクエリ文字列はコンマで結合され、`queryStringParameters` フィールドに含められます。
+ 形式 `2.0` には `rawPath` があります。API マッピングを使用してステージをカスタムドメイン名に接続する場合、`rawPath` は API マッピング値を提供しません。カスタムドメイン名の API マッピングにアクセスするには、形式 `1.0` と `path` を使用します。
+ 形式 `2.0` には、新しい `cookies` フィールドが含まれています。リクエスト内のすべてのクッキーヘッダーはコンマで結合され、`cookies` フィールドに追加されます。クライアントへのレスポンスでは、各クッキーは `set-cookie` ヘッダーになります。
### ペイロード形式の構造
次の例は、各ペイロード形式バージョンの構造を示しています。すべてのヘッダー名は小文字です。
------
#### [ 2.0 ]
```
{
"version": "2.0",
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": [
"cookie1",
"cookie2"
],
"headers": {
"header1": "value1",
"header2": "value1,value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"authorizer": {
"jwt": {
"claims": {
"claim1": "value1",
"claim2": "value2"
},
"scopes": [
"scope1",
"scope2"
]
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "192.0.2.1",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"body": "Hello from Lambda",
"pathParameters": {
"parameter1": "value1"
},
"isBase64Encoded": false,
"stageVariables": {
"stageVariable1": "value1",
"stageVariable2": "value2"
}
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2"
},
"multiValueHeaders": {
"header1": [
"value1"
],
"header2": [
"value1",
"value2"
]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value"
},
"multiValueQueryStringParameters": {
"parameter1": [
"value1",
"value2"
],
"parameter2": [
"value"
]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "192.0.2.1",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
------
## Lambda 関数レスポンス形式
ペイロード形式バージョンによって、Lambda 関数が返す必要があるレスポンスの構造が決まります。
### Lambda 関数レスポンス形式 1.0
`1.0` 形式バージョンの場合、Lambda 統合は次の JSON 形式でレスポンスを返す必要があります。
**Example**
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
"body": "..."
}
```
### Lambda 関数レスポンス形式 2.0
`2.0` 形式バージョンでは、API Gateway がレスポンス形式を推測できます。API Gateway は、Lambda 関数が有効な JSON を返し、`statusCode` を返さない場合、次の仮定を行います。
+ `isBase64Encoded` は `false`。
+ `statusCode` は `200`。
+ `content-type` は `application/json`。
+ `body` は関数のレスポンスです。
次の例は、Lambda 関数と API Gateway の解釈の出力を示しています。
| Lambda 関数出力 | API Gateway 解釈 |
| --- | --- |
| "Hello from Lambda!"
| {
"isBase64Encoded": false,
"statusCode": 200,
"body": "Hello from Lambda!",
"headers": {
"content-type": "application/json"
}
} |
| { "message": "Hello from Lambda!" } | {
"isBase64Encoded": false,
"statusCode": 200,
"body": "{ \"message\": \"Hello from Lambda!\" }",
"headers": {
"content-type": "application/json"
}
} |
レスポンスをカスタマイズするには、Lambda 関数は以下の形式でレスポンスを返す必要があります。
```
{
"cookies" : ["cookie1", "cookie2"],
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"body": "Hello from Lambda!"
}
```
# HTTP API の HTTP プロキシ統合を作成する
HTTP プロキシ統合を使用すると、API ルートをパブリックにルーティング可能な HTTP エンドポイントに接続できます。この統合タイプでは、API Gateway はフロントエンドとバックエンド間でリクエストとレスポンスの全体を渡します。
HTTP プロキシ統合を作成するには、パブリックにルーティング可能な HTTP エンドポイントの URL を指定します。
## パス変数と HTTP プロキシの統合
HTTP API ルートでパス変数を使用できます。
たとえば、ルート `/pets/{petID}` は `/pets/6` へのリクエストをキャッチします。統合 URI でパス変数を参照して、変数の内容を統合に送信できます。例: 「`/pets/extendedpath/{petID}`」。
greedy パス変数を使用して、ルートのすべての子リソースをキャッチできます。greedy パス変数を作成するには、変数名に `+` を追加します (例: `{proxy+}`)。
すべてのリクエストをキャッチする HTTP プロキシ統合でルートを設定するには、greedy パス変数 (`/parent/{proxy+}` など) を使用して API ルートを作成します。`https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}` メソッドでルートを HTTP エンドポイント (`ANY` など) と統合します。greedy パス変数は、リソースパスの末尾にある必要があります。
# API Gateway で HTTP API の AWS のサービス統合を作成する
HTTP API と AWS のサービスは、*ファーストクラス統合*を使用して統合できます。ファーストクラス統合は、HTTP API ルートを AWS のサービス API に接続します。クライアントがファーストクラス統合でサポートされるルートを呼び出すと、API Gateway は AWS のサービス API を呼び出します。例えば、ファーストクラス統合を使用して、Amazon Simple Queue Service キューにメッセージを送信したり、AWS Step Functions ステートマシンを起動したりすることができます。サポートされているサービスアクションについては、「[統合サブタイプのリファレンス](http-api-develop-integrations-aws-services-reference.md)」を参照してください。
## リクエストパラメータのマッピング
ファーストクラス統合には、必須およびオプションのパラメータがあります。統合を作成するには、すべての必須のパラメータを設定する必要があります。静的な値を使用するか、実行時に動的に評価されるパラメータをマッピングできます。サポートされている統合とパラメータの完全なリストについては、「[統合サブタイプのリファレンス](http-api-develop-integrations-aws-services-reference.md)」を参照してください。
次の表は、サポートされているマッピング要求パラメータを示しています。
| タイプ | 例 | コメント |
| --- | --- | --- |
| ヘッダー値 | \$1request.header.name | ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。 |
| クエリ文字列値 | \$1request.querystring.name | クエリ文字列名では大文字と小文字が区別されます。API Gateway は複数の値をコンマで結合します (例: "querystring1": "Value1,Value2")。 |
| パスパラメータ | \$1request.path.name | リクエストのパスパラメータの値。例えば、ルートが /pets/\$1petId\$1 の場合は、\$1request.path.petId を使用してリクエストの petId パラメータをマッピングできます。 |
| リクエストボディのパススルー | \$1request.body | API Gateway はリクエストボディ全体をパススルーします。 |
| リクエストボディ | \$1request.body.name | [JSON パス式](https://goessner.net/articles/JsonPath/index.html#e2)。再帰下降 (\$1request.body..name) およびフィルター式 (?(expression)) はサポートされていません。 JSON パスを指定すると、API Gateway はリクエスト本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、`$request.body` を指定します。 |
| コンテキスト変数 | \$1context.variableName | サポートされている[コンテキスト変数](http-api-logging-variables.md)の値。 |
| ステージ変数 | \$1stageVariables.variableName | [ステージ変数](http-api-stages.stage-variables.md)の値。 |
| 静的な値 | string | 定数値。 |
## ファーストクラス統合を作成する
ファーストクラス統合を作成する前に、統合する AWS のサービスアクションを呼び出す API Gateway アクセス許可を付与する IAM ロールを作成する必要があります。詳細については、「[AWS のサービスのロールの作成](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)」を参照してください。
ファーストクラス統合を作成するには、`SQS-SendMessage` などのサポートされている AWS のサービスアクションを選択し、リクエストパラメータを設定して、統合された AWS のサービス API を呼び出すアクセス許可を API Gateway に付与するロールを提供します。統合サブタイプに応じて、異なるリクエストパラメータが必要です。詳細については[統合サブタイプのリファレンス](http-api-develop-integrations-aws-services-reference.md)を参照してください。
次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、Amazon SQS メッセージを送信する統合を作成します。
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-subtype SQS-SendMessage \
--integration-type AWS_PROXY \
--payload-format-version 1.0 \
--credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
--request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'
```
## CloudFormation を使用してファーストクラス統合を作成する
次の例は、Amazon EventBridge とのファーストクラス統合を使用して `/{source}/{detailType}` ルートを作成する CloudFormation スニペットを示しています。
`Source` パラメータは `{source}` パスパラメータ、`DetailType` は `{DetailType}` パスパラメータ、`Detail` パラメータはリクエスト本文にマップされます。
このスニペットは、`PutEvents` アクションを呼び出すための API Gateway アクセス許可を付与するイベントバスや IAM ロールを表示しません。
```
Route:
Type: AWS::ApiGatewayV2::Route
Properties:
ApiId: !Ref HttpApi
AuthorizationType: None
RouteKey: 'POST /{source}/{detailType}'
Target: !Join
- /
- - integrations
- !Ref Integration
Integration:
Type: AWS::ApiGatewayV2::Integration
Properties:
ApiId: !Ref HttpApi
IntegrationType: AWS_PROXY
IntegrationSubtype: EventBridge-PutEvents
CredentialsArn: !GetAtt EventBridgeRole.Arn
RequestParameters:
Source: $request.path.source
DetailType: $request.path.detailType
Detail: $request.body
EventBusName: !GetAtt EventBus.Arn
PayloadFormatVersion: "1.0"
```
# 統合サブタイプのリファレンス
以下の[統合サブタイプ](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype)は HTTP API でサポートされています。
**Topics**
+ [EventBridge-PutEvents 1.0](#EventBridge-PutEvents)
+ [SQS-SendMessage 1.0](#SQS-SendMessage)
+ [SQS-ReceiveMessage 1.0](#SQS-ReceiveMessage)
+ [SQS-DeleteMessage 1.0](#SQS-DeleteMessage)
+ [SQS-PurgeQueue 1.0](#SQS-PurgeQueue)
+ [AppConfig-GetConfiguration 1.0](#AppConfig-GetConfiguration)
+ [Kinesis-PutRecord 1.0](#Kinesis-PutRecord)
+ [StepFunctions-StartExecution 1.0](#StepFunctions-StartExecution)
+ [StepFunctions-StartsyncExecution 1.0](#StepFunctions-StartSyncExecution)
+ [StepFunctions-StopExecution 1.0](#StepFunctions-StopExecution)
## EventBridge-PutEvents 1.0
カスタムイベントを、ルールとマッチングできるように Amazon EventBridge に送信します。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| 詳細 | True |
| DetailType | True |
| 送信元 | True |
| 時間 | False |
| EventBusName | False |
| リソース | False |
| リージョン | False |
| TraceHeader | False |
詳細については、* Amazon EventBridge API リファレンス*の「[PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html)」を参照してください。
## SQS-SendMessage 1.0
指定されたキューにメッセージを配信します。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| QueueUrl | True |
| MessageBody | True |
| DelaySeconds | False |
| MessageAttributes | False |
| MessageDeduplicationId | False |
| MessageGroupId | False |
| MessageSystemAttributes | False |
| リージョン | False |
詳細については、*Amazon Simple Queue Service API リファレンス*の「[SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)」を参照してください。
## SQS-ReceiveMessage 1.0
指定されたキューから 1 個以上 (最大 10 個) のメッセージを取得します。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| QueueUrl | True |
| AttributeNames | False |
| MaxNumberOfMessages | False |
| MessageAttributeNames | False |
| ReceiveRequestAttemptId | False |
| VisibilityTimeout | False |
| WaitTimeSeconds | False |
| リージョン | False |
詳細については、*Amazon Simple Queue Service API リファレンス*の「[ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)」を参照してください。
## SQS-DeleteMessage 1.0
指定されたキュー内の指定されたメッセージを削除します。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| ReceiptHandle | True |
| QueueUrl | True |
| リージョン | False |
詳細については、*Amazon Simple Queue Service API リファレンス*の「[DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html)」を参照してください。
## SQS-PurgeQueue 1.0
指定されたキュー内のすべてのメッセージを削除します。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| QueueUrl | True |
| リージョン | False |
詳細については、*Amazon Simple Queue Service API リファレンス*の 「[PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html)」を参照してください。
## AppConfig-GetConfiguration 1.0
設定に関する情報を受け取ります。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| アプリケーション | True |
| 環境 | True |
| 設定 | True |
| ClientId | True |
| ClientConfigurationVersion | False |
| リージョン | False |
詳細については、*AWS AppConfig API リファレンス*の「[GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html)」を参照してください。
## Kinesis-PutRecord 1.0
1 つのデータレコードを Amazon Kinesis Data Streams に書き込みます。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| StreamName | True |
| データ | True |
| PartitionKey | True |
| SequenceNumberForOrdering | False |
| ExplicitHashKey | False |
| リージョン | False |
詳細については、*Amazon Kinesis Data Streams API リファレンス*の「[PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html)」を参照してください。
## StepFunctions-StartExecution 1.0
ステートマシンの実行を開始します。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| StateMachineArn | True |
| 名前 | False |
| Input | False |
| リージョン | False |
詳細については、*AWS Step Functions API リファレンス*の「[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)」を参照してください。
## StepFunctions-StartsyncExecution 1.0
同期状態マシンの実行を開始します。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| StateMachineArn | True |
| 名前 | False |
| Input | False |
| リージョン | False |
| TraceHeader | False |
詳細については、*AWS Step Functions API リファレンス*の「[StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html)」を参照してください。
## StepFunctions-StopExecution 1.0
実行を停止します。
| [Parameter] (パラメータ) | 必須 |
| --- | --- |
| ExecutionArn | True |
| 原因 | False |
| エラー | False |
| リージョン | False |
詳細については、*AWS Step Functions API リファレンス*の「[StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html)」を参照してください。
# API Gateway で HTTP API のプライベート統合を作成する
プライベート統合を使用すると、Application Load Balancer や Amazon ECS コンテナベースのアプリケーションなど、VPC 内のプライベートリソースと API 統合を作成できます。
プライベート統合を使用して、VPC 外のクライアントがアクセスできるように VPC 内のリソースを公開できます。API Gateway がサポートするいずれかの[認可方法](http-api-access-control.md)を使用して、API へのアクセスを制御できます。
**注記**
プライベート統合を作成するには、まず VPC リンクを作成する必要があります。VPC リンク V2 が HTTP API と REST API の両方でサポートされるようになりました。VPC リンク V2 の詳細については、「[API Gateway で VPC リンク V2 を設定する](apigateway-vpc-links-v2.md)」を参照してください。
VPC リンク V2 を作成したら、Application Load Balancer、Network Load Balancer、または AWS Cloud Map サービスに登録されたリソースに接続するプライベート統合を設定できます。
## 考慮事項
以下の考慮事項は、プライベート統合の使用に影響する可能性があります。
+ すべてのリソースは、同じ AWS アカウントによって所有されている必要があります。これには、ロードバランサーまたは AWS Cloud Map サービス、VPC リンク、HTTP API が含まれます。
+ デフォルトでは、プライベート統合トラフィックは HTTP プロトコルを使用します。HTTPS を使用するには、[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html) を指定します。AWS マネジメントコンソール を使用してこれを行うには、プライベート統合を作成するときに、**[詳細設定]** を選択し、安全なサーバー名を入力します。
+ プライベート統合では、API Gateway はバックエンドリソースへのリクエストに API エンドポイントの[ステージ](http-api-stages.md)部分を含めます。例えば、API の `test` ステージへのリクエストには、プライベート統合へのリクエストに `test/route-path` が含まれます。バックエンドリソースへのリクエストからステージ名を削除するには、[パラメータのマッピング](http-api-parameter-mapping.md)を使用して、リクエストパスを `$request.path` にオーバーライドします。
## Application Load Balancer または Network Load Balancer を使用したプライベート統合の作成
プライベート統合を作成する前に、VPC リンク V2 を作成する必要があります。VPC リンク V2 の詳細については、「[API Gateway で VPC リンク V2 を設定する](apigateway-vpc-links-v2.md)」を参照してください。
Application Load Balancer または Network Load Balancer とのプライベート統合を作成するには、HTTP プロキシ統合を作成し、使用する VPC リンクを指定して、ロードバランサーのリスナー ARN を指定します。
次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、VPC リンクを使用してロードバランサーに接続するプライベート統合を作成します。
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65
--payload-format-version 1.0
```
## AWS Cloud Map サービス検出を使用したプライベート統合の作成
プライベート統合を作成する前に、VPC リンク V2 を作成する必要があります。VPC リンクの詳細については、「[API Gateway で VPC リンク V2 を設定する](apigateway-vpc-links-v2.md)」を参照してください。
AWS Cloud Map との統合のために、API Gateway は `DiscoverInstances` を使用してリソースを識別します。クエリパラメータを使用して、特定のリソースをターゲットにすることができます。登録されたリソースの属性には、IP アドレスとポートを含める必要があります。API Gateway は、`DiscoverInstances` から返される正常なリソース間にリクエストを分散します。詳細については、AWS Cloud Map API リファレンスの「[DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html)」を参照してください。
**注記**
Amazon ECS を使用して AWS Cloud Map にエントリを入力する場合は、Amazon ECS サービス検出で SRV レコードを使用するように Amazon ECS タスクを設定するか、Amazon ECS Service Connect を有効にする必要があります。詳細については、「Amazon Elastic Container Service デベロッパーガイド」の「[相互接続サービス](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html)」を参照してください。
AWS Cloud Map とのプライベート統合を作成するには、HTTP プロキシ統合を作成し、使用する VPC リンクを指定して、AWS Cloud Map サービスの ARN を指定します。
次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、AWS Cloud Map サービス検出を使用してリソースを識別するプライベート統合を作成します。
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment
--payload-format-version 1.0
```
# API Gateway で HTTP API の CORS を設定する
[Cross-origin resource sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) は、ブラウザで実行されているスクリプトから開始される HTTP リクエストを制限するブラウザのセキュリティ機能です。API にアクセスできず、`Cross-Origin Request Blocked` を含むエラーメッセージが表示される場合は、CORS を有効にする必要がある場合があります。詳細については、「[CORS とは](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)」を参照してください。
通常、CORS は、異なるドメインまたはオリジンでホストされている API にアクセスするウェブアプリケーションを構築するために必要です。CORS を有効にして、別のドメインでホストされているウェブアプリケーションから API へのリクエストを許可することができます。たとえば、API が `https://{api_id}.execute-api.{region}.amazonaws.com/` でホストされていて、`example.com` でホストされているウェブアプリケーションから API を呼び出す場合、API が CORS をサポートしている必要があります。
API に CORS を設定した場合、API Gateway は API に OPTIONS ルートが設定されていない場合でも、プリフライト OPTIONS リクエストに対するレスポンスを自動的に送信します。CORS リクエストの場合、API Gateway は設定された CORS ヘッダーを、統合からのレスポンスに追加します。
**注記**
API の CORS を設定する場合、API Gateway はバックエンド統合から返された CORS ヘッダーを無視します。
CORS 設定では、次のパラメータを指定できます。API Gateway HTTP API コンソールを使用してこれらのパラメータを追加するには、値を入力した後に **[追加]** を選択します。
| CORS ヘッダー | CORS 設定プロパティ | 値の例 |
| --- | --- | --- |
| Access-Control-Allow-Origin | allowOrigins | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/http-api-cors.html) |
| Access-Control-Allow-Credentials | allowCredentials | true |
| Access-Control-Expose-Headers | exposeHeaders | date, x-api-id, \$1 |
| Access-Control-Max-Age | maxAge | 300 |
| Access-Control-Allow-Methods | allowMethods | GET, POST, DELETE , \$1 |
| Access-Control-Allow-Headers | allowHeaders | authorization, \$1 |
CORS ヘッダーを返すには、リクエストに `origin` ヘッダーが含まれている必要があります。`OPTIONS` メソッドの場合、リクエストには `origin` ヘッダーと `Access-Control-Request-Method` ヘッダーが含まれている必要があります。
CORS 設定は次の例のようになります。
![\[HTTP API の CORS 設定\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/http-cors-console.png)
## `$default` ルートおよびオーソライザーによる HTTP API の CORS の設定
CORS を有効にし、 HTTP API の任意のルートに対して認可を設定できます。[`$default` ルート](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default)の CORS および認可を有効にする場合、いくつかの特別な考慮事項があります。`$default` ルートは、`OPTIONS` リクエストを含め、明示的に定義していないすべてのメソッドとルートのリクエストをキャッチします。未認可の `OPTIONS` リクエストをサポートするには、認可を必要としない `OPTIONS /{proxy+}` ルートを API に追加し、ルートに統合をアタッチします。`OPTIONS /{proxy+}` ルートの優先順位は `$default` ルートよりも高くなります。その結果、クライアントは認可なしで API に `OPTIONS` リクエストを送信できます。ルーティングの優先順位の詳細については、「[API リクエストのルーティング](http-api-develop-routes.md#http-api-develop-routes.evaluation)」を参照してください。
## AWS CLI を使用して HTTP API の CORS を設定する
次の [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) コマンドは、`https://www.example.com` からの CORS リクエストを有効にします。
**Example**
```
aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://www.example.com"
```
詳細については、Amazon API Gateway バージョン 2 API リファレンスの「[CORS](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid.html#apis-apiid-model-cors)」を参照してください。
# API Gateway で HTTP API の API リクエストとレスポンスを変換する
バックエンド統合に到達する前に、クライアントからの API リクエストを変更できます。API Gateway がクライアントに応答を返す前に、統合からレスポンスを変更することもできます。*パラメータマッピング*を使用して、HTTP API の API リクエストとレスポンスを変更します。パラメータマッピングを使用するには、変更する API リクエストまたはレスポンスパラメータを指定し、それらのパラメータを変更する方法を指定します。
## API リクエストの変換
リクエストパラメータを使用して、バックエンド統合に到達する前にリクエストを変更します。ヘッダー、クエリ文字列、またはリクエストパスを変更できます。
リクエストパラメータは、キーと値のマップです。キーは、変更するリクエストパラメータの場所とその変更方法を識別します。値は、パラメータの新しいデータを指定します。
次の表に、サポートされているキーを示します。
| タイプ | 構文 |
| --- | --- |
| ヘッダー | append\$1overwrite\$1remove:header.headername |
| クエリ文字列 | append\$1overwrite\$1remove:querystring.querystring-name |
| パス | overwrite:path |
次の表に、パラメータにマップできるサポートされている値を示します。
| タイプ | 構文 | コメント |
| --- | --- | --- |
| ヘッダー値 | \$1request.header.name または \$1\$1request.header.name\$1 | ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。一部のヘッダーは予約されています。詳細については、「[予約済みヘッダー](#http-api-mapping-reserved-headers)」を参照してください。 |
| クエリ文字列値 | \$1request.querystring.name または \$1\$1request.querystring.name\$1 | クエリ文字列名では大文字と小文字が区別されます。API Gateway は複数の値をコンマで結合します (例: "querystring1" "Value1,Value2")。 |
| リクエストボディ | \$1request.body.name または \$1\$1request.body.name\$1 | JSON path 式。再帰下降 (\$1request.body..name)) およびフィルタ式 (?(expression)) はサポートされていません。 JSON パスを指定すると、API Gateway はリクエスト本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、`$request.body` を指定します。 |
| リクエストパス | \$1request.path または \$1\$1request.path\$1 | ステージ名を含まないリクエストパス。 |
| パスパラメータ | \$1request.path.name または \$1\$1request.path.name\$1 | リクエストのパスパラメータの値。例えば、ルートが /pets/\$1petId\$1 の場合は、petId を使用してリクエストのパラメータ\$1request.path.petIdをマッピングできます。 |
| コンテキスト変数 | \$1context.variableName または \$1\$1context.variableName\$1 | [コンテキスト変数](http-api-logging-variables.md)の値 。特殊文字の `.` と `_` のみがサポートされています。 |
| ステージ変数 | \$1stageVariables.variableName または \$1\$1stageVariables.variableName\$1 | [ステージ変数](http-api-stages.stage-variables.md)の値。 |
| 静的な値 | string | 定数値。 |
**注記**
選択式で複数の変数を使用するには、変数を角かっこで囲みます。例えば、`${request.path.name} ${request.path.id}` と指定します。
## API レスポンスの変換
レスポンスをクライアントに返す前に、レスポンスパラメータを使用して HTTP レスポンスをバックエンド統合から変換します。API Gateway がクライアントにレスポンスを返す前に、ヘッダーまたはステータスコードを変更できます。
統合によって返されるステータスコードごとに、レスポンスパラメータを構成します。レスポンスパラメータは、キーと値のマップです。キーは、変更するリクエストパラメータの場所とその変更方法を識別します。値は、パラメータの新しいデータを指定します。
次の表に、サポートされているキーを示します。
| タイプ | 構文 |
| --- | --- |
| ヘッダー | append\$1overwrite\$1remove:header.headername |
| ステータスコード | overwrite:statuscode |
次の表に、パラメータにマップできるサポートされている値を示します。
| タイプ | 構文 | コメント |
| --- | --- | --- |
| ヘッダー値 | \$1response.header.name または \$1\$1response.header.name\$1 | ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。一部のヘッダーは予約されています。詳細については、「[予約済みヘッダー](#http-api-mapping-reserved-headers)」を参照してください。 |
| レスポンス本文 | \$1response.body.name または \$1\$1response.body.name\$1 | JSON path 式。再帰下降 (\$1response.body..name) およびフィルター式 (?(expression)) はサポートされていません。 JSON パスを指定すると、API Gateway はレスポンス本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、`$response.body` を指定します。 |
| コンテキスト変数 | \$1context.variableName または \$1\$1context.variableName\$1 | サポートされている[コンテキスト変数](http-api-logging-variables.md)の値。 |
| ステージ変数 | \$1stageVariables.variableName または \$1\$1stageVariables.variableName\$1 | [ステージ変数](http-api-stages.stage-variables.md)の値。 |
| 静的な値 | string | 定数値。 |
**注記**
選択式で複数の変数を使用するには、変数を角かっこで囲みます。例えば、`${request.path.name} ${request.path.id}` と指定します。
## 予約済みヘッダー
次のヘッダーは予約されています。これらのヘッダーには、要求またはレスポンスマッピングを構成できません。
+ access-control-\$1
+ apigw-\$1
+ Authorization
+ Connection
+ Content-Encoding
+ Content-Length
+ Content-Location
+ Forwarded
+ Keep-Alive
+ Origin
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers
+ Transfer-Encoding
+ Upgrade
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via
## 例
以下の AWS CLI 例は、パラメータマッピングを設定します。CloudFormation テンプレートの例については、[GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates) を参照してください。
### API リクエストへのヘッダーの追加
次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、バックエンド統合に到達する前に API リクエストに `header1` という名前のヘッダーを追加します。API Gateway は、ヘッダーにリクエスト ID を設定します。
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header1": "$context.requestId" }'
```
### リクエストヘッダーの名前を変更する
次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、リクエストヘッダーの名前を `header1` から `header2` に変更します。
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}'
```
### 統合からのレスポンスの変更
次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、統合のレスポンスパラメータを設定します。インテグレーションが 500 ステータスコードを返すと、API Gateway はステータスコードを 403 に変更し、応答に `header1` 1 を追加します。統合によって 404 ステータスコードが返されると、API Gateway は応答にヘッダー`error`を追加します。
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }'
```
### 構成されたパラメータマッピングの削除
次の [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、`append:header.header1` に対して以前に設定されたリクエストパラメータを削除します。また、200 ステータスコードに対して以前に構成されたレスポンスパラメータも削除されます。
```
aws apigatewayv2 update-integration \
--api-id abcdef123 \
--integration-id hijk456 \
--request-parameters '{"append:header.header1" : ""}' \
--response-parameters '{"200" : {}}'
```
# API Gateway で HTTP API の OpenAPI 定義を使用する
HTTP API は、OpenAPI 3.0 定義ファイルを使用して定義できます。次に、定義を API Gateway にインポートして API を作成できます。OpenAPI への API Gateway 拡張の詳細については、「[API Gateway の OpenAPI 拡張機能](api-gateway-swagger-extensions.md)」を参照してください。
## HTTP API のインポート
HTTP API は、OpenAPI 3.0 定義ファイルをインポートすることによって作成できます。
REST API から HTTP API に移行するには、REST API を OpenAPI 3.0 定義ファイルとしてエクスポートできます。次に、API 定義を HTTP API としてインポートします。REST API のエクスポートの詳細については、「[API Gateway から REST API をエクスポートする](api-gateway-export-api.md)」を参照してください。
**注記**
HTTP API は、REST API と同じ AWS 変数をサポートします。詳細については、「[AWSOpenAPI インポート用の変数](import-api-aws-variables.md)」を参照してください。
### 検証情報のインポート
API のインポート時に、API Gateway から 3 つのカテゴリの検証情報が提供されます。
**Info**
プロパティは OpenAPI 仕様では有効ですが、そのプロパティは HTTP API ではサポートされていません。
たとえば、次の OpenAPI 3.0 スニペットは、HTTP API がリクエストの検証をサポートしていないため、インポート時に情報を生成します。API Gateway は、`requestBody` フィールドと `schema` フィールドを無視します。
```
"paths": {
"/": {
"get": {
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Body"
}
}
}
}
}
}
...
},
"components": {
"schemas": {
"Body": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
}
...
}
...
}
```
**警告**
プロパティまたは構造は、OpenAPI 仕様では無効ですが、API の作成をブロックしません。API Gateway でこれらの警告を無視して API の作成を続行するか、警告時に API の作成を停止するかを指定できます。
次の OpenAPI 3.0 ドキュメントでは、HTTP API は Lambda プロキシと HTTP プロキシの統合のみをサポートしているため、インポート時に警告が生成されます。
```
"x-amazon-apigateway-integration": {
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
}
```
**エラー**
OpenAPI 仕様が無効であるか、形式が正しくありません。API Gateway は、不正な形式のドキュメントからリソースを作成できません。エラーを修正してから、もう一度やり直してください。
次の API 定義では、HTTP API は OpenAPI 3.0 仕様のみをサポートしているため、インポート時にエラーが発生します。
```
{
"swagger": "2.0.0",
"info": {
"title": "My API",
"description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
"version": "1.0"
}
...
}
```
別の例として、OpenAPI では、ユーザーが特定のオペレーションに複数のセキュリティ要件を適用した API を定義できますが、API Gateway はこれをサポートしません。各オペレーションには、IAM 認可、Lambda オーソライザー 、または JWT オーソライザーのいずれかしか持つことができません。複数のセキュリティ要件をモデル化しようとすると、エラーが発生します。
### AWS CLI を使用した API のインポート
次の [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) コマンドは、OpenAPI 3.0 定義ファイル `api-definition.json` を HTTP API としてインポートします。
**Example**
```
aws apigatewayv2 import-api --body file://api-definition.json
```
**Example**
次のサンプル OpenAPI 3.0 定義をインポートして、HTTP API を作成することができます。
```
{
"openapi": "3.0.1",
"info": {
"title": "Example Pet Store",
"description": "A Pet Store API.",
"version": "1.0"
},
"paths": {
"/pets": {
"get": {
"operationId": "GET HTTP",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
},
"post": {
"operationId": "Create Pet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPetResponse"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "POST",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
}
},
"/pets/{petId}": {
"get": {
"operationId": "Get Pet",
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}",
"payloadFormatVersion": 1.0
}
}
}
},
"x-amazon-apigateway-cors": {
"allowOrigins": [
"*"
],
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-amzm-header",
"x-apigateway-header",
"x-api-key",
"authorization",
"x-amz-date",
"content-type"
]
},
"components": {
"schemas": {
"Pets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
},
"Empty": {
"type": "object"
},
"NewPetResponse": {
"type": "object",
"properties": {
"pet": {
"$ref": "#/components/schemas/Pet"
},
"message": {
"type": "string"
}
}
},
"Pet": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"price": {
"type": "number"
}
}
},
"NewPet": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/PetType"
},
"price": {
"type": "number"
}
}
},
"PetType": {
"type": "string",
"enum": [
"dog",
"cat",
"fish",
"bird",
"gecko"
]
}
}
}
}
```
# API Gateway から HTTP API をエクスポートする
HTTP API を作成したら、API Gateway から API の OpenAPI 3.0 定義をエクスポートできます。エクスポートするステージを選択するか、API の最新の設定をエクスポートできます。エクスポートした API 定義を API Gateway にインポートして、同一の API をもう 1 つ作成することもできます。API 定義のインポートの詳細については、「[HTTP API のインポート](http-api-open-api.md#http-api-import)」を参照してください。
## AWS CLI を使用してステージの OpenAPI 3.0 定義をエクスポートする
次の [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) コマンドは、`prod` という名前の API ステージの OpenAPI 定義を、`stage-definition.yaml` という名前の YAML ファイルにエクスポートします。エクスポートされた定義ファイルには、デフォルトで [API Gateway 拡張](api-gateway-swagger-extensions.md)が含まれます。
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type YAML \
--specification OAS30 \
--stage-name prod \
stage-definition.yaml
```
## AWS CLI を使用して API の最新変更の OpenAPI 3.0 定義をエクスポートする
次の [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) コマンドは、HTTP API の OpenAPI 定義を `latest-api-definition.json` という名前の JSON ファイルにエクスポートします。このコマンドはステージを指定しないため、API Gateway は、ステージにデプロイされているかどうかに関係なく、API の最新の設定をエクスポートします。エクスポートされた定義ファイルには、[API Gateway 拡張](api-gateway-swagger-extensions.md)は含まれません。
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type JSON \
--specification OAS30 \
--no-include-extensions \
latest-api-definition.json
```
詳細については、*Amazon API Gateway バージョン 2 API リファレンス*の「[ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods)」を参照してください。
## API Gateway コンソールを使用して OpenAPI 3.0 定義をエクスポートする
以下の手順は、HTTP API の OpenAPI 定義をエクスポートする方法を示しています。
**API Gateway コンソールを使用して OpenAPI 3.0 定義をエクスポートするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. HTTP API を選択します。
1. メインナビゲーションペインの **[開発]** で、**[エクスポート]** を選択します。
1. API をエクスポートするには、以下のオプションから選択してください。
![\[HTTP API のエクスポートオプション。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/export-http-api.png)
1. **[ソース]** で、OpenAPI 3.0 定義のソースを選択します。エクスポートするステージを選択するか、API の最新の設定をエクスポートできます。
1. [API Gateway 拡張機能を含める](api-gateway-swagger-extensions.md)場合は、**[API Gateway 拡張機能を含める]** をオンにします。
1. **[出力形式]** では、出力形式を選択します。
1. [**ダウンロード**] を選択します。