Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Sebagai developer yang bekerja dengan Apigee Edge, aktivitas pengembangan utama Anda melibatkan konfigurasi proxy API yang berfungsi sebagai proxy untuk API atau layanan backend. Dokumen ini adalah referensi semua elemen konfigurasi yang tersedia bagi Anda saat membuat proxy API.
Jika Anda sedang mempelajari cara membuat proxy API, sebaiknya mulai dengan topik Membangun proxy API sederhana.
Cara paling umum untuk mengedit konfigurasi proxy adalah:
- Menggunakan editor XML dalam UI Edge
- Download konfigurasi dan edit secara lokal, seperti yang dijelaskan dalam Pengembangan konfigurasi proxy lokal.
Pengembangan lokal konfigurasi proxy
Anda dapat mendownload konfigurasi proxy agar dapat mengeditnya di komputer lokal. Setelah selesai, Anda dapat mengupload hasilnya ke Edge. Dengan pendekatan ini, Anda dapat mengintegrasikan konfigurasi proxy ke dalam kontrol sumber, pembuatan versi, dan alur kerja bersama lainnya. Selain itu, dengan mengerjakan konfigurasi proxy secara lokal, Anda dapat menggunakan editor dan alat validasi XML Anda sendiri.
Bagian ini menjelaskan cara menggunakan UI untuk mendownload konfigurasi proxy yang ada, mengeditnya,
lalu menguploadnya kembali ke Edge untuk deployment. Anda juga dapat menggunakan
apigeetool
untuk mendownload dan men-deploy konfigurasi proxy baru (dengan menggunakan perintah fetchproxy dan
deployproxy).
Untuk mengedit konfigurasi proxy secara lokal menggunakan UI:
- Download konfigurasi proxy saat ini di UI Edge. (Di tampilan API Proxies, pilih Project > Download Revision.)
- Di komputer lokal, buat direktori baru dan ekstrak file ZIP yang didownload ke
direktori tersebut.
Untuk mengekstrak file ZIP, Anda dapat menggunakan utilitas seperti
unzip, seperti yang ditunjukkan dalam contoh berikut:mkdir myappdir
unzip ./my-app_app_rev3_2019_04_20.zip -d myappdirIsi file ZIP yang diekstrak harus serupa dengan struktur yang dijelaskan dalam Struktur proxy API.
- Edit file sumber sesuai kebutuhan. Untuk deskripsi file sumber dalam konfigurasi
proxy, lihat
File konfigurasi dan
struktur direktori proxy API.
Misalnya, untuk mengaktifkan pemantauan kondisi sistem di proxy API, edit file konfigurasi TargetEndpoint di direktori
/apiproxy/targets/. File default di direktori ini adalahdefault.xml, meskipun mungkin ada file dengan nama berbeda jika Anda menggunakan target bersyarat.Dalam kasus ini, jika file konfigurasi TargetEndpoint dan direktorinya tidak ada, buat file dan direktori tersebut.
- Setelah selesai mengedit file konfigurasi proxy, pastikan untuk menyimpan perubahan Anda.
- Beralih ke direktori baru yang Anda buat saat mengekstrak file ZIP (root dari
file konfigurasi yang diekstrak).
Misalnya, jika Anda mengekstrak file ke direktori
/myappdir, ubah ke direktori tersebut, seperti yang ditunjukkan contoh berikut:cd myappdir
Anda harus beralih ke direktori ini sebelum mengarsipkan ulang file konfigurasi proxy karena Anda tidak ingin direktori
/myappdirdisertakan dalam file ZIP. Direktori tingkat teratas dalam file ZIP harus berupa/apiproxy. - Arsipkan kembali file konfigurasi proxy, termasuk file baru atau yang diubah. Anda dapat menggunakan
utilitas seperti
zip, seperti yang ditunjukkan dalam contoh berikut:zip my-new-proxy.zip -r .
Direktori tingkat teratas dalam file ZIP harus berupa
/apiproxy.Tidak ada persyaratan khusus untuk nama file ZIP. Misalnya, Anda tidak perlu menaikkan nomor revisi atau menentukan tanggal dalam nama file, tetapi tindakan ini dapat berguna untuk proses debug atau kontrol sumber.
Edge akan menaikkan nomor revisi konfigurasi proxy baru untuk Anda saat Anda menguploadnya.
- Upload konfigurasi proxy baru menggunakan UI Edge. (Di tampilan API Proxies, pilih Project > Upload a New Revision.)
Jika Anda mendapatkan error seperti Bundle is invalid. Empty bundle., pastikan direktori tingkat atas file ZIP Anda adalah
/apiproxy. Jika tidak, arsipkan ulang file konfigurasi proxy Anda dari root direktori yang diekstrak.Setelah mengupload konfigurasi proxy baru, Edge akan menaikkan nomor revisi dan menampilkannya di tampilan Ringkasan Revisi.
Edge tidak men-deploy revisi baru untuk Anda setelah Anda menguploadnya dengan UI.
- Deploy revisi baru Anda.
Untuk mengetahui informasi selengkapnya, lihat Tutorial: Cara mendownload proxy menggunakan UI dan Management API di Komunitas Apigee.
Struktur proxy API
Proxy API terdiri dari konfigurasi berikut:
| Konfigurasi Dasar | Setelan konfigurasi utama untuk proxy API. Lihat Konfigurasi Dasar. |
| Konfigurasi ProxyEndpoint | Setelan untuk koneksi HTTP masuk (dari aplikasi yang meminta ke Apigee Edge), alur permintaan dan respons, serta lampiran kebijakan. Lihat ProxyEndpoint. |
| Konfigurasi TargetEndpoint | Setelan untuk koneksi HTTP keluar (dari Apigee Edge ke layanan backend), alur permintaan dan respons, serta lampiran kebijakan. Lihat TargetEndpoint. |
| Flows | Pipeline permintaan dan respons ProxyEndpoint dan TargetEndpoint yang dapat dilampiri kebijakan. Lihat Alur. |
| Kebijakan | File konfigurasi berformat XML yang sesuai dengan skema kebijakan Apigee Edge. Lihat Kebijakan. |
| Referensi | Skrip, file JAR, dan file XSLT yang dirujuk oleh kebijakan untuk menjalankan logika kustom. Lihat Resource. |
Struktur direktori proxy API dan konten
Komponen dalam tabel di atas ditentukan oleh file konfigurasi dalam struktur direktori berikut:

