REST API デプロイのステージ変数のセットアップ

ステージ変数は、REST API のデプロイステージと関連付けられた設定属性として定義できる名前と値のペアです。環境変数と同様に機能し、API のセットアップやマッピングテンプレートで使用できます。

たとえば、ステージ設定でステージ変数を定義し、REST API のメソッド用に、HTTP 統合の URL 文字列としてその値を設定できます。後で、API のセットアップから関連するステージの変数名を使用して URL 文字列を参照できます。これによって、ステージ変数の値を対応する URL にリセットすることで、各ステージで異なるエンドポイントとともに同じ API セットアップを使用することができます。

また、マッピングテンプレートでステージ変数にアクセスしたり、AWS Lambda または HTTP バックエンドに設定パラメータを渡したりできます。

マッピングテンプレートの詳細については、「API Gateway マッピングテンプレートとアクセスのログ記録の変数リファレンス」を参照してください。

注記

ステージ変数は、認証情報などの機密データに使用されることを意図していません。機密データを統合に渡すには、AWS Lambda オーソライザーを使用します。Lambda オーソライザーの出力では、機密データを統合に渡すことができます。詳細については、「Amazon API Gateway Lambda オーソライザーからの出力」を参照してください。

ユースケース

API Gateway のデプロイステージでは、アルファ、ベータ、本番稼働など、各 API 用の複数のリリースステージを管理できます。ステージ変数を使用することで、異なるバックエンドのエンドポイントとやり取りするよう API デプロイステージを設定できます。

たとえば、API は HTTP プロキシとして GET リクエストをバックエンドウェブホスト (http://example.com など) に渡すことができます。この場合、バックエンドウェブホストはステージ変数で設定されるため、デベロッパーが本番稼働エンドポイントを呼び出した場合、API Gateway は example.com を呼び出します。ベータエンドポイントを呼び出す場合、API Gateway は、ベータステージ用にステージ変数で設定された値を使用し、別のウェブホスト (例: beta.example.com) を呼び出します。同様に、ステージ変数を使用して、API で各ステージに別の AWS Lambda 関数名を指定することができます。

また、ステージ変数を使用して、マッピングテンプレートを通じて Lambda 関数に設定パラメータを渡すこともできます。たとえば、API で複数のステージ用に同じ Lambda 関数を再利用するが、呼び出しているステージによって、関数が別の Amazon DynamoDB テーブルからデータを読み取るようにしたい場合があります。Lambda 関数のリクエストを生成するマッピングテンプレートで、ステージ変数を使用してテーブル名を Lambda に渡すことができます。

ステージ変数は、API 仕様のセキュリティ定義のセクションには適用されません。たとえば、さまざまな Amazon Cognito ユーザープールを異なるステージに使用することはできません。

例

ステージ変数を使用して HTTP 統合エンドポイントをカスタマイズするには、最初に指定された名前 (url など) のステージ変数を設定し、次に値 (example.com など) を割り当てます。次に、メソッド設定から HTTP プロキシ統合をセットアップします。エンドポイントの URL を入力する代わりに、ステージ変数の値、http://${stageVariables.url} を使用するように API Gateway に指示できます 。この値により、API が実行中のステージに基づいて、ランタイムにステージ変数 ${} を置き換えるよう API Gateway が指示されます。

同様の方法でステージ変数を参照し、Lambda 関数名、AWS のサービスプロキシのパス、または AWS ロール ARN を認証情報フィールドで指定できます。

ステージ変数値として Lambda 関数名を指定する場合は、その Lambda 関数に対するアクセス許可を手動で設定する必要があります。これを行うには、AWS コマンドラインインターフェイス (AWS CLI) を使用できます。

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 メソッドに代わって AWS アカウントの米国西部 (オレゴン) リージョンでホストされた helloWorld という名前の Lambda 関数を呼び出す API Gateway アクセス許可を割り当てます。

arn arn:aws:execute-api:us-west-2:123123123123:bmmuvptwze/*/GET/hello

AWS CLI を使用する同じコマンドを次に示します。

aws lambda add-permission --function-name arn:aws:lambda:us-east-1:123123123123:function:helloWorld --source-arn  arn:aws:execute-api:us-west-2:123123123123:bmmuvptwze/*/GET/hello --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction