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

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 に渡すことができます。

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

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

ステージ変数値として Lambda 関数名を指定する場合は、その Lambda 関数に対するアクセス許可を手動で設定する必要があります。API Gateway コンソールで Lambda 関数を指定すると、AWS CLI コマンドがポップアップ表示され、適切なアクセス許可を設定できるようになります。AWS Command Line Interface (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