Mengonfigurasi proxy dengan YAML

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Anda dapat menentukan proxy API Apigee dalam YAML dan men-deploy-nya dengan Google Cloud CLI, sebagai alternatif untuk membuat paket proxy XML tradisional. Anda menjelaskan endpoint, rute, kebijakan, dan target backend proxy dalam file YAML yang disebut Apigee Feature Templates, dan Apigee mengompilasinya menjadi paket proxy API standar untuk Anda.

Karena hasilnya adalah paket proxy API Apigee biasa, proxy yang Anda buat dengan cara ini berjalan di runtime Apigee yang sama, dengan kebijakan dan perilaku yang sama seperti proxy yang Anda buat di UI Apigee atau dari paket XML.

Alasan menggunakan YAML untuk menentukan proxy

Format proxy API Apigee tradisional adalah arsip ZIP file XML. YAML menawarkan alternatif yang menurut banyak developer lebih cepat dibaca, ditulis, dan ditinjau, serta berfungsi baik dengan alat bantu dan alat berbasis agen yang dibantu AI. Template Fitur Apigee dirancang untuk:

  • Developer dan arsitek API yang lebih memilih format deklaratif yang ringkas dan ingin menyimpan konfigurasi proxy dalam kontrol sumber.
  • Praktisi AI yang menginginkan cara standar untuk menempatkan gateway Apigee di depan backend model.
  • Tim Platform dan DevOps yang ingin mengemas bagian konfigurasi proxy yang dapat digunakan kembali dan menerapkannya secara konsisten di banyak proxy.

Konsep utama

Template Fitur Apigee menggunakan tiga jenis dokumen. Setiap file adalah file YAML yang diidentifikasi oleh kolom type-nya.

Jenis dokumen Nilai type Tujuan
Template template Titik entri yang Anda deploy. Template terdiri dari satu atau beberapa fitur dan menentukan endpoint serta rute proxy.
Fitur feature Unit konfigurasi yang dapat digunakan kembali—seperti pemeriksaan autentikasi, batas kecepatan, atau target backend—yang Anda sertakan dalam template. Fitur menyimpan kebijakan dan resource.
Proxy proxy Proxy yang sepenuhnya diselesaikan yang dihasilkan CLI saat mengompilasi template dengan fiturnya. Meskipun biasanya merupakan output perantara yang dihasilkan oleh CLI, Anda juga dapat mengimpor file proxy secara langsung untuk diterjemahkan menjadi paket proxy API.

Anda membuat template dan fitur. Apigee membuat proxy untuk Anda selama kompilasi.

Cara kerjanya

Saat Anda mengimpor template, Google Cloud CLI akan melakukan langkah-langkah berikut secara lokal, lalu mengupload hasilnya ke Apigee:

  1. Kompilasi. CLI membaca template Anda dan file fitur yang direferensikannya, menggabungkannya, dan menghasilkan satu definisi proxy.
  2. Konversi. CLI mengonversi definisi proxy menjadi paket proxy API Apigee standar (ZIP file XML yang diharapkan Apigee).
  3. Impor. CLI mengupload bundle ke Apigee, yang membuat revisi proxy API baru.

Mengimpor proxy tidak akan mengaktifkannya. Sebagai langkah terpisah, Anda men-deploy revisi ke lingkungan, persis seperti yang Anda lakukan untuk proxy API lainnya:

YAML template + feature files
  |  gcloud beta apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)

Untuk mengetahui petunjuk langkah demi langkah, lihat Membuat proxy API dari template YAML.

Contoh minimal

Template berikut menentukan proxy yang menyusun dua fitur—satu yang menambahkan target backend dan satu yang menambahkan pesan respons:

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

Setiap file fitur yang direferensikan harus berada di direktori yang sama dengan template. Untuk contoh yang lengkap dan dapat dijalankan serta file fitur yang digunakannya, lihat artikel Membuat proxy API dari template YAML.

Yang dapat Anda lakukan

  • Tentukan endpoint, jalur dasar, rute, alur, dan target backend proxy dalam YAML.
  • Kemas kebijakan dan resource yang dapat digunakan kembali sebagai fitur dan susun dalam template.
  • Tambahkan autentikasi backend untuk target Google Cloud (misalnya, token akses Google untuk backend Vertex AI).
  • Impor template sebagai revisi proxy API baru dengan Google Cloud CLI, lalu deploy dengan perintah deployment standar.

Batasan

Perhatikan hal-hal berikut saat Anda membuat template dan fitur:

  • Fitur adalah file lokal. Template hanya dapat mereferensikan file fitur yang ada di direktori yang sama. Fitur yang dirujuk berdasarkan URL atau dari katalog bersama tidak didukung.
  • Nilai parameter menggunakan nilai defaultnya. Fitur dapat menentukan parameter, tetapi nilai parameter diselesaikan ke default yang ditentukan dalam fitur. Tidak ada flag command line untuk mengganti nilai parameter pada waktu impor.
  • Parameter JSONPath tidak didukung. Parameter yang menggunakan ekspresi paths (JSONPath) menyebabkan kompilasi gagal.
  • Pengujian tidak didukung. Bagian tests diterima oleh skema, tetapi diabaikan dan tidak disertakan dalam paket yang dihasilkan.
  • Skemanya ketat. Kolom yang tidak diketahui akan menyebabkan error. Hanya gateway: apigee dan schemaVersion: 1.0.0 yang didukung.
  • Pemecahan masalah menggunakan XML yang dihasilkan. UI dan runtime Apigee bekerja dengan paket yang dihasilkan. Tidak ada perjalanan pulang-pergi kembali ke sumber YAML Anda di UI.

Langkah berikutnya