バックエンド サービスとのデータの受け渡し

API クライアントが API Gateway にデプロイされた API にリクエストを行うと、クライアントはリクエストの一部として次のいずれかまたはすべての情報を渡すことができます。

• リクエスト ヘッダー
• クエリ パラメータ
• フォームデータ
• XML ペイロードまたは JSON ペイロード
• リクエストパス

API リクエストに対するレスポンスを構築する際に、バックエンド サービスは次のようなデータを API クライアントに返すことができます。

• レスポンス ヘッダー
• XML ペイロードまたは JSON ペイロード

このドキュメントでは、このデータをバックエンド サービスとの間で受け渡しする方法について説明します。

リクエスト データをバックエンド サービスに渡す方法

API クライアントからのリクエスト内のすべてのデータは、変更されることなくバックエンド サービスに渡されます。そのうえで、バックエンド サービスがリクエストの処理の一環としてリクエスト データを解析します。

レスポンス データを API クライアントに返す方法

バックエンド サービスからのレスポンスで受信したすべてのデータが、変更されることなく API クライアントに渡されます。その後、レスポンスで返されたデータを処理するのは API クライアントです。

リクエスト URL をバックエンド サービスに渡す方法

バックエンド サービスへのリクエストに使用される URL は、x-google-backend 拡張機能によって制御されます。このセクションでは、バックエンド サービスの URL を構成するためのオプションについて説明します。

OpenAPI 仕様でのバックエンド サービスのアドレスとパスの設定

API 構成の作成に使用する OpenAPI 仕様では、x-google-backend 拡張機能を使用してバックエンド サービスの URL を指定します。たとえば、バックエンド サービスを次の形式で指定します。

バックエンド	x-google-backend
Cloud Functions	x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run	x-google-backend: address: https://hello-HASH.a.run.app
App Engine スタンダード環境	x-google-backend: address: https://PROJECT_ID.appspot.com

この例では次のようになります。

1. GCP_REGION は、デプロイされるバックエンドの GCP リージョンを指定します。
2. PROJECT_ID は、Google Cloud プロジェクト ID を指定します。
3. HASH は、Cloud Run サービスの作成時に生成される一意のハッシュコードを指定します。

さらに、OpenAPI 仕様の path パラメータでは、API でサポートされるエンドポイント（リソース）を指定します。絶対パスまたはパスパラメータを使用するパスを指定できます。

パス	パラメータを含むパス
paths: /hello:	paths: /hello/{name}:

API リクエストからのバックエンド サービス URL の生成

API Gateway は API クライアントからのリクエストを処理するときに、API クライアントから送信されたリクエスト URL を受け取り、バックエンド サービスへのリクエストに使用する URL に変換します。この変換がどのように行われるかは、使用しているパス変換方法によって異なります。

x-google-backend 拡張機能の path_translation オプションでは、2 つのパス変換戦略がサポートされます。

• APPEND_PATH_TO_ADDRESS: バックエンド サービス URL は、クライアント リクエストから x-google-backend 拡張子の address URL にリソースパスを付加することによって生成されます。

  ほとんどのバックエンド サービスは、バックエンドが API クライアントで指定されたものと同じリソースパスを受信することを表す APPEND_PATH_TO_ADDRESS を使用します。

• CONSTANT_ADDRESS: バックエンド サービスの URL は定数です。これは x-google-backend 拡張子の address URL で定義されます。クライアント リクエストにリソースパスが含まれている場合、クエリ パラメータを使用してリソースパスがバックエンド サービス URL に追加されます。

  このメソッドは通常、Cloud Functions で使用されます。

次に例を示します。

• APPEND_PATH_TO_ADDRESS
  • address: https://PROJECT_ID.appspot.com
  • OpenAPI パスパラメータを使用しない場合。
    • OpenAPI パス: /hello
    • API クライアント リクエストのリソースパス: /hello
    • バックエンド サービスのリクエスト URL: https://PROJECT_ID.appspot.com/hello
  • OpenAPI パスパラメータを使用する場合。
    • OpenAPI パス: /hello/{name}
    • API クライアント リクエストのリソースパス: /hello/Dave
    • バックエンド サービスのリクエスト URL: https://PROJECT_ID.appspot.com/hello/Dave
• CONSTANT_ADDRESS
  • address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • OpenAPI パスパラメータを使用しない場合。
    • OpenAPI パス: /hello
    • API クライアント リクエストのリソースパス: /hello
    • バックエンド サービスのリクエスト URL: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • OpenAPI パスパラメータを使用する場合。
    • OpenAPI パス: /hello/{name}
    • API クライアント リクエストのリソースパス: /hello/Dave
    • バックエンド サービスのリクエスト URL: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

path_translation の設定

x-google-backend の設定の一部として path_translation を設定します。

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]`

path_translation のデフォルト値は、OpenAPI 仕様で x-google-backend を設定した場所によって異なります。

• x-google-backend が OpenAPI 仕様のトップレベルで使用される場合、path_translation はデフォルトで APPEND_PATH_TO_ADDRESS になります。

• x-google-backend が OpenAPI 仕様のオペレーション レベルで使用される場合、path_translation はデフォルトで CONSTANT_ADDRESS になります。