File konfigurasi dan struktur direktori proxy API
Bagian ini menjelaskan file konfigurasi dan struktur direktori proxy API.
Konfigurasi Dasar
/apiproxy/weatherapi.xml
Konfigurasi dasar untuk proxy API, yang menentukan nama proxy API. Nama harus unik dalam organisasi.
Contoh konfigurasi:
<APIProxy name="weatherapi"> </APIProxy>
Elemen Konfigurasi Dasar
| Nama | Deskripsi | Default | Wajib? |
|---|---|---|---|
APIProxy |
|||
name |
Nama proxy API, yang harus unik dalam organisasi. Karakter yang diizinkan untuk digunakan dalam nama dibatasi sebagai berikut:
A-Za-z0-9_- |
T/A | Ya |
revision |
Nomor revisi konfigurasi proxy API. Anda tidak perlu menetapkan nomor revisi secara eksplisit, karena Apigee Edge secara otomatis melacak revisi saat ini dari proxy API. | T/A | Tidak |
ConfigurationVersion |
Versi skema konfigurasi proxy API yang sesuai dengan proxy API ini. Satu-satunya nilai yang didukung saat ini adalah majorVersion 4 dan minorVersion 0. Setelan ini dapat digunakan di masa mendatang untuk memungkinkan evolusi format proxy API. | 4.0 | Tidak |
Description |
Deskripsi tekstual proxy API. Jika disediakan, deskripsi akan ditampilkan di UI pengelolaan Edge. | T/A | Tidak |
DisplayName |
Nama yang mudah digunakan yang mungkin berbeda dengan atribut name dari
konfigurasi proxy API. |
T/A | Tidak |
Policies |
Daftar kebijakan di direktori /policies proxy API ini. Anda
biasanya hanya melihat elemen ini saat proxy API dibuat menggunakan UI pengelolaan Edge.
Ini hanyalah setelan 'manifest', yang dirancang untuk memberikan visibilitas ke konten
proxy API. |
T/A | Tidak |
ProxyEndpoints |
Daftar ProxyEndpoint dalam direktori /proxies proxy API ini. Anda
biasanya hanya akan melihat elemen ini saat proxy API dibuat menggunakan UI pengelolaan
Edge. Ini hanyalah setelan 'manifest', yang dirancang untuk memberikan visibilitas ke
isi proxy API. |
T/A | Tidak |
Resources |
Daftar resource (JavaScript, Python, Java, XSLT) di direktori /resources
proxy API ini. Biasanya Anda hanya akan melihat elemen ini saat proxy API
dibuat menggunakan UI pengelolaan Edge. Ini hanyalah setelan 'manifest', yang dirancang untuk
memberikan visibilitas ke dalam konten proxy API. |
T/A | Tidak |
Spec |
Mengidentifikasi Spesifikasi OpenAPI yang terkait dengan proxy API. Nilai
ditetapkan ke URL atau ke jalur di toko spesifikasi. Catatan: Toko spesifikasi hanya tersedia di pengalaman New Edge. Untuk mengetahui informasi selengkapnya tentang penyimpanan spesifikasi, lihat Mengelola dan membagikan spesifikasi. |
T/A | Tidak |
TargetServers |
Daftar TargetServer yang dirujuk di TargetEndpoint proxy API ini. Anda biasanya hanya melihat elemen ini saat proxy API dibuat menggunakan UI pengelolaan Edge. Ini hanyalah setelan 'manifest', yang dirancang untuk memberikan visibilitas ke konten proxy API. | T/A | Tidak |
TargetEndpoints |
Daftar TargetEndpoint di direktori /targets proxy API ini. Anda
biasanya hanya akan melihat elemen ini saat proxy API dibuat menggunakan UI pengelolaan
Edge. Ini hanyalah setelan 'manifest', yang dirancang untuk memberikan visibilitas ke
isi proxy API. |
T/A | Tidak |
ProxyEndpoint
Gambar berikut menunjukkan alur permintaan/respons:

