# API Gateway で REST API をデプロイする
API を作成したら、この API をデプロイしてユーザーが呼び出せるようにする必要があります。
API をデプロイするには、API デプロイを作成し、それを ステージに関連付けます。ステージは、API のライフサイクル状態への論理的なリファレンスです (例:`dev` 、`prod`、`beta`、`v2`) 。API ステージは API ID とステージ名によって識別されます。これらは、API を呼び出すために使用する URL に含まれています。各ステージは、API のデプロイの名前付きリファレンスで、クライアントアプリケーションから呼び出すことができます。
**重要**
API を更新するたびに、API を既存のステージまたは新しいステージに再デプロイする必要があります。API の更新には、ルート、メソッド、統合、オーソライザー、リソースポリシーなど、ステージ設定以外のすべての変更が含まれます。
API が進化するにつれて、API の異なるバージョンとしてさまざまなステージにデプロイし続けることができます。API アップデートは、[Canary リリースデプロイ](canary-release.md)としてデプロイすることもできます。これにより、API クライアントは、同じステージで、プロダクションリリースからプロダクションバージョン、および Canary リリースから更新されたバージョンにアクセスできます。
デプロイされた API を呼び出すために、クライアントは API の URL に対してリクエストを送信します。URL は、API のプロトコル (HTTP(S) または (WSS))、ホスト名、ステージ名、および (REST API の場合) リソースパスによって決定されます。ホスト名とステージ名によって、API のベース URL が決まります。
API のデフォルトドメイン名を使用すると、特定のステージ (`{stageName}`) の REST API のベース URL (たとえば) は、次の形式になります。
```
https://{restapi-id}.execute-api.{region}.amazonaws.com/{stageName}
```
API のデフォルトのベース URL をよりユーザーフレンドリなものにするには、カスタムドメイン名 (たとえば、`api.example.com`) を作成し、API のデフォルトのホスト名と置き換えることができます。カスタムドメイン名で複数の API をサポートするには、API ステージをベースパスにマッピングする必要があります。
`{api.example.com}` のカスタムドメイン名と API ステージがカスタムドメイン名の下の (`{basePath}`) ベースパスにマップされると、REST API のベース URL は次のようになります。
```
https://{api.example.com}/{basePath}
```
ステージごとに、アカウントレベルのデフォルトのリクエストスロットリング制限を調整し、API キャッシュを有効にすることで、API のパフォーマンスを最適化できます。また、API コールのログを CloudTrail や CloudWatch に記録し、バックエンドで API リクエストを認証するためのクライエント証明書を選択することもできます。さらに、ランタイムに、ステージ固有の環境コンテキストを API 統合に渡すために、個々のメソッドのステージレベル設定を上書きし、ステージ変数を定義することができます。
ステージを使用すると、API の堅牢なバージョン管理が可能になります。たとえば、API を `test` ステージと、`prod` ステージにデプロイし、`test` ステージをテストビルドとして使用し、`prod` ステージを安定したビルドとして使用できます。更新がテストに合格したら、`test` ステージを `prod` ステージに昇格させることができます。昇格は、API を `prod` 本番稼働ステージに再デプロイするか、ステージ変数値をステージ名 `test` から `prod` に更新することによって行うことができます。
このセクションでは、[API Gateway コンソール](https://console.aws.amazon.com/apigateway)を使用するか、[API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/) を呼び出して API をデプロイする方法について説明します。他のツールを使用するには、[AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/) または [AWS SDK](https://aws.amazon.com/developer/tools/#sdk) のドキュメントを参照してください。
**Topics**
+ [API Gateway で REST API のデプロイを作成する](set-up-deployments.md)
+ [API Gateway で REST API のステージをセットアップする](set-up-stages.md)
+ [API Gateway の Canary リリースデプロイの設定](canary-release.md)
+ [再デプロイが必要な REST API の更新](updating-api.md)
# API Gateway で REST API のデプロイを作成する
API Gateway では、REST API のデプロイは [Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) リソースにより表現されます。これは、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースによって表される API の実行可能ファイルと似ています。
クライアントが API を呼び出すには、デプロイを作成してステージを関連付ける必要があります。ステージは、[Stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) リソースによって表されます。これは、メソッド、統合、モデル、マッピングテンプレート、Lambda オーソライザー (以前のカスタムオーソライザー) を含む API のスナップショットを表します。API を更新すると、新しいステージを既存のステージに関連付けることによって API を再デプロイできます。ステージの作成については、[API Gateway で REST API のステージをセットアップする](set-up-stages.md) で説明されています。
**Topics**
+ [デプロイを作成する](#create-deployment)
+ [API デプロイの次のステップ](#apigateway-deployment-next-steps)
## デプロイを作成する
次の手順は、REST API のデプロイを作成する方法を示しています。
------
#### [ AWS マネジメントコンソール ]
REST API は、初めてデプロイする前に作成済みであることが必要です。詳細については、「[API Gateway で REST API を開発する](rest-api-develop.md)」を参照してください。
API Gateway コンソールでは、デプロイを作成して新規または既存のステージに関連付けることで API をデプロイできます。
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. [**API**] ナビゲーションペインで、デプロイする API を選択します。
1. [**リソース**] ペインで、[**API のデプロイ**] を選択します。
1. **[ステージ]** では、次の中から選択します。
1. 新しいステージを作成するには、**[新規ステージ]** を選択し、**[ステージ名]** に名前を入力します。オプションで **[デプロイの説明]** にこのデプロイの説明を入力できます。
1. 既存のステージを選択するには、ドロップダウンメニューからステージ名を選択します。**[デプロイの説明]** に新しいデプロイの説明を入力することもできます。
1. ステージに関連付けられていないデプロイを作成するには、**[ステージなし]** を選択します。後で、このデプロイをステージに関連付けることができます。
1. [**デプロイ**] を選択します。
------
#### [ AWS CLI ]
デプロイを作成するときは、[Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) リソースをインスタンス化します。
次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドは、新しいデプロイを作成します。
```
aws apigateway create-deployment --rest-api-id rest-api-id
```
このデプロイをステージに関連付けるまで、API を呼び出すことはできません。既存のステージでは、そのために、ステージの [deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) プロパティを新しく作成されたデプロイ ID で更新します。次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドは、ステージを新しいデプロイで更新します。コンソールでは、これは**アクティブなデプロイ**と呼ばれます。
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name 'stage-name' \
--patch-operations op='replace',path='/deploymentId',value='deployment-id'
```
デプロイを作成するときに、同時に新しいステージに関連付けることもできます。次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドは、新しいデプロイを作成し、それを `beta` という新しいステージに関連付けます。
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name beta
```
------
API を再デプロイするには、同じ手順を実行します。同じステージを再利用できます。
## API デプロイの次のステップ
API デプロイの次のステップは次のとおりです。
ステージ設定の変更
API のデプロイ後に、ステージ設定を変更して API キャッシュ、ログ記録、またはリクエストのスロットリングを有効または無効にすることができます。また、バックエンドで API Gateway を検証するためのクライアント証明書を選択したり、ランタイム時に API 統合にデプロイコンテキストを渡すようにステージ変数を設定したりすることもできます。詳細については、「[ステージ設定の変更](set-up-stages.md#how-to-stage-settings)」を参照してください。
ステージ設定を変更したら、変更を有効にするために API を再デプロイする必要があります。
ログ記録の有効化など、更新した設定が新しい IAM ロールを必要とする場合、API を再デプロイせずに必要な IAM ロールを追加できます。ただし新しい IAM ロールが有効になるまでには、数分かかる場合があります。有効になるまでは、ログ作成オプションを有効にしていたとしても、API 呼び出しのトレースは記録されません。
さまざまなデプロイステージの組み合わせを選択する
デプロイは API スナップショットを表し、ステージはスナップショットへのパスを定義するため、別のデプロイとステージの組み合わせを選択して、ユーザーが API の異なるバージョンを呼び出す方法を制御できます。これは、API のステージを前のデプロイにロールバックしたり、API の「プライベートブランチ」をパブリックブランチにマージしたりする場合に役立ちます。
次の手順では、この操作を API Gateway コンソールの [**Stage Editor (ステージエディター)**] を使用して行う方法について説明します。以下では、API を複数回デプロイした経験があることを前提としています。
1. まだ **[ステージ]** ペインを開いていない場合は、メインナビゲーションペインで **[ステージ]** を選択します。
1. 更新するステージを選択します。
1. **[デプロイ履歴]** タブで、ステージに使用するデプロイを選択します。
1. **[アクティブなデプロイの変更]** を選択します。
1. アクティブなデプロイを変更することを確認し、**[アクティブなデプロイを作成]** ダイアログボックスの **[アクティブなデプロイを変更]** を選択します。
デプロイ固有のデータを API に渡します。
デプロイで、ランタイムに API 統合に対してデプロイ固有のデータを渡すようにステージ変数を設定または変更できます。この操作は、[**ステージエディター**] の [**ステージ変数**] タブで行うことができます。詳細については、「[API Gateway で REST API のステージ変数を使用する](stage-variables.md)」の手順を参照してください。
# API Gateway で REST API のステージをセットアップする
ステージは、デプロイに対する名前付きのリファレンスで、API のスナップショットです。[Stage (ステージ)](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)を使用して、特定のデプロイを管理および最適化します。たとえば、ステージ設定を設定して、キャッシングを有効にしたり、リクエストスロットリングをカスタマイズしたり、ログ記録を設定したり、ステージ変数を定義したり、テストのために Canary リリースをアタッチしたりすることができます。次のセクションでは、ステージを作成して設定する方法を示します。
## 新しいステージを作成する
最初のデプロイ後に、さらにステージを追加して既存のデプロイに関連付けることができます。API Gateway コンソールを使用して新しいステージを作成して使用するか、API をデプロイするときに既存のステージを選択できます。通常は、API を再デプロイする前に、API デプロイに新しいステージを追加できます。API Gateway コンソールを使用して新しいステージを作成するには、次の手順に従います。
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メインナビゲーションペインで、API の下にある **[ステージ]** を選択します。
1. **[ステージ]** ナビゲーションペインから、**[ステージの作成]** を選択します。
1. **[ステージ名]** に、名前を入力します（例: **prod**）。
**注記**
ステージ名には、英数字、ハイフン、およびアンダースコアのみ含めることができます。最大長は 128 文字です。
1. (オプション)。**[説明]** に、ステージの説明を入力します。
1. **[デプロイメント]** には、このステージに関連付ける既存の API デプロイの日付と時刻を選択します。
1. **[追加設定]** では、ステージの追加設定を指定できます。
1. **[テーブルの作成]** を選択します。
## ステージ設定の変更
API が正常にデプロイされると、ステージにデフォルト設定が入力されます。API キャッシュやログ記録などのステージ設定は、コンソールまたは API Gateway REST API を使用して変更できます。REST API のデフォルトエンドポイントを変更した場合、ステージを更新すると、その変更は API のすべてのステージに反映されます。次の手順では、API Gateway コンソールの**ステージエディタ**を使用してその方法を示します。
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メインナビゲーションペインで、API の下にある **[ステージ]** を選択します。
1. [**Stages**] (ステージ) ペインで、ステージの名前を選択します。
1. **[ステージの詳細]** セクションで、**[編集]** を選択します。
1. (オプション) **[ステージの説明]** で、説明を編集します。
1. **[その他の設定]** で、以下の設定を変更します。
**キャッシュ設定**
ステージの API キャッシュを有効にするには、**[API キャッシュをプロビジョニング]** をオンにします。次に、**[デフォルトのメソッドレベルのキャッシュ]**、**[キャッシュキャパシティ]**、**[キャッシュデータを暗号化]**、**[キャッシュの有効期限 (TTL)]**、およびキーごとのキャッシュの無効化の要件を設定します。
デフォルトのメソッドレベルのキャッシュをオンにするか、特定のメソッドについてメソッドレベルのキャッシュをオンにするまで、キャッシュはアクティブになりません。
キャッシュ設定の詳細については、「[API Gateway での REST API のキャッシュ設定](api-gateway-caching.md)」を参照してください。
API ステージの API キャッシュを有効にすると、AWS アカウントに対して API キャッシュの使用料金が発生することがあります。キャッシュは AWS 無料利用枠の対象ではありません。
**スロットリング設定**
この API に関連付けられたすべてのメソッドに対してステージレベルのスロットリング目標を設定するには、**[スロットリング]** をオンにします。
[**Rate**] (レート) に目標レートを入力します。これは、トークンバケットにトークンを追加するレート (秒あたりのリクエスト数) です。ステージレベルのレートは、[アカウントレベル](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits)のレート ([API Gateway での REST API の設定および実行に関するクォータ](api-gateway-execution-service-limits-table.md) で指定) を超えないものとします。
**[バースト]** に目標バーストレートを入力します。バーストレートとは、トークンバケットの容量です。これにより、目標レートよりも多くのリクエストが一定の期間にわたって許可されます。このステージレベルのバーストレートは、[アカウントレベル](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits)のバーストレート ([API Gateway での REST API の設定および実行に関するクォータ](api-gateway-execution-service-limits-table.md) で指定) を超えないものとします。
スロットリングレートはハードリミットではなく、ベストエフォートベースで適用されます。場合によっては、クライアントは設定されている目標を超えることがあります。コストの管理や API へのアクセスのブロックを行う際にスロットリングに依存しないでください。[AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) を使用してコストをモニタリングすること、および [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) を使用して API リクエストを管理することを検討してください。
**ファイアウォールと証明書の設定**
AWS WAF ウェブ ACL をステージに関連付けるには、**[ウェブ ACL]** ドロップダウンリストからウェブ ACL を選択します。必要に応じて、[**Block API Request if WebACL cannot be evaluated (Fail- Close) (WebACL を評価できない場合は API リクエストをブロックする (フェイルクローズ))**] を選択します。
ステージのクライアント証明書を選択するには、**[クライアント証明書]** ドロップダウンメニューから証明書を選択します。
1. [**続行**] をクリックしてください。
1. 変更内容を確認してから、**[変更を保存]** を選択します。
1. この API Gateway API のこのステージに関連付けられているすべてのメソッドで Amazon CloudWatch Logs を有効にするには、**[ログとトレース]** セクションで **[編集]** を選択します。
**注記**
CloudWatch Logs を有効にするには、ユーザーの代わりに API Gateway が CloudWatch Logs に情報を書き込むことを可能にする IAM ロールの ARN も指定する必要があります。そのためには、[**API**] メインナビゲーションペインから [**設定**] を選択します。次に、**[CloudWatch ログロール]** に IAM ロールの ARN を入力します。
一般的なアプリケーションシナリオでは、IAM ロールは [AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) のマネージドポリシーをアタッチできます。
IAM ロールには、以下の信頼関係ステートメントも含まれている必要があります。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
Amazon CloudWatch の詳細については、*[Amazon CloudWatch ユーザーガイド](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)*を参照してください。
1. **[CloudWatch Logs]** ドロップダウンメニューからログ記録レベルを選択します。ログ記録レベルは、以下のとおりです。
+ **オフ** — この段階ではログ記録はオンになっていません。
+ **エラーのみ** — ログ記録はエラーに対してのみ有効になっています。
+ **エラーと情報ログ** — ログ記録はすべてのイベントに対して有効になっています。
1. **[データトレース]** を選択すると、API Gateway がステージのデータトレースログを CloudWatch に報告します。このログは API のトラブルシューティングに役立ちますが、機密データが記録される可能性があります。
**注記**
本番稼働用 API では **[データトレース]** を有効にしないことをお勧めします。
1. API Gateway から CloudWatch に `API calls`、`Latency`、`Integration latency`、`400 errors`、`500 errors` の API メトリクスをレポートするには、**[詳細なメトリクス]** を選択します。CloudWatch の詳細については、「Amazon CloudWatch ユーザーガイド」の「[基本モニタリングと詳細モニタリング](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html)」を参照してください。
**重要**
アカウントではメソッドレベルの CloudWatch メトリクスへのアクセスに対して課金されますが、API レベルまたはステージレベルのメトリクスでは課金されません。
1. 送信先へのアクセスログを有効にするには、**[カスタムのアクセスログ]** をオンにします。
1. **[アクセスログの送信先 ARN]** に、ロググループまたは Firehose ストリームの ARN を入力します。
Firehose の ARN 形式は `arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}` です。Firehose ストリームの名前は `amazon-apigateway-{your-stream-name}` にする必要があります。
1. **[ログの形式]** にログの形式を入力します。ログ形式の例について詳しくは、「[API Gateway での CloudWatch によるログの形式](set-up-logging.md#apigateway-cloudwatch-log-formats)」を参照してください。
1. API ステージで [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) トレースを有効にするには、**[X-Ray トレース]** を選択します。詳細については、「[API Gateway で X-Ray を使用して REST API へのユーザーリクエストをトレースする](apigateway-xray.md)」を参照してください。
1. **[Save changes]** (変更の保存) をクリックします。API を再デプロイして新しい設定を有効にします。
## ステージレベルの設定のオーバーライド
ステージレベルの設定をカスタマイズしたら、API メソッドごとにそれらを上書きできます。オプションによっては、AWS アカウントに追加料金がかかる場合があります。
1. メソッドのオーバーライドを設定するには、セカンダリナビゲーションペインでステージを展開し、メソッドを選択します。
![\[セカンダリナビゲーションペインでステージを展開し、メソッドを選択します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/method-override-view-new-console.png)
1. 次に、**[メソッドオーバーライド]** で **[編集]** を選択します。
1. メソッドレベルの CloudWatch 設定を有効にするには、**CloudWatch Logs** でログ記録レベルを選択します。
1. メソッドのデータトレースログ記録を有効にするには、**[データトレース]** を選択します。
**注記**
本番稼働用 API では **[データトレース]** を有効にしないことをお勧めします。
1. メソッドレベルの詳細メトリクスを有効にするには、**[詳細なメトリクス]** を選択します。アカウントではメソッドレベルの CloudWatch メトリクスへのアクセスに対して課金されますが、API レベルまたはステージレベルのメトリクスでは課金されません。
1. メソッドレベルのスロットリングを有効にするには、**[スロットリング]** を選択します。適切なメソッドレベルのオプションを入力します。スロットリングの詳細については、「[API Gateway のスループットを向上させるために REST API へのリクエストをスロットリングする](api-gateway-request-throttling.md)」を参照してください。
1. メソッドレベルのキャッシュを設定するには、**[メソッドキャッシュを有効にする]** を選択します。**[ステージの詳細]** でデフォルトのメソッドレベルのキャッシュ設定を変更しても、この設定には影響しません。
1. **[保存]** を選択します。
# Amazon Bedrock AgentCore Gateway のターゲットとして API Gateway REST API を追加する
Amazon Bedrock AgentCore Gateway は、AI エージェントデベロッパーが API Gateway REST API をモデルコンテキストプロトコル (MCP) 互換ツールとして公開するための安全な方法を提供します。AgentCore Gateway はターゲットを使用してツールを定義します。ステージをターゲットとして追加すると、Gateway はエージェントのツールへのアクセスを可能にする単一の MCP URL になります。詳細については、「*Amazon Bedrock AgentCore Gateway デベロッパーガイド*」の「[ターゲットとしての API Gateway REST API のステージ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-api-gateway.html)」を参照してください。
API Gateway ターゲットは、AgentCore Gateway を REST APIsのステージに接続します。ステージ全体をターゲットとして含めることも、リソースを選択することもできます。API Gateway ターゲットを作成すると、AgentCore Gateway は受信 MCP リクエストを HTTP リクエストに変換し、レスポンスのフォーマットを処理します。MCP クライアントは、`tools/list` メソッドを使用して API ドキュメントを取得し、`tools/call` メソッドを使用して API を呼び出すことができます。
## 考慮事項
AgentCore Gateway にステージをターゲットとして追加する場合、次の考慮事項が使用に影響する場合があります。
+ AgentCore Gateway が既に必要です。
+ パブリック REST API のみがサポートされています。
+ API のデフォルトのエンドポイントを無効にすることはできません。
+ API のすべてのメソッドには、[オペレーション名](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html#apigw-PutMethod-request-operationName)を定義するか、ステージをターゲットとして追加するときに名前の上書きを作成する必要があります。この名前は、エージェントが メソッドとやり取りするために使用するツール名として使用されます。
+ アウトバウンド認証には、`API_KEY`、`NO_AUTH`、または `GATEWAY_IAM_ROLE` 認証情報プロバイダータイプを使用して、ゲートウェイが API にアクセスできるようにすることができます。`API_KEY` 認証情報プロバイダーは AgentCore Gateway によって定義されます。既存の API Gateway API キーを使用できます。詳細については、「[アウトバウンド認証のセットアップ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-outbound-auth.html)」を参照してください。
+ Amazon Cognito ユーザープールまたは Lambda オーソライザーを使用して API へのアクセスを制御する場合、MCP クライアントは API にアクセスできません。
+ API は AgentCore Gateway と同じアカウントとリージョンに存在する必要があります。
## AgentCore Gateway のターゲットとして API のステージを追加する
次の手順は、API のステージを AgentCore Gateway のターゲットとして追加する方法を示しています。
**AgentCore Gateway のターゲットとして API のステージを追加するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. ステージにデプロイされる REST API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択します。
1. **[ステージアクション]**、**[MCP ターゲットの作成]** の順に選択します。
1. **AgentCore Gateway** で、AgentCore Gateway を選択します。
1. **[ターゲット名]** に、ターゲット名を入力します。
1. **[ターゲットの説明]** に、説明を入力します。
1. 提供された API とステージを維持します。
1. **[API リソースの選択]** で、AgentCore Gateway を使用するエージェントがアクセスできる API のリソースを選択します。
リソースを選択しない場合、エージェントはドキュメントを表示したり、エンドポイントを呼び出すことはできません。
1. リソースとメソッドの組み合わせは、ツールのオペレーションです。オペレーションに名前がない場合は、名前の上書きを作成します。
メソッドの作成時に、メソッドのオペレーション名を定義することもできます。
1. **[アウトバウンド認証設定]** では、**[IAM ロール]**、**[認可なし]**、または **[API キー]** のいずれかを選択します。
1. **[ターゲットの作成]** を選択します。
API にアクセスできるすべての AgentCore Gateway を表示するには、メインナビゲーションペインで **[MCP ターゲット]** セクションを選択します。このセクションでは、ステージにデプロイされたリージョン内の任意の API の MCP ターゲットを作成できます。**[MCP ターゲットの作成]** を選択し、前のステップに従います。
AgentCore Gateway コンソールで、ターゲットに使用できるツールを表示したり、ターゲットを編集したりすることもできます。詳細については、「[既存の AgentCore Gateway にターゲットを追加する](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets.html)」を参照してください。
# ステージを削除する
ステージが不要になったら、それを削除して未使用のリソースに対する請求を避けることができます。次の手順は、API Gateway コンソールを使用してステージを削除する方法を示しています。
**警告**
ステージを削除すると、対応する API の一部または全部を API 発信者が使用できなくなる場合があります。ステージの削除は元に戻すことができません。ただし、ステージを再作成して同じデプロイに関連付けることができます。
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択します。
1. **[ステージ]** ペインで、削除するステージを選択してから **[ステージアクション]**、**[ステージの削除]** を選択します。
1. プロンプトが表示されたら、「**confirm**」と入力し、**[削除]** を選択します。
# API Gateway で API ステージのタグをセットアップする
API Gateway では、API ステージにタグを追加したり、ステージからタグを削除したり、タグを表示したりすることができます。これを行うには、API Gateway コンソール、AWS CLI/SDK、または API Gateway REST API を使用できます。
ステージは、その親 REST API からタグを継承することもできます。詳細については、「[Amazon API Gateway V1 API でのタグの継承](apigateway-tagging-supported-resources.md#apigateway-tagging-inheritance)」を参照してください。
API Gateway リソースのタグ付けの詳細については、「[API Gateway リソースのタグ付け](apigateway-tagging.md)」を参照してください。
**Topics**
+ [API Gateway コンソールを使用した API ステージのタグのセットアップ](#set-up-tags-using-console)
+ [AWS CLI を使用して API ステージのタグを設定する](#set-up-tags-using-cli)
+ [API Gateway REST API を使用した API ステージのタグのセットアップ](#set-up-tags-using-api)
## API Gateway コンソールを使用した API ステージのタグのセットアップ
次の手順では、API ステージのタグを設定する方法を説明します。
**API Gateway コンソールを使用して API ステージのタグを設定するには**
1. [API Gateway コンソール] にサインインします。
1. 既存の API を選択するか、リソース、メソッド、および対応する統合を含む新しい API を作成します。
1. ステージを選択するか、新しいステージに API をデプロイします。
1. メインナビゲーションペインで、**[ステージ]** を選択します。
1. **[タグ]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. [**Manage tags (タグの管理)**] を選択します。
1. **[タグエディター]** で、**[新しいタグの追加]** を選択します。[**キー**] フィールドにタグキー (`Department` など) を入力し、[**値**] フィールドにタグ値 (`Sales` など) を入力します。**[保存]** を選択してタグを保存します。
1. 必要に応じて、ステップ 5 を繰り返して API ステージにさらにタグを追加します。ステージあたりのタグの最大数は 50 です。
1. 既存のステージからタグを削除するには、**[削除]** を選択します。
1. API が API Gateway コンソールで既にデプロイされているという場合は、それを再度デプロイして変更を有効にする必要があります。
## AWS CLI を使用して API ステージのタグを設定する
AWS CLI で [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) コマンドまたは [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) コマンドを使用して API ステージのタグを設定できます。API ステージから 1 つ以上のタグを削除するには、[untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) コマンドを使用できます。
次の [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) コマンドは、`test` ステージを作成するときにタグを追加します。
```
aws apigateway create-stage --rest-api-id abc1234 --stage-name test --description 'Testing stage' --deployment-id efg456 --tag Department=Sales
```
次の [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) コマンドは、`prod` ステージにタグを追加します。
```
aws apigateway tag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/prod --tags Department=Sales
```
次の [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) コマンドは、`test` ステージから `Department=Sales` タグを削除します。
```
aws apigateway untag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/test --tag-keys Department
```
## API Gateway REST API を使用した API ステージのタグのセットアップ
API Gateway REST API を使用して API ステージのタグを設定するには、次のいずれかの操作を行います。
+ API ステージにタグ付けするには [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) を呼び出します。
+ API ステージから 1 つまたは複数のタグを削除するには [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html) を呼び出します。
+ 作成する API ステージに 1 つまたは複数のタグを追加するには [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) を呼び出します。
また、API ステージでタグを記述するには [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html) を呼び出します。
### API ステージのタグ付け
ステージ (`m5zr3vnks7`) に API (`test`) をデプロイした後は、[https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) を呼び出すことで、ステージをタグ付けします。必須のステージである Amazon リソースネーム (ARN) (`arn:aws:apigateway:us-east-1::/restapis/m5zr3vnks7/stages/test`) は URL エンコードされている必要があります (`arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest`)。
```
PUT /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest
{
"tags" : {
"Department" : "Sales"
}
}
```
前回のリクエストを使用して既存のタグを新しい値で更新することもできます。
[https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) を呼び出してステージを作成するときに、ステージにタグ付けできます。
```
POST /restapis//stages
{
"stageName" : "test",
"deploymentId" : "adr134",
"description" : "test deployment",
"cacheClusterEnabled" : "true",
"cacheClusterSize" : "500",
"variables" : {
"sv1" : "val1"
},
"documentationVersion" : "test",
"tags" : {
"Department" : "Sales",
"Division" : "Retail"
}
}
```
### API ステージのタグ解除
ステージから `Department` タグを削除するには、[https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html) を呼び出します。
```
DELETE /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest?tagKeys=Department
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
複数のタグを削除するには、クエリ式でタグキーのカンマ区切りのリストを使用します (例: `?tagKeys=Department,Division,…`)。
### API ステージのタグを説明する
特定のステージで既存のタグを記述するには、[https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html) を呼び出します。
```
GET /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
正常に終了すると、レスポンスは以下のようになります。
```
200 OK
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-tags-{rel}.html",
"name": "tags",
"templated": true
},
"tags:tag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags"
},
"tags:untag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags{?tagKeys}",
"templated": true
}
},
"tags": {
"Department": "Sales"
}
}
```
# API Gateway で REST API のステージ変数を使用する
ステージ変数は、REST API のデプロイステージと関連付けられた設定属性として定義できるキーと値のペアです。環境変数と同様に機能し、API のセットアップやマッピングテンプレートで使用できます。API Gateway のデプロイステージでは、API ごとに複数のリリースステージを管理し、ステージ変数を使用して、さまざまなバックエンドエンドポイントとやり取りするように API デプロイステージを設定できます。
ステージ変数は、認証情報などの機密データに使用されることを意図していません。機密データを統合に渡すには、AWS Lambda オーソライザーを使用します。Lambda オーソライザーの出力では、機密データを統合に渡すことができます。詳細については、「[API Gateway Lambda オーソライザーからの出力](api-gateway-lambda-authorizer-output.md)」を参照してください。
## ステージ変数のユースケース
ステージ変数のユースケースを次に示します。
**別のバックエンドエンドポイントを指定する**
API は HTTP プロキシとして `GET` リクエストをバックエンドウェブホストに渡すことができます。ステージ変数を使用すると、API の呼び出し元が本番用エンドポイントを呼び出すときに API Gateway が `example.com` を呼び出すようにできます。次に、API の呼び出し元がベータステージを呼び出すと、API Gateway は `beta.example.com` などの別のウェブホストを呼び出します。同様に、ステージ変数を使用して、API で各ステージに別の AWS Lambda 関数名を指定することができます。ステージ変数を使用して、あるステージでは `GET` リクエストを HTTP プロキシ統合にポイントし、別のステージでは Lambda プロキシ統合にポイントするなど、異なる統合エンドポイントを設定することはできません。
ステージ変数値として Lambda 関数名を指定する場合は、その Lambda 関数に対するアクセス許可を手動で設定する必要があります。API Gateway コンソールで Lambda 関数を指定すると、AWS CLI コマンドがポップアップ表示され、適切なアクセス許可を設定できるようになります。これを行うには、次の AWS CLI コマンドを使用することもできます。
```
aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
**マッピングテンプレートを使用して情報を渡す**
また、マッピングテンプレートでステージ変数にアクセスしたり、AWS Lambda または HTTP バックエンドに設定パラメータを渡したりできます。例えば、API で複数のステージ用に同じ Lambda 関数を再利用するが、ステージに応じて、関数が別の Amazon DynamoDB テーブルからデータを読み取るようにしたい場合があります。Lambda 関数のリクエストを生成するマッピングテンプレートで、ステージ変数を使用してテーブル名を Lambda に渡すことができます。
ステージ変数を使用するには、まずステージ変数を設定し、次に値を割り当てます。例えば、HTTP 統合エンドポイントをカスタマイズするには、まず `url` ステージ変数を作成し、次に API の統合リクエストでステージ変数値 **http://\$1\$1stageVariables.url\$1** を入力します。この値により、API が実行中のステージに基づいて、ランタイムにステージ変数 `${}` を置き換えるよう API Gateway が指示されます。詳細については、「[API Gateway で REST API のステージ変数をセットアップする](how-to-set-stage-variables-aws-console.md)」を参照してください。
# API Gateway で REST API のステージ変数をセットアップする
このセクションでは、Amazon API Gateway コンソールを使用してサンプル API の 2 つのデプロイステージにさまざまなステージ変数を設定する方法を示します。API Gateway でステージ変数を使用する方法を理解するには、このセクションのすべての手順に従うことをお勧めします。
## 前提条件
開始する前に、以下の前提条件を満たしていることを確認します。
+ API が API Gateway で使用可能であることが必要です。「[API Gateway で REST API を開発する](rest-api-develop.md)」の手順に従います。
+ API は少なくとも 1 度はデプロイする必要があります。「[API Gateway で REST API をデプロイする](how-to-deploy-api.md)」の手順に従います。
+ デプロイされた API の最初のステージを作成済みである必要があります。「[新しいステージを作成する](set-up-stages.md#how-to-create-stage-console)」の手順に従います。
## ステージ変数を使用し、API を通じて HTTP エンドポイントを呼び出す
この手順では、HTTP エンドポイントのステージ変数と API の 2 つのステージを作成する方法について説明します。さらに、このセクションの次の手順で使用するステージ変数 `url`、`stageName`、`function` を作成します。
**ステージ変数を使用し、API を通じて HTTP エンドポイントを呼び出すには**
1. API Gateway コンソール ([https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)) にサインインします。
1. API を作成し、API のルートリソースで `GET` メソッドを作成します。統合タイプを **HTTP** に設定し、**[エンドポイント URL]** を **http://\$1\$1stageVariables.url\$1** に設定します。
1. **beta** という名前の新しいステージに API をデプロイします。
1. メインナビゲーションペインで、**[ステージ]** を選択してから、**beta** ステージを選択します。
1. **[ステージ変数]** タブで **[編集]** を選択します。
1. **[ステージ変数を追加]** を選択します。
1. [**名前**] に**url**と入力してください。**[値]** に「**httpbin.org/get**」と入力します。
1. **[ステージ変数の追加]** を選択し、次の操作を行います。
[**名前**] に**stageName**と入力してください。**[値]** に「**beta**」と入力します。
1. **[ステージ変数の追加]** を選択し、次の操作を行います。
[**名前**] に**function**と入力してください。**[値]** に「**HelloWorld**」と入力します。
1. **[保存]** を選択します。
1. 次に、2 つ目のステージを作成します。**[ステージ]** ナビゲーションペインから、**[ステージの作成]** を選択します。[**Stage name (ステージ名)**] に **prod** と入力します。**[デプロイメント]** から最近のデプロイを選択し、**[ステージの作成]** を選択します。
1. **beta** ステージと同じように、3 つのステージ変数 (**url**、**stageName**、**function**) をそれぞれ異なる値 (**petstore-demo-endpoint.execute-api.com/petstore/pets**、**prod**、**HelloEveryone**) に設定します。
1. [**ステージ**] ナビゲーションペインで、[**beta**] を選択します。**[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーし、Web ブラウザに API の呼び出し URL を入力します。これにより、API のルートリソースで **beta** ステージの `GET` リクエストが開始されます。
**注記**
[**Invoke URL**] リンクは、**beta** ステージの API のルートリソースを指します。Web ブラウザに URL を入力すると、ルートリソースで **beta** ステージの `GET` メソッドが呼び出されます。ルートリソースそのものではなく子リソースでメソッドが定義されている場合は、Web ブラウザに URL を入力すると、`{"message":"Missing Authentication Token"}` エラーレスポンスが返されます。この場合、特定の子リソースの名前を [**呼び出し URL**] リンクに追加する必要があります。
1. **beta** ステージの `GET` リクエストから取得するレスポンスを次に示します。また、ブラウザを使用し、**http://httpbin.org/get** に移動して結果を確認することもできます。この値は **beta** ステージの `url` 変数に割り当てられました。2 つのレスポンスは同一です。
1. [**ステージ**] ナビゲーションペインで、[**prod**] ステージを選択します。**[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーし、Web ブラウザに API の呼び出し URL を入力します。これにより、API のルートリソースで **prod** ステージの `GET` リクエストが開始されます。
1. **prod** ステージの `GET` リクエストから取得するレスポンスを次に示します。ブラウザを使用し、**http://petstore-demo-endpoint.execute-api.com/petstore/pets** に移動して結果を確認できます。この値は **prod** ステージの `url` 変数に割り当てられました。2 つのレスポンスは同一です。
## ステージ固有のメタデータを HTTP バックエンドに渡す
この手順では、クエリパラメータ式でステージ変数値を使用して、ステージ固有のメタデータを HTTP バックエンドに渡す方法について説明します。前の手順で宣言した `stageName` ステージ変数を使用します。
**ステージ固有のメタデータを HTTP バックエンドに渡すには**
1. [**リソース**] ナビゲーションペインで、**GET** メソッドを選択します。
メソッドの URL にクエリ文字列パラメータを追加するには、**[メソッドリクエスト]** タブを選択し、**[メソッドリクエストの設定]** セクションで、**[編集]** を選択します。
1. **[URL クエリ文字列パラメータ]** を選択してから、次の操作を行います。
1. [**クエリ文字列の追加**] を選択します。
1. [**名前**] に**stageName**と入力してください。
1. **[必須]** と **[キャッシュ]** はオフのままにしておきます。
1. **[保存]** を選択します。
1. **[統合リクエスト]** タブを選択し、**[統合リクエスト設定]** セクションで **[編集]** を選択します。
1. **[エンドポイント URL]** では、以前に定義した URL 値に **?stageName=\$1\$1stageVariables.stageName\$1** を追加し、**エンドポイント URL** 全体が **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1** になるようにします。
1. **[API をデプロイ]** を選択し、**beta** ステージを選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択します。[**ステージ**] ナビゲーションペインで、[**beta**] を選択します。**[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーし、Web ブラウザに API の呼び出し URL を入力します。
**注記**
ここでベータステージを使用するのは、(`url` 変数「http://httpbin.org/get」によって指定される) HTTP エンドポイントがクエリパラメータ式を受け取り、レスポンスで `args` オブジェクトとしてそれらを返すためです。
1. 次のレスポンスが返されます。`beta` ステージ変数に割り当てられた `stageName` は、`stageName` 引数としてバックエンドで渡されることに注意してください。
![\[url ステージ変数を使用した HTTP エンドポイントにおける API の GET メソッドからのレスポンス。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)
## ステージ変数を使用して API 経由で Lambda 関数を呼び出す
この手順では、ステージ変数を使用して API のバックエンドとして Lambda 関数を呼び出す方法について説明します。「[ステージ変数を使用し、API を通じて HTTP エンドポイントを呼び出す](#how-to-set-stage-variables-aws-console-http-endpoint)」で宣言された `function` ステージ変数を使用します。
Lambda 関数をステージ変数の値に設定するときは、関数のローカル名を使用します。エイリアスまたはバージョン仕様は、**HelloWorld**、**HelloWorld:1**、**HelloWorld:alpha** のように含めます。関数の ARN を使用しないでください (例: **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**)。API Gateway コンソールは、 Lambda 関数のステージ変数値が非修飾関数名であると想定し、指定されたステージ変数を ARN に展開します。
**ステージ変数を使用して API 経由で Lambda 関数を呼び出すには**
1. デフォルトの Node.js ランタイムを使用して、**HelloWorld** という名前の Lambda 関数を作成します。コードには次が含まれている必要があります。
```
export const handler = function(event, context, callback) {
if (event.stageName)
callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
else
callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
};
```
Lambda 関数の作成方法の詳細については、「[REST API コンソール入門](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function)」を参照してください。
1. **[リソース]** ペインで **[リソースの作成]** を選択し、次の操作を行います。
1. **[リソースパス]** には、**/**を選択します。
1. **[リソース名]** に「**lambdav1**」と入力します。
1. **[リソースの作成]** を選択します。
1. **[/lambdav1]** リソースを選択し、**[メソッドを作成]** を選択します。
次に、以下の操作を実行します。
1. **[メソッドタイプ]** には、**GET** を選択します。
1. **[統合タイプ]** で、**[Lambda 関数]** を選択します。
1. **[Lambda プロキシ統合]** はオフのままにしておきます。
1. [**Lambda 関数**] に「`${stageVariables.function}`」と入力します。
![\[function ステージ変数の指定通りに、Lambda 関数と統合された GET メソッドを作成しします。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**ヒント**
**[アクセス許可を追加]** コマンドのプロンプトが表示されたら、[add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) コマンドをコピーします。`function` ステージ変数に今後割り当てられる各 Lambda 関数でコマンドを実行します。たとえば、`$stageVariables.function` 値が `HelloWorld` の場合、以下の AWS CLI コマンドを実行します。
```
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
```
これを行わなかった場合、メソッドを呼び出すと `500 Internal Server Error` レスポンスが発生します。ステージ変数に割り当てられる Lambda 関数で `${stageVariables.function}` を置き換えます。
![\[AWS CLI コマンドを実行して、作成したメソッドで呼び出した Lambda 関数にアクセス許可を追加します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)
1. **[メソッドの作成]** を選択します。
1. API を、**prod** ステージと **beta** ステージの両方にデプロイします。
1. メインナビゲーションペインで、**[ステージ]** を選択します。[**ステージ**] ナビゲーションペインで、[**beta**] を選択します。**[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーし、Web ブラウザに API の呼び出し URL を入力します。Enter キーを押す前に **/lambdav1** を URL に追加します。
次のレスポンスが返されます。
```
"Hello, World! I'm not sure where I'm calling from..."
```
## ステージ変数を使用してステージ固有のメタデータを Lambda 関数に渡す
この手順では、ステージ変数を使用して、ステージ固有の設定メタデータを Lambda 関数に渡す方法を示します。`POST` メソッドと入力マッピングテンプレートを使用して、前に宣言した `stageName` ステージ変数でペイロードを生成します。
**ステージ変数を使用してステージ固有のメタデータを Lambda 関数に渡すには**
1. **[/lambdav1]** リソースを選択し、**[メソッドを作成]** を選択します。
次に、以下の操作を実行します。
1. **[メソッドタイプ]** では、**POST** を選択します。
1. **[統合タイプ]** で、**[Lambda 関数]** を選択します。
1. **[Lambda プロキシ統合]** はオフのままにしておきます。
1. [**Lambda 関数**] に「`${stageVariables.function}`」と入力します。
1. **[アクセス許可を追加]** コマンドのプロンプトが表示されたら、[add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) コマンドをコピーします。`function` ステージ変数に今後割り当てられる各 Lambda 関数でコマンドを実行します。
1. **[メソッドの作成]** を選択します。
1. **[統合リクエスト]** タブを選択し、**[統合リクエスト設定]** セクションで **[編集]** を選択します。
1. **[マッピングテンプレート]**、**[マッピングテンプレートの追加]** の順に選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** には、次のテンプレートを入力します。
```
#set($inputRoot = $input.path('$'))
{
"stageName" : "$stageVariables.stageName"
}
```
**注記**
マッピングテンプレートでは、ステージ変数を引用符で囲んで参照する必要があります (`"$stageVariables.stageName"` または `"${stageVariables.stageName}"` のように)。他の場所では、引用符なしで参照する必要があります (`${stageVariables.function}` のように)。
1. **[保存]** を選択します。
1. API を、**beta** ステージと **prod** ステージの両方にデプロイします。
1. REST API クライアントを使用してステージ固有のメタデータを渡すには、以下を実行します。
1. [**ステージ**] ナビゲーションペインで、[**beta**] を選択します。**[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーし、REST API クライアントの入力フィールドに API の呼び出し URL を入力します。リクエストを送信する前に **/lambdav1** を追加します。
次のレスポンスが返されます。
```
"Hello, World! I'm calling from the beta stage."
```
1. **[ステージ]** ナビゲーションペインで、**prod** を選択します。**[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーし、REST API クライアントの入力フィールドに API の呼び出し URL を入力します。リクエストを送信する前に **/lambdav1** を追加します。
次のレスポンスが返されます。
```
"Hello, World! I'm calling from the prod stage."
```
1. **テスト**機能を使用してステージ固有のメタデータを渡すには、以下を実行します。
1. **[リソース]** ナビゲーションペインで、**[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[関数]** に「**HelloWorld**」と入力します。
1. **StageName** に「**beta**」と入力します。
1. **[テスト]** を選択します。`POST` リクエストに本文を追加する必要はありません。
次のレスポンスが返されます。
```
"Hello, World! I'm calling from the beta stage."
```
1. 前の手順を繰り返して、**Prod** ステージをテストできます。**StageName** に「**Prod**」と入力します。
次のレスポンスが返されます。
```
"Hello, World! I'm calling from the prod stage."
```
# API Gateway での REST API の API Gateway ステージ変数リファレンス
次のような場合に、API Gateway ステージ変数を使用できます。
## パラメータマッピング式
ステージ変数は、API メソッドのリクエストまたはレスポンスヘッダーパラメータ用のパラメータマッピング式で、一部を置き換えることなく使用できます。次の例では、`$` を使用したり、`{...}` で囲むことなくステージ変数を参照しています。
+ `stageVariables.`
## マッピングテンプレート
ステージ変数は、次の例に示すように、マッピングテンプレートのどこでも使用できます。
+ `{ "name" : "$stageVariables."}`
+ `{ "name" : "${stageVariables.}"}`
## HTTP 統合 URI
ステージ変数は、次の例に示すように、HTTP 統合 URLの一部として使用できます。
+ プロトコルのない完全な URI – `http://${stageVariables.}`
+ 完全なドメイン – `http://${stageVariables.}/resource/operation`
+ サブドメイン – `http://${stageVariables.}.example.com/resource/operation`
+ パス – `http://example.com/${stageVariables.}/bar`
+ クエリ文字列 – `http://example.com/foo?q=${stageVariables.}`
## AWS 統合 URI
ステージ変数は、次の例に示すように、AWS URI アクションまたはパスコンポーネントの一部として使用できます。
+ `arn:aws:apigateway:::${stageVariables.}`
## AWS 統合 URI (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 関数をサポートしていません。
## Amazon Cognito ユーザープール
ステージ変数は、`COGNITO_USER_POOLS` オーソライザーの Amazon Cognito ユーザープールの代わりに使用できます。
+ `arn:aws:cognito-idp:::userpool/${stageVariables.}`
## AWS 統合認証情報
ステージ変数は、次の例に示すように、AWS ユーザー/ロールの認証情報 ARN の一部として使用できます。
+ `arn:aws:iam:::${stageVariables.}`
# API Gateway の Canary リリースデプロイの設定
[Canary リリース](https://martinfowler.com/bliki/CanaryRelease.html)は、新しいバージョンの API (および他のソフトウェア) をテスト目的でデプロイするソフトウェア開発戦略であり、ベースバージョンは同じステージで通常のオペレーション用の本稼働リリースとしてデプロイされたままになります。説明のため、このドキュメントではベースバージョンを本稼働リリースとします。これは合理的ですが、テストのために Canary リリースを非本稼働バージョンにも自由に適用できます。
Canary リリースのデプロイでは、すべての API トラフィックはランダムに区切られて事前に設定された比率で本稼働リリースと Canary リリースに送られます。通常、Canary リリースは低い割合の API トラフィックを受け取り、残りは本稼働リリースが受け取ります。更新された API 機能は、Canary を介した API トラフィックのみに認識されます。Canary トラフィックの割合を調整してテストカバレッジやパフォーマンスを最適化できます。
Canary トラフィックを低く保ち、選択をランダムにすることにより、どのような時でもほとんどのユーザーは新しいバージョンの潜在的なバグに悪影響を受けず、また、常に悪影響を受け続けるユーザーもいません。
テストメトリクスが要件を満たしたら、Canary リリースを本稼働リリースに昇格させ、Canary をデプロイから無効にします。これにより、本稼働ステージで新機能が使用可能になります。
**Topics**
+ [API Gateway での Canary リリースのデプロイ](#api-gateway-canary-release-deployment-overview)
+ [Canary リリースのデプロイを作成する](create-canary-deployment.md)
+ [Canary リリースの更新](update-canary-deployment.md)
+ [Canary リリースの昇格](promote-canary-deployment.md)
+ [Canary リリースをオフにする](delete-canary-deployment.md)
## API Gateway での Canary リリースのデプロイ
API Gateway で、Canary リリースのデプロイでは、API のベースバージョンの本番稼働リリース用のデプロイステージを使用し、その API のベースバージョンに関連した新しいバージョンの Canary リリースへアタッチします。ステージは初期のデプロイと関連付けられ、Canary は後続のデプロイに関連付けられます。最初は、ステージと Canary ポイントの両方が同じ API バージョンを指します。このセクションでは、ステージと本稼働リリースを同じ意味で使用し、また、Canary と Canary リリースを同じ意味で使用します。
Canary リリースで API をデプロイするには、[Canary 設定](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings)を通常の[デプロイ](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html)の[ステージ](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)に追加して Canary リリースのデプロイを作成します。Canary の設定は基礎となる Canary リリースを表し、ステージはこのデプロイ内の API の本稼働リリースを表します。Canary の設定を追加するには、デプロイステージの `canarySettings` を設定して以下を指定します。
+ デプロイ ID。最初はステージで設定されるベースバージョンのデプロイの ID と同じ。
+ 0.0 から 100.0 までの間の、Canary リリース用の[API トラフィックの割合](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#percentTraffic)。
+ 本番稼働リリースのステージ変数を上書きできる[Canary リリースのステージ変数](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#stageVariableOverrides)。
+ Canary リクエストの[ステージキャッシュの使用](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache)。[useStageCache](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) が設定され API キャッシュがステージで有効になっている場合。
Canary リリースが有効にされると、Canary リリースが無効にされて Canary 設定がステージから削除されるまで、デプロイステージは別の非 Canary リリースデプロイに関連付けることができなくなります。
API 実行のログ作成を有効にすると、Canary リリースはすべての Canary リクエストに生成される独自のログとメトリクスを持つようになります。これらは、本番稼働ステージの CloudWatch Logs グループおよび Canary 固有の CloudWatch Logs グループにレポートされます。アクセスログ記録も同じです。個別の Canary 固有のログは新しい API の変更を検証し、変更を受け入れて Canary リリースを本稼働ステージへ昇格させるか、または、変更を破棄して Canary リリースを本稼働ステージから戻すかを決定するのに役立ちます。
本稼働ステージの実行ロググループの名前は `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}` で、Canary リリースの実行ロググループの名前は `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary` です。アクセスログの記録には、新しいロググループを作成する、または、既存のものを選択する必要があります。Canary リリースのアクセスロググループ名には、選択されたロググループ名に `/Canary` サフィックスが付加されます。
Canary リリースはステージキャッシュを使用でき、有効にされると、レスポンスを保存しキャッシュされたエントリを使用して、事前に設定された有効期限 (TTL) 内に次の Canary リクエストへ結果を返します。
Canary リリースのデプロイでは、本稼働リリースと Canary リリースの API は同じバージョンまたは異なるバージョンに関連付けることができます。異なるバージョンに関連付けられている場合、本稼働と Canary リクエストへのレスポンスは別々にキャッシュされ、ステージキャッシュは本稼働と Canary リクエストへ対応する結果を返します。本稼働リリースと Canary リリースが同じデプロイに関連付けられている場合、ステージキャッシュは両方のタイプのリクエストに単一のキャッシュキーを使用し、本稼働リリースと Canary リリースからの同じリクエストに同じレスポンスを返します。
# Canary リリースのデプロイを作成する
[Canary 設定](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings)で[デプロイ作成](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html)オペレーションへの追加の入力として API をデプロイする場合は、Canary リリースのデプロイを作成します。
また、Canary 設定をステージに追加する [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) リクエストを行うことで、既存の非カナリアデプロイから Canary リリースのデプロイを作成することもできます。
非 Canary リリースのデプロイを作成する場合、存在しないステージ名を指定できます。指定されたステージが存在しない場合、API Gateway がそれを作成します。ただし、Canary リリースのデプロイを作成する場合は、存在しないステージ名を指定することはできません。エラーが表示され、API Gateway は Canary リリースのデプロイを作成しません。
API Gateway コンソール、AWS CLI、または AWS SDK を使用して、API Gateway で Canary リリースデプロイを作成できます。
**Topics**
+ [API Gateway コンソールを使用したカナリアデプロイの作成](#create-canary-deployment-using-console)
+ [AWS CLI を使用してカナリアデプロイを作成する](#create-canary-deployment-using-cli)
## API Gateway コンソールを使用したカナリアデプロイの作成
API Gateway コンソールを使用して Canary デプロイのリリースを作成するには、以下の手順に従います。
**最初の Canary リリースのデプロイを作成するには**
1. [API Gateway コンソール] にサインインします。
1. 既存の REST API を選択するか、新しい REST API を作成します。
1. メインナビゲーションペインで、**[リソース]** を選択してから **[API をデプロイ]** を選択します。[**API のデプロイ**] にある画面の指示に従って API を新しいステージにデプロイします。
ここまでで、API を本稼働リリースステージにデプロイしました。次に、ステージの Canary 設定を編集し、必要に応じて、キャッシュの有効化、ステージ変数の設定、または API 実行またはアクセスログの設定を行います。
1. API キャッシュを有効にするか、AWS WAF Web ACL をステージに関連付けるには、**[ステージの詳細]** セクションで **[編集]** を選択します。詳細については、「[API Gateway での REST API のキャッシュ設定](api-gateway-caching.md)」または「[API Gateway コンソールを使用して AWS WAF ウェブ ACL を API Gateway API ステージに関連付けるには](apigateway-control-access-aws-waf.md#apigateway-control-access-aws-waf-console)」を参照してください。
1. 実行またはアクセスログを設定するには、**[ログとトレース]** セクションで、**[編集]** を選択して画面の手順に従います。詳細については、「[API Gateway で REST API の CloudWatch ログ記録を設定する](set-up-logging.md)」を参照してください。
1. ステージ変数を設定するには、**[ステージ変数]** タブを選択し、画面の手順に従ってステージ変数を追加または変更します。詳細については、「[API Gateway で REST API のステージ変数を使用する](stage-variables.md)」を参照してください。
1. **[Canary]** タブを選択し、**[Canary の作成]** を選択します。**[Canary]** タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[Canary 設定]** の **[Canary]** で、canary に転送されるリクエストの割合を入力します。
1. 必要に応じて、**[ステージキャッシュ]** を選択し、Canary リリースのキャッシュを有効にします。API キャッシュが有効になるまでは Canary リリースのキャッシュは使用できません。
1. 既存のステージ変数を上書きするには、**[Canary の上書き]** に新しいステージ変数値を入力します。
Canary リリースがデプロイステージで初期化された後、API を変更して変更をテストできます。更新されたバージョンとベースバージョンの両方に同じステージからアクセスできるように、同じステージに API を再デプロイできます。以下のステップでは、その方法について説明します。
**最新の API バージョンを Canary にデプロイするには**
1. 各 API の更新で、**[API のデプロイ]** を選択します。
1. **[API のデプロイ]** で、**[デプロイされるステージ]** ドロップダウンリストから Canary を含むステージを選択します。
1. (オプション)**[デプロイの説明]** に、デプロイの説明を入力します。
1. [**デプロイ**] を選択し、最新の API バージョンを Canary リリースにプッシュします。
1. 必要に応じて、[最初の Canary リリースのデプロイを作成するには](#to-create-canary-release-on-new-deployment) の説明にあるとおり、ステージ設定、ログ、または Canary 設定を再設定します。
その結果、Canary リリースは最新バージョンを指し、本稼働リリースは API の最初のバージョンを指します。[[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings)] には新しい [**deploymentId**] 値ができていますが、ステージには引き続き当初の [[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId)] があります。内部では、コンソールは [[**stage:update**]](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) を呼び出します。
## AWS CLI を使用してカナリアデプロイを作成する
**新しいステージのカナリアデプロイを作成するには**
1. 次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドを使用して、2 つのステージ変数を含むデプロイを作成しますが、Canary は作成しません。
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'prod'
```
出力は次のようになります。
```
{
"id": "du4ot1",
"createdDate": 1511379050
}
```
1. 次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドを使用して、`prod` ステージにカナリアデプロイを作成します。
```
aws apigateway create-deployment \
--rest-api-id abcd1234 \
--canary-settings percentTraffic=10.5,stageVariableOverrides={sv1='val2',sv2='val3'},useStageCache=false \
--stage-name 'prod'
```
出力は次のようになります。
```
{
"id": "a6rox0",
"createdDate": 1511379433
}
```
結果的に生じるデプロイ `id` により Canary リリースの API のテストバージョンが識別されます。その結果、関連付けられたステージは Canary が有効になっています。
1. (オプション) 次の [get-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-stage.html) コマンドを使用して、ステージ表現を表示します。
```
aws apigateway get-stage --rest-api-id acbd1234 --stage-name prod
```
以下に示すのは、コマンドの出力としての `Stage` の表現です。
```
{
"stageName": "prod",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "du4ot1",
"lastUpdatedDate": 1511379433,
"createdDate": 1511379050,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "a6rox0",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
この例では、ベースバージョンの API は `{"sv0":val0", "sv1":val1"}` のステージ変数を使用し、テストバージョンではステージ変数 `{"sv1":val2", "sv2":val3"}` を使用します。本稼働リリースと Canary リリースの両方が同じステージ変数 `sv1` を使用しますが、それぞれ別の値、`val1` および `val2` をそれぞれ使用します。ステージ変数 `sv0` は本稼働リリースでのみ使用され、ステージ変数 `sv2` は Canary リリースでのみ使用されます。
既存の通常のデプロイから Canary リリースのデプロイを作成するには、Canary が有効になるようにステージを更新します。
**既存のデプロイから Canary リリースデプロイを作成するには**
1. [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドを使用して、Canary なしのデプロイを作成します。
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'beta'
```
1. [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドを使用して、ステージを更新して Canary を有効にします。
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name 'beta' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
出力は次のようになります。
```
{
"stageName": "beta",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "cifeiw",
"lastUpdatedDate": 1511381930,
"createdDate": 1511380879,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "cifeiw",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
API の既存のバージョンで Canary を有効にしたため、本番リリース (`Stage`) と Canary リリース (`canarySettings`) の両方が同じデプロイを指しています。API を変更して再度このステージにデプロイした後、新しいバージョンは Canary リリースに入り、ベースバージョンは本稼働リリースに残ります。これは、ステージ進化で明らかになります。Canary リリースの `deploymentId` は新しいデプロイ `id` に更新され、本稼働リリースの `deploymentId` は変更されません。
# Canary リリースの更新
Canary リリースがデプロイされた後、テストパフォーマンスを最適化するため、Canary トラフィックの割合を調整したり、ステージキャッシュの使用を有効または無効にしたりするかもしれません。また、実行コンテキストが更新されたとき、Canary リリースで使用されているステージ変数を変更することもできます。このような更新を行うには、[https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) オペレーションを呼び出すとき [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) に新しい値を入れます。
Canary リリースは、API Gateway コンソール、AWS CLI [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンド、または AWS SDK を使用して更新できます。
**Topics**
+ [API Gateway コンソールを使用して Canary リリースを更新する](#update-canary-deployment-using-console)
+ [AWS CLI を使用して Canary リリースを更新する](#update-canary-deployment-using-cli)
## API Gateway コンソールを使用して Canary リリースを更新する
API Gateway コンソールを使用してステージで既存の Canary 設定を更新するには、次の操作を行います。
**既存の canary 設定を更新するには**
1. API Gateway コンソールにサインインし、既存の REST API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択してから、既存のステージを選択します。
1. **[canary]** タブを選択してから、**[編集]** をクリックします。**[Canary]** タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. 0.0～100.0 の間でパーセント数を調整して、**[リクエストの割合 (%)]** を更新します。
1. **[ステージキャッシュ]** チェックボックスを選択または選択解除します。
1. **Canary ステージ変数**を追加、削除、または変更します。
1. **[保存]** を選択します。
## AWS CLI を使用して Canary リリースを更新する
AWS CLI を使用して Canary を更新するには、[https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドを使用し、Canary の各パラメータのパッチオペレーションを変更します。
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドは、Canary がステージキャッシュを使用するかどうかを更新します。
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/useStageCache,value=true
```
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドは、Canary トラフィックの割合を更新します。
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/percentTraffic,value=25.0
```
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) は、ステージ変数を更新します。この例では、`newVar` という名前の新しいステージ変数を作成し、`var2` ステージ変数を上書きして、`var1` ステージ変数を削除する方法を示します。
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/var2",
"value": "val4"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}]'
```
上記のすべてを更新するには、オペレーションを 1 つの `patch-operations` 値にまとめます。
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/percentTraffic",
"value": "20.0"
}, {
"op": "replace",
"path": "/canarySettings/useStageCache",
"value": "true"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/val2",
"value": "val4"
}]'
```
# Canary リリースの昇格
Canary リリースを昇格させると、Canary リリースが現在のステージ設定を置き換えます。Canary リリースが昇格してもステージで Canary は無効になりません。Canary を無効にするには、ステージで Canary 設定を削除する必要があります。Canary を昇格させるには、以下を実行します。
+ ステージの[デプロイ ID](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) を Canary の[デプロイ ID](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) 設定でリセットします。これによりステージの API スナップショットが Canary のスナップショットで更新され、テストバージョンを本稼働リリースにもします。
+ Canary のステージ変数でステージ変数を更新する (存在する場合) これによりステージの API 実行コンテキストが Canary のもので更新されます。この更新をしないと、テストバージョンでさまざまなステージ変数やさまざまな既存のステージの値を使用している場合、新しい API バージョンで予期しない結果が生じる場合があります。
+ Canary トラフィックの割合を 0.0% に設定します。
**Topics**
+ [API Gateway コンソールを使用して Canary リリースを昇格させる](#promote-canary-release-deployment-console)
+ [AWS CLI を使用して Canary リリースを昇格させる](#promote-canary-release-cli)
## API Gateway コンソールを使用して Canary リリースを昇格させる
API Gateway コンソールを使用して Canary リリースのデプロイを昇格させるには、以下を実行します。
**Canary リリースのデプロイを昇格させるには**
1. API Gateway コンソールにサインインし、プライマリナビゲーションペインで既存の API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択してから、既存のステージを選択します。
1. **[Canary]**タブを選択します。
1. **[Canary の昇格]** を選択します。
1. 変更内容を確認し、**[Canary の昇格]** を選択します。
昇格後、本稼働リリースは Canary リリースと同じ API バージョン (**deploymentId**) を参照します。AWS CLI を使用してこれを検証できます。例については、「[AWS CLI を使用して Canary リリースを昇格させる](#promote-canary-release-cli)」を参照してください。
## AWS CLI を使用して Canary リリースを昇格させる
AWS CLI コマンドを使用して Canary リリースを本稼働リリースに昇格させるには、`update-stage` コマンドを呼び出して Canary に関連付けられた `deploymentId` をステージに関連付けられた `deploymentId` にコピーし、Canary トラフィックの割合をゼロ (`0.0`) にリセットして、Canary にバインドされたステージ変数を対応するステージにバインドされた変数にコピーします。
次のようなステージで示された、Canary リリースのデプロイがあるとします。
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 10.5
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "nfcn0x",
"lastUpdatedDate": "2017-11-22T00:54:28Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv1": "val1"
}
}
```
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドを使用して、Canary を昇格させます。
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
出力は次のようになります。
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 0
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "eh1sby",
"lastUpdatedDate": "2017-11-22T05:29:47Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv2": "val3",
"sv1": "val2"
}
}
```
Canary リリースをステージに昇格させても Canary は無効にならず、デプロイは Canary リリースのデプロイのままになります。通常の本番稼働用デプロイにするには、Canary 設定を無効にする必要があります。Canary リリースのデプロイを無効にする方法については、「[Canary リリースをオフにする](delete-canary-deployment.md)」を参照してください。
# Canary リリースをオフにする
Canary リリースのデプロイをオフにするには、[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) を null に設定してステージから削除します。
API Gateway コンソール、AWS CLI、または AWS SDK を使用して、Canary リリースのデプロイを無効にすることができます。
**Topics**
+ [API Gateway コンソールを使用して Canary リリースをオフにする](#delete-canary-release-console)
+ [AWS CLI を使用して Canary リリースをオフにする](#delete-canary-release-cli)
## API Gateway コンソールを使用して Canary リリースをオフにする
API Gateway コンソールを使用して Canary リリースのデプロイをオフにするには、以下のステップを使用します。
**Canary リリースのデプロイをオフにするには**
1. API Gateway コンソールにサインインし、メインナビゲーションペインで既存の API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択してから、既存のステージを選択します。
1. **[Canary]**タブを選択します。
1. [**削除**] を選択します。
1. [**削除**] を選択して Canary を削除することを確認します。
その結果、[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) プロパティは `null` となり、デプロイされる[ステージ](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)から削除されます。AWS CLI を使用してこれを検証できます。例については、「[AWS CLI を使用して Canary リリースをオフにする](#delete-canary-release-cli)」を参照してください。
## AWS CLI を使用して Canary リリースをオフにする
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドは、Canary リリースのデプロイをオフにします。
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name canary \
--patch-operations '[{"op":"remove", "path":"/canarySettings"}]'
```
出力は次のようになります。
```
{
"stageName": "prod",
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "nfcn0x",
"lastUpdatedDate": 1511309280,
"createdDate": 1511152939,
"methodSettings": {
...
}
}
```
出力で示されているように、[canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) プロパティは、Canary が無効になっているデプロイの[ステージ](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)には存在しなくなりました。
# 再デプロイが必要な REST API の更新
API の管理は、既存の API セットアップを表示、更新、削除することを意味します。API Gateway コンソール、AWS CLI、CloudFormation、SDK、または API Gateway REST API を使用して、API を維持できます。API の更新には、特定のリソースプロパティまたは API の構成設定の変更が含まれます。リソースの更新には API の再デプロイが必要ですが、設定の更新の場合は必要ありません。
次の表は、更新時に API を再デプロイする必要がある API リソースを示しています。
| リソース | メモ |
| --- | --- |
| [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[apikey:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateApiKey.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [オーソライザー](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[authorizer:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAuthorizer.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [disableExecuteApiEndpoint](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html#apigw-UpdateRestApi-response-disableExecuteApiEndpoint) | 更新では、API をステージに再デプロイするなど、API のいずれかのステージを変更する必要があります。 |
| [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[documentationversion:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationVersion.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html#remarks)」を参照してください。更新では API を再デプロイする必要があります。 |
| [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[integration:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegration.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[integrationresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegrationResponse.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [方法](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[method:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[methodresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethodResponse.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [[Model]](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) (モデル) | 適用可能なプロパティとサポートされているオペレーションについては、「[model:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateModel.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [RequestValidator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[requestvalidator:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRequestValidator.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [[リソース]](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[resource:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)」を参照してください。更新では API を再デプロイする必要があります。 |
| [RestApi 数](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html)」を参照してください。更新では API を再デプロイする必要があります。これには、リソースポリシーの変更が含まれます。 |
| [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[vpclink:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateVpcLink.html)」を参照してください。更新では API を再デプロイする必要があります。 |
次の表は、更新時に API を再デプロイを必要としない API 設定を示しています。
| 設定 | メモ |
| --- | --- |
| [アカウント](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[account:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html)」を参照してください。更新では API を再デプロイする必要はありません。 |
| [デプロイメント](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[deployment:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDeployment.html)」を参照してください。 |
| [DomainName](https://docs.aws.amazon.com/apigateway/latest/api/API_DomainName.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html)」を参照してください。更新では API を再デプロイする必要はありません。 |
| [BasePathMapping](https://docs.aws.amazon.com/apigateway/latest/api/API_BasePathMapping.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[basepathmapping:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateBasePathMapping.html)」を参照してください。更新では API を再デプロイする必要はありません。 |
| [IP アドレスタイプ](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateRestApi.html) | 更新では API を再デプロイする必要はありません。 |
| [ステージ](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html)」を参照してください。更新では API を再デプロイする必要はありません。 |
| [使用方法](https://docs.aws.amazon.com/apigateway/latest/api/API_GetUsage.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[usage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsage.html)」を参照してください。更新では API を再デプロイする必要はありません。 |
| [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) | 適用可能なプロパティとサポートされているオペレーションについては、「[usageplan:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html)」を参照してください。更新では API を再デプロイする必要はありません。 |