Referensi konfigurasi proxy API

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

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

Jika Anda mempelajari cara membuat proxy API, sebaiknya Anda mulai dengan topik Membangun proxy API sederhana.

Cara paling umum untuk mengedit konfigurasi proxy adalah:

Pengembangan lokal konfigurasi proxy

Anda dapat mendownload konfigurasi proxy sehingga Anda dapat mengeditnya di mesin lokal. Setelah selesai, upload hasilnya ke Edge. Pendekatan ini memungkinkan Anda mengintegrasikan konfigurasi proxy ke dalam kontrol sumber, pembuatan versi, dan alur kerja bersama lainnya. Selain itu, dengan menangani konfigurasi proxy secara lokal, Anda dapat menggunakan alat validasi dan editor 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:

  1. Download konfigurasi proxy saat ini di UI Edge. (Pada tampilan Proxy API, pilih Project > Download Revision.)
  2. Di komputer lokal, buat direktori baru dan luaskan file ZIP yang didownload ke direktori tersebut.

    Untuk memperluas file ZIP, Anda dapat menggunakan utilitas seperti unzip, seperti yang ditampilkan pada contoh berikut:

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

    Konten yang diperluas pada file ZIP harus serupa dengan struktur yang dijelaskan dalam struktur proxy API.

  3. Edit file sumber seperlunya. Untuk deskripsi file sumber dalam konfigurasi proxy, 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 default 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, buat file tersebut.

  4. Setelah selesai mengedit file konfigurasi proxy, pastikan untuk menyimpan perubahan Anda.
  5. Beralihlah ke direktori baru yang Anda buat saat memperluas file ZIP (root dari file konfigurasi yang diperluas).

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

    cd myappdir

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

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

    Direktori level teratas dalam file ZIP harus /apiproxy.

    Tidak ada persyaratan khusus untuk nama file ZIP. Misalnya, Anda tidak perlu menambah nomor revisi atau menentukan tanggal dalam nama file, tetapi tindakan ini dapat berguna untuk proses debug atau kontrol sumber.

    Edge menambahkan nomor revisi konfigurasi proxy baru saat Anda menguploadnya.

  7. Upload konfigurasi proxy baru menggunakan Edge UI. (Pada tampilan API Proxy, pilih Project > Upload a New Revision.)

    Jika Anda mendapatkan error seperti Bundle is invalid. Empty bundle., pastikan direktori level teratas file ZIP Anda adalah /apiproxy. Jika tidak, arsipkan ulang file konfigurasi proxy dari root direktori yang diperluas.

    Setelah mengupload konfigurasi proxy baru, Edge akan menambahkan nomor revisi dan menampilkannya dalam tampilan Revision Summary.

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

  8. Deploy revisi baru Anda.

