Meneruskan data ke dan dari layanan backend

Saat klien API membuat permintaan ke API Anda yang di-deploy di Gateway API, klien dapat meneruskan salah satu 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 mengurai 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 perubahan ke klien API. Kemudian, klien API akan memproses data 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, gunakan ekstensi x-google-backend untuk menentukan URL layanan backend. Misalnya, Anda menentukan layanan backend dalam bentuk:

Backend	x-google-backend
Cloud Run Functions	x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run	Salah satu dari berikut ini: x-google-backend: address: APP_URL x-google-backend: address: DETERMINISTIC_URL
Lingkungan standar App Engine	x-google-backend: address: https://PROJECT_ID.appspot.com

Dalam contoh ini:

• APP_URL menentukan URL sebenarnya dari layanan Cloud Run Anda (jalur lengkap API yang dipanggil), yang juga disebut sebagai URL non-deterministik. Misalnya: https://hello-abc1def2gh-uc.a.run.app
• DETERMINISTIC_URL adalah URL deterministik untuk backend layanan Cloud Run Anda.

Catatan: Jika Anda berencana menggunakan URL deterministik untuk membuat versi backend layanan Cloud Run, Anda harus menentukan salah satu hal berikut:

• OpenAPI 2.0: Kolom jwt_audience bersama address di bagian x-google-backend
• OpenAPI 3.x: Kolom jwtAudience bersama address dalam definisi backend di bagian x-google-api-management.backends

Tetapkan kolom jwt_audience atau jwtAudience ke nama host layanan Cloud Run. Misalnya, untuk OpenAPI 2.0:

...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...

Jika kolom jwt_audience atau jwtAudience tidak ada, kolom tersebut akan ditetapkan secara default ke nilai kolom address untuk klaim audiens JWT. Hal ini dapat menyebabkan klaim audiens JWT yang tidak terduga untuk Cloud Run jika URL tag revisi digunakan untuk address dan tidak ada jwt_audience atau jwtAudience yang ditentukan.

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, Gateway API mengambil URL permintaan yang dikirim oleh klien API dan menerjemahkannya ke dalam URL yang digunakan untuk membuat permintaan ke layanan backend. Cara tepat terjadinya penerjemahan ini bergantung pada strategi penerjemahan 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 dari ekstensi x-google-backend.

  Sebagian besar layanan backend menggunakan APPEND_PATH_TO_ADDRESS karena ini 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 dari ekstensi x-google-backend. Jika permintaan klien berisi jalur resource, jalur resource akan 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

Setel path_translation

Tetapkan path_translation sebagai bagian dari setelan 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 akan ditetapkan secara default ke APPEND_PATH_TO_ADDRESS.

• Jika x-google-backend digunakan di tingkat operasi spesifikasi OpenAPI, path_translation ditetapkan secara default ke CONSTANT_ADDRESS.