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 melihat panduan, lihat Membuat proxy API dari template YAML.

Konvensi

  • Nama kolom menggunakan camelCase. Misalnya, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • Skemanya ketat. Kolom yang tidak diketahui menyebabkan error saat Anda mengimpor file.
  • Kolom wajib diisi. Hanya gateway dan schemaVersion yang divalidasi saat file diurai. Kolom lain yang ditandai Ya dalam tabel berikut sebenarnya wajib diisi 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 rendah akan diterapkan terlebih dahulu. 100 Tidak

Jenis dokumen: template

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

Nama Deskripsi Default Wajib?
features Daftar nama file fitur yang akan disusun ke dalam proxy. Setiap nama harus di-resolve ke file di direktori yang sama dengan template. [] Tidak
parameters Daftar nilai parameter yang menyediakan default ke fitur. [] Tidak
endpoints Daftar endpoint yang menentukan jalur dasar dan rute. [] Tidak
targets Daftar target yang menentukan koneksi backend. [] Tidak

Jenis dokumen: fitur

Fitur adalah unit konfigurasi yang dapat digunakan kembali yang Anda sertakan dalam template. Fitur menyimpan kebijakan dan resource, serta dapat berkontribusi pada alur, endpoint, dan target ke proxy yang dikompilasi. Selain kolom level teratas umum, fitur memiliki kolom berikut.

Nama Deskripsi Default Wajib?
displayName Nama tampilan yang dapat dibaca manusia. T/A Tidak
uid ID unik yang digunakan untuk memberi namespace pada kebijakan dan resource fitur. Jika tidak disetel, name akan digunakan. T/A Tidak
documentation Memperluas dokumentasi untuk fitur ini. T/A Tidak
categories Daftar label kategori bentuk bebas. [] Tidak
parameters Daftar parameter yang ditentukan oleh fitur. [] Tidak
defaultEndpoint Endpoint proxy yang alur dan aturan kesalahan defaultnya digabungkan ke 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. Nama kebijakan otomatis diawali dengan uid (atau name) fitur selama kompilasi. [] Tidak
resources Daftar resource yang disediakan fitur, seperti file JavaScript atau properti. [] Tidak

Jenis dokumen: proxy

Proxy adalah dokumen yang sepenuhnya di-resolve yang dihasilkan CLI saat mengompilasi template dengan fiturnya. Anda biasanya tidak membuat 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 menggunakan endpoints dan targets (bukan defaultEndpoint atau defaultTarget) dan selalu merepresentasikan proxy yang lengkap dan dapat di-deploy. type-nya adalah proxy.

Objek bertingkat

parameter

Parameter memberikan nilai ke fitur. Nilai parameter di-resolve ke default-nya.

Nama Deskripsi Default Wajib?
name Nama parameter. Dirujuk dalam konten fitur sebagai {name}. T/A Ya
displayName Nama yang dapat dibaca manusia. T/A Tidak
description Deskripsi parameter. T/A Tidak
default Nilai default. Digantikan dengan {name} di 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 diganti dengan nilai yang dipetakan. T/A Tidak
paths Daftar ekspresi JSONPath. Tidak didukung dalam rilis ini—menggunakannya 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 aliran.

Nama Deskripsi Default Wajib?
flows Daftar alur. Alur yang dinamai PreFlow atau PostFlow dipetakan ke alur Apigee yang sesuai; nama lainnya ditempatkan di penampung alur generik. [] Tidak
postClientFlow Satu alur yang berjalan setelah respons dikirim ke klien. T/A Tidak
faultRules Daftar flow 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 dituju. T/A Tidak
condition Kondisi yang harus benar agar rute ini dapat diterapkan. 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 urutan langkah (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 ke nama yang memiliki namespace. T/A Ya
condition Kondisi yang harus benar agar langkah dapat berjalan. T/A Tidak

faultRule

Memperluas flow dengan satu kolom tambahan.

Nama Deskripsi Default Wajib?
alwaysEnforce Jika true, aturan kesalahan default 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 flow yang berjalan pada permintaan atau respons target. [] Tidak
faultRules Daftar flow yang digunakan sebagai aturan kesalahan. [] Tidak
defaultFaultRule Aturan kesalahan. T/A Tidak
httpTargetConnection Representasi mentah elemen HTTPTargetConnection, untuk konfigurasi lanjutan. Jika ditetapkan, nilai ini akan lebih diprioritaskan daripada url, auth, scopes, dan aud. T/A Tidak
localTargetConnection Representasi mentah dari elemen LocalTargetConnection. Jika disetel, 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-satunya kunci tingkat teratas di content. T/A Ya
content Kamus satu kunci yang satu kuncinya sama dengan type. Nilai bertumpuk menjelaskan XML kebijakan menggunakan konvensi di bawah. {} Ya

Konvensi konten kebijakan

Kebijakan Apigee adalah XML. Di YAML, Anda merepresentasikan XML 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 berkontribusi pada bundle, seperti file JavaScript atau file properti.

Nama Deskripsi Default Wajib?
name Nama file, misalnya hello-world.js. Nama resource diawali dengan uid (atau name) fitur selama kompilasi. T/A Ya
type Jenis resource, yang menentukan subdirektori dalam bundle, misalnya jsc (JavaScript) atau properties. T/A Ya
content Isi file mentah. T/A Tidak

Kolom yang tidak didukung dalam rilis ini

  • paths pada parameter (JSONPath). Menggunakannya akan menyebabkan kompilasi gagal.
  • tests pada dokumen apa pun. Kolom 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