Untuk mengetahui 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 Konfigurasi Dasar.
Konfigurasi ProxyEndpoint Setelan untuk koneksi HTTP masuk (dari meminta aplikasi 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.
Alur Pipeline permintaan dan respons ProxyEndpoint dan TargetEndpoint yang dapat ditambahi kebijakan. Lihat Flow.
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 dan konten direktori proxy API

Komponen dalam tabel di atas ditentukan oleh file konfigurasi dalam struktur direktori berikut:

Menampilkan struktur direktori tempat apiproxy adalah root. Langsung di bawah direktori apiproxy adalah kebijakan, proxy, resource, dan direktori target, serta file weatherapi.xml.

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 ini harus unik dalam suatu organisasi.

Contoh konfigurasi:

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

Elemen Konfigurasi Dasar

Nama Deskripsi Default Wajib diisi?
APIProxy
name Nama proxy API, yang harus unik dalam organisasi. Karakter yang boleh 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 otomatis melacak revisi proxy API saat ini. 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 mengaktifkan 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. Biasanya, Anda hanya akan melihat elemen ini ketika proxy API dibuat menggunakan UI pengelolaan Edge. Ini hanyalah setelan 'manifes', yang dirancang untuk memberikan visibilitas ke dalam konten proxy API. T/A Tidak
ProxyEndpoints Daftar ProxyEndpoint di direktori /proxies proxy API ini. Biasanya, Anda hanya akan melihat elemen ini ketika proxy API dibuat menggunakan UI pengelolaan Edge. Ini hanyalah setelan 'manifes', yang dirancang untuk memberikan visibilitas ke konten proxy API. T/A Tidak
Resources Daftar resource (JavaScript, Python, Java, XSLT) dalam direktori /resources proxy API ini. Biasanya, Anda hanya akan melihat elemen ini ketika proxy API dibuat menggunakan UI pengelolaan Edge. Ini hanyalah setelan 'manifes', 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 jalur di penyimpanan spesifikasi.

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

ProxyEndpoint

Gambar berikut menampilkan alur permintaan/respons:

Menampilkan klien yang memanggil layanan HTTP. Permintaan akan melewati endpoint proxy, lalu endpoint target sebelum diproses oleh layanan HTTP. Respons akan melewati endpoing target, lalu
  endpoint proxy sebelum ditampilkan ke klien.

/apiproxy/proxies/default.xml

Konfigurasi ProxyEndpoint menentukan antarmuka masuk (menghadap klien) untuk proxy API. Saat mengonfigurasi ProxyEndpoint, Anda menyiapkan konfigurasi jaringan yang menentukan cara aplikasi klien ('aplikasi') memanggil API ber-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:

Elemen Konfigurasi ProxyEndpoint

Nama Deskripsi Default Wajib diisi?
ProxyEndpoint
name Nama ProxyEndpoint. Harus unik dalam konfigurasi proxy API, jika (dalam kasus yang jarang terjadi) beberapa ProxyEndpoint ditentukan. Karakter yang boleh digunakan dalam nama memiliki batasan sebagai berikut: A-Za-z0-9._\-$ %. T/A Ya
PreFlow Menentukan kebijakan dalam alur PraAlur permintaan atau respons. T/A Ya
Flows
Menentukan kebijakan dalam alur bersyarat dari 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 dikaitkan dengan proxy API
BasePath

String yang diperlukan yang secara unik mengidentifikasi jalur URI yang digunakan oleh Apigee Edge untuk mengarahkan 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 suatu lingkungan. Keunikan divalidasi saat 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, jalur dasar /team/*/members memungkinkan klien memanggil https://[host]/team/blue/members dan https://[host]/team/green/members tanpa perlu membuat proxy API baru untuk mendukung tim baru. Perhatikan bahwa /**/ tidak didukung.

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

/ Ya
VirtualHost

Mengaitkan proxy API dengan URL dasar spesifik untuk suatu lingkungan. VirtualHost adalah konfigurasi bernama yang menentukan satu atau beberapa URL untuk suatu 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 sebuah lingkungan: default dan secure. Organisasi juga dapat menentukan domain kustom. Untuk memastikan bahwa proxy API hanya tersedia melalui HTTPS, misalnya, setel VirtualHost di HTTPProxyConnection ke secure.

default Tidak
Properties Kumpulan setelan konfigurasi HTTP opsional dapat ditentukan sebagai properti <ProxyEndpoint>. T/A Tidak
FaultRules
Mendefinisikan bagaimana ProxyEndpoint bereaksi terhadap error. Aturan fault menentukan dua item:
  • Kondisi yang menentukan kesalahan yang akan ditangani berdasarkan kategori, subkategori, atau nama kesalahan yang telah ditentukan sebelumnya
  • Satu atau beberapa kebijakan yang menentukan perilaku aturan kesalahan untuk Kondisi yang sesuai

Lihat Menangani kesalahan.

T/A Tidak
DefaultFaultRule

Menangani 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 yang telah diberi nama, tetapi juga dapat mengarah langsung ke URL.
Name Atribut wajib, yang memberikan nama untuk RouteRule. Karakter yang boleh Anda gunakan dalam nama dibatasi untuk hal berikut: A-Za-z0-9._\-$ %. Misalnya, Cat2 %_ adalah nama resmi. T/A Ya
Condition Pernyataan kondisional opsional yang digunakan untuk perutean dinamis saat runtime. RouteRules bersyarat berguna, misalnya, untuk mengaktifkan pemilihan rute berbasis konten untuk mendukung pembuatan versi backend. T/A Tidak
TargetEndpoint

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

Dengan memberi nama TargetEndpoint, Anda menunjukkan tempat 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, 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 tempat RouteRule meneruskan permintaan setelah diproses oleh ProxyEndpoint.

Misalnya, RouteRule berikut merujuk ke 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 akan mengabaikan konfigurasi TargetEndpoints yang bernama pada /apiproxy/targets). Karena alasan ini, TargetEndpoint adalah konfigurasi proxy API opsional, meskipun, pada 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 dirantai untuk mendukung perutean dinamis saat runtime. Permintaan masuk dapat dirutekan ke konfigurasi TargetEndpoint yang diberi nama, langsung ke URL, atau ke kombinasi keduanya, berdasarkan header HTTP, konten pesan, parameter kueri, atau informasi kontekstual seperti waktu, lokalitas, dll.

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

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