/apiproxy/proxies/default.xml
Konfigurasi ProxyEndpoint menentukan antarmuka inbound (yang menghadap klien) untuk proxy API. Saat mengonfigurasi ProxyEndpoint, Anda menyiapkan konfigurasi jaringan yang menentukan cara aplikasi klien ('aplikasi') harus memanggil API yang di-proxy.
Contoh konfigurasi ProxyEndpoint berikut akan disimpan di
/apiproxy/proxies:
<ProxyEndpoint name="default">
<PreFlow/>
<Flows/>
<PostFlow/>
<HTTPProxyConnection>
<BasePath>/weather</BasePath>
<VirtualHost>default</VirtualHost>
</HTTPProxyConnection>
<FaultRules/>
<DefaultFaultRule/>
<RouteRule name="default">
<TargetEndpoint>default</TargetEndpoint>
</RouteRule>
</ProxyEndpoint>Elemen konfigurasi yang diperlukan dalam ProxyEndpoint dasar adalah:
Konfigurasi ProxyEndpoint Elemen
| Nama | Deskripsi | Default | Wajib? |
|---|---|---|---|
ProxyEndpoint |
|||
name |
Nama ProxyEndpoint. Harus unik dalam konfigurasi proxy API, saat
(dalam kasus yang jarang terjadi) beberapa ProxyEndpoint ditentukan. Karakter yang diizinkan untuk digunakan
dalam nama dibatasi sebagai berikut: A-Za-z0-9._\-$ %. |
T/A | Ya |
PreFlow |
Menentukan kebijakan dalam alur PreFlow permintaan atau respons. | T/A | Ya |
Flows |
Menentukan kebijakan dalam alur bersyarat permintaan atau respons.
|
T/A | Ya |
PostFlow |
Menentukan kebijakan dalam alur PostFlow permintaan atau respons.
|
T/A | Ya |
HTTPProxyConnection |
Menentukan alamat jaringan dan jalur URI yang terkait dengan proxy API | ||
BasePath |
String wajib yang mengidentifikasi jalur URI yang digunakan oleh Apigee Edge secara unik untuk merutekan pesan masuk ke proxy API yang tepat. BasePath adalah fragmen URI (misalnya Menggunakan karakter pengganti di jalur dasar Anda dapat menggunakan satu atau beberapa karakter pengganti "*" di jalur dasar proxy API. Misalnya, jalur
dasar Penting: Apigee TIDAK mendukung penggunaan karakter pengganti "*" sebagai elemen
pertama dari jalur dasar. Misalnya, |
/ | Ya |
VirtualHost |
Mengaitkan proxy API dengan URL dasar tertentu untuk lingkungan. VirtualHost adalah konfigurasi bernama yang menentukan satu atau beberapa URL untuk lingkungan. VirtualHost bernama yang ditentukan untuk ProxyEndpoint menentukan domain dan port tempat proxy API diekspos, dan, dengan demikian, URL yang digunakan aplikasi untuk memanggil proxy API. Secara default, dua VirtualHost bernama ditentukan untuk lingkungan:
|
default | Tidak |
Properties |
Kumpulan setelan konfigurasi HTTP opsional dapat ditentukan sebagai properti
<ProxyEndpoint>. |
T/A | Tidak |
FaultRules |
Menentukan cara ProxyEndpoint bereaksi terhadap error. Aturan kesalahan menentukan dua item:
Lihat Menangani kesalahan. |
T/A | Tidak |
DefaultFaultRule |
Menangani semua error (sistem, transportasi, pesan, atau kebijakan) yang tidak ditangani secara eksplisit oleh aturan kesalahan lain. Lihat Menangani kesalahan. |
T/A | Tidak |
RouteRule |
Menentukan tujuan pesan permintaan masuk setelah diproses oleh pipeline permintaan ProxyEndpoint. Biasanya, RouteRule mengarah ke konfigurasi TargetEndpoint bernama, tetapi juga dapat mengarah langsung ke URL. | ||
Name |
Atribut wajib diisi, yang memberikan nama untuk RouteRule. Karakter yang diizinkan untuk digunakan dalam nama dibatasi sebagai berikut: A-Za-z0-9._\-$ %. Misalnya, Cat2 %_ adalah nama resmi. |
T/A | Ya |
Condition |
Pernyataan bersyarat opsional yang digunakan untuk perutean dinamis saat runtime. Bersyarat RouteRules berguna, misalnya, untuk mengaktifkan perutean berdasarkan konten guna mendukung pembuatan versi backend. | T/A | Tidak |
TargetEndpoint |
String opsional yang mengidentifikasi konfigurasi TargetEndpoint bernama. TargetEndpoint
bernama adalah TargetEndpoint yang ditentukan dalam proxy API yang sama di
direktori Dengan memberi nama TargetEndpoint, Anda menunjukkan ke mana pesan permintaan harus diteruskan setelah diproses oleh pipeline permintaan ProxyEndpoint. Perhatikan bahwa ini adalah setelan opsional. ProxyEndpoint dapat memanggil URL secara langsung. Misalnya, resource JavaScript atau Java, yang berfungsi dalam peran klien HTTP, dapat menjalankan tugas dasar TargetEndpoint, yaitu meneruskan permintaan ke layanan backend. |
T/A | Tidak |
| URL | String opsional yang menentukan alamat jaringan keluar yang dipanggil oleh
ProxyEndpoint, dengan melewati konfigurasi TargetEndpoint yang mungkin disimpan di bagian
/targets |
T/A | Tidak |
Cara mengonfigurasi RouteRules
TargetEndpoint bernama merujuk ke file konfigurasi di /apiproxy/targets yang
meneruskan permintaan RouteRule setelah diproses oleh ProxyEndpoint.
Misalnya, RouteRule berikut merujuk pada konfigurasi
/apiproxy/targets/myTarget.xml:
<RouteRule name="default"> <TargetEndpoint>myTarget</TargetEndpoint> </RouteRule>
Pemanggilan URL Langsung
ProxyEndpoint juga dapat memanggil layanan backend secara langsung. Pemanggilan URL langsung melewati konfigurasi TargetEndpoint bernama di bagian /apiproxy/targets). Oleh karena itu, TargetEndpoint adalah konfigurasi proxy API opsional, meskipun, dalam praktiknya, pemanggilan langsung dari ProxyEndpoint tidak direkomendasikan.
Misalnya, RouteRule berikut membuat panggilan HTTP ke
http://api.mycompany.com/v2.
<RouteRule name="default"> <URL>http://api.mycompany.com/v2</URL> </RouteRule>
Rute Bersyarat
RouteRules dapat dirangkai untuk mendukung pemilihan rute dinamis saat runtime. Permintaan masuk dapat dirutekan ke konfigurasi TargetEndpoint bernama, langsung ke URL, atau ke kombinasi keduanya, berdasarkan header HTTP, konten pesan, parameter kueri, atau informasi kontekstual seperti waktu dalam sehari, lokalitas, dll.
Conditional RouteRules berfungsi seperti pernyataan bersyarat lainnya di Apigee Edge. Lihat Referensi kondisi dan Referensi variabel.
Misalnya, kombinasi RouteRule berikut pertama-tama mengevaluasi permintaan masuk untuk memverifikasi
nilai header HTTP. Jika header HTTP routeTo memiliki nilai
TargetEndpoint1, permintaan akan diteruskan ke TargetEndpoint bernama
TargetEndpoint1. Jika tidak, permintaan masuk akan diteruskan ke
http://api.mycompany.com/v2.
<RouteRule name="MyRoute"> <Condition>request.header.routeTo = "TargetEndpoint1"</Condition> <TargetEndpoint>TargetEndpoint1</TargetEndpoint> </RouteRule> <RouteRule name="default"> <URL>http://api.mycompany.com/v2</URL> </RouteRule>
Rute Null
RouteRule null dapat ditentukan untuk mendukung skenario saat pesan permintaan tidak perlu diteruskan ke TargetEndpoint. Hal ini berguna saat ProxyEndpoint melakukan semua pemrosesan yang diperlukan, misalnya dengan menggunakan JavaScript untuk memanggil layanan eksternal atau mengambil data dari pencarian ke penyimpanan nilai/kunci Layanan API.
Misalnya, kode berikut menentukan Rute null:
<RouteRule name="GoNowhere"/>
Rute null bersyarat dapat berguna. Pada contoh berikut, Rute null dikonfigurasi untuk
dieksekusi saat header HTTP request.header.X-DoNothing memiliki nilai selain
null.
<RouteRule name="DoNothingOnDemand"> <Condition>request.header.X-DoNothing != null</Condition> </RouteRule>
Ingat, RouteRules dapat dirangkai, sehingga Route null bersyarat biasanya menjadi salah satu komponen dari serangkaian RouteRules yang dirancang untuk mendukung pemilihan rute bersyarat.
Penggunaan praktis Rute null bersyarat adalah untuk mendukung caching. Dengan menggunakan nilai variabel yang ditetapkan oleh kebijakan Cache, Anda dapat mengonfigurasi proxy API untuk menjalankan rute null saat entri ditayangkan dari cache.
<RouteRule name="DoNothingUnlessTheCacheIsStale"> <Condition>lookupcache.LookupCache-1.cachehit is true</Condition> </RouteRule>
TargetEndpoint

