Referensi konfigurasi YAML proxy API

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan format YAML untuk Template Fitur Apigee: jenis dokumen template, feature, dan proxy serta semua kolomnya. Untuk pengantar konseptual, lihat Mengonfigurasi proxy dengan YAML. Untuk panduan, lihat Membuat proxy API dari template YAML.

Konvensi

  • Nama kolom menggunakan camelCase. Misalnya, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • Skema bersifat ketat. Kolom yang tidak diketahui akan menyebabkan error saat Anda mengimpor file.
  • Kolom wajib diisi. Hanya gateway dan schemaVersion yang divalidasi saat file diuraikan. Kolom lain yang ditandai Ya dalam tabel berikut diperlukan dalam praktiknya untuk menghasilkan proxy API yang berfungsi.

Kolom level teratas umum

Setiap dokumen template, feature, dan proxy dimulai dengan kolom berikut.

Nama Deskripsi Default Wajib?
gateway Gateway target. Harus berupa apigee. T/A Ya
schemaVersion Versi skema dokumen. Harus berupa 1.0.0. T/A Ya
name Nama dokumen. Untuk template atau proxy, ini adalah nama proxy API yang ditulis ke dalam paket. T/A Ya
type Jenis dokumen: template, feature, atau proxy. T/A Ya
description Deskripsi yang dapat dibaca manusia. T/A Tidak
priority Bilangan bulat yang mengontrol urutan penerapan fitur selama kompilasi. Angka yang lebih kecil akan diterapkan terlebih dahulu. 100 Tidak

Jenis dokumen: template

Template adalah titik entri yang Anda impor. File ini menyusun fitur serta menentukan endpoint dan rute proxy. Template tidak berisi kebijakan atau resource; kebijakan atau resource tersebut berasal dari fitur yang dirujuknya.

Nama Deskripsi Default Wajib?
features Daftar file fitur yang akan disusun ke dalam proxy. Setiap entri adalah jalur ke file fitur, yang relatif terhadap direktori yang berisi template (misalnya, ./features/spike-arrest.yaml). [] Tidak
parameters Daftar parameter yang menetapkan nilai untuk parameter fitur. default entri menggantikan default parameter fitur dengan name yang sama. Lihat parameter. [] Tidak
endpoints Daftar endpoint yang menentukan jalur dan rute dasar. [] Tidak
targets Daftar target yang menentukan koneksi backend. [] Tidak

Jenis dokumen: fitur

Fitur adalah unit konfigurasi yang dapat digunakan kembali dan Anda sertakan dalam template. Fitur menyimpan kebijakan dan resource, serta dapat menyumbangkan flow, endpoint, dan target ke proxy yang dikompilasi. Selain kolom tingkat atas umum, fitur memiliki kolom berikut.

Nama Deskripsi Default Wajib?
displayName Nama tampilan yang dapat dibaca manusia. T/A Tidak
uid ID unik yang memisahkan kebijakan dan resource fitur saat template menyertakan fitur lebih dari sekali. Jika fitur menetapkan uid, CLI akan mengawali setiap nama kebijakan dan resource-nya dengan UID- dan memperbarui referensi ke nama tersebut. Jika fitur tidak menetapkan uid, CLI akan menggunakan nama seperti yang tertulis. T/A Tidak
documentation Dokumentasi yang diperluas untuk fitur ini. T/A Tidak
categories Daftar label kategori bentuk bebas. [] Tidak
parameters Daftar parameter yang ditentukan fitur. [] Tidak
defaultEndpoint Endpoint proxy yang alur dan aturan kesalahan defaultnya digabungkan ke dalam setiap endpoint proxy yang dikompilasi. Gunakan ini untuk melampirkan kebijakan fitur ke alur permintaan atau respons. T/A Tidak
defaultTarget Target proxy yang digunakan sebagai koneksi backend default. T/A Tidak
endpoints Daftar endpoint proxy yang akan ditambahkan ke proxy. Endpoint dengan nama yang sama dengan endpoint yang ada akan menggantikannya. [] Tidak
targets Daftar target proxy yang akan ditambahkan ke proxy. Target dengan nama yang sama dengan target yang ada akan menggantikannya. [] Tidak
policies Daftar kebijakan yang disediakan fitur. Jika set fitur menetapkan uid, CLI akan memberi awalan pada setiap nama kebijakan dengan UID- selama kompilasi, misalnya sa1-SA-SpikeArrest. Jika tidak, CLI akan menggunakan nama kebijakan seperti yang tertulis. [] Tidak
resources Daftar resource yang disediakan fitur, seperti JavaScript atau file properti. [] Tidak

Jenis dokumen: proxy

Proxy adalah dokumen yang di-resolve sepenuhnya yang dihasilkan CLI saat mengompilasi template dengan fiturnya. Anda biasanya tidak menulis jenis ini secara langsung; jenis ini dijelaskan di sini karena merupakan bentuk yang menjadi paket proxy API.

Proxy memiliki kolom yang sama dengan fitur, kecuali bahwa proxy menggunakan endpoints dan targets (bukan defaultEndpoint atau defaultTarget) dan selalu mewakili proxy yang lengkap dan dapat di-deploy. type-nya adalah proxy.

Objek bertingkat

parameter

Parameter memberikan nilai ke fitur. Fitur mendeklarasikan parameternya, dan template dapat menetapkan nilainya dalam daftar parameters-nya sendiri. Saat mengompilasi template, CLI akan me-resolve setiap parameter fitur sebagai berikut:

  1. Jika daftar parameters template memiliki entri yang name-nya cocok dan default-nya tidak kosong, CLI akan menggunakan nilai tersebut. Jika set fitur menetapkan uid, nama entri template harus FEATURE_NAME.UID.PARAMETER_NAME.
  2. Jika tidak, CLI akan menggunakan default parameter fitur.
  3. Jika tidak ada yang menetapkan nilai, parameter akan di-resolve ke string kosong. CLI tidak melaporkan error.

Tidak ada tanda command line untuk menetapkan nilai parameter pada waktu impor. Untuk mengubah nilai, edit template.

Nama Deskripsi Default Wajib?
name Nama parameter. Direferensikan dalam konten unggulan sebagai {name}. T/A Ya
displayName Nama yang dapat dibaca manusia. T/A Tidak
description Deskripsi parameter. T/A Tidak
default Dalam fitur, nilai yang digunakan saat template tidak menetapkannya. Dalam template, nilai untuk parameter fitur dengan nama yang sama. CLI mengabaikan nilai kosong. CLI mengganti nilai yang di-resolve untuk {name} dalam string fitur. T/A Tidak
examples Daftar contoh nilai. [] Tidak
maps Peta penggantian nilai. Jika nilai yang di-resolve adalah kunci dalam peta, nilai tersebut akan diganti dengan nilai yang dipetakan. T/A Tidak
paths Daftar ekspresi JSONPath. Tidak didukung dalam rilis ini—penggunaannya akan menyebabkan error. T/A Tidak

endpoint

Digunakan dalam daftar endpoints template.

Nama Deskripsi Default Wajib?
name Nama endpoint. T/A Ya
basePath Jalur dasar yang digunakan klien untuk memanggil proxy, misalnya /v1/gemini. T/A Tidak
routes Daftar rute yang memetakan permintaan ke target. [] Tidak

proxyEndpoint

Digunakan dalam defaultEndpoint dan endpoints fitur, serta dalam proxy yang dikompilasi. Memperluas endpoint dengan penanganan alur.

Nama Deskripsi Default Wajib?
flows Daftar alur. Alur bernama PreFlow atau PostFlow dipetakan ke alur Apigee yang sesuai; nama lainnya ditempatkan di penampung alur umum. [] Tidak
postClientFlow Satu alur yang berjalan setelah respons dikirim ke klien. T/A Tidak
faultRules Daftar alur yang digunakan sebagai aturan kesalahan. [] Tidak
defaultFaultRule Aturan kesalahan yang berjalan saat tidak ada aturan kesalahan lain yang cocok. T/A Tidak

rute

Nama Deskripsi Default Wajib?
name Nama rute. T/A Ya
target Nama endpoint target yang akan dirutekan. T/A Tidak
condition Kondisi yang harus benar agar rute ini berlaku. T/A Tidak

konsentrasi

Nama Deskripsi Default Wajib?
name Nama alur. Gunakan PreFlow atau PostFlow untuk alur permintaan/respons standar. T/A Ya
mode Request atau Response. Menentukan apakah langkah-langkah dijalankan pada permintaan atau respons. Request Tidak
condition Kondisi yang harus benar agar alur dapat berjalan. T/A Tidak
steps Daftar langkah yang diurutkan (pemanggilan kebijakan). [] Tidak

langkah

Langkah menjalankan kebijakan dalam alur.

Nama Deskripsi Default Wajib?
name Nama kebijakan yang akan dijalankan. Dalam fitur, gunakan nama lokal kebijakan; compiler akan menulis ulang nama tersebut ke nama yang diberi namespace. T/A Ya
condition Kondisi yang harus benar agar langkah dapat dijalankan. T/A Tidak

faultRule

Memperluas flow dengan satu kolom tambahan.

Kolom mode yang diwarisi dari alur tidak berlaku untuk aturan kesalahan. Karena aturan kesalahan berjalan setelah permintaan gagal, aturan ini tidak memiliki fase permintaan atau respons; langkah-langkahnya selalu berjalan secara langsung. Jika Anda menetapkan mode pada aturan kesalahan, alat ini akan mencatat peringatan dan mengabaikan kolom tersebut.

Nama Deskripsi Default Wajib?
alwaysEnforce Jika true, aturan kesalahan default akan selalu diterapkan. false Tidak

target

Digunakan dalam daftar targets template.

Nama Deskripsi Default Wajib?
name Nama target. Dirujuk oleh target rute. T/A Ya
url URL backend. T/A Tidak
auth Skema autentikasi untuk backend Google Cloud, misalnya GoogleAccessToken atau GoogleIDToken. T/A Tidak
scopes Daftar cakupan OAuth yang akan diminta. Berlaku saat auth ditetapkan. [] Tidak
aud Audiens untuk token. Berlaku saat auth ditetapkan. T/A Tidak

proxyTarget

Digunakan dalam defaultTarget dan targets fitur, serta dalam proxy yang dikompilasi. Memperluas target dengan penanganan alur dan penggantian koneksi mentah.

Nama Deskripsi Default Wajib?
flows Daftar alur yang berjalan pada permintaan atau respons target. [] Tidak
faultRules Daftar alur yang digunakan sebagai aturan kesalahan. [] Tidak
defaultFaultRule Aturan kesalahan. T/A Tidak
httpTargetConnection Representasi mentah elemen HTTPTargetConnection, untuk konfigurasi lanjutan. Jika ditetapkan, setelan ini akan lebih diprioritaskan daripada url, auth, scopes, dan aud. T/A Tidak
localTargetConnection Representasi mentah elemen LocalTargetConnection. Jika ditetapkan, koneksi ini akan lebih diprioritaskan daripada koneksi HTTP. T/A Tidak

kebijakan

Kebijakan ditentukan dalam fitur. Konfigurasinya ditulis di bagian content menggunakan konvensi atribut/teks yang dijelaskan dalam Konvensi konten kebijakan.

Nama Deskripsi Default Wajib?
name Nama kebijakan. T/A Ya
type Jenis kebijakan Apigee, misalnya VerifyAPIKey, SpikeArrest, atau Javascript. Harus cocok dengan satu kunci tingkat teratas di content. T/A Ya
content Kamus satu kunci yang satu kuncinya sama dengan type. Nilai bertingkat menjelaskan XML kebijakan menggunakan konvensi di bawah. {} Ya

Konvensi konten kebijakan

Kebijakan Apigee menggunakan XML. Di YAML, Anda merepresentasikan XML tersebut di content dengan aturan berikut:

  • Kamus content memiliki tepat satu kunci, yang harus cocok dengan type kebijakan.
  • Atribut elemen berada di bawah kunci metadata.
  • Teks elemen berada di bawah kunci _text. Misalnya, <Foo bar="baz">qux</Foo> menjadi Foo: {metadata: {bar: "baz"}, _text: "qux"}. Jika elemen hanya memiliki teks dan tidak memiliki atribut, Anda dapat menulis teks secara langsung sebagai nilai.
  • Elemen turunan disusun bertingkat di bawah nama tag-nya. Tag berulang menjadi daftar.

Misalnya, kebijakan fitur ini:

policies:
- name: VA-VerifyAPIKey
  type: VerifyAPIKey
  content:
    VerifyAPIKey:
      metadata:
        name: VA-VerifyAPIKey
        enabled: "true"
        continueOnError: "false"
      DisplayName: VA-VerifyAPIKey
      APIKey:
        metadata:
          ref: request.header.x-api-key

dikompilasi ke XML kebijakan ini:

<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey">
  <APIKey ref="request.header.x-api-key"></APIKey>
  <DisplayName>VA-VerifyAPIKey</DisplayName>
</VerifyAPIKey>

resource

Resource adalah file yang dikontribusikan oleh fitur ke paket, seperti file JavaScript atau file properti.

Nama Deskripsi Default Wajib?
name Nama file, misalnya hello-world.js. Jika fitur menetapkan uid, CLI akan mengawali nama resource dengan UID- selama kompilasi. Jika tidak, CLI akan menggunakan nama seperti yang tertulis. T/A Ya
type Jenis resource, yang menentukan subdirektori dalam paket, misalnya jsc (JavaScript) atau properties. T/A Ya
content Konten file mentah. T/A Tidak

Kolom yang tidak didukung dalam rilis ini

  • paths pada parameter (JSONPath). Penggunaannya akan menyebabkan kompilasi gagal.
  • tests di dokumen mana pun. Kolom ini diterima, tetapi diabaikan, dan tidak disertakan dalam paket yang dihasilkan.

Batas

Paket proxy API yang dihasilkan tidak boleh melebihi 10 MiB yang tidak dikompresi atau 256 file.

Langkah berikutnya