Referensi konfigurasi proxy API

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X.
info

Sebagai developer yang bekerja dengan Apigee Edge, aktivitas pengembangan utama Anda melibatkan mengonfigurasi proxy API yang berfungsi sebagai proxy untuk API atau layanan backend. Dokumen ini adalah yang merupakan referensi dari semua elemen konfigurasi yang tersedia untuk Anda saat membuat proxy API.

Jika Anda mempelajari cara membangun proxy API, sebaiknya Anda memulai dengan topik Membangun API sederhana proxy.

Cara paling umum untuk mengedit konfigurasi proxy adalah:

Pengembangan lokal konfigurasi proxy

Anda dapat mendownload konfigurasi proxy sehingga dapat mengeditnya di mesin lokal. Kapan selesai, Anda kemudian mengunggah hasilnya ke Edge. Pendekatan ini memungkinkan Anda mengintegrasikan ke dalam kontrol sumber, pembuatan versi, dan alur kerja bersama lainnya. Selain itu, dengan saat bekerja pada konfigurasi proxy secara lokal, Anda bisa menggunakan editor XML dan validasi alat.

Bagian ini menjelaskan cara menggunakan UI untuk mendownload konfigurasi proxy yang ada, mengeditnya, lalu menguploadnya kembali ke Edge untuk di-deploy. Anda juga dapat menggunakan apigeetool untuk mendownload dan men-deploy konfigurasi proxy baru (dengan menggunakan fetchproxy dan deployproxy.)

Untuk mengedit konfigurasi proxy secara lokal menggunakan UI:

  1. Download konfigurasi proxy saat ini di UI Edge. (Di Proxy API lihat, pilih Project > Download Revisi.)
  2. Pada komputer lokal Anda, buat direktori baru dan perluas file ZIP yang diunduh ke anotasi.

    Untuk memperluas file ZIP, Anda dapat menggunakan utilitas seperti unzip, seperti berikut contoh menampilkan:

    mkdir myappdir
    unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

    Isi file ZIP yang diperluas seharusnya serupa dengan struktur yang dijelaskan di Struktur proxy API.

  3. Edit file sumber seperlunya. Untuk deskripsi file sumber dalam proxy konfigurasi, lihat File konfigurasi dan struktur direktori proxy API.

    Misalnya, untuk mengaktifkan pemantauan kesehatan di proxy API Anda, edit file konfigurasi TargetEndpoint di Direktori /apiproxy/targets/. File {i>default<i} dalam direktori ini adalah default.xml, meskipun mungkin ada file dengan nama yang berbeda jika Anda menggunakan target bersyarat.

    Dalam hal ini, jika file konfigurasi TargetEndpoint dan direktorinya tidak ada, membuatnya.

  4. Setelah Anda selesai mengedit file konfigurasi proxy, pastikan untuk menyimpan perubahan.
  5. Ubah ke direktori baru yang Anda buat ketika Anda memperluas file ZIP ({i>root<i} dari file konfigurasi yang diperluas).

    Misalnya, jika Anda memperluas file ke direktori /myappdir, ubah menjadi direktori tersebut, seperti yang ditunjukkan contoh berikut:

    cd myappdir

    Anda harus mengubah ke direktori ini sebelum mengarsipkan ulang file konfigurasi proxy karena Anda tidak ingin direktori /myappdir disertakan dalam file ZIP. Direktori level teratas dalam file ZIP harus berupa /apiproxy.

  6. Arsipkan ulang file konfigurasi proxy, termasuk file baru atau yang telah diubah. Anda dapat menggunakan seperti zip, seperti yang ditunjukkan dalam contoh berikut:
    zip my-new-proxy.zip -r .

    Direktori level teratas dalam file ZIP harus berupa /apiproxy.

    Tidak ada persyaratan khusus untuk nama file ZIP. Misalnya, Anda tidak perlu menambah nomor revisi atau menentukan tanggal dalam nama {i>file<i}, tetapi melakukan ini bisa berguna untuk proses debug atau kontrol sumber.

    Edge menambah nomor revisi konfigurasi proxy baru saat Anda mengunggah anotasi.

  7. Upload konfigurasi proxy baru menggunakan UI Edge. (Di Proxy API lihat, pilih Project > Upload Revisi Baru.)

    Jika Anda mendapatkan error seperti Bundle is invalid. Empty bundle., pastikan direktori {i>high-level <i}file ZIP Anda adalah /apiproxy. Jika tidak, arsipkan ulang file konfigurasi {i>proxy<i} dari {i> root <i}direktori yang diperluas.

    Setelah mengunggah konfigurasi proxy baru Anda, Edge akan menambah nomor revisi dan menampilkannya di tampilan Ringkasan Revisi.

    Edge tidak men-deploy revisi baru untuk Anda setelah Anda menguploadnya dengan UI.

  8. Deploy revisi baru Anda.