TargetEndpoint adalah padanan keluar dari ProxyEndpoint. TargetEndpoint berfungsi sebagai klien ke layanan atau API backend -- mengirim permintaan dan menerima respons.
Proxy API tidak memerlukan TargetEndpoint. ProxyEndpoint dapat dikonfigurasi untuk memanggil URL secara langsung. Proxy API tanpa TargetEndpoints biasanya berisi ProxyEndpoint yang memanggil layanan backend secara langsung, atau yang dikonfigurasi untuk memanggil layanan menggunakan Java atau JavaScript.
Konfigurasi TargetEndpoint
/targets/default.xml
TargetEndpoint menentukan koneksi keluar dari Apigee Edge ke layanan atau resource lain.
Berikut adalah contoh konfigurasi TargetEndpoint:
<TargetEndpoint name="default">
<PreFlow/>
<Flows/>
<PostFlow/>
<HTTPTargetConnection>
<URL>http://mocktarget.apigee.net</URL>
<SSLInfo/>
</HTTPTargetConnection>
<FaultRules/>
<DefaultFaultRule/>
<ScriptTarget/>
<LocalTargetConnection/>
</TargetEndpoint>Konfigurasi TargetEndpoint Elemen
TargetEndpoint dapat memanggil target dengan salah satu cara berikut:
- HTTPTargetConnection untuk panggilan HTTP(S)
- LocalTargetConnection untuk penggabungan proxy-ke-proxy lokal
- ScriptTarget untuk panggilan ke skrip Node.js yang dihosting di Edge
Konfigurasi hanya salah satu opsi ini di TargetEndpoint.
| Nama | Deskripsi | Default | Wajib? |
|---|---|---|---|
TargetEndpoint |
|||
name |
Nama TargetEndpoint, yang harus unik dalam konfigurasi proxy API. Nama TargetEndPoint digunakan dalam RouteRule ProxyEndpoint untuk
mengarahkan permintaan untuk pemrosesan keluar. Karakter yang diizinkan untuk digunakan dalam nama
dibatasi sebagai berikut: A-Za-z0-9._\-$ %. |
T/A | Ya |
PreFlow |
Menentukan kebijakan dalam alur PreFlow permintaan atau respons. | T/A | Ya |
Flows |
Menentukan kebijakan dalam alur bersyarat permintaan atau respons.
|
T/A | Ya |
PostFlow |
Menentukan kebijakan dalam alur PostFlow permintaan atau respons.
|
T/A | Ya |
HTTPTargetConnection |
Dengan elemen turunannya, menentukan jangkauan resource backend melalui HTTP. Jika Anda menggunakan HTTPTargetConnection, jangan mengonfigurasi jenis koneksi target lainnya (ScriptTarget atau LocalTargetConnection). |
||
URL |
Menentukan alamat jaringan layanan backend yang menjadi tujuan penerusan pesan permintaan oleh TargetEndpoint. | T/A | Tidak |
LoadBalancer |
Menentukan satu atau beberapa konfigurasi TargetServer bernama. Konfigurasi TargetServer bernama dapat digunakan untuk load balancing yang menentukan 2 koneksi konfigurasi endpoint atau lebih. Anda juga dapat menggunakan TargetServer untuk memisahkan konfigurasi proxy API dari URL endpoint layanan backend konkret. |
T/A | Tidak |
Properties |
Kumpulan setelan konfigurasi HTTP opsional dapat ditentukan sebagai properti
<TargetEndpoint>. |
T/A | Tidak |
SSLInfo |
Secara opsional, tentukan setelan TLS/SSL di TargetEndpoint untuk mengontrol koneksi TLS/SSL antara proxy API dan layanan target. Lihat Konfigurasi TargetEndpoint TLS/SSL. | T/A | Tidak |
LocalTargetConnection |
Dengan elemen turunannya, menentukan resource yang akan dijangkau secara lokal, dengan melewati karakteristik jaringan seperti load balancing dan pemroses pesan.
Untuk menentukan resource target, sertakan elemen turunan APIProxy (dengan elemen ProxyEndpoint) atau elemen turunan Path. Untuk mengetahui informasi selengkapnya, lihat Menggabungkan proxy API. Jika Anda menggunakan LocalTargetConnection, jangan konfigurasi jenis koneksi target lainnya (HTTPTargetConnection atau ScriptTarget). |
||
APIProxy |
Menentukan nama proxy API yang akan digunakan sebagai target untuk permintaan. Proxy target harus berada di organisasi dan lingkungan yang sama dengan proxy yang mengirim permintaan. Ini adalah alternatif untuk menggunakan elemen Jalur. | T/A | Tidak |
ProxyEndpoint |
Digunakan dengan APIProxy untuk menentukan nama ProxyEndpoint proxy target. | T/A | Tidak |
Path |
Menentukan jalur endpoint proxy API yang akan digunakan sebagai target untuk permintaan. Proxy target harus berada di organisasi dan lingkungan yang sama dengan proxy yang mengirim permintaan. Ini adalah alternatif untuk menggunakan APIProxy. | T/A | Tidak |
FaultRules |
Menentukan cara TargetEndpoint bereaksi terhadap error. Aturan kesalahan menentukan dua item:
Lihat Menangani kesalahan. |
T/A | Tidak |
DefaultFaultRule |
Menangani error apa pun (sistem, transportasi, pesan, atau kebijakan) yang tidak ditangani secara eksplisit oleh FaultRule lain. Lihat Menangani kesalahan. |
T/A | Tidak |
ScriptTarget |
|||
ResourceURL |
Menentukan jenis resource (node) dan nama skrip Node.js utama yang menerapkan fungsi TargetEndpoint.
Skrip harus disertakan dengan file resource proxy API Anda. Lihat Menambahkan Node.js ke proxy API yang ada. Jika Anda menggunakan ScriptTarget, jangan konfigurasi jenis koneksi target lainnya (HTTPTargetConnection atau LocalTargetConnection). |
T/A | Ya |
EnvironmentVariable |
Secara opsional, teruskan variabel lingkungan ke skrip Node.js utama. |
T/A | Tidak |
Arguments |
Secara opsional, teruskan argumen ke skrip Node.js utama. |
T/A | Tidak |
Konfigurasi TargetEndpoint TLS/SSL
TargetEndpoint sering kali perlu mengelola koneksi HTTPS dengan infrastruktur backend heterogen. Oleh karena itu, sejumlah setelan konfigurasi TLS/SSL didukung.
TLS/SSL Elemen Konfigurasi TargetEndpoint
| Nama | Deskripsi | Default | Wajib? |
|---|---|---|---|
SSLInfo |
|||
Enabled |
Menunjukkan apakah TLS/SSL diaktifkan untuk endpoint.
Nilai defaultnya adalah true jika <URL> menentukan protokol HTTPS,
dan false jika <URL> menentukan HTTP. |
benar jika <URL> menentukan HTTPS |
Tidak |
TrustStore |
Keystore yang berisi sertifikat server tepercaya. | T/A | Tidak |
ClientAuthEnabled |
Setelan yang mengaktifkan autentikasi klien keluar (TLS/SSL 2 arah) | false | Tidak |
KeyStore |
Keystore yang berisi kunci pribadi yang digunakan untuk autentikasi klien keluar | T/A | Ya (jika ClientAuthEnabled adalah benar) |
KeyAlias |
Alias kunci dari kunci pribadi yang digunakan untuk autentikasi klien keluar | T/A | Ya (jika ClientAuthEnabled adalah benar) |
Ciphers |
Cipher yang didukung untuk TLS/SSL keluar. Jika tidak ada sandi yang ditentukan, semua sandi yang tersedia untuk JVM akan diizinkan. Untuk membatasi sandi, tambahkan elemen berikut yang mencantumkan sandi yang didukung: <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers> |
T/A | Tidak |
Protocols |
Protokol yang didukung untuk TLS/SSL keluar. Jika tidak ada protokol yang ditentukan, semua protokol yang tersedia untuk JVM akan diizinkan. Untuk membatasi protokol, tambahkan elemen berikut yang mencantumkan protokol yang didukung: <Protocols> <Protocol>TLSv1.1</Protocol> <Protocol>TLSv1.2</Protocol> </Protocols> |
T/A | Tidak |
CommonName |
Jika ditentukan, nilai yang digunakan untuk memvalidasi nama umum sertifikat target. Nilai ini hanya valid untuk konfigurasi TargetEndpoint dan TargetServer. Tidak valid untuk konfigurasi VirtualHost. Secara default, nilai yang ditentukan dicocokkan persis dengan nama umum sertifikat target.
Misalnya, menggunakan Secara opsional, Apigee dapat melakukan pencocokan dengan karakter pengganti menggunakan atribut Misalnya, nama umum yang ditentukan sebagai <CommonName wildcardMatch="true">*.myhost.com</CommonName> |
T/A | Tidak |
Contoh TargetEndpoint dengan autentikasi klien keluar diaktifkan
<TargetEndpoint name="default">
<HttpTargetConnection>
<URL>https://myservice.com</URL>
<SSLInfo>
<Enabled>true</Enabled>
<ClientAuthEnabled>true</ClientAuthEnabled>
<KeyStore>myKeystore</KeyStore>
<KeyAlias>myKey</KeyAlias>
<TrustStore>myTruststore</TrustStore>
</SSLInfo>
</HttpTargetConnection>
</TargetEndpoint>Untuk petunjuk mendetail, lihat Mengonfigurasi TLS dari Edge ke backend (Cloud dan Private Cloud).
Menggunakan variabel alur untuk menetapkan nilai TLS/SSL secara dinamis
Anda juga dapat menetapkan detail TLS/SSL secara dinamis untuk mendukung persyaratan runtime yang fleksibel. Misalnya, jika proxy Anda terhubung ke dua target yang berpotensi berbeda (target pengujian dan target produksi), Anda dapat membuat proxy API mendeteksi secara terprogram lingkungan yang dipanggil dan menetapkan referensi secara dinamis ke keystore dan truststore yang sesuai. Artikel Komunitas Apigee berikut menjelaskan skenario ini secara lebih mendetail dan memberikan contoh proxy API yang dapat di-deploy: Dynamic SSLInfo for TargetEndpoint using variable reference.
Dalam contoh berikut tentang cara menetapkan tag <SSLInfo> dalam konfigurasi TargetEndpoint, nilai dapat diberikan saat runtime, misalnya, oleh Java Callout, kebijakan JavaScript, atau kebijakan Assign Message. Gunakan variabel pesan mana pun yang berisi nilai yang ingin Anda tetapkan.
Variabel hanya diizinkan dalam elemen berikut.
<SSLInfo> <Enabled>{myvars.ssl.enabled}</Enabled> <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled> <KeyStore>{myvars.ssl.keystore}</KeyStore> <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias> <TrustStore>{myvars.ssl.trustStore}</TrustStore> </SSLInfo>
Menggunakan referensi untuk menetapkan nilai TLS/SSL secara dinamis
Saat mengonfigurasi TargetEndpoint yang menggunakan HTTPS, Anda harus mempertimbangkan kasus saat masa berlaku sertifikat TLS/SSL berakhir, atau perubahan pada konfigurasi sistem mengharuskan Anda memperbarui sertifikat. Dalam penginstalan Edge untuk Private Cloud, saat mengonfigurasi TLS/SSL menggunakan nilai statis atau menggunakan variabel alur, ada kemungkinan Anda harus memulai ulang Pemroses Pesan.
Untuk mengetahui informasi selengkapnya, lihat Memperbarui sertifikat TLS.
Namun, Anda dapat secara opsional mengonfigurasi TargetEndpoint untuk menggunakan referensi ke keystore atau truststore. Keuntungan menggunakan referensi adalah Anda dapat mengupdate referensi untuk mengarah ke keystore atau truststore yang berbeda guna mengupdate sertifikat TLS/SSL tanpa harus memulai ulang Pemroses Pesan.
Misalnya, di bawah ini ditampilkan TargetEndpoint yang menggunakan referensi ke keystore:
<SSLInfo>
<Enabled>true</Enabled>
<ClientAuthEnabled>false</ClientAuthEnabled>
<KeyStore>ref://keystoreref</KeyStore>
<KeyAlias>myKeyAlias</KeyAlias>
</SSLInfo>Gunakan panggilan API POST berikut untuk membuat referensi bernama keystoreref:
curl -X POST -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
<Refers>myTestKeystore</Refers>
<ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:passwordReferensi menentukan nama keystore dan jenisnya.
Gunakan panggilan GET API berikut untuk melihat referensi:
curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:passwordUntuk mengubah referensi agar mengarah ke keystore yang berbeda di lain waktu, pastikan alias memiliki nama yang sama, gunakan panggilan PUT berikut:
curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
<Refers>myNewKeystore</Refers>
<ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:passwordTargetEndpoint dengan load balancing target
TargetEndpoint mendukung load balancing di beberapa TargetServer bernama menggunakan tiga algoritma load balancing.
Untuk mendapatkan petunjuk mendetail, lihat Load balancing di seluruh server backend.
Kebijakan
Direktori /policies dalam proxy API berisi semua kebijakan yang tersedia untuk
dilampirkan ke Alur dalam proxy API.
Elemen Konfigurasi Kebijakan
| Nama | Deskripsi | Default | Wajib? |
|---|---|---|---|
Policy |
|||
name |
Nama internal kebijakan. Karakter yang dapat Anda gunakan dalam nama dibatasi
ke: Secara opsional, gunakan elemen |
T/A | Ya |
enabled |
Setel ke Setel ke |
true | Tidak |
continueOnError |
Disetel ke Setel ke |
false | Tidak |
async |
Catatan: Atribut ini tidak membuat kebijakan dijalankan secara asinkron.
Dalam sebagian besar kasus, biarkan setelan ini dengan nilai default Jika disetel ke Untuk menggunakan perilaku asinkron di proxy API, lihat model objek JavaScript. |
false | Tidak |
Lampiran Kebijakan
Gambar berikut menunjukkan urutan eksekusi alur proxy API:

