Meneruskan data ke dan dari layanan backend

Saat klien API membuat permintaan ke API Anda yang di-deploy di API Gateway, klien dapat meneruskan sebagian atau semua informasi berikut sebagai bagian dari permintaan:

Header permintaan
Parameter kueri
Data formulir
Payload XML atau JSON
Jalur permintaan

Dalam membuat respons terhadap permintaan API, layanan backend dapat menampilkan data ke klien API, termasuk:

Header respons
Payload XML atau JSON

Dokumen ini menjelaskan cara data ini diteruskan ke dan dari layanan backend.

Bagaimana data permintaan diteruskan ke layanan backend?

Semua data dalam permintaan dari klien API diteruskan tanpa perubahan ke layanan backend. Kemudian, layanan backend akan mem-parsing data permintaan sebagai bagian dari penanganan permintaan.

Bagaimana data respons ditampilkan ke klien API?

Semua data yang diterima dalam respons dari layanan backend diteruskan tanpa diubah ke klien API. Kemudian, klien API yang akan memproses data apa pun yang ditampilkan dalam respons.

Bagaimana URL permintaan diteruskan ke layanan backend?

URL yang digunakan untuk membuat permintaan ke layanan backend dikontrol oleh ekstensi x-google-backend. Bagian ini menjelaskan opsi untuk mengonfigurasi URL layanan backend.

Menetapkan alamat dan jalur layanan backend dalam spesifikasi OpenAPI

Dalam spesifikasi OpenAPI yang Anda gunakan untuk membuat konfigurasi API, Anda menggunakan ekstensi x-google-backend untuk menentukan URL layanan backend. Misalnya, Anda menentukan layanan backend dalam formulir:

Backend	x-google-backend
Cloud Run Functions	x-google-backend: address: https://`GCP_REGION`-`PROJECT_ID`.cloudfunctions.net/hello
Cloud Run	x-google-backend: address: https://[`TAG`---]`SERVICE_NAME`-`PROJECT_NUMBER`.`REGION`.run.app
Lingkungan standar App Engine	x-google-backend: address: https://`PROJECT_ID`.appspot.com

Backend

x-google-backend

Cloud Run Functions

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello

Cloud Run

x-google-backend:
  address: https://[TAG---]SERVICE_NAME-PROJECT_NUMBER.REGION.run.app

Lingkungan standar App Engine

x-google-backend:
  address: https://PROJECT_ID.appspot.com

Dalam contoh ini:

GCP_REGION menentukan Google Cloud region untuk backend yang di-deploy.
PROJECT_ID menentukan Google Cloud project ID.
TAG adalah tag traffic opsional untuk revisi Cloud Run yang Anda minta. Lihat juga URL Deterministik dalam dokumentasi Cloud Run.
SERVICE_NAME adalah nama layanan Cloud Run.
PROJECT_NUMBER adalah Google Cloud nomor project.
REGION adalah nama region, seperti us-west1.

Selain itu, parameter path dalam spesifikasi OpenAPI menentukan endpoint, atau resource, yang didukung oleh API Anda. Anda dapat menentukan jalur absolut atau jalur yang menggunakan parameter jalur:

Jalur	Jalur dengan parameter
paths: /hello:	paths: /hello/{name}:

Membuat URL layanan backend dari permintaan API

Saat menangani permintaan dari klien API, API Gateway mengambil URL permintaan yang dikirim oleh klien API dan menerjemahkannya menjadi URL yang digunakan untuk membuat permintaan ke layanan backend. Cara persisnya terjemahan ini terjadi bergantung pada strategi terjemahan jalur yang Anda gunakan.

Opsi path_translation untuk ekstensi x-google-backend mendukung dua strategi terjemahan jalur:

APPEND_PATH_TO_ADDRESS: URL layanan backend dibuat dengan menambahkan jalur resource dari permintaan klien ke URL address ekstensi x-google-backend.

Sebagian besar layanan backend menggunakan APPEND_PATH_TO_ADDRESS karena berarti backend menerima jalur resource yang sama seperti yang ditentukan oleh klien API.
CONSTANT_ADDRESS: URL layanan backend bersifat konstan, seperti yang ditentukan oleh URL address ekstensi x-google-backend. Jika permintaan klien berisi jalur resource, jalur resource ditambahkan ke URL layanan backend menggunakan parameter kueri.

Metode ini biasanya digunakan oleh Cloud Run Functions.

Contoh:

APPEND_PATH_TO_ADDRESS
- address: https://PROJECT_ID.appspot.com
- Tanpa parameter jalur OpenAPI:
  - Jalur OpenAPI: /hello
  - Jalur resource permintaan klien API: /hello
  - URL permintaan layanan backend: https://PROJECT_ID.appspot.com/hello
- Dengan parameter jalur OpenAPI:
  - Jalur OpenAPI: /hello/{name}
  - Jalur resource permintaan klien API: /hello/Dave
  - URL permintaan layanan backend: https://PROJECT_ID.appspot.com/hello/Dave
CONSTANT_ADDRESS
- address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- Tanpa parameter jalur OpenAPI
  - Jalur OpenAPI: /hello
  - Jalur resource permintaan klien API: /hello
  - URL permintaan layanan backend: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- Dengan parameter jalur OpenAPI
  - Jalur OpenAPI: /hello/{name}
  - Jalur resource permintaan klien API: /hello/Dave
  - URL permintaan layanan backend: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

Menetapkan `path_translation`

Tetapkan path_translation sebagai bagian dari penetapan x-google-backend:

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

Nilai default path_translation bergantung pada tempat Anda menetapkan x-google-backend dalam spesifikasi OpenAPI:

Jika x-google-backend digunakan di tingkat teratas spesifikasi OpenAPI, path_translation secara default adalah APPEND_PATH_TO_ADDRESS.
Jika x-google-backend digunakan di tingkat operasi spesifikasi OpenAPI, path_translation secara default adalah CONSTANT_ADDRESS.