Misalnya, hal berikut mendefinisikan Rute null:

<RouteRule name="GoNowhere"/>

Rute null bersyarat bisa berguna. Dalam contoh berikut, Rute null dikonfigurasi untuk dijalankan saat request.header.X-DoNothing header HTTP memiliki nilai selain null.

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

Ingat, RouteRules dapat dibuat rantai, sehingga Route null bersyarat biasanya akan menjadi salah satu komponen dari rangkaian RouteRules yang dirancang untuk mendukung perutean bersyarat.

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

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

TargetEndpoint

Menampilkan klien yang memanggil layanan HTTP. Permintaan akan melewati endpoint proxy, lalu endpoint target sebelum diproses oleh layanan HTTP. Respons akan melewati endpoing target, lalu
  endpoint proxy sebelum ditampilkan ke klien.

TargetEndpoint adalah ekuivalen keluar dari ProxyEndpoint. TargetEndpoint berfungsi sebagai klien bagi layanan backend atau API, yang mengirimkan permintaan dan menerima respons.

Proxy API tidak perlu memiliki TargetEndpoints. ProxyEndpoint dapat dikonfigurasi untuk memanggil URL secara langsung. Proxy API tanpa TargetEndpoint biasanya berisi ProxyEndpoint yang langsung memanggil layanan backend, 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>

Elemen Konfigurasi TargetEndpoint

TargetEndpoint dapat memanggil target dengan salah satu cara berikut:

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

Hanya konfigurasi salah satu dari parameter ini di TargetEndpoint.

Nama Deskripsi Default Wajib diisi?
TargetEndpoint
name Nama TargetEndpoint, yang harus unik dalam konfigurasi proxy API. Nama TargetEndPoint digunakan dalam ProxyEndpoint RouteRule untuk mengarahkan permintaan keluar untuk pemrosesan keluar. Karakter yang boleh digunakan dalam nama dibatasi untuk hal berikut: A-Za-z0-9._\-$ %. T/A Ya
PreFlow Menentukan kebijakan dalam alur PraAlur permintaan atau respons. T/A Ya
Flows
Menentukan kebijakan dalam alur bersyarat dari permintaan atau respons.
T/A Ya
PostFlow
Menentukan kebijakan dalam alur PostFlow permintaan atau respons.
T/A Ya
HTTPTargetConnection

Menentukan jangkauan resource backend melalui HTTP dengan elemen turunannya.

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

URL Menentukan alamat jaringan layanan backend tempat TargetEndpoint meneruskan pesan permintaan. T/A Tidak
LoadBalancer

Menentukan satu atau beberapa konfigurasi TargetServer bernama. Konfigurasi TargetServer bernama dapat digunakan untuk load balancing yang menentukan 2 atau beberapa koneksi konfigurasi endpoint.

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

Lihat Load balancing di beberapa server backend.

T/A Tidak
Properties Kumpulan setelan konfigurasi HTTP opsional dapat ditentukan sebagai properti <TargetEndpoint>. T/A Tidak
SSLInfo Secara opsional, tentukan setelan TLS/SSL pada 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, yang mengabaikan karakteristik jaringan seperti load balancing dan pemroses pesan.

Untuk menentukan resource target, sertakan elemen turunan APIProxy (dengan elemen ProxyEndpoint) atau elemen turunan Path.

Untuk informasi selengkapnya, lihat Membuat rantai proxy API bersama.

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 penggunaan 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. Proxy target 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 fault menentukan dua item:
  • Kondisi yang menentukan kesalahan yang akan ditangani berdasarkan kategori, subkategori, atau nama kesalahan yang telah ditentukan sebelumnya
  • Satu atau beberapa kebijakan yang menentukan perilaku aturan kesalahan untuk Kondisi yang sesuai

Lihat Menangani kesalahan.

T/A Tidak
DefaultFaultRule

Menangani error (sistem, transport, 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 mengimplementasikan fungsi TargetEndpoint.

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

Skrip harus disertakan bersama 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

Jika ingin, teruskan variabel lingkungan ke skrip Node.js utama.

Lihat Memahami dukungan Edge untuk modul Node.js.

T/A Tidak
Arguments

Jika ingin, teruskan argumen ke skrip Node.js utama.

Lihat Memahami dukungan Edge untuk modul Node.js.

T/A Tidak

Konfigurasi TargetEndpoint TLS/SSL

TargetEndpoint sering kali perlu mengelola koneksi HTTPS dengan infrastruktur backend yang heterogen. Karena alasan ini, sejumlah setelan konfigurasi TLS/SSL didukung.

Elemen Konfigurasi TargetEndpoint TLS/SSL

Nama Deskripsi Default Wajib diisi?
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 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 cipher yang ditentukan, semua cipher 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, 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

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 mendapatkan 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 menyetel proxy API secara terprogram untuk mendeteksi 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: https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html.

Dalam contoh berikut tentang cara menetapkan tag <SSLInfo> dalam konfigurasi TargetEndpoint, nilai dapat diberikan saat runtime, misalnya, oleh Pemanggilan Java, kebijakan JavaScript, atau kebijakan Tetapkan Pesan. Gunakan variabel pesan yang berisi nilai yang ingin Anda tetapkan.

Variabel hanya boleh ada di 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. Pada penginstalan Edge for Private Cloud, saat mengonfigurasi TLS/SSL dengan menggunakan nilai statis atau menggunakan variabel alur, ada kemungkinan Anda harus memulai ulang Message Processors.

Untuk mengetahui informasi selengkapnya, lihat Mengupdate sertifikat TLS.

Namun, Anda dapat mengonfigurasi TargetEndpoint secara opsional agar menggunakan reference ke keystore atau truststore. Keuntungan menggunakan referensi adalah Anda dapat memperbarui referensi agar mengarah ke keystore atau truststore lain untuk memperbarui sertifikat TLS/SSL tanpa harus memulai ulang Message Processors.

Misalnya, yang 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 tersebut menetapkan 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 nanti agar mengarah ke keystore yang berbeda, untuk memastikan bahwa alias tersebut 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:password

TargetEndpoint dengan load balancing target

TargetEndpoint mendukung load balancing di beberapa TargetServers bernama menggunakan tiga algoritma load balancing.

Untuk petunjuk terperinci, lihat Load balancing di seluruh server backend.

Kebijakan

Direktori /policies dalam proxy API berisi semua kebijakan yang tersedia untuk dilampirkan ke Flow di proxy API.

Elemen Konfigurasi Kebijakan

Nama Deskripsi Default Wajib diisi?
Policy
name

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

Secara opsional, gunakan elemen <DisplayName> untuk memberi label 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 "menonaktifkan" kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.

true Tidak
continueOnError

Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal.

false Tidak
async

Catatan: Atribut ini tidak membuat kebijakan dijalankan secara asinkron. Dalam sebagian besar kasus, biarkan nilai ini dengan default false.

Jika ditetapkan ke true, eksekusi kebijakan akan dialihkan ke thread lain, sehingga thread utama bebas untuk menangani permintaan tambahan. Setelah pemrosesan offline selesai, thread utama akan kembali dan selesai menangani alur pesan. Dalam beberapa kasus, menyetel asinkron ke true akan meningkatkan performa proxy API. Namun, penggunaan asinkron yang berlebihan dapat menurunkan performa dengan terlalu banyak pengalihan thread.

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

false Tidak

Lampiran Kebijakan

Gambar berikut menunjukkan urutan eksekusi alur proxy API:

menunjukkan klien yang memanggil layanan HTTP. Permintaan tersebut menemukan ProxyEndpoint dan TargetEndpoint yang masing-masing berisi langkah-langkah yang memicu kebijakan. Setelah layanan HTTP menampilkan respons, respons tersebut diproses oleh TargetEndpoint, lalu ProxyEndpoing sebelum ditampilkan ke klien. Seperti permintaan, respons diproses oleh kebijakan secara bertahap.

Seperti yang ditunjukkan di atas:

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

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

Kebijakan diberlakukan sesuai urutan lampirannya pada Alur. Contoh:

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

Elemen Konfigurasi Lampiran Kebijakan

Nama Deskripsi Default Wajib diisi?
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 suatu kebijakan memiliki kondisi yang terkait, kebijakan tersebut hanya akan dijalankan jika pernyataan kondisional bernilai true (benar). 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 'kondisional' atau 'bernama' opsional, dan sebuah PostFlow.

  • PreFlow: Selalu dijalankan. Dieksekusi sebelum Flow bersyarat apa pun.
  • PostFlow: Selalu dijalankan. Dieksekusi setelah Flow kondisional.

Selain itu, Anda dapat menambahkan PostClientFlow ke ProxyEndpoint yang berjalan setelah respons ditampilkan ke aplikasi klien yang meminta. Hanya kebijakan MessageLogging dan Ekstensi Google Stackdriver Logging yang dapat ditambahkan ke alur ini. PostClientFlow mengurangi latensi proxy API dan menyediakan informasi untuk logging yang tidak dihitung hingga setelah respons ditampilkan ke klien, seperti client.sent.start.timestamp dan client.sent.end.timestamp.Alur ini terutama digunakan untuk mengukur interval waktu antara stempel waktu mulai dan akhir untuk pesan respons.

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 menjalankan Flow dalam urutan berikut:

Pipeline Permintaan:

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

Pipeline Respons:

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

Hanya Flow dengan lampiran kebijakan yang perlu dikonfigurasi di konfigurasi ProxyEndpoint atau TargetEndpoint. PreFlow dan PostFlow hanya perlu ditentukan dalam konfigurasi ProxyEndpoint atau TargetEndpoint jika kebijakan perlu diberlakukan selama pemrosesan PreFlow atau PostFlow.

Berbeda dengan flow kondisional, pengurutan elemen PreFlow dan PostFlow tidak penting--proxy API akan selalu mengeksekusi masing-masing pada titik yang sesuai dalam pipeline, di mana pun elemen tersebut muncul dalam konfigurasi Endpoint.

Alur Bersyarat

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

Proxy API menguji kondisi yang ditentukan dalam flow kondisional dan, jika kondisi terpenuhi, langkah-langkah pemrosesan dalam flow kondisional akan dijalankan oleh proxy API. Jika kondisi tidak terpenuhi, langkah pemrosesan dalam alur bersyarat akan diabaikan. Alur bersyarat dievaluasi dalam urutan yang ditentukan dalam proxy API dan alur pertama yang kondisinya terpenuhi akan dijalankan.

Dengan menentukan alur bersyarat, Anda mendapatkan kemampuan untuk menerapkan langkah-langkah pemrosesan dalam proxy API berdasarkan:

  • URI Permintaan
  • Kata kerja HTTP (GET/PUT/POST/DELETE)
  • Nilai parameter kueri, header, dan parameter formulir
  • Banyak jenis kondisi lainnya

Misalnya, flow kondisional berikut menentukan bahwa flow hanya dijalankan jika jalur resource permintaan adalah /accesstoken. Setiap permintaan masuk dengan jalur /accesstoken menyebabkan alur ini dijalankan, beserta kebijakan apa pun yang disertakan pada alur tersebut. Jika jalur permintaan tidak menyertakan akhiran /accesstoken, flow tidak akan dijalankan (meskipun flow kondisional lainnya mungkin).

<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 diisi?
Flow Pipeline pemrosesan permintaan atau respons yang ditentukan oleh ProxyEndpoint atau TargetEndpoint
Name Nama unik Flow. T/A Ya
Condition Pernyataan kondisional yang mengevaluasi pada atau beberapa variabel untuk dievaluasi menjadi benar atau salah. Semua Flow selain jenis PraFlow dan PostFlow yang telah ditetapkan 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

Urutan Flow kondisional diterapkan oleh Apigee Edge. Alur Bersyarat dijalankan dari atas ke bawah. Flow kondisional pertama yang kondisinya bernilai true akan dieksekusi, dan hanya satu Flow bersyarat yang dijalankan.

Misalnya, dalam konfigurasi Alur berikut, setiap permintaan masuk yang tidak menyertakan akhiran jalur /first atau /second akan menyebabkan ThirdFlow dijalankan, yang menerapkan kebijakan bernama 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 dalam proxy API) adalah transformasi skrip, kode, dan XSL yang dapat dilampirkan ke Flow menggunakan kebijakan. Skrip ini muncul di bagian "Skrip" 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 direferensikan dengan nama dalam Kebijakan. Layanan API me-resolve nama ini dengan berpindah dari proxy API ke lingkungan, ke tingkat organisasi.

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