Seperti yang ditunjukkan di atas:
Kebijakan dilampirkan sebagai langkah pemrosesan ke Alur. Nama kebijakan digunakan untuk mereferensikan kebijakan yang akan diterapkan sebagai Langkah pemrosesan. Format lampiran kebijakan adalah sebagai berikut:
<Step><Name>MyPolicy</Name></Step>
Kebijakan diterapkan sesuai urutan penempelannya ke Alur. Contoh:
<Step><Name>FirstPolicy</Name></Step> <Step><Name>SecondPolicy</Name></Step>
Konfigurasi Lampiran Kebijakan Elemen
| Nama | Deskripsi | Default | Wajib? |
|---|---|---|---|
Step |
|||
Name |
Nama kebijakan yang akan dieksekusi oleh definisi Langkah ini. | T/A | Ya |
Condition |
Pernyataan bersyarat yang menentukan apakah kebijakan diterapkan atau tidak. Jika kebijakan memiliki kondisi terkait, maka kebijakan hanya dijalankan jika pernyataan bersyarat bernilai benar (true). | T/A | Tidak |
Alur
ProxyEndpoint dan TargetEndpoint menentukan pipeline untuk pemrosesan pesan permintaan dan respons. Pipeline pemrosesan terdiri dari alur permintaan dan alur respons. Setiap alur permintaan dan alur respons dibagi lagi menjadi PreFlow, satu atau beberapa alur 'bersyarat' atau 'bernama' opsional, dan PostFlow.
- PreFlow: Selalu dieksekusi. Dieksekusi sebelum Alur kondisional apa pun.
- PostFlow: Selalu dieksekusi. Dieksekusi setelah Alur bersyarat.
Selain itu, Anda dapat menambahkan PostClientFlow ke ProxyEndpoint, yang dieksekusi setelah
respons dikembalikan ke aplikasi klien yang meminta. Hanya kebijakan MessageLogging dan
Ekstensi Google Stackdriver Logging yang dapat dilampirkan
ke alur ini. PostClientFlow mengurangi latensi proxy API dan membuat informasi tersedia untuk
pencatatan yang tidak dihitung hingga setelah respons dikembalikan ke klien, seperti
client.sent.start.timestamp dan client.sent.end.timestamp.Alur ini digunakan
terutama untuk mengukur interval waktu antara stempel waktu mulai dan berakhir untuk pesan
respons.
Tonton video singkat cara melakukannya
Video: Tonton video singkat ini tentang cara menggunakan Pencatatan Pesan di PostClientFlow.
Berikut adalah contoh PostClientFlow dengan kebijakan pencatatan pesan yang dilampirkan.
...
<PostFlow name="PostFlow">
<Request/>
<Response/>
</PostFlow>
<PostClientFlow>
<Request/>
<Response>
<Step>
<Name>Message-Logging-1</Name>
</Step>
</Response>
</PostClientFlow>
...Pipeline pemrosesan proxy API menjalankan Alur dalam urutan berikut:
Minta Pipeline:
- Proxy Request PreFlow
- Alur Bersyarat Permintaan Proxy (Opsional)
- Proxy Request PostFlow
- PreFlow Permintaan Target
- Alur Bersyarat Permintaan Target (Opsional)
- Target Request PostFlow
Pipeline Respons:
- Target Response PreFlow
- Alur Bersyarat Respons Target (Opsional)
- Target Response PostFlow
- Proxy Response PreFlow
- Alur Bersyarat Respons Proxy (Opsional)
- Proxy Response PostFlow
- Respons PostClientFlow (Opsional)
Hanya Alur dengan lampiran kebijakan yang perlu dikonfigurasi dalam konfigurasi ProxyEndpoint atau TargetEndpoint. PreFlow dan PostFlow hanya perlu ditentukan dalam konfigurasi ProxyEndpoint atau TargetEndpoint jika kebijakan perlu diterapkan selama pemrosesan PreFlow atau PostFlow.
Berbeda dengan alur bersyarat, urutan elemen PreFlow dan PostFlow tidak penting--proxy API akan selalu mengeksekusi setiap elemen pada titik yang sesuai dalam pipeline, terlepas dari tempat kemunculannya dalam konfigurasi Endpoint.
Alur Bersyarat
ProxyEndpoint dan TargetEndpoint mendukung alur bersyarat dalam jumlah tak terbatas (juga dikenal sebagai 'alur bernama').
Proxy API menguji kondisi yang ditentukan dalam alur bersyarat dan, jika kondisi terpenuhi, langkah-langkah pemrosesan dalam alur bersyarat akan dieksekusi oleh proxy API. Jika kondisi tidak terpenuhi, langkah-langkah pemrosesan dalam alur bersyarat akan dilewati. Alur bersyarat dievaluasi dalam urutan yang ditentukan di proxy API dan alur pertama yang kondisinya terpenuhi akan dieksekusi.
Dengan menentukan alur bersyarat, Anda mendapatkan kemampuan untuk menerapkan langkah-langkah pemrosesan di proxy API berdasarkan:
- URI Permintaan
- Kata kerja HTTP (GET/PUT/POST/DELETE)
- Nilai parameter kueri, header, dan parameter formulir
- Banyak jenis kondisi lainnya
Misalnya, alur bersyarat berikut menentukan bahwa alur tersebut hanya dijalankan saat
jalur resource permintaan adalah /accesstoken. Setiap permintaan masuk dengan
jalur /accesstoken menyebabkan alur ini dieksekusi, bersama dengan kebijakan
apa pun yang dilampirkan ke alur. Jika jalur permintaan tidak menyertakan akhiran
/accesstoken, alur tidak akan dieksekusi (meskipun alur bersyarat lain
mungkin dieksekusi).
<Flows>
<Flow name="TokenEndpoint">
<Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
<Request>
<Step>
<Name>GenerateAccessToken</Name>
</Step>
</Request>
</Flow>
</Flows>Elemen Konfigurasi Flow
| Nama | Deskripsi | Default | Wajib? |
|---|---|---|---|
Flow |
Pipeline pemrosesan permintaan atau respons yang ditentukan oleh ProxyEndpoint atau TargetEndpoint | ||
Name |
Nama unik Flow. | T/A | Ya |
Condition |
Pernyataan kondisional yang mengevaluasi satu atau beberapa variabel untuk dievaluasi sebagai benar atau salah. Semua Alur selain jenis PreFlow dan PostFlow yang telah ditentukan sebelumnya harus menentukan kondisi untuk eksekusinya. | T/A | Ya |
Request |
Pipeline yang terkait dengan pemrosesan pesan Permintaan | T/A | Tidak |
Response |
Pipeline yang terkait dengan pemrosesan pesan Respons | T/A | Tidak |
Pemrosesan langkah
Pengurutan berurutan dari Flow bersyarat diterapkan oleh Apigee Edge. Alur Bersyarat
dieksekusi dari atas ke bawah. Alur kondisional pertama yang kondisinya bernilai
true akan dieksekusi, dan hanya satu Alur kondisional yang dieksekusi.
Misalnya, dalam konfigurasi Flow berikut, setiap permintaan masuk yang tidak menyertakan
akhiran jalur /first atau /second akan menyebabkan ThirdFlow
dieksekusi, yang menerapkan kebijakan yang disebut Return404.
<Flows>
<Flow name="FirstFlow">
<Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
<Request>
<Step><Name>FirstPolicy</Name></Step>
</Request>
</Flow>
<Flow name="SecondFlow">
<Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
<Request>
<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>
</Request>
</Flow>
<Flow name="ThirdFlow">
<Request>
<Step><Name>Return404</Name></Step>
</Request>
</Flow>
</Flows>Referensi
"Resource" (file resource untuk digunakan di proxy API) adalah skrip, kode, dan transformasi XSL yang dapat dilampirkan ke Alur menggunakan kebijakan. Skrip ini muncul di bagian "Scripts" pada editor proxy API di UI pengelolaan.
Lihat File resource untuk jenis resource yang didukung.
Resource dapat disimpan di proxy API, lingkungan, atau organisasi. Dalam setiap kasus, resource dirujuk berdasarkan nama dalam Kebijakan. Layanan API menyelesaikan nama dengan berpindah dari proxy API, ke lingkungan, ke tingkat organisasi.
Resource yang disimpan di tingkat organisasi dapat dirujuk oleh Kebijakan di lingkungan mana pun. Resource yang disimpan di tingkat lingkungan dapat dirujuk oleh Kebijakan di lingkungan tersebut. Resource yang disimpan di tingkat proxy API hanya dapat dirujuk oleh Kebijakan di proxy API tersebut.