API デプロイメントのステージ変数の設定
ステージ変数は、API のデプロイステージと関連付けられた設定属性として定義できる名前と値のペアです。環境変数と同様に機能し、API のセットアップやマッピングテンプレートで使用できます。
たとえば、ステージ設定でステージ変数を定義し、API のメソッド用に、HTTP 統合の URL 文字列としてその値を設定できます。後で、API のセットアップから関連するステージの変数名を使用して URL 文字列を参照できます。これによって、ステージ変数の値を対応する URL にリセットすることで、各ステージで異なるエンドポイントとともに同じ API セットアップを使用することができます。また、マッピングテンプレートでステージ変数にアクセスしたり、AWS Lambda または HTTP バックエンドに設定パラメータを渡したりできます。
マッピングテンプレートの詳細については、「API Gateway のマッピングテンプレートリファレンス」を参照してください。
ユースケース
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 に渡すことができます。
例
ステージ変数を使用して HTTP 統合エンドポイントをカスタマイズするには、最初に指定された名前 (url など) のステージ変数を設定し、次に値 (example.com など) を割り当てます。次に、メソッド設定から HTTP プロキシ統合をセットアップし、エンドポイントの URL を入力する代わりに、ステージ変数の値 http://${stageVariables.url} を使用するよう API Gateway に伝えます。この値により、API が実行中のステージに基づいて、実行時にステージ変数 ${} を置き換えるよう API Gateway に指示されます。同様の方法でステージ変数を参照し、Lambda 関数名、AWS サービスプロキシのパス、または AWS
ロール ARN を認証情報フィールドで指定できます。
ステージ変数値として Lambda 関数名を指定するときは、Lambda 関数で手動でアクセス権限を設定する必要があります。これを行うには、AWS Command Line Interface を使用できます。
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