Untuk informasi selengkapnya, lihat Tutorial: Cara mendownload proxy menggunakan UI dan API pengelolaan di Komunitas Apigee.

Struktur proxy API

Proxy API terdiri dari konfigurasi berikut:

Konfigurasi Dasar Setelan konfigurasi utama untuk proxy API. Lihat Dasar Konfigurasi.
Konfigurasi ProxyEndpoint Setelan untuk koneksi HTTP masuk (dari meminta aplikasi ke Apigee Edge), meminta alur respons, dan 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.
Alur Pipeline permintaan dan respons ProxyEndpoint dan TargetEndpoint yang dapat menerapkan kebijakan terlampir. 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:

Menampilkan struktur direktori tempat apiproxy adalah root. Tepat di bawah
    direktori apiproxy adalah direktori kebijakan, proxy, sumber daya, dan target, serta
    {i>weatherapi.xml<i}.

File dan direktori konfigurasi struktur 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 suatu organisasi.

Contoh konfigurasi:

<APIProxy name="weatherapi">
</APIProxy>

Elemen Konfigurasi Dasar

Nama Deskripsi Default Wajib?
APIProxy
name Nama proxy API yang harus unik dalam suatu organisasi. Karakter ini yang boleh Anda gunakan dalam nama dibatasi untuk hal-hal berikut: A-Za-z0-9_- T/A Ya
revision Nomor revisi konfigurasi proxy API. Anda tidak perlu secara eksplisit mengatur nomor revisi, karena Apigee Edge secara otomatis melacak revisi API saat ini {i>proxy<i}. T/A Tidak
ConfigurationVersion Versi skema konfigurasi proxy API yang sesuai dengan proxy API ini. Tujuan satu-satunya nilai yang didukung saat ini adalah mainVersion 4 dan minorVersion 0. Setelan ini mungkin yang 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 dari atribut name konfigurasi proxy API. T/A Tidak
Policies Daftar kebijakan dalam direktori /policies proxy API ini. Anda akan biasanya hanya melihat elemen ini saat proxy API dibuat menggunakan UI pengelolaan Edge. Ini hanyalah 'manifes' yang dirancang untuk memberikan visibilitas ke dalam konten proxy API. T/A Tidak
ProxyEndpoints Daftar ProxyEndpoint dalam direktori /proxies proxy API ini. Anda biasanya hanya akan melihat elemen ini ketika proxy API dibuat menggunakan Edge UI manajemen proyek. Ini hanyalah 'manifes' yang dirancang untuk memberikan visibilitas ke isi proxy API. T/A Tidak
Resources Daftar resource (JavaScript, Python, Java, XSLT) di /resources proxy API ini. Biasanya Anda hanya akan melihat elemen ini ketika proxy API yang dibuat menggunakan UI pengelolaan Edge. Ini hanyalah 'manifes' setelan, yang dirancang untuk memberikan visibilitas ke konten proxy API. T/A Tidak
Spec Mengidentifikasi Spesifikasi OpenAPI yang terkait dengan proxy API. Nilainya ditetapkan ke URL atau jalur di penyimpanan spesifikasi.

Catatan: Penyimpanan spesifikasi tersedia di pengalaman Edge Baru saja. Untuk informasi selengkapnya tentang penyimpanan spesifikasi, lihat Mengelola dan membagikan spesifikasi.
T/A Tidak
TargetServers Daftar TargetServers yang dirujuk di TargetEndpoint dari proxy API ini. Anda akan biasanya hanya melihat elemen ini saat proxy API dibuat menggunakan UI pengelolaan Edge. Ini hanyalah 'manifes' yang dirancang untuk memberikan visibilitas ke dalam konten proxy API. T/A Tidak
TargetEndpoints Daftar TargetEndpoint dalam direktori /targets proxy API ini. Anda biasanya hanya akan melihat elemen ini ketika proxy API dibuat menggunakan Edge UI manajemen proyek. Ini hanyalah 'manifes' yang dirancang untuk memberikan visibilitas ke isi proxy API. T/A Tidak

ProxyEndpoint

