# 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.}`