# API Gateway HTTP API
REST API と HTTP API は、いずれも RESTful API 製品です。REST API は HTTP API よりも多くの機能をサポートしていますが、HTTP API は低価格で提供できるように最小限の機能で設計されています。詳細については、「[REST API と HTTP API のどちらかを選択する](http-api-vs-rest.md)」を参照してください。
HTTP API を使用して、AWS Lambda 関数またはルーティング可能な HTTP エンドポイントにリクエストを送信できます。たとえば、バックエンドの Lambda 関数と統合する HTTP API を作成できます。クライアントが API を呼び出すと、API Gateway はリクエストを Lambda 関数に送信し、関数のレスポンスをクライアントに返します。
HTTP API は、[OpenID Connect](https://openid.net/developers/how-connect-works/) と [OAuth 2.0](https://oauth.net/2/) 認可をサポートしています。クロスオリジンリソース共有 (CORS) と自動デプロイのサポートが組み込まれています。
AWS マネジメントコンソール、AWS CLI、API、CloudFormation、または SDK を使用して HTTP API を作成できます。
**Topics**
+ [API Gateway で HTTP API を開発する](http-api-develop.md)
+ [HTTP API を公開してユーザーが呼び出せるようにする](http-api-publish.md)
+ [API Gateway で HTTP API を保護する](http-api-protect.md)
+ [API Gateway で HTTP API をモニタリングする](http-api-monitor.md)
+ [API Gateway における HTTP API の問題のトラブルシューティング](http-api-troubleshooting.md)
# 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 変数をサポートします。詳細については、「[OpenAPI インポート用の AWS 変数](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. API Gateway コンソール ([https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)) にサインインします。
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. [**ダウンロード**] を選択します。
# HTTP API を公開してユーザーが呼び出せるようにする
ステージとカスタムドメイン名を使用して、クライアントが呼び出す API を発行できます。
API ステージは、API のライフサイクル状態への論理的なリファレンスです (例: `dev`、`prod`、`beta`、`v2` など)。各ステージは、API のデプロイの名前付きリファレンスで、クライアントアプリケーションから呼び出すことができます。API の各ステージに対して、さまざまな統合と設定を構成できます。
カスタムドメイン名を使用すると、クライアントがデフォルト URL ではなく API を呼び出すための、よりシンプルで直感的な URL `https://api-id.execute-api.region.amazonaws.com/stage` を提供できます。
**注記**
API Gateway API のセキュリティを強化するため、`execute-api.{region}.amazonaws.com` ドメインは[パブリックサフィックスリスト (PSL)](https://publicsuffix.org/) に登録されます。セキュリティ強化のため、API Gateway API のデフォルトドメイン名に機密な Cookie を設定する必要が生じた場合は、`__Host-` プレフィックスの付いた Cookie の使用をお勧めします。このプラクティスは、クロスサイトリクエストフォージェリ (CSRF) 攻撃からドメインを防ぐ際に役立ちます。詳細については、Mozilla 開発者ネットワークの「[Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes)」ページを参照してください。
**Topics**
+ [API Gateway の HTTP API のステージ](http-api-stages.md)
+ [API Gateway での HTTP API のセキュリティポリシー](http-api-ciphers.md)
+ [API Gateway での HTTP API のカスタムドメイン名](http-api-custom-domain-names.md)
# API Gateway の HTTP API のステージ
API ステージは、API のライフサイクル状態への論理的なリファレンスです (例: `dev`、`prod`、`beta`、`v2` など)。API ステージは API ID とステージ名で識別され、API の呼び出しに使用する URL に含まれます。各ステージは、API のデプロイの名前付きリファレンスで、クライアントアプリケーションから呼び出すことができます。
ステージには、API のベース URL から呼び出される `$default` のステージを作成することができます。ベース URL は、`https://{api_id}.execute-api.{region}.amazonaws.com/` のような形式になります。この URL を使用して API ステージを呼び出します。
デプロイは、API 設定のスナップショットです。ステージに API をデプロイすると、クライアントがその API を呼び出すことができます。変更を有効にするには、API をデプロイする必要があります。自動デプロイを有効にすると、API に対する変更が自動的にリリースされます。
# API Gateway で REST API のステージ変数を使用する
ステージ変数は、HTTP API のステージに対して定義できるキーと値のペアです。環境変数と同様に機能し、API のセットアップで使用できます。
ステージ変数は、認証情報などの機密データに使用されることを意図していません。機密データを統合に渡すには、AWS Lambda オーソライザーを使用します。Lambda オーソライザーの出力では、機密データを統合に渡すことができます。詳細については、「[Lambda オーソライザーのレスポンス形式](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response)」を参照してください。
## 例 – ステージ変数を使用して HTTP 統合エンドポイントをカスタマイズする
たとえば、ステージ変数を定義し、その値を HTTP プロキシ統合の HTTP エンドポイントとして設定することができます。後で、関連付けられたステージ変数名を使用してエンドポイントを参照できます。これにより、各ステージで異なるエンドポイントで同じ API セットアップを使用できます。同様に、ステージ変数を使用して、API の各ステージに異なる AWS Lambda 関数の統合を指定できます。
ステージ変数を使用して HTTP 統合エンドポイントをカスタマイズするには、まずステージ変数の名前と値 (`url` など) を `example.com` の値で設定する必要があります。次に、HTTP プロキシ統合を設定します。エンドポイントの URL を入力する代わりに、ステージ変数の値、**http://\$1\$1stageVariables.url\$1** を使用するように API Gateway に指示できます 。この値を指定すると、API Gateway は、ランタイムに API のステージに応じてステージ変数の `${}` を置き換えます。
同様に、ステージ変数を参照して Lambda 関数名や AWS のロールの ARN を指定することができます。
ステージ変数値として Lambda 関数名を指定する場合は、その Lambda 関数に対するアクセス許可を手動で設定する必要があります。次の [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) コマンドは、Lambda 関数に対するアクセス許可を設定します。
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
# API Gateway での HTTP API の API Gateway ステージ変数リファレンス
次のような場合に、HTTP API に API Gateway ステージ変数を使用できます。
## HTTP 統合 URI
ステージ変数は、次の例に示すように、HTTP 統合 URI の一部として使用できます。
+ プロトコルのない完全な URI – `http://${stageVariables.}`
+ 完全なドメイン – `http://${stageVariables.}/resource/operation`
+ サブドメイン – `http://${stageVariables.}.example.com/resource/operation`
+ パス – `http://example.com/${stageVariables.}/bar`
+ クエリ文字列 – `http://example.com/foo?q=${stageVariables.}`
## Lambda 関数
ステージ変数は、次の例に示すように、Lambda 関数の統合名やエイリアスの代わりに使用できます。
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**注記**
Lambda 関数にステージ変数を使用するには、関数が API と同じアカウントにある必要があります。ステージ変数は、クロスアカウント Lambda 関数をサポートしていません。
## AWS 統合認証情報
次の例に示すように、ステージ変数を AWS ユーザーまたはロールの認証情報 ARN の一部として使用できます。
+ `arn:aws:iam:::${stageVariables.}`
# API Gateway での HTTP API のセキュリティポリシー
API Gateway は、すべての HTTP API エンドポイントに `TLS_1_2` のセキュリティポリシーを適用します。
*セキュリティポリシー*とは、Amazon API Gateway が提供する TLS の最小バージョンと暗号スイートの事前定義された組み合わせです。TLS プロトコルは、クライアントとサーバーの間の改ざんや傍受などのネットワークセキュリティの問題に対処します。クライアントがカスタムドメインを介して API に TLS ハンドシェイクを確立すると、セキュリティポリシーにより、TLS バージョンと暗号スイートのオプションが適用されます。ここで使用するオプションは、クライアントが選択できます。このセキュリティポリシーは、TLS 1.2 および TLS 1.3 トラフィックを受け入れ、TLS 1.0 トラフィックを拒否します。
## HTTP API でサポートされている TLS プロトコルと暗号
次の表は、HTTP API でサポートされている TLS プロトコルを示しています。
| **TLS プロトコル** | **TLS\$11\$12 セキュリティポリシー** |
| --- | --- |
| TLSv1.3 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| TLSv1.2 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
次の表は、HTTP API の TLS 1\$12 セキュリティポリシーで使用できる TLS 暗号について説明しています。
| **TLS 暗号** | **TLS\$11\$12 セキュリティポリシー** |
| --- | --- |
| TLS-AES-128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| TLS-AES-256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| TLS-CHACHA20-POLY1305-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| ECDHE-ECDSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| ECDHE-RSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| ECDHE-ECDSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| ECDHE-RSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| ECDHE-ECDSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| ECDHE-RSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| ECDHE-ECDSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| ECDHE-RSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/success_icon.svg) はい |
## OpenSSL および RFC の暗号名
OpenSSL と IETF RFC 5246 では、同じ暗号に異なる名前を使用します。暗号名のリストについては、「[OpenSSL および RFC の暗号名](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names)」を参照してください。
## REST API と WebSocket API に関する情報
REST API と WebSocket API の詳細については、「[API Gateway でカスタムドメインのセキュリティポリシーを選択する](apigateway-custom-domain-tls-version.md)」と「[API Gateway での WebSocket API のセキュリティポリシー](websocket-api-ciphers.md)」を参照してください。
# API Gateway での HTTP API のカスタムドメイン名
*カスタムドメイン名*は、API ユーザーに提供できる、よりシンプルで直感的な URL です。
API のデプロイ後、お客様 (およびその顧客) は、以下の形式のデフォルトのベース URL を使用して API を呼び出すことができます。
```
https://api-id.execute-api.region.amazonaws.com/stage
```
*api-id* は API Gateway が生成します。*region* は AWS リージョンであり、*stage* は API のデプロイ時にユーザーが指定します。
URL のホスト名の部分 (`api-id.execute-api.region.amazonaws.com`) は、API エンドポイントを参照します。デフォルトの API エンドポイント名は、ランダムに生成され、再呼び出しが難しく、ユーザーフレンドリではありません。
カスタムドメイン名を使用すると、API のホスト名を設定し、代替パスを API にマッピングするための基本パス (`myservice` など) を選択できます。たとえば、API のよりわかりやすい ベース URL は以下のようになります。
```
https://api.example.com/myservice
```
## 考慮事項
以下の考慮事項は、カスタムドメイン名の使用に影響する可能性があります。
+ リージョン別カスタムドメイン名は、REST API や HTTP API に関連付けることができます。API Gateway バージョン 2 の API を使用すると、REST API のリージョン別カスタムドメイン名を作成および管理できます。
+ TLS の最小バージョンでは、TLS 1.2 のみがサポートされます。
+ API エンドポイントにマッピングするために DNS プロバイダーのリソースレコードを作成または更新する必要があります。このマッピングを行わないと、カスタムドメイン名宛ての API リクエストが API Gateway に届きません。
+ ワイルドカード証明書を使用すると、デフォルトのクォータを超えることなく、ほぼ無数のドメイン名をサポートできます。詳細については、「[ワイルドカードカスタムドメイン名](#http-wildcard-custom-domain-names)」を参照してください。
## 前提条件
カスタムドメイン名を作成するための前提条件は、以下のとおりです。
### ドメイン名を登録する
API のカスタムドメイン名を設定するには、登録されたインターネットドメイン名が必要です。インターネットドメインを登録するには、[Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) を使用するか、任意のサードパーティのドメインレジストラを使用できます。カスタムドメイン名は、登録したインターネットドメインのサブドメイン名またはルートドメイン名 ("Zone Apex" とも呼ばれます) にすることができます。
ドメイン名は [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) 仕様に準拠している必要があり、ラベルあたり最大 63オクテット、合計 255 オクテットを含めることができます。
### カスタムドメイン名の証明書
API のカスタムドメイン名を設定する前に、ACM で SSL/TLS 証明書を準備する必要があります。カスタムドメイン名を作成する AWS リージョンで ACM を使用できない場合は、そのリージョンの API Gateway に証明書をインポートする必要があります。
SSL/TLS 証明書をインポートするには、カスタムドメイン名の PEM 形式の SSL/TLS 認証本文、そのプライベートキー、およびカスタムドメイン名の証明書チェーンを提供する必要があります。
ACM に保存された各証明書は ARN によって識別されます。ACM 発行の証明書により、プライベートキーなど証明書の機密の詳細が漏れる心配はありません。AWS で管理された証明書をドメイン名で使用するには、その ARN を単に参照します。
アプリケーションで証明書ピンニング (SSL ピンニングとも呼ばれる) を使用して ACM 証明書を固定すると、AWS が証明書を更新した後にアプリケーションがドメインに接続できないことがあります。詳細については、「*AWS Certificate Manager ユーザーガイド*」の「[証明書のピンニングの問題](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html)」を参照してください。
## ワイルドカードカスタムドメイン名
ワイルドカードカスタムドメイン名を使用すると、[デフォルトのクォータ](limits.md)を超えずにほぼ無数のドメイン名をサポートできます。たとえば、各お客様に個別のドメイン名を付けることができます `customername.api.example.com`。
ワイルドカードカスタムドメイン名を制作するためには、ルートドメインの可能なすべてのサブドメインを表すカスタムドメインの最初のサブドメインとして、ワイルドカード (`*`) を指定します。
たとえば、ワイルドカードカスタムドメイン名として `*.example.com` を使用すると、`a.example.com`、`b.example.com`、`c.example.com` などのサブドメインが生成され、これらはすべて同じドメインにルーティングされます。
ワイルドカードカスタムドメイン名は、API Gateway の標準のカスタムドメイン名とは異なる設定をサポートします。たとえば、1 つの AWS アカウントで、`*.example.com` と `a.example.com` を異なる動作に設定できます。
ワイルドカードカスタムドメイン名を作成するには、DNS または E メール検証方法を使用して検証された証明書を ACM から発行してもらう必要があります。
**注記**
別の AWS アカウントで作成済みのカスタムドメイン名と競合するようなワイルドカードカスタムドメイン名を作成することはできません。たとえば、アカウント A で `a.example.com` が作成済みである場合、アカウント B はワイルドカードカスタムドメイン名として `*.example.com` を作成できません。
アカウント A とアカウント B の所有者が同じである場合は、[AWS サポートセンター](https://console.aws.amazon.com/support/home#/)に連絡して例外をリクエストできます。
## カスタムドメイン名に関する次のステップ
HTTP API のカスタムドメイン名を設定するには、「API Gateway 開発者ガイド」の「REST API」セクションの説明に従います。
まず、カスタムドメイン名の証明書を指定します。詳細については、「[AWS Certificate Manager で証明書を準備する](how-to-specify-certificate-for-custom-domain-name.md)」を参照してください。次に、リージョン別カスタムドメイン名を作成します。詳細については、「[API Gateway でリージョン別カスタムドメイン名を設定する](apigateway-regional-api-custom-domain-create.md)」を参照してください。
# API ステージを HTTP API のカスタムドメイン名にマッピングする
API マッピングを使用して、API ステージをカスタムドメイン名に接続します。ドメイン名を作成し、DNS レコードを設定したら、API マッピングを使用して、カスタムドメイン名を使用して API にトラフィックを送信します。
API マッピングは、API、ステージ、およびオプションでマッピングに使用するパスを指定します。たとえば、API の `production` ステージを `https://api.example.com/orders` にマッピングできます。
HTTP API と REST API ステージを同じカスタムドメイン名にマッピングできます。
API マッピングを作成する前に、API、ステージ、およびカスタムドメイン名が必要です。カスタムドメイン名の作成と設定の詳細については、「[API Gateway でリージョン別カスタムドメイン名を設定する](apigateway-regional-api-custom-domain-create.md)」を参照してください。
## API リクエストのルーティング
API マッピングは、例えば `orders/v1/items` と `orders/v2/items` のように、複数のレベルで設定できます。
複数のレベルを持つ API マッピングの場合、API Gateway は、一致するパスが最も長い API マッピングにリクエストをルーティングします。API Gateway は、API マッピング用に設定されたパスだけを考慮し、呼び出す API を選択します。API ルートは考慮しません。リクエストに一致するパスがない場合、API Gateway は空のパス `(none)` にマッピングした API にリクエストを送信します。
複数のレベルの API マッピングを使用するカスタムドメイン名の場合、API Gateway は、一致するプレフィックスが最も長い API マッピングにリクエストをルーティングします。
たとえば、次の API マッピングを持つカスタムドメイン名 `https://api.example.com` を考えてます。
1. API 1 にマッピングされている `(none)`。
1. API 2 にマッピングされている `orders`。
1. API 3 にマッピングされている `orders/v1/items`。
1. API 4 にマッピングされている `orders/v2/items`。
1. API 5 にマッピングされている `orders/v2/items/categories`。
| リクエスト | 選択した API | 説明 |
| --- | --- | --- |
| `https://api.example.com/orders` | `API 2` | リクエストは、この API マッピングと完全に一致します。 |
| `https://api.example.com/orders/v1/items` | `API 3` | リクエストは、この API マッピングと完全に一致します。 |
| `https://api.example.com/orders/v2/items` | `API 4` | リクエストは、この API マッピングと完全に一致します。 |
| `https://api.example.com/orders/v1/items/123` | `API 3` | API Gateway は、最も長い一致パスを持つ API マッピングを選択します。リクエストの最後にある `123` は、選択には影響しません。 |
| `https://api.example.com/orders/v2/items/categories/5` | `API 5` | API Gateway は、最も長い一致パスを持つ API マッピングを選択します。 |
| `https://api.example.com/customers` | `API 1` | API Gateway は、空のマッピングをキャッチオールとして使用します。 |
| `https://api.example.com/ordersandmore` | `API 2` | API Gateway は、一致するプレフィックスが最も長い API マッピングを選択します。 単一レベルのマッピングで設定されたカスタムドメイン名の場合 (`https://api.example.com/orders` と`https://api.example.com/` のみなど)、API ゲートウェイは、`ordersandmore` と一致するパスがないため、`API 1` を選択します。 |
## 制限事項
+ API マッピングでは、カスタムドメイン名とマップされた API が同じ AWS アカウントにある必要があります。
+ API マッピングに含めることができるのは、文字、数字、および `$-_.+!*'()/` の文字だけです。
+ API マッピングのパスの最大文字数は 300 文字です。
+ ドメイン名ごとに、複数のレベルで 200 個の API マッピングを設定できます。この制限には、`/prod` などの単一レベルの API マッピングは含まれません。
+ TLS 1.2 セキュリティポリシーでは、HTTP API をリージョン別カスタムドメイン名にだけマッピングできます。
+ WebSocket API を HTTP API または REST API と同じカスタムドメイン名にマッピングすることはできません。
+ 複数レベルの API マッピングを作成する場合、API Gateway はすべてのヘッダー名を小文字に変換します。
## API マッピングを作成する
API マッピングを作成するには、最初にカスタムドメイン名、API、およびステージを作成する必要があります。カスタムドメイン名の作成方法については、「[API Gateway でリージョン別カスタムドメイン名を設定する](apigateway-regional-api-custom-domain-create.md)」を参照してください。
例えば、すべてのリソースを作成する AWS Serverless Application Model テンプレートについては、GitHub で「[Sessions With SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains)」を参照してください。
------
#### [ AWS マネジメントコンソール ]
**API マッピングを作成するには**
1. API Gateway コンソール ([https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)) にサインインします。
1. [**カスタムドメイン名**] を選択します。
1. 既に作成したカスタムドメイン名を選択します。
1. [**API マッピング**] を選択します。
1. [**Configure API mappings (API マッピングの設定)**] を選択します。
1. [**Add new mapping (新しいマッピングを追加)**] を選択します。
1. **API**、**Stage**、必要に応じて **Path** を入力します。
1. **[保存]** を選択します。
------
#### [ AWS CLI ]
次の [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) コマンドは、API マッピングを作成します。この例では、API Gateway が指定された API およびステージに `api.example.com/v1/orders` に対するリクエストを送信します。
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
次の CloudFormation 例は、API マッピングを作成します。
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# HTTP API のデフォルトのエンドポイントを無効にする
デフォルトでは、クライアントは、API Gateway が API 用に生成する `execute-api` エンドポイントを使用して API を呼び出すことができます。クライアントがカスタムドメイン名を使用した場合のみ API にアクセスできるようにするには、デフォルトの `execute-api` エンドポイントを無効にします。デフォルトのエンドポイントを無効にすると、API のすべてのステージに影響します。
次の手順では、HTTP API のデフォルトのエンドポイントを無効にする方法を示します。
------
#### [ AWS マネジメントコンソール ]
1. API Gateway コンソール ([https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)) にサインインします。
1. HTTP API を選択します。
1. API の ID を選択して、**[API の詳細]** ページを開きます。
1. **[API の詳細]** で、**[編集]** を選択します。
1. **[デフォルトのエンドポイント]** で、**[無効化]** を選択します。
1. **[保存]** を選択します。
ステージの自動デプロイを有効にすると、変更を有効にするために API を再デプロイする必要はありません。それ以外の場合は、API を再デプロイする必要があります。
1. (オプション) **[デプロイ]** を選択して API を再デプロイするか、新しいステージを作成して変更を有効にします。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) コマンドは、HTTP API のデフォルトエンドポイントを無効にします。
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
デフォルトエンドポイントを無効にした後は、自動デプロイが有効になっている場合を除き、その変更を有効にするために API をデプロイする必要があります。
次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) コマンドでは、デプロイを作成します。
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# HTTP API のカスタムドメイン名の IP アドレスタイプ
API を作成する場合、ドメイン を呼び出すことができる IP アドレスのタイプを指定します。IPv4 を選択すると、IPv4 アドレスを解決してドメインを呼び出すことができます。デュアルスタックを選択すると、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 アドレスタイプの使用に影響する可能性があります。
+ API Gateway カスタムドメイン名のデフォルトの IP アドレスタイプは IPv4 です。
+ カスタムドメイン名には、マッピングされたすべての API で同じ IP アドレスタイプを使用する必要はありません。デフォルトの API エンドポイントを無効にすると、発信者が API を呼び出す方法が影響を受ける可能性があります。
## カスタムドメイン名の IP アドレスタイプを変更する
IP アドレスタイプは、ドメインのエンドポイント設定を更新して、変更できます。ドメインのエンドポイント設定は、AWS マネジメントコンソール、AWS CLI、CloudFormation、または AWS SDK を使用して、更新できます。
------
#### [ AWS マネジメントコンソール ]
**カスタムドメイン名の IP アドレスタイプを変更するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. パブリックカスタムドメイン名を選択します。
1. **[エンドポイント設定]** を選択します。
1. [IP アドレスタイプ] で、**[IPv4]** または **[デュアルスタック]** を選択します。
1. **[保存]** を選択します。
------
#### [ AWS CLI ]
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) コマンドは、IP アドレスタイプがデュアルスタックになるように API を更新します。
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
出力は次のようになります。
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# API Gateway で HTTP API を保護する
API Gateway は、悪意のあるユーザーやトラフィックの急増など、特定の脅威から API を保護するさまざまな方法を提供します。スロットリングターゲットの設定や相互 TLS の有効化などの戦略を使用して、API を保護できます。このセクションでは、API Gateway を使用してこれらの機能を有効にする方法を説明しています。
**Topics**
+ [HTTP API へのリクエストをスロットリングして API Gateway のスループットを向上させる](http-api-throttling.md)
+ [API Gateway で HTTP API の相互 TLS 認証を有効にする方法](http-api-mutual-tls.md)
# HTTP API へのリクエストをスロットリングして API Gateway のスループットを向上させる
API のスロットリングを設定して、多すぎるリクエストで API の負荷が高くなりすぎないように保護できます。スロットルはベストエフォートベースで適用されるため、これらは保証されたリクエスト上限ではなく、目標として考える必要があります。
API Gateway は、トークンバケットアルゴリズムを使用してトークンでリクエストをカウントし、API へのリクエストを調整します。特に API Gateway では、アカウントのすべての API に送信されるリクエストのレートとバーストをリージョンごとに検証します。トークンバケットアルゴリズムでは、これらの制限の事前定義されたオーバーランがバーストによって許可されますが、場合によっては、他の要因によって制限のオーバーランが発生することがあります。
リクエストの送信数がリクエストの定常レートおよびバーストを超えると、API Gateway はリクエストを調整を開始します。クライアントは、この時点で `429 Too Many Requests` エラーレスポンスを受け取ることがあります。このような例外をキャッチすると、クライアントは失敗したリクエストをレート制限する方法で再送信できます。
API デベロッパーは、API の個々のステージまたはルートに制限を設定して、アカウントのすべての API にわたるパフォーマンス全体を向上させることができます。
## リージョンごとのアカウントレベルのスロットリング
API Gateway はデフォルトで、リージョンごとに AWS アカウント内のすべての API 全体で定常状態のリクエスト/秒 (RPS) を制限します。また、リージョンごとに AWS アカウント内のすべての API にわたってバースト (最大バケットサイズ) を制限します。API Gateway では、バースト制限は、API Gateway が `429 Too Many Requests` エラーレスポンスを返す前に処理する同時リクエスト送信の目標最大数を表します。スロットリングクォータの詳細については、「[Amazon API Gateway のクォータ](limits.md)」を参照してください。
アカウントごとの制限は、指定したリージョンのアカウント内のすべての API に適用されます。このアカウントレベルのレート制限は、申請に応じて引き上げることができます。API のタイムアウトが短く、ペイロードが小さい場合、高い制限を設定できます。リージョンごとのアカウントレベルのスロットリング制限の引き上げを申請するには、[AWS サポートセンター](https://console.aws.amazon.com/support/home#/)にお問い合わせください。詳細については、「[Amazon API Gateway のクォータ](limits.md)」を参照してください。これらの制限は、AWS スロットリングの制限以上に高くすることはできません。
## ルートレベルのスロットリング
特定のステージでまたは API の個々のルートでアカウントレベルのリクエストスロットリング制限を上書きするように、ルートレベルのスロットリングを設定できます。デフォルトのルートスロットリング制限は、アカウントレベルのレート制限を超えることはできません。
AWS CLI を使用して、ルートレベルのスロットリングを設定できます。次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) コマンドは、API の指定されたステージとルートのカスタムスロットリングを設定します。
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"GET /pets":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# API Gateway で HTTP API の相互 TLS 認証を有効にする方法
相互 TLS 認証には、クライアントとサーバー間の双方向認証が必要です。相互 TLS では、クライアントは X.509 証明書を提示して、API にアクセスするためのアイデンティティを検証する必要があります。相互 TLS は、モノのインターネット (IoT) および B2B アプリケーションの一般的な要件です。
相互 TLS は、API Gateway がサポートする他の[認可オペレーションおよび認証オペレーション](apigateway-control-access-to-api.md)と共に使用できます。API Gateway は、クライアントが提供する証明書を Lambda オーソライザーおよびバックエンド統合に転送します。
**重要**
デフォルトでは、クライアントは、API Gateway が API 用に生成する `execute-api` エンドポイントを使用して API を呼び出すことができます。相互 TLS でカスタムドメイン名を使用することによってのみクライアントが API にアクセスできるようにするには、デフォルトの `execute-api` エンドポイントを無効にします。詳細については[HTTP API のデフォルトのエンドポイントを無効にする](http-api-disable-default-endpoint.md)を参照してください。
## 相互 TLS の前提条件
相互 TLS を設定するには、以下が必要です。
+ カスタムドメイン名
+ カスタムドメイン名用の AWS Certificate Manager で構成されている少なくとも 1 つの証明書
+ 設定され Amazon S3 にアップロードされた信頼ストア
### カスタムドメイン名
HTTP API の相互 TLS を有効にするには、API のカスタムドメイン名を設定する必要があります。カスタムドメイン名の相互 TLS を有効にした後、カスタムドメイン名をクライアントに提供できます。相互 TLS が有効なカスタムドメイン名を使用して API にアクセスするには、クライアントは API リクエストで信頼できる証明書を提示する必要があります。詳細な情報は、「[API Gateway での HTTP API のカスタムドメイン名](http-api-custom-domain-names.md)」にあります。
### AWS Certificate Manager が発行した証明書を使用する
パブリックに信頼できる証明書は ACM から直接要求すること、またはパブリック証明書または自己署名証明書をインポートすることができます。ACM で証明書を設定するには、「[ACM](https://console.aws.amazon.com/acm/)」を参照してください。証明書をインポートする場合は、次のセクションを参照してください。
### インポートされた証明書、または AWS Private Certificate Authority 証明書を使用する
ACM にインポートされた証明書、または相互 TLS を用いた AWS Private Certificate Authority からの証明書を使用するには、API Gateway には ACM が発行した `ownershipVerificationCertificate` が必要です。この所有権証明書は、ドメイン名を使用する許可を持っていることを確認するためにのみ使用されます。TLS ハンドシェイクには使用されません。まだ `ownershipVerificationCertificate` を持っていない場合は、[https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/) に進み、その 1 つをセットアップします。
ドメイン名の有効期間中、この証明書を有効にしておく必要があります。証明書の有効期限が切れ、自動更新が失敗した場合、ドメイン名の更新はすべてロックされます。他の変更を加える前に、有効な `ownershipVerificationCertificate` を用いて `ownershipVerificationCertificateArn` を更新する必要があります。`ownershipVerificationCertificate` は、API Gateway の別の相互 TLS ドメインのサーバー証明書として使用できません。証明書を ACM に直接再インポートする場合、発行者は以前と同じである必要があります。
### 信頼ストアの設定
信頼ストアは、`.pem` ファイル拡張子が付いたテキストファイルです。これらは、証明機関からの証明書の信頼できるリストです。相互 TLS を使用するには、API にアクセスするために信頼する X.509 証明書の信頼ストアを作成します。
信頼ストアには、発行元の CA 証明書からルート CA 証明書までの完全な信頼チェーンを含める必要があります。API Gateway は、信頼チェーンに存在する任意の CA によって発行されたクライアント証明書を受け入れます。パブリックまたはプライベート認証機関からの証明書を使用できます。証明書チェーンの最大長は 4 です。自己署名証明書を提供することもできます。信頼ストアでは、次のハッシュアルゴリズムがサポートされています。
+ SHA-256 以上
+ RSA-2048 以上
+ ECDSA-256 以上
API Gateway はいくつかの証明書プロパティを検証します。Lambda オーソライザーを使用して、証明書が失効しているかどうかのチェックなど、クライアントによる API の呼び出し時に追加のチェックを実行できます。API Gateway は、次のプロパティを検証します。
| 検証 | 説明 |
| --- | --- |
| X.509 構文 | 証明書は X.509 構文の要件を満たしている必要があります。 |
| 整合性 | 証明書の内容は、信頼ストアの認証機関によって署名された内容から変更されていないことが必要です。 |
| Validity | 証明書の有効期間は最新のものであることが必要です。 |
| 名前のチェーン/キーのチェーン | 証明書の名前とサブジェクトは、途切れのないチェーンを形成する必要があります。証明書チェーンの最大長は 4 です。 |
### 信頼ストアを 1 つのファイルで Amazon S3 バケットにアップロードします。
**Example certificates.pem**
```
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
...
```
次の [cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) AWS CLI コマンドは、`certificates.pem` を Amazon S3 バケットにアップロードします。
```
aws s3 cp certificates.pem s3://bucket-name
```
## カスタムドメイン名の相互 TLS の設定
HTTP API の相互 TLS を設定するには、API のリージョン別カスタムドメイン名を使用してください。TLS バージョンは 1.2 以上であることが必要です。カスタムドメイン名の作成と設定の詳細については、「[API Gateway でリージョン別カスタムドメイン名を設定する](apigateway-regional-api-custom-domain-create.md)」を参照してください。
**注記**
相互 TLS は、プライベート API ではサポートされていません。
信頼ストアを Amazon S3 にアップロードした後、相互 TLS を使用するようにカスタムドメイン名を設定できます。次の [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html) は、相互 TLS を有効にしたカスタムドメイン名を作成します。
```
aws apigatewayv2 create-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name
```
ドメイン名を作成したら、API オペレーション用に DNS レコードと基本パスのマッピングを設定する必要があります。詳細については[API Gateway でリージョン別カスタムドメイン名を設定する](apigateway-regional-api-custom-domain-create.md)を参照してください。
## 相互 TLS を必要とするカスタムドメイン名を使用して API を呼び出す
相互 TLS が有効な API を呼び出すには、クライアントは API リクエストで信頼できる証明書を提示する必要があります。クライアントが API を呼び出そうとすると、API Gateway は信頼ストアでクライアント証明書の発行者を探します。API Gateway でリクエストを続行するには、証明書の発行者と、ルート CA 証明書までの完全な信頼チェーンが信頼ストアにある必要があります。
以下の例の `curl` コマンドは、`api.example.com,` が含まれるリクエストを `my-cert.pem` に送信します。`my-key.key` は証明書のプライベートキーです。
```
curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com
```
API は、信頼ストアが証明書を信頼している場合にのみ呼び出されます。次の条件により、API Gateway が TLS ハンドシェイクに失敗し、`403` ステータスコードのリクエストが拒否されます。証明書が以下の場合:
+ 信頼されていない
+ 有効期限切れである
+ サポートされているアルゴリズムを使用していない
**注記**
API Gateway は、証明書が失効したかどうかを検証しません。
## 信頼ストアの更新
信頼ストアの証明書を更新するには、新しい証明書バンドルを Amazon S3 にアップロードします。次に、カスタムドメイン名を更新して、更新された証明書を使用することができます。
[Amazon S3 バージョニング](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)を使用して、信頼ストアの複数のバージョンを維持します。新しい信頼ストアバージョンを使用するようにカスタムドメイン名を更新すると、証明書が無効な場合に API Gateway から警告が返されます。
API Gateway は、ドメイン名を更新するときにのみ、証明書の警告を生成します。API Gateway は、以前にアップロードされた証明書の有効期限が切れた場合でも、通知しません。
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) コマンドは、新しいトラストストアバージョンを使用するようにカスタムドメイン名を更新します。
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreVersion='abcdef123'
```
## 相互 TLS を無効にする
カスタムドメイン名の相互 TLS を無効にするには、以下のコマンドに示すように、カスタムドメイン名から信頼ストアを削除します。
次の [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) コマンドは、カスタムドメイン名からトラストストアを削除するようにカスタムドメイン名を更新します。
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=''
```
## HTTP API の相互 TLS のトラブルシューティング
以下では、相互 TLS を有効にするときに発生する可能性のあるエラーや問題に関するトラブルシューティングのアドバイスを示します。
### 証明書の警告のトラブルシューティング
相互 TLS でカスタムドメイン名を作成する場合、信頼ストア内の証明書が有効でない場合に API Gateway から警告が返されます。これは、新しい信頼ストアを使用するようにカスタムドメイン名を更新するときにも発生します。警告は、証明書の問題と、警告の発生元となった証明書のサブジェクトを示します。相互 TLS は引き続き API で有効ですが、一部のクライアントは API にアクセスできない場合があります。
警告の発生元となった証明書を特定するには、信頼ストア内の証明書をデコードする必要があります。`openssl` などのツールを使用して、証明書をデコードし、そのサブジェクトを特定できます。
以下のコマンドは、証明書の内容 (サブジェクトなど) を表示します。
```
openssl x509 -in certificate.crt -text -noout
```
警告の発生元となった証明書を更新または削除してから、新しい信頼ストアを Amazon S3 にアップロードします。新しい信頼ストアをアップロードした後、その信頼ストアを使用するようにカスタムドメイン名を更新します。
### ドメイン名の競合のトラブルシューティング
エラー `"The certificate subject conflicts with an existing certificate from a different issuer."` は、複数の認証機関がこのドメインの証明書を発行したことを表します。証明書の件名ごとに、相互 TLS ドメイン用の API Gateway には 1 人の発行者しか存在できません。1 つの発行者を通じて、その件名に関するすべての証明書を取得する必要があります。管理できない証明書に問題があるけれども、ドメイン名の所有権を証明できる場合は、[連絡先 サポート](https://console.aws.amazon.com/support/cases#/create) からチケットを開きます。
### ドメイン名のステータスメッセージのトラブルシューティング
`PENDING_CERTIFICATE_REIMPORT`: これは、証明書を ACM に再インポートし、検証に失敗したことを意味します。すなわち、新しい証明書には SAN (サブジェクトの別名) があり、`ownershipVerificationCertificate` または証明書のサブジェクトまたは SAN はドメイン名をカバーしないからです。何かが正しく設定されていないか、無効な証明書がインポートされた可能性があります。有効な証明書を ACM に再インポートする必要があります。検証の詳細については、「[ドメインの所有権の検証](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html)」を参照してください。
`PENDING_OWNERSHIP_VERIFICATION`: 以前に検証した証明書の有効期限が切れ、ACM がそれを自動更新できなかったことを意味します。証明書を更新するか、新しい証明書をリクエストする必要があります。証明書の更新の詳細については、「[ACM の管理された証明書の更新に関するトラブルシューティング](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-renewal.html)ガイド」を参照してください。
# API Gateway で HTTP API をモニタリングする
CloudWatch メトリクスと CloudWatch Logs を使用して HTTP API をモニタリングできます。ログとメトリクスを組み合わせることで、エラーをログに記録し、API のパフォーマンスを監視できます。
**注記**
API Gateway は、次の場合にログとメトリクスが生成されない可能性があります。
413 Request Entity Too Large エラー
過剰な 429 Too Many Requests エラー
API マッピングを持たないカスタムドメインに送信されたリクエストからの 400 シリーズのエラー
内部の障害によって発生した 500 シリーズのエラー
**Topics**
+ [API Gateway で HTTP API の CloudWatch メトリクスをモニタリングする](http-api-metrics.md)
+ [API Gateway で HTTP API のログ記録を設定する](http-api-logging.md)
# API Gateway で HTTP API の CloudWatch メトリクスをモニタリングする
CloudWatch を使用して API の実行をモニタリングすることで、API Gateway から raw データを収集し、リアルタイムに近い読み取り可能なメトリクスに加工することができます。これらの統計は 15 か月間記録されるため、履歴情報にアクセスしてウェブアプリケーションやサービスの動作をより的確に把握できます。デフォルトでは、API Gateway のメトリクスデータは 1 分間隔で自動的に CloudWatch に送信されます。メトリクスをモニタリングするには、API 用の CloudWatch ダッシュボードを作成します。CloudWatch ダッシュボードの作成方法の詳細については、「Amazon CloudWatch ユーザーガイド」の「[CloudWatch ダッシュボードの作成](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create_dashboard.html)」を参照してください。**詳細については、*Amazon CloudWatch ユーザーガイド*の「[Amazon CloudWatch とは](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)」を参照してください。
HTTP API では、次のメトリクスがサポートされています。ルートレベルのメトリクスを Amazon CloudWatch に書き込む詳細メトリクスを有効にすることもできます。
| メトリクス | 説明 |
| --- | --- |
| 4xx | 指定された期間に取得されたクライアント側エラーの数。 |
| 5xx | 指定された期間に取得されたサーバー側エラーの数。 |
| カウント | 指定期間内の API リクエストの合計数。 |
| IntegrationLatency | API Gateway がバックエンドにリクエストを中継してから、バックエンドからレスポンスを受け取るまでの時間。 |
| レイテンシー | API Gateway がクライアントからリクエストを受け取ってから、クライアントにレスポンスを返すまでの時間。レイテンシーには、統合のレイテンシーおよびその他の API Gateway のオーバーヘッドが含まれます。 |
| DataProcessed | 処理されたデータの量 (バイト単位)。 |
API Gateway のメトリクスをフィルタリングするには、次の表のディメンションを使用できます。
| ディメンション | 説明 |
| --- | --- |
| ApiId | 指定した API ID で API の API Gateway メトリクスをフィルタリングします。 |
| ApiId、ステージ | 指定した API ID とステージ ID で API ステージの API Gateway メトリクスをフィルタリングします。 |
| ApiId、メソッド、リソース、ステージ | 指定した API ID、ステージ ID、リソースパス、ルート ID で API メソッドの API Gateway メトリクスをフィルタリングします。 詳細な CloudWatch のメトリクスを明示的に有効にしない限り、API Gateway はこれらのメトリクスを送信しません。そのためには、API Gateway V2 REST API の [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) アクションを呼び出して、`detailedMetricsEnabled` プロパティを `true` に更新します。[update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) AWS CLI コマンドを呼び出して `DetailedMetricsEnabled` プロパティを `true` に更新することもできます。このようなメトリクスを有効にすることで、アカウントに追加料金が発生します。詳細については、[Amazon CloudWatch 料金表](https://aws.amazon.com/cloudwatch/pricing/)をご覧ください。 |
# API Gateway で HTTP API のログ記録を設定する
ログ記録を有効にして CloudWatch Logs にログを記録することができます。[ログ変数](http-api-logging-variables.md)を使用して、ログの内容をカスタマイズできます。
セキュリティ体制を向上させるには、HTTP API のすべてのステージのログを CloudWatch Logs に書き込むことをお勧めします。これは、さまざまなコンプライアンスフレームワークに準拠するために必要になる場合があります。詳細については、*AWS Security Hub ユーザーガイド*の「[Amazon API Gateway のコントロール](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)」を参照してください。
HTTP API のログ記録を有効にするには、以下を実行する必要があります。
1. ログ記録を有効にするために必要なアクセス許可がユーザーにあることを確認します。
1. CloudWatch Logs ロググループを作成します。
1. API のステージの CloudWatch Logs ロググループの ARN を指定します。
## ログ記録を有効にするアクセス許可
API のログ記録を有効にするには、 ユーザーに次のアクセス許可が必要です。
**Example**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents",
"logs:FilterLogEvents"
],
"Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:PutResourcePolicy",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:CreateLogGroup",
"logs:DescribeResourcePolicies",
"logs:GetLogDelivery",
"logs:ListLogDeliveries"
],
"Resource": "*"
}
]
}
```
## ロググループを作成し、HTTP API のログ記録を有効にする
ロググループを作成し、AWS マネジメントコンソール または AWS CLI を使用してアクセスログ記録を有効化できます。
------
#### [ AWS マネジメントコンソール ]
1. ロググループを作成します。
コンソールを使用してロググループを作成する方法については、[Amazon CloudWatch Logs ユーザーガイドの「ロググループとログストリームの操作」](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)を参照してください。
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. HTTP API を選択します。
1. プライマリナビゲーションパネルの **[Monitor]** (モニタリング) タブで、**[Logging]** (ログ記録) を選択します。
1. ログ記録を有効にするステージを選択し、**[Select]** (選択) を選択します。
1. **[Edit]** (編集) を選択してアクセスログを有効にします。
1. **[Access logging]** (アクセスのログ記録) を有効にし、CloudWatch Logs を入力して、ログ形式を選択します。
1. **[保存]** を選択します。
------
#### [ AWS CLI ]
次の [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html) コマンドは、ロググループを作成します。
```
aws logs create-log-group --log-group-name my-log-group
```
ログ記録を有効にするには、ロググループの Amazon リソースネーム (ARN) が必要です。ARN 形式は、arn:aws:logs:*region*:*account-id*:log-group:*log-group-name* です。
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) コマンドは、HTTP API の `$default` ステージのログをオンにします。
```
aws apigatewayv2 update-stage --api-id abcdef \
--stage-name '$default' \
--access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}'
```
------
## ログ形式の例
いくつかの一般的なアクセスログ形式の例は API Gateway コンソールで使用できます。それらの例を以下に示します。
+ `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
```
+ `JSON`:
```
{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" }
```
+ `XML`:
```
$context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId
```
+ `CSV` (カンマ区切り値):
```
$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
```
# HTTP API アクセスログをカスタマイズする
次の変数を使用して、HTTP API のアクセスログをカスタマイズできます。HTTP API のアクセスログの詳細については、「[API Gateway で HTTP API のログ記録を設定する](http-api-logging.md)」を参照してください。
| パラメータ | 説明 |
| --- | --- |
| \$1context.accountId | API 所有者の AWS アカウント ID。 |
| \$1context.apiId | API Gateway が API に割り当てる識別子。 |
| \$1context.authorizer.claims.property | メソッドの呼び出し元が正常に認証された後で JSON ウェブトークン (JWT) から返されるクレームのプロパティ (`$context.authorizer.claims.username` など)。詳細については、「[API Gateway の JWT オーソライザーを使用して HTTP API へのアクセスを制御する](http-api-jwt-authorizer.md)」を参照してください。 `$context.authorizer.claims` を呼び出すと NULL が返されます。 |
| \$1context.authorizer.error | オーソライザーから返されたエラーメッセージ。 |
| \$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` が返されます。 |
| \$1context.awsEndpointRequestId | `x-amz-request-id` または `x-amzn-requestId` ヘッダーからの AWS エンドポイントのリクエスト ID。 |
| \$1context.awsEndpointRequestId2 | `x-amz-id-2` ヘッダーからの AWS エンドポイントのリクエスト ID。 |
| \$1context.customDomain.basePathMatched | 受信リクエストが一致した API マッピングのパス。クライアントがカスタムドメイン名を使用して API にアクセスする場合に適用されます。たとえば、クライアントがリクエストを `https://api.example.com/v1/orders/1234` に送信し、リクエストがパス `v1/orders` を持つ API マッピングと一致する場合 、値は `v1/orders` になります。詳細については、「[API ステージを HTTP API のカスタムドメイン名にマッピングする](http-api-mappings.md)」を参照してください。 |
| \$1context.dataProcessed | 処理されたデータの量 (バイト単位)。 |
| \$1context.domainName | API の呼び出しに使用された完全ドメイン名。これは、受信 `Host` ヘッダーと同じである必要があります。 |
| \$1context.domainPrefix | `$context.domainName` の 1 つ目のラベル。 |
| \$1context.error.message | API Gateway エラーメッセージを含む文字列。 |
| \$1context.error.messageString | \$1context.error.message を引用符で囲んだ値、つまり "\$1context.error.message"。 |
| \$1context.error.responseType | `GatewayResponse` のタイプ。詳細については、「[CloudWatch メトリクスを使用して WebSocket API の実行をモニタリングする](apigateway-websocket-api-logging.md)」および「[エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)」を参照してください。 |
| \$1context.extendedRequestId | \$1context.requestId と同等です。 |
| \$1context.httpMethod | 使用される HTTP メソッドです。有効な値には、`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` および `PUT` があります。 |
| \$1context.identity.accountId | リクエストに関連付けられた AWS アカウント ID です。IAM 認可を使用するルートでサポートされています。 |
| \$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)。IAM 認可を使用するルートでサポートされています。 |
| \$1context.identity.clientCert.clientCertPem | クライアントが相互 TLS 認証中に提示した PEM エンコードされたクライアント証明書。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。 |
| \$1context.identity.clientCert.subjectDN | クライアントが提示する証明書のサブジェクトの識別名。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。 |
| \$1context.identity.clientCert.issuerDN | クライアントが提示する証明書の発行者の識別名。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。 |
| \$1context.identity.clientCert.serialNumber | 証明書のシリアル番号。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。 |
| \$1context.identity.clientCert.validity.notBefore | 証明書が無効になる前の日付。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。 |
| \$1context.identity.clientCert.validity.notAfter | 証明書が無効になった日付。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。 |
| \$1context.identity.sourceIp | API Gateway エンドポイントへのリクエストを実行する即時 TCP 接続のソース IP アドレス。 |
| \$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) です。IAM 認可を使用するルートでサポートされています。詳細については、「[https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)」を参照してください。 |
| \$1context.integration.error | 統合から返されたエラーメッセージ。これは \$1context.integrationErrorMessage と同等です。 |
| \$1context.integration.integrationStatus | Lambda プロキシ統合の場合、バックエンドの Lambda 関数コードからではなく、AWS Lambda から返されるステータスコード。 |
| \$1context.integration.latency | 統合レイテンシー (ミリ秒)。これは \$1context.integrationLatency と同等です。 |
| \$1context.integration.requestId | AWS エンドポイントのリクエスト ID これは \$1context.awsEndpointRequestId と同等です。 |
| \$1context.integration.status | 統合から返されたステータスコード。Lambda プロキシ統合では、これは Lambda 関数コードから返されたステータスコードです。 |
| \$1context.integrationErrorMessage | 統合エラーメッセージを含む文字列。 |
| \$1context.integrationLatency | 統合レイテンシー (ミリ秒)。 |
| \$1context.integrationStatus | Lambda プロキシ統合の場合、このパラメータはバックエンド Lambda 関数からではなく、AWS Lambda から返されたステータスコードを表します。 |
| \$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 | API Gateway が API リクエストに割り当てる ID。 |
| \$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.responseLatency | レスポンスレイテンシー (ミリ秒)。 |
| \$1context.responseLength | レスポンスペイロードの長さ (バイト単位)。 |
| \$1context.routeKey | API リクエストのルートキー (例:`/pets`)。 |
| \$1context.stage | API リクエストのデプロイステージ (`beta`、`prod` など)。 |
| \$1context.status | メソッドレスポンスのステータス。 |
# API Gateway における HTTP API の問題のトラブルシューティング
以下のトピックでは、HTTP API の使用時に発生する可能性のあるエラーや問題のトラブルシューティングに関するアドバイスを提供します。
**Topics**
+ [HTTP API Lambda 統合に関する問題のトラブルシューティング](http-api-troubleshooting-lambda.md)
+ [HTTP API JWT オーライザーに関する問題のトラブルシューティング](http-api-troubleshooting-jwt.md)
# HTTP API Lambda 統合に関する問題のトラブルシューティング
次に、HTTP API で [AWS Lambda の統合](http-api-develop-integrations-lambda.md) を使用するときに発生する可能性のあるエラーや問題に関するトラブルシューティングのアドバイスを示します。
## 問題: Lambda 統合のある API が `{"message":"Internal Server Error"}` を返します
内部サーバーエラーのトラブルシューティングを行うには、ログ形式に `$context.integrationErrorMessage` [ログ記録変数](http-api-logging-variables.md)を追加し、HTTP API のログを表示します。これを達成するには、次の操作を行います。
**を使用してロググループを作成するにはAWS マネジメントコンソール**
1. CloudWatch コンソール ([https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)) を開きます。
1. [**ロググループ**] を選択します。
1. [**ロググループの作成**] を選択します。
1. ロググループ名を入力し、[**作成**] を選択します。
1. ロググループの Amazon リソースネーム (ARN) を書き留めます。ARN 形式は、arn:aws:logs:*region*: *account-id*:log-group:*log-group-name* です。HTTP API のアクセスのログ記録を有効にするには、ロググループ ARN が必要です。
**`$context.integrationErrorMessage` ロギング変数を追加するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. HTTP API を選択します。
1. [**モニタリング**] で、[**ログ記録**] を選択します。
1. API のステージを選択します。
1. [**編集**] を選択し、アクセスログを有効にします。
1. [**Log destination**] (ログの送信先) で、前のステップで作成したロググループの ARN を入力します。
1. [**ログの形式**] で、[**CLF**] を選択します。API Gateway はサンプルのログ形式を作成します。
1. ログ形式の末尾に `$context.integrationErrorMessage` を追加します。
1. [**保存**] を選択します。
**API のログを表示するには**
1. ログを生成します。ブラウザまたは `curl` を使用して API を呼び出します。
```
$curl https://api-id.execute-api.us-west-2.amazonaws.com/route
```
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. HTTP API を選択します。
1. [**モニタリング**] で、[**ログ記録**] を選択します。
1. ロギングを有効にした API のステージを選択します。
1. [**CloudWatch のログを表示**] を選択します。
1. 最新のログストリームを選択して、HTTP API のログを表示します。
1. ログエントリは、以下のようになります。
![\[CloudWatch Logs ログエントリに、Lambda からの統合エラーメッセージが表示されます。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/troubleshoot-http-api-logs.png)
ログ形式に `$context.integrationErrorMessage` を追加したため、問題の概要を示すエラーメッセージがログに表示されます。
Lambda 関数コードに問題があることを示す別のエラーメッセージがログに含まれている可能性があります。その場合は、Lambda 関数コードを確認し、Lambda 関数が[必要な形式](http-api-develop-integrations-lambda.md#http-api-develop-integrations-lambda.response)でレスポンスを返すことを確認します。ログにエラーメッセージが含まれていない場合は、トラブルシューティングに役立つ詳細情報のために、ログ形式に `$context.error.message` および `$context.error.responseType` を追加します。
この場合、API Gateway には Lambda 関数を呼び出すために必要なアクセス許可がないことがログに示されます。
API Gateway コンソールで Lambda 統合を作成すると、API Gateway は Lambda 関数を呼び出すためのアクセス許可を自動的に設定します。AWS CLI、CloudFormation、または SDK を使用して Lambda 統合を作成する場合、API Gateway に関数を呼び出すアクセス許可を付与する必要があります。次の [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) コマンドは、さまざまな HTTP API ルートに Lambda 関数を呼び出すためのアクセス許可を付与します。
**Example 例 — HTTP API の `$default` ステージと `$default` ルートの場合**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/\$default/\$default"
```
**Example 例 — HTTP API の `prod` ステージと `test` ルートの場合**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/prod/*/test"
```
Lambda コンソールの [**Permissions (アクセス権限)**] タブで[関数ポリシーを確認](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)します。
API をもう一度呼び出してみてください。Lambda 関数のレスポンスが表示されるはずです。
# HTTP API JWT オーライザーに関する問題のトラブルシューティング
次に、HTTP API で JSON ウェブトークン (JWT) オーソライザーを使用するときに発生する可能性のあるエラーおよび問題のトラブルシューティングに関するアドバイスを示します。
## 問題: API が `401 {"message":"Unauthorized"}` を返します
API からのレスポンスで `www-authenticate` ヘッダーを確認します。
次のコマンドは、`curl` を使用して、`$request.header.Authorization` を ID ソース として使用する JWT オーソライザーを使用して API にリクエストを送信します。
```
$curl -v -H "Authorization: token" https://api-id.execute-api.us-west-2.amazonaws.com/route
```
API からのレスポンスには `www-authenticate` ヘッダーが含まれます。
```
...
< HTTP/1.1 401 Unauthorized
< Date: Wed, 13 May 2020 04:07:30 GMT
< Content-Length: 26
< Connection: keep-alive
< www-authenticate: Bearer scope="" error="invalid_token" error_description="the token does not have a valid audience"
< apigw-requestid: Mc7UVioPPHcEKPA=
<
* Connection #0 to host api-id.execute-api.us-west-2.amazonaws.com left intact
{"message":"Unauthorized"}}
```
この場合、`www-authenticate` ヘッダーには、有効な対象者に対してトークンが発行されなかったことが示されます。API Gateway でリクエストを承認するには、JWT の `aud` または `client_id` クレームが、オーソライザー用に設定されている対象者のエントリの 1 つと一致する必要があります。API Gateway は、`aud` が存在しない場合にのみ、`client_id` を検証します。`aud` と `client_id` の両方が存在する場合、API Gateway は `aud` を評価します。
また、JWTをデコードし、APIが必要とする発行者、対象者、スコープと一致することを確認することもできます。ウェブサイトの [jwt.io](https://jwt.io/) は、ブラウザで JWT をデバッグすることができます。OpenID Foundation では、[JWT で使用するライブラリのリスト](https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/)が管理されます。
JWT オーソライザーの詳細については、「[API Gateway の JWT オーソライザーを使用して HTTP API へのアクセスを制御する](http-api-jwt-authorizer.md)」を参照してください 。