Gambar berikut menunjukkan alur permintaan/respons:

Menunjukkan klien yang memanggil HTTP
  layanan. Permintaan melewati titik akhir {i>proxy<i} 
dan kemudian titik akhir target sebelum
  yang diproses oleh layanan HTTP. Respons melewati endpoint target dan kemudian
  endpoint proxy sebelum dikembalikan ke klien.

/apiproxy/proxies/default.xml

Konfigurasi ProxyEndpoint menentukan antarmuka masuk (dihadap klien) untuk API {i>proxy<i}. Saat Anda mengonfigurasi ProxyEndpoint, Anda sedang menyiapkan konfigurasi jaringan yang mendefinisikan cara aplikasi klien ('aplikasi') memanggil API melalui 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 Elements

Nama Deskripsi Default Wajib?
ProxyEndpoint
name Nama ProxyEndpoint. Harus unik dalam konfigurasi proxy API, jika (dalam kasus yang jarang terjadi) beberapa ProxyEndpoint ditentukan. Karakter yang boleh Anda gunakan dalam namanya dibatasi untuk hal 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 sebuah permintaan atau respons.
T/A Ya
PostFlow
Menentukan kebijakan dalam alur PostFlow dari 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 secara unik yang digunakan oleh Apigee Edge untuk merutekan pesan masuk ke proxy API yang tepat.

