Meneruskan data ke dan dari layanan backend

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

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

Dalam membuat responsnya 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. Selanjutnya terserah layanan backend untuk mengurai data permintaan sebagai bagian dari penanganan permintaan.

Bagaimana data respons ditampilkan ke klien API?

Semua data yang diterima dalam respons dari layanan backend akan diteruskan tidak berubah ke klien API. Selanjutnya, klien API akan bertanggung jawab untuk memproses data yang ditampilkan dalam respons.

Bagaimana cara 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

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

Backend 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
Lingkungan standar App Engine 

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

Dalam contoh ini:

  1. GCP_REGION menentukan region GCP untuk backend yang di-deploy.
  2. PROJECT_ID menentukan ID project Google Cloud.
  3. HASH menentukan kode hash unik yang dihasilkan saat layanan Cloud Run dibuat.

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 lokasi:

Jalur Jalur dengan parameter 

paths:
  /hello:
 

paths:
  /hello/{name}:

Membuat URL layanan backend dari permintaan API

Karena Gateway API menangani permintaan dari klien API, Gateway API mengambil URL permintaan yang dikirim oleh klien API dan menerjemahkannya menjadi URL yang digunakan untuk membuat permintaan ke layanan backend. Persisnya, cara penerjemahan ini bergantung pada strategi terjemahan jalur yang Anda gunakan.

Opsi path_translation ke 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 artinya backend menerima jalur resource yang sama seperti yang ditetapkan 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 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

Setelan path_translation

Setel 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 pada level teratas spesifikasi OpenAPI, path_translation akan ditetapkan secara default ke APPEND_PATH_TO_ADDRESS.

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