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

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 Run 関数	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 Run 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 になります。