BasePath adalah fragmen URI (misalnya /weather) yang ditambahkan ke URL dasar proxy API (misalnya, http://apifactory-test.apigee.net). BasePath harus unik dalam lingkungan. Keunikan divalidasi ketika proxy API dibuat atau diimpor.

Menggunakan karakter pengganti di jalur dasar

Anda dapat menggunakan satu atau beberapa "*" karakter pengganti di jalur dasar proxy API. Misalnya, basis jalur /team/*/members memungkinkan klien untuk memanggil https://[host]/team/blue/members dan https://[host]/team/green/members tanpa perlu Anda membuat proxy API baru untuk mendukung tim baru. Perhatikan bahwa /**/ tidak didukung.

Penting: Apigee TIDAK mendukung penggunaan karakter pengganti "*" sebagai yang pertama elemen jalur dasar. Misalnya, ini TIDAK didukung: /*/search. Memulai jalur dasar dengan "*" dapat menyebabkan kesalahan tak terduga karena cara Edge mengidentifikasi jalur yang valid.

/ Ya
VirtualHost

Mengaitkan proxy API dengan URL dasar tertentu untuk suatu lingkungan. Host Virtual adalah konfigurasi bernama yang menentukan satu atau beberapa URL untuk sebuah lingkungan.

VirtualHost bernama yang ditentukan untuk ProxyEndpoint menentukan domain dan port di proxy API diekspos, dan juga URL yang digunakan aplikasi untuk memanggil API {i>proxy<i}.

Secara default, dua VirtualHost bernama ditetapkan untuk suatu lingkungan: default dan secure. Sebuah organisasi juga dapat menentukan domain. Untuk memastikan bahwa proxy API hanya tersedia melalui HTTPS, misalnya, setel atribut VirtualHost di HTTPProxyConnection ke secure.

default Tidak
Properties Satu set pengaturan konfigurasi HTTP opsional dapat didefinisikan sebagai properti dari <ProxyEndpoint>. T/A Tidak
FaultRules
Menentukan bagaimana ProxyEndpoint bereaksi terhadap error. Aturan kesalahan menentukan dua item:
  • Kondisi yang menentukan kesalahan yang akan ditangani berdasarkan kategori, subkategori, atau nama kesalahan
  • Satu atau beberapa kebijakan yang mendefinisikan perilaku aturan kesalahan untuk Kondisi yang sesuai

Lihat Menangani kesalahan.

T/A Tidak
DefaultFaultRule

Menangani error (sistem, transport, pesan, atau kebijakan) yang tidak secara eksplisit ditangani 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 TargetEndpoint yang telah diberi nama tapi juga bisa mengarah langsung ke URL.
Name Atribut wajib, yang memberikan nama untuk RouteRule. Karakter yang digunakan dalam nama dibatasi untuk hal berikut: A-Za-z0-9._\-$ %. Sebagai contoh, Cat2 %_ adalah nama resmi. T/A Ya
Condition Pernyataan kondisional opsional yang digunakan untuk perutean dinamis saat runtime. Bersyarat RouteRules berguna, misalnya, untuk mengaktifkan perutean berbasis konten guna mendukung backend pembuatan versi. T/A Tidak
TargetEndpoint

String opsional yang mengidentifikasi konfigurasi TargetEndpoint bernama. Nama TargetEndpoint adalah TargetEndpoint yang ditentukan dalam proxy API yang sama di direktori /targets).

Dengan memberi nama TargetEndpoint, Anda menunjukkan tempat pesan permintaan harus diteruskan setelah diproses oleh pipeline permintaan ProxyEndpoint. Perhatikan bahwa ini adalah deskripsi tempat.

ProxyEndpoint dapat memanggil URL secara langsung. Misalnya, resource JavaScript atau Java, berfungsi dalam peran klien HTTP, dapat melakukan tugas dasar sebuah TargetEndpoint, yaitu meneruskan permintaan ke layanan backend.

T/A Tidak
URL String opsional yang menentukan alamat jaringan keluar yang dipanggil oleh ProxyEndpoint, yang mengabaikan konfigurasi TargetEndpoint apa pun yang mungkin disimpan di /targets T/A Tidak

Cara mengonfigurasi RouteRules

TargetEndpoint bernama merujuk pada file konfigurasi di /apiproxy/targets untuk yang mana RouteRule meneruskan permintaan setelah diproses oleh ProxyEndpoint.

Misalnya, RouteRule berikut mengacu pada konfigurasi /apiproxy/targets/myTarget.xml:

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

Pemanggilan URL Langsung

ProxyEndpoint juga dapat langsung memanggil layanan backend. Pemanggilan URL langsung mengabaikan bernama konfigurasi TargetEndpoints di bagian /apiproxy/targets). Karena alasan ini, TargetEndpoint adalah konfigurasi proxy API opsional, meskipun dalam praktiknya, pemanggilan langsung dari ProxyEndpoint tidak disarankan.

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 dirantai untuk mendukung perutean dinamis saat runtime. Permintaan masuk dapat dirutekan ke konfigurasi TargetEndpoint bernama, langsung ke URL, atau ke kombinasi keduanya, berdasarkan header HTTP, isi pesan, parameter kueri, atau informasi kontekstual seperti hari, lokalitas, dll.

RouteRules berfungsi seperti pernyataan kondisional lainnya di Apigee Edge. Lihat Referensi kondisi dan Referensi variabel.

Misalnya, kombinasi RouteRule berikut terlebih dahulu mengevaluasi permintaan masuk untuk diverifikasi nilai header HTTP. Jika header HTTP routeTo memiliki nilai TargetEndpoint1, lalu permintaan diteruskan ke TargetEndpoint yang 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 jika pesan permintaan tidak harus diteruskan ke TargetEndpoint. Ini berguna saat {i>ProxyEndpoint<i} menjalankan semua pemrosesan yang diperlukan, misalnya dengan menggunakan JavaScript untuk memanggil layanan eksternal atau mengambil data dari pencarian ke Layanan API, penyimpanan kunci/nilai.

Misalnya, hal berikut menentukan Rute null:

<RouteRule name="GoNowhere"/>

Rute null bersyarat dapat berguna. Pada contoh berikut, Rute {i>null<i} dikonfigurasi untuk dijalankan 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 dirantai, sehingga Rute null kondisional biasanya adalah satu dari kumpulan RouteRules yang dirancang untuk mendukung perutean bersyarat.

Penggunaan praktis Rute null bersyarat akan mendukung caching. Dengan menggunakan nilai untuk variabel yang disetel oleh kebijakan Cache, Anda dapat mengonfigurasi proxy API untuk menjalankan Rute null saat entri disajikan dari cache.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

Menunjukkan klien yang memanggil HTTP
  layanan. Permintaan melewati titik akhir {i>proxy<i} 
dan kemudian titik akhir target sebelum
  yang diproses oleh layanan HTTP. Respons melewati endpoint target dan kemudian
  endpoint proxy sebelum dikembalikan ke klien.

TargetEndpoint adalah setara dengan ProxyEndpoint keluar. TargetEndpoint berfungsi sebagai klien ke layanan backend atau API -- klien mengirim permintaan dan menerima respons.

Proxy API tidak perlu memiliki TargetEndpoint. ProxyEndpoint dapat dikonfigurasi untuk memanggil URL secara langsung. Proxy API tanpa TargetEndpoint biasanya berisi ProxyEndpoint yang layanan backend, atau yang dikonfigurasi untuk memanggil layanan menggunakan Java atau pada JavaScript.

Konfigurasi TargetEndpoint

/targets/default.xml

TargetEndpoint menentukan koneksi keluar dari Apigee Edge ke layanan lain atau resource Anda

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 Elements

TargetEndpoint dapat memanggil target dengan salah satu cara berikut:

  • HTTPTargetConnection untuk panggilan HTTP(S)
  • LocalTargetConnection untuk rantai proxy-ke-proxy lokal
  • ScriptTarget untuk panggilan ke skrip yang dihosting Edge Skrip Node.js

Hanya konfigurasi salah satunya di TargetEndpoint.

Nama Deskripsi Default Wajib?
TargetEndpoint
name Nama TargetEndpoint, yang harus unik dalam proxy API konfigurasi Anda. Nama TargetEndPoint digunakan dalam ProxyEndpoint RouteRule untuk permintaan langsung untuk pemrosesan keluar. Karakter yang boleh Anda gunakan dalam nama dibatasi untuk hal 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 sebuah permintaan atau respons.
T/A Ya
PostFlow
Menentukan kebijakan dalam alur PostFlow dari permintaan atau respons.
T/A Ya
HTTPTargetConnection

Dengan elemen turunannya, menentukan jangkauan resource backend melalui HTTP.

Jika Anda menggunakan HTTPTargetConnection, jangan konfigurasi jenis koneksi target lainnya (ScriptTarget atau LocalTargetConnection).

URL Menentukan alamat jaringan layanan backend yang menjadi tujuan penerusan TargetEndpoint pesan permintaan. T/A Tidak
LoadBalancer

Menentukan satu atau beberapa konfigurasi TargetServer yang bernama. TargetServer Bernama konfigurasi dapat digunakan untuk load balancing yang menentukan 2 konfigurasi endpoint atau lebih koneksi jarak jauh.

Anda juga bisa menggunakan TargetServers untuk memisahkan konfigurasi proxy API dari URL endpoint layanan backend.

Lihat Pemuatan balancing di seluruh server backend.

T/A Tidak
Properties Satu set pengaturan konfigurasi HTTP opsional dapat didefinisikan sebagai properti dari <TargetEndpoint>. T/A Tidak
SSLInfo Secara opsional, tentukan setelan TLS/SSL pada TargetEndpoint untuk mengontrol TLS/SSL koneksi 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, melewati jaringan seperti load balancing dan pemroses pesan.

Untuk menetapkan sumber daya target, sertakan salah satu elemen turunan APIProxy (dengan elemen ProxyEndpoint ) atau elemen turunan Path.

Untuk informasi selengkapnya, lihat Proxy rantai API bersama-sama.

Jika Anda menggunakan LocalTargetConnection, jangan konfigurasi jenis koneksi target lainnya (HTTPTargetConnection atau ScriptTarget).

APIProxy Menentukan nama proxy API yang akan digunakan sebagai target permintaan. Proxy target harus berada dalam organisasi dan lingkungan yang sama dengan permintaan pengiriman proxy. Ini adalah alternatif untuk menggunakan elemen Path. 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 permintaan. Target proxy harus berada dalam organisasi dan lingkungan yang sama dengan permintaan pengiriman proxy. Ini adalah alternatif untuk menggunakan APIProxy. T/A Tidak
FaultRules
Menentukan bagaimana TargetEndpoint bereaksi terhadap error. Aturan kesalahan menentukan dua item:
  • Kondisi yang menentukan kesalahan yang akan ditangani berdasarkan kategori, subkategori, atau nama kesalahan
  • Satu atau beberapa kebijakan yang mendefinisikan perilaku aturan kesalahan untuk Kondisi yang sesuai

Lihat Menangani kesalahan.

T/A Tidak
DefaultFaultRule

Menangani error (sistem, transport, pesan, atau kebijakan) yang tidak secara eksplisit ditangani oleh {i>FaultRule<i} lain.

Lihat Menangani kesalahan.

T/A Tidak
ScriptTarget
ResourceURL

Menentukan jenis resource (node) dan nama skrip Node.js utama yang menerapkan fungsi TargetEndpoint.

<ResourceURL>node://server.js</ResourceURL>

Skrip harus disertakan dengan file resource proxy API Anda. Lihat Menambahkan Node.js ke proxy API yang sudah ada.

Jika Anda menggunakan ScriptTarget, jangan konfigurasi jenis koneksi target lainnya (HTTPTargetConnection atau LocalTargetConnection).

T/A Ya
EnvironmentVariable

Teruskan variabel lingkungan ke skrip Node.js utama secara opsional.

Lihat Memahami Edge dukungan untuk modul Node.js.

T/A Tidak
Arguments

Secara opsional, teruskan argumen ke skrip Node.js utama.

Lihat Memahami Edge dukungan untuk modul Node.js.

T/A Tidak

Konfigurasi TargetEndpoint TLS/SSL

TargetEndpoint sering kali perlu mengelola koneksi HTTPS dengan backend yang heterogen infrastruktur IT. Karena alasan ini, 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 (true) 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) salah Tidak
KeyStore Keystore yang berisi kunci pribadi yang digunakan untuk autentikasi klien keluar T/A Ya (jika ClientAuthEnabled benar)
KeyAlias Alias kunci dari kunci pribadi yang digunakan untuk autentikasi klien keluar T/A Ya (jika ClientAuthEnabled benar)
Ciphers

Cipher yang didukung untuk TLS/SSL keluar. Jika tidak ada penyandian yang ditentukan, maka semua penyandian yang tersedia untuk JVM akan diizinkan.

Untuk membatasi cipher, tambahkan elemen berikut yang mencantumkan cipher 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, maka 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 akan divalidasi oleh nama umum sertifikat target. Nilai ini hanya valid untuk konfigurasi TargetEndpoint dan TargetServer. Tidak valid untuk konfigurasi Host Virtual.

Secara default, nilai yang ditentukan dicocokkan persis dengan nama umum sertifikat target. Misalnya, menggunakan *.myhost.com sebagai nilai untuk <CommonName> hanya akan cocok dan memvalidasi nama host target jika nilai tepat *.myhost.com ditentukan sebagai nama umum dalam target sertifikat.

Secara opsional, Apigee dapat melakukan pencocokan dengan karakter pengganti menggunakan atribut wildcardMatch.

Misalnya, nama umum yang ditetapkan sebagai abc.myhost.com dalam sertifikat target akan dicocokkan dan divalidasi jika <CommonName> ditentukan sebagai berikut:

<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 terperinci, lihat Mengonfigurasi TLS dari Edge ke backend (Cloud dan Private Cloud).

Menggunakan variabel flow 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 bisa membuat proxy API secara terprogram mendeteksi lingkungan dan secara dinamis menetapkan referensi ke keystore dan truststore yang sesuai. Hal berikut Artikel Komunitas Apigee menjelaskan skenario ini secara lebih mendetail dan menyediakan API yang dapat di-deploy contoh proxy: https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html.

Pada contoh berikut tentang cara tag <SSLInfo> akan ditetapkan dalam Dengan konfigurasi TargetEndpoint, nilai dapat diberikan saat runtime, misalnya, oleh aplikasi Info, kebijakan JavaScript, atau kebijakan Tetapkan Pesan. Gunakan variabel pesan mana pun berisi nilai-nilai yang ingin Anda tetapkan.

Variabel hanya diizinkan pada 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 telah berakhir, atau perubahan pada konfigurasi sistem mengharuskan Anda untuk memperbarui sertifikat. Di beberapa 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 Mengupdate TLS sertifikat.

Namun, Anda dapat mengonfigurasi TargetEndpoint untuk menggunakan referensi ke keystore atau truststore sebagai gantinya. Keuntungan menggunakan referensi adalah Anda dapat memperbarui referensi agar mengarah ke keystore atau truststore yang berbeda untuk memperbarui sertifikat TLS/SSL tanpa harus memulai ulang {i>Message Processor<i}.

Misalnya, ditampilkan di bawah ini adalah TargetEndpoint yang menggunakan referensi ke keystore:

<SSLInfo> 
    <Enabled>true</Enabled> 
    <ClientAuthEnabled>false</ClientAuthEnabled> 
    <KeyStore>ref://keystoreref</KeyStore> 
    <KeyAlias>myKeyAlias</KeyAlias> 
</SSLInfo>

Gunakan panggilan POST API 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:password

Referensi 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:password

Untuk mengubah referensi di lain waktu agar mengarah ke keystore yang berbeda, pastikan alias memiliki dengan 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:password

TargetEndpoint dengan load balancing target

TargetEndpoint mendukung load balancing di beberapa TargetServers yang diberi nama menggunakan tiga beban algoritma balancing.

Untuk petunjuk terperinci, lihat Load balancing lintas backend server.

Kebijakan

Direktori /policies dalam proxy API berisi semua kebijakan yang tersedia untuk yang dikaitkan dengan Flows di proxy API.

Elemen Konfigurasi Kebijakan

Nama Deskripsi Default Wajib?
Policy
name

Nama internal kebijakan. Karakter yang dapat Anda gunakan dalam nama dibatasi menjadi: A-Za-z0-9._\-$ % Namun, UI pengelolaan Edge menerapkan seperti menghapus karakter yang bukan alfanumerik secara otomatis.

Atau, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama natural language yang berbeda.

T/A Ya
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk "matikan" kebijakan tersebut. Kebijakan ini tidak akan ditegakkan meskipun tetap terikat pada alur.

true Tidak
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Ini adalah perilaku yang diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur dapat dilanjutkan bahkan setelah kebijakan gagal.

salah Tidak
async

Catatan: Atribut ini tidak membuat kebijakan dieksekusi secara asinkron. Dalam sebagian besar kasus, gunakan nilai default false.

Jika disetel ke true, eksekusi kebijakan akan dialihkan ke eksekusi kebijakan yang berbeda sehingga thread utama bebas menangani permintaan tambahan. Saat offline selesai, thread utama kembali dan selesai menangani pesan alur kerja. Dalam beberapa kasus, menetapkan asinkron ke true akan meningkatkan proxy API tingkat tinggi. Namun, penggunaan asinkron yang berlebihan dapat mengganggu performa dengan terlalu banyak thread secara manual.

Untuk menggunakan perilaku asinkron di proxy API, lihat model objek JavaScript.

salah Tidak

Lampiran Kebijakan

Gambar berikut menunjukkan urutan eksekusi alur proxy API:

menunjukkan klien memanggil 
layanan HTTP. Permintaan bertemu dengan
  ProxyEndpoint dan TargetEndpoint, yang masing-masing berisi langkah-langkah yang memicu kebijakan. Setelah
  Layanan HTTP menampilkan respons, respons diproses oleh TargetEndpoint lalu
  ProxyEndpoing sebelum dikembalikan ke klien. Sesuai dengan permintaan, respons akan diproses
  oleh kebijakan dalam langkah-langkah.

Seperti yang ditunjukkan di atas:

Kebijakan dilampirkan sebagai langkah pemrosesan ke Flow. Nama kebijakan digunakan untuk merujuk ke kebijakan yang akan diterapkan sebagai Langkah pemrosesan. Format lampiran kebijakan adalah hal berikut:

<Step><Name>MyPolicy</Name></Step>

Kebijakan ditegakkan sesuai urutan penerapannya ke Flow. Contoh:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

Konfigurasi Lampiran Kebijakan Elements

Nama Deskripsi Default Wajib?
Step
Name Nama kebijakan yang akan dijalankan oleh definisi Langkah ini. T/A Ya
Condition Pernyataan kondisional yang menentukan apakah kebijakan diterapkan atau tidak. Jika kebijakan memiliki kondisi terkait, maka kebijakan hanya dijalankan jika bernilai benar (true). T/A Tidak

Alur

ProxyEndpoint dan TargetEndpoint menentukan pipeline untuk pesan permintaan dan respons diproses. Pipeline pemrosesan terdiri dari alur permintaan dan alur respons. Setiap permintaan alur dan alur respons dibagi lagi menjadi PreFlow, satu atau beberapa 'conditional' opsional atau 'bernama' {i>flow<i} (alur), dan {i>PostFlow<i}.

  • PreFlow: Selalu dijalankan. Dijalankan sebelum Flow kondisional.
  • PostFlow: Selalu dijalankan. Dieksekusi setelah Flow kondisional.

Selain itu, Anda dapat menambahkan PostClientFlow ke ProxyEndpoint, yang dieksekusi setelah ditampilkan ke aplikasi klien yang meminta. Hanya kebijakan MessageLogging dan Ekstensi Google Stackdriver Logging dapat dilampirkan ke alur ini. PostClientFlow mengurangi latensi proxy API dan menyediakan informasi untuk yang tidak dihitung sampai respons dikembalikan ke klien, seperti client.sent.start.timestamp dan client.sent.end.timestamp.Flow digunakan terutama untuk mengukur interval waktu antara stempel waktu awal dan akhir untuk respons untuk membuat pesan email baru.

Tonton video petunjuk singkat

Video: Tonton video singkat ini tentang cara menggunakan Logging Pesan di PostClientFlow.

Berikut adalah contoh PostClientFlow dengan kebijakan logging pesan terlampir.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

Pipeline pemrosesan proxy API mengeksekusi Flow dalam urutan berikut:

Pipeline Permintaan:

  1. PreFlow Permintaan Proxy
  2. Alur Bersyarat Permintaan Proxy (Opsional)
  3. PostFlow Permintaan Proxy
  4. PreFlow Permintaan Target
  5. Alur Bersyarat Permintaan Target (Opsional)
  6. PostFlow Permintaan Target

Pipeline Respons:

  1. PreFlow Respons Target
  2. Alur Bersyarat Respons Target (Opsional)
  3. PostFlow Respons Target
  4. PreFlow Respons Proxy
  5. Alur Bersyarat Respons Proxy (Opsional)
  6. PostFlow Respons Proxy
  7. Respons PostClientFlow (Opsional)

Hanya Flow dengan lampiran kebijakan yang perlu dikonfigurasi di ProxyEndpoint atau Konfigurasi TargetEndpoint. PreFlow dan PostFlow hanya perlu ditentukan di ProxyEndpoint atau Konfigurasi TargetEndpoint saat kebijakan perlu diterapkan selama PreFlow atau PostFlow diproses.

Berbeda dengan alur bersyarat, urutan elemen PreFlow dan PostFlow tidak penting--proxy API akan selalu mengeksekusi masing-masing pada titik yang sesuai dalam pipeline, terlepas dari tempat munculnya konfigurasi Endpoint.

Flow Bersyarat

ProxyEndpoint dan TargetEndpoints mendukung alur bersyarat dalam jumlah yang tidak terbatas (juga yang dikenal sebagai 'alur bernama').

Proxy API menguji kondisi yang ditetapkan dalam alur bersyarat dan, jika kondisi tersebut terpenuhi, langkah pemrosesan dalam alur bersyarat dijalankan oleh proxy API. Jika tidak terpenuhi, maka langkah pemrosesan dalam alur bersyarat akan diabaikan. Bersyarat alur dievaluasi dalam urutan yang ditentukan dalam proxy API dan alur pertama dengan kondisi 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 menetapkan bahwa itu hanya dieksekusi ketika jalur resource permintaan adalah /accesstoken. Setiap permintaan masuk dengan jalur /accesstoken menyebabkan flow ini dijalankan, bersama dengan semua kebijakan yang melekat pada alur. Jika jalur permintaan tidak menyertakan akhiran /accesstoken, flow tidak akan dieksekusi (meskipun alur bersyarat lainnya ).

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request> 
  </Flow>
</Flows>   

Elemen Konfigurasi Alur

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 bersyarat yang mengevaluasi satu atau lebih variabel untuk dievaluasi menjadi benar atau {i>false<i}. Semua Flow selain jenis PreFlow dan PostFlow yang telah ditentukan harus menentukan syarat untuk eksekusinya. T/A Ya
Request Pipeline yang terkait dengan pemrosesan pesan Request T/A Tidak
Response Pipeline yang terkait dengan pemrosesan pesan Response T/A Tidak

Pemrosesan langkah

Urutan Flow kondisional secara berurutan diterapkan oleh Apigee Edge. Flow Bersyarat mengeksekusi dari atas ke bawah. Flow kondisional pertama yang kondisinya dievaluasi untuk true dieksekusi, dan hanya satu Flow kondisional yang dieksekusi.

Misalnya, dalam konfigurasi Flow berikut, setiap permintaan masuk yang tidak termasuk akhiran jalur /first atau /second akan menyebabkan ThirdFlow untuk dijalankan, dengan 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

"Sumber daya" (file resource untuk digunakan dalam proxy API) adalah skrip, kode, dan transformasi XSL yang dapat disertakan ke Flow menggunakan kebijakan. Ini muncul di bagian "Skrip" pada bagian API editor proxy di UI pengelolaan.

Lihat File resource untuk mengetahui jenis resource.

Resource dapat disimpan di proxy API, lingkungan, atau organisasi. Dalam setiap kasus, resource yang direferensikan oleh nama dalam Kebijakan. Layanan API menyelesaikan nama dengan berpindah dari API {i>proxy<i}, ke lingkungan, ke tingkat organisasi.

Resource yang disimpan di tingkat organisasi dapat dirujuk oleh Kebijakan di lingkungan apa pun. Resource yang disimpan pada tingkat lingkungan dapat direferensikan oleh Kebijakan di lingkungan tersebut. J resource yang disimpan di level proxy API hanya dapat direferensikan oleh Kebijakan di proxy API tersebut.