API 統合リクエストの基本タスク - Amazon API Gateway

API 統合リクエストの基本タスク

統合リクエストは、API Gateway がバックエンドに送る HTTP リクエストであり、クライアントから送信されたリクエストデータを渡し、必要に応じて変換します。統合リクエストの HTTP メソッド (つまり動詞) と URI は、バックエンド (つまり統合エンドポイント) が指定します。HTTP メソッドと URI はそれぞれ、メソッドリクエストのものと同じ場合もあれば異なる場合もあります。

たとえば、Lambda 関数が、Amazon S3 からフェッチされたファイルを返す場合、このオペレーションを直観的に GET メソッドリクエストとしてクライアントに公開できます。これは、対応する統合リクエストで POST リクエストを使用して Lambda 関数を呼び出す必要があっても同じです。HTTP エンドポイントの場合は、メソッドリクエストおよび対応する統合リクエストの両方で同じ HTTP 動詞を使用することがよくあります。ただし、これは必須ではありません。以下のメソッドリクエストがあるとします。

GET /{var}?query=value
Host: api.domain.net

これを以下の統合リクエストに統合できます。

POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...

{
   path: "{var}'s value",
   type: "value"
}

API 開発者は、要件に合わせてどのような HTTP 動詞と URI でもメソッドリクエストに使用できます。しかし、統合エンドポイントの要件に従う必要があります。メソッドリクエストデータが統合リクエストデータと異なる場合、メソッドリクエストデータから統合リクエストデータへのマッピングを提供することで、その差異を調整できます。

ここまでの例では、マッピングにより、{var} メソッドリクエストのパス変数 (query) とクエリパラメータ (GET) の値が、統合リクエストのペイロードプロパティ path と type の値に変換されます。その他のマップ可能なリクエストデータとしては、リクエストのヘッダーと本文があります。これらについては、「API Gateway コンソールを使用してリクエストとレスポンスのデータマッピングを設定する」で説明しています。

HTTP または HTTP プロキシ統合リクエストを設定するときは、バックエンド HTTP エンドポイント URL を統合リクエスト URI 値として割り当てます。たとえば、PetStore API では、pets のページを取得するメソッドリクエストに以下の統合リクエスト URI があります。

http://petstore-demo-endpoint.execute-api.com/petstore/pets

Lambda または Lambda プロキシ統合を設定するときは、Lambda 関数を呼び出すための Amazon リソースネーム (ARN) を統合リクエスト URI 値として割り当てます。この ARN は以下の形式になります。

arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations

arn:aws:apigateway:api-region:lambda:path/ の後の部分、つまり、/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations は、Lambda の Invoke アクションの REST API URI パスです。API Gateway コンソールを使用して Lambda 統合を設定する場合は、API Gateway によって ARN が作成され、統合 URI に割り当てられます。ただし、その前にリージョンから lambda-function-name を選択するように求められます。

別の AWS のサービスアクションとの統合リクエストを設定する場合、統合リクエスト URI は ARN でもあります。これは、Lambda Invoke アクションとの統合と同様です。たとえば、Amazon S3 の GetBucket アクションとの統合の場合、統合リクエスト URI は以下の形式の ARN です。

arn:aws:apigateway:api-region:s3:path/{bucket}

統合リクエスト URI は、アクションを指定するためのパス規約です。ここで、{bucket} はバケット名のプレースホルダーです。または、AWS のサービスアクションをその名前で参照することもできます。アクション名を使用すると、Amazon S3 の GetBucket アクションの統合リクエスト URI は以下のようになります。

arn:aws:apigateway:api-region:s3:action/GetBucket

アクションベースの統合リクエスト URI では、{bucket} アクションの入力形式に従って、バケット名 ({ Bucket: "{bucket}" }) を統合リクエストボディ (GetBucket) で指定する必要があります。

AWS 統合の場合、認証情報を設定して、API Gateway が統合アクションを呼び出せるようにする必要もあります。新しい IAM ロールを作成するか既存のものを選択して、API Gateway がそのアクションを呼び出せるようにしたら、そのロールを ARN で指定できます。以下に示しているのは、この ARN の例です。

arn:aws:iam::account-id:role/iam-role-name

この IAM ロールには、アクションの実行を許可するポリシーが含まれている必要があります。また、そのロールを引き受ける信頼されたエンティティとして API Gateway を (ロールの信頼関係で) 宣言する必要があります。そのようなアクセス権限はアクション自体に対して付与できます。それらはリソースベースのアクセス権限と呼ばれます。Lambda 統合の場合、Lambda の addPermission アクションを呼び出して、リソースベースのアクセス許可を設定したら、API Gateway 統合リクエストで credentials を null に設定できます。

統合の基本設定については説明しました。詳細設定には、メソッドリクエストデータから統合リクエストデータへのマッピングが含まれます。統合レスポンスの基本設定について説明した後、「API Gateway コンソールを使用してリクエストとレスポンスのデータマッピングを設定する」で詳細設定を取り上げています。また、ペイロードを渡す方法とコンテンツエンコードを処理する方法も取り上げています。