# API Gateway の HTTP API のステージ
<a name="http-api-stages"></a>

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 のステージ変数を使用する
<a name="http-api-stages.stage-variables"></a>

ステージ変数は、HTTP API のステージに対して定義できるキーと値のペアです。環境変数と同様に機能し、API のセットアップで使用できます。

ステージ変数は、認証情報などの機密データに使用されることを意図していません。機密データを統合に渡すには、AWS Lambda オーソライザーを使用します。Lambda オーソライザーの出力では、機密データを統合に渡すことができます。詳細については、「[Lambda オーソライザーのレスポンス形式](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response)」を参照してください。

## 例 – ステージ変数を使用して HTTP 統合エンドポイントをカスタマイズする
<a name="http-api-stages.stage-variables-examples"></a>

たとえば、ステージ変数を定義し、その値を 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 ステージ変数リファレンス
<a name="http-api-stages.stage-variables-reference"></a>

次のような場合に、HTTP API に API Gateway ステージ変数を使用できます。

## HTTP 統合 URI
<a name="http-api-stages.stage-variables-in-integration-HTTP-uris"></a>

ステージ変数は、次の例に示すように、HTTP 統合 URI の一部として使用できます。
+ プロトコルのない完全な URI – `http://${stageVariables.<variable_name>}`
+ 完全なドメイン – `http://${stageVariables.<variable_name>}/resource/operation`
+ サブドメイン – `http://${stageVariables.<variable_name>}.example.com/resource/operation`
+ パス – `http://example.com/${stageVariables.<variable_name>}/bar`
+ クエリ文字列 – `http://example.com/foo?q=${stageVariables.<variable_name>}` 

## Lambda 関数
<a name="http-api-stages.stage-variables-in-integration-lambda-functions"></a>

 ステージ変数は、次の例に示すように、Lambda 関数の統合名やエイリアスの代わりに使用できます。
+ `arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:${stageVariables.<function_variable_name>}/invocations`
+ `arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:<function_name>:${stageVariables.<version_variable_name>}/invocations`

**注記**  
Lambda 関数にステージ変数を使用するには、関数が API と同じアカウントにある必要があります。ステージ変数は、クロスアカウント Lambda 関数をサポートしていません。

## AWS 統合認証情報
<a name="http-api-stages.stage-variables-in-integration-aws-credentials"></a>

 次の例に示すように、ステージ変数を AWS ユーザーまたはロールの認証情報 ARN の一部として使用できます。
+  `arn:aws:iam::<account_id>:${stageVariables.<variable_name>}`