API Gateway での Lambda プロキシ統合

次のセクションでは、Lambda プロキシ統合を使用する方法を示します。

API Gateway Lambda プロキシの統合について理解する

Amazon API Gateway Lambda プロキシ統合は、単一の API メソッドのセットアップで API を構築するシンプル、強力、高速なメカニズムです。Lambda プロキシ統合は、クライアントが単一の Lambda 関数をバックエンドで呼び出すことを可能にします。この関数は、他の Lambda 関数の呼び出しを含め、他の AWS のサービスのさまざまなリソースや機能にアクセスします。

Lambda プロキシ統合では、クライアントが API リクエストを送信すると、API Gateway は、統合された Lambda 関数にイベントオブジェクトを渡します。ただし、リクエストパラメータの順序は保持されません。このリクエストデータには、リクエストヘッダー、クエリ文字列パラメータ、URL パス変数、ペイロード、および API 設定データが含まれます。設定データには、現在のデプロイステージ名、ステージ変数、ユーザー ID、または承認コンテキスト (存在する場合) を含めることができます。バックエンド Lambda 関数では、受信リクエストデータを解析して、返すレスポンスを決定します。API Gateway が Lambda 出力を API レスポンスとしてクライアントに渡すには、Lambda 関数は結果をこの形式で返す必要があります。

API Gateway は Lambda プロキシ統合でクライアントとバックエンド Lambda 関数間にあまり介入しないため、クライアントと統合された Lambda 関数は、API の既存の 統合セットアップを損なうことなく、相互の変更に適応できます。これを有効にするには、クライアントはバックエンド Lambda 関数が制定したアプリケーションプロトコルに従う必要があります。

任意の API メソッドで Lambda プロキシ統合をセットアップできます。しかし、Lambda プロキシ統合は、汎用的なプロキシリソースが含まれる API メソッドに設定されていると、より強力です。汎用的なプロキシリソースは、特別なテンプレートパス変数である {proxy+} 、キャッチオールである ANY メソッドプレースホルダー、または両方によって示すことができます。クライアントは、受信リクエストのバックエンド Lambda 関数に、入力をリクエストパラメータまたは適切なペイロードとして渡すことができます。リクエストパラメータには、ヘッダー、URL パス変数、クエリ文字列パラメータ、および適切なペイロードが含まれます。統合された Lambda 関数は、リクエストを処理して、必要な入力がない場合に意味のあるエラーメッセージでクライアントに応答する前に、すべての入力ソースを検証します。

ANY の汎用的な HTTP メソッドと {proxy+} の汎用的なリソースと統合されている API メソッドを呼び出す際、クライアントは ANY の代わりに特定の HTTP メソッドを持つリクエストを送信します。クライアントはさらに、{proxy+} の代わりに特定の URL パスを指定し、要求されるヘッダー、クエリ文字列パラメータ、または適切なペイロードを含めます。

次のリストは、Lambda プロキシ統合での異なる API メソッドのランタイム動作を要約しています。

{proxy+} のプロキシリソースと {custom} のカスタムリソースの両方が、テンプレートパス変数として表現されています。ただし、{proxy+} はパス階層に沿った任意のリソースを参照できますが、{custom} は特定のパスセグメントのみを参照します。たとえば、食料品店はオンラインの製品インベントリを部門名、農産物カテゴリ、および製品タイプで整理しています。食料品店のウェブサイトは、カスタムリソースの次のテンプレートパス変数によって、利用可能な製品を表すことができます: /{department}/{produce-category}/{product-type}。たとえば、リンゴは /produce/fruit/apple で表され、ニンジンは /produce/vegetables/carrot で表されます。また、/{proxy+} を使用して、顧客がオンラインストアで買い物中に検索できる任意の部門、農産物カテゴリ、または製品タイプを表すことができます。たとえば、/{proxy+} は次のいずれかのアイテムを参照できます。

顧客が利用可能な製品、その農産物カテゴリ、および関連するストア部門を検索できるようにするには、GET /{proxy+} の単一メソッドを読み取り専用アクセス権限で公開することができます。同様に、責任者が produce 部門のインベントリをアップデートできるようにするには、別の PUT /produce/{proxy+} の単一メソッドを読み取り/書き込みアクセス権限でセットアップできます。レジ係が野菜の合計を更新できるようにするには、POST /produce/vegetables/{proxy+} メッセージを読み取り/書き込みアクセス権限でセットアップできます。店長が任意のアクションを任意の利用可能な製品に実行できるようにするには、オンラインストア開発者は ANY /{proxy+} メソッドを読み取り/書き込みアクセス権限で公開できます。いずれの場合も、実行時には、顧客または従業員は選択された部門のあるタイプの特定の製品、製品部門の特定の農産物カテゴリ、または特定の部門を選択する必要があります。

API Gateway プロキシ統合のセットアップの詳細については、「プロキシリソースとのプロキシ統合を設定する」を参照してください。

プロキシ統合は、クライアントがバックエンド要件のより詳細な知識を持っていることを要求します。したがって、最適なアプリケーションパフォーマンスとユーザーエクスペリエンスを確保するために、バックエンド開発者はバックエンドの要件をクライアント開発者に明確に伝え、要件が満たされない場合は堅牢なエラーフィードバックメカニズムを提供する必要があります。

複数値のヘッダーとクエリ文字列パラメータのサポート

API Gateway は、同じ名前を持つ複数のヘッダーやクエリ文字列パラメータをサポートするようになりました。複数値ヘッダーや単一値ヘッダー、およびパラメータを、同じリクエストとレスポンスで組み合わせることができます。詳細については、プロキシ統合のための Lambda 関数の入力形式およびプロキシ統合のための Lambda 関数の出力形式を参照してください。

プロキシ統合のための Lambda 関数の入力形式

Lambda プロキシ統合では、API Gateway がクライアントリクエスト全体をバックエンド Lambda 関数の入力 event パラメータにマップします。次の例は、API Gateway が Lambda プロキシ統合に送信するイベントの構造を示しています。

{
  "resource": "/my/path",
  "path": "/my/path",
  "httpMethod": "GET",
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "multiValueHeaders": {
    "header1": [
      "value1"
    ],
    "header2": [
      "value1",
      "value2"
    ]
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "multiValueQueryStringParameters": {
    "parameter1": [
      "value1",
      "value2"
    ],
    "parameter2": [
      "value"
    ]
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "id",
    "authorizer": {
      "claims": null,
      "scopes": null
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "extendedRequestId": "request-id",
    "httpMethod": "GET",
    "identity": {
      "accessKey": null,
      "accountId": null,
      "caller": null,
      "cognitoAuthenticationProvider": null,
      "cognitoAuthenticationType": null,
      "cognitoIdentityId": null,
      "cognitoIdentityPoolId": null,
      "principalOrgId": null,
      "sourceIp": "IP",
      "user": null,
      "userAgent": "user-agent",
      "userArn": null,
      "clientCert": {
        "clientCertPem": "CERT_CONTENT",
        "subjectDN": "www.example.com",
        "issuerDN": "Example issuer",
        "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
        "validity": {
          "notBefore": "May 28 12:30:02 2019 GMT",
          "notAfter": "Aug  5 09:36:04 2021 GMT"
        }
      }
    },
    "path": "/my/path",
    "protocol": "HTTP/1.1",
    "requestId": "id=",
    "requestTime": "04/Mar/2020:19:15:17 +0000",
    "requestTimeEpoch": 1583349317135,
    "resourceId": null,
    "resourcePath": "/my/path",
    "stage": "$default"
  },
  "pathParameters": null,
  "stageVariables": null,
  "body": "Hello from Lambda!",
  "isBase64Encoded": false
}

バックエンド Lambda 関数への入力では、requestContext オブジェクトはキーと値のペアのマップです。各ペアにおいて、キーは $context 変数プロパティの名前であり、値はそのプロパティの値です。API Gateway は、マップに新しいキーを追加する場合があります。

有効になっている機能に応じて、requestContext マップは API ごとに異なる場合があります。たとえば、前述の例では、認証タイプが指定されていないため、$context.authorizer.* や $context.identity.* プロパティは存在しません。認証タイプが指定されると、API Gateway は、認証されたユーザー情報を requestContext.identity オブジェクト内の統合エンドポイントに次のように渡します。

プロキシ統合のための Lambda 関数の出力形式

Lambda プロキシ統合では、以下の JSON 形式に従って出力を返すために、API Gateway はバックエンドの Lambda 関数を必要とします。

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

出力では、次のようになります。

Lambda プロキシ統合に対して CORS を有効にするには、Access-Control-Allow-Origin:domain-name を出力 headers に追加する必要があります。domain-name は、任意のドメイン名に対して * にすることができます。出力 body は、メソッドレスポンスペイロードとしてフロントエンドにマーシャリングされます。body がバイナリ BLOB の場合、isBase64Encoded を true に設定し、*/* を [バイナリメディアタイプ] に設定することで、Base64 エンコード文字列としてエンコードできます。それ以外の場合は、false に設定するか、指定しないでおくことができます。

関数出力が別の形式である場合、API Gateway は 502 Bad Gateway エラーレスポンスを返します。

Node.js での Lambda 関数でレスポンスを返すには、次のようなコマンドを使用できます。

Node.js の Lambda async 関数では、同等の構文は次のようになります。