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
gatewaydanschemaVersionyang 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:
- Jika daftar
parameterstemplate memiliki entri yangname-nya cocok dandefault-nya tidak kosong, CLI akan menggunakan nilai tersebut. Jika set fitur menetapkanuid, nama entri template harusFEATURE_NAME.UID.PARAMETER_NAME. - Jika tidak, CLI akan menggunakan
defaultparameter fitur. - 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
contentmemiliki tepat satu kunci, yang harus cocok dengantypekebijakan. - Atribut elemen berada di bawah kunci
metadata. - Teks elemen berada di bawah kunci
_text. Misalnya,<Foo bar="baz">qux</Foo>menjadiFoo: {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
pathspada parameter (JSONPath). Penggunaannya akan menyebabkan kompilasi gagal.testsdi 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.