Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Sebagai developer yang menangani Apigee, aktivitas pengembangan utama Anda melibatkan mengonfigurasi proxy API yang berfungsi sebagai proxy untuk API atau layanan backend. Dokumen ini merupakan referensi untuk semua elemen konfigurasi yang tersedia bagi Anda saat membangun proxy API.
Jika Anda mempelajari cara membangun proxy API, sebaiknya mulai dengan topik Membangun proxy API sederhana.
Edit konfigurasi proxy API Anda menggunakan salah satu metode berikut:
- Gunakan UI atau API Apigee.
- Download paket konfigurasi proxy API, edit secara manual, dan upload konfigurasi baru ke Apigee, seperti yang dijelaskan di Mendownload dan mengupload paket konfigurasi proxy API.
Struktur direktori konfigurasi proxy API
Struktur direktori konfigurasi proxy API ditampilkan di bawah ini:
Konfigurasi proxy API terdiri dari konten berikut:
Konfigurasi dasar | Setelan konfigurasi utama untuk proxy API. |
ProxyEndpoint | Setelan untuk koneksi HTTP masuk (dari meminta aplikasi ke Apigee), alur permintaan dan respons, serta lampiran kebijakan. |
TargetEndpoint | Setelan untuk koneksi HTTP keluar (dari Apigee ke layanan backend), alur permintaan dan respons, serta lampiran kebijakan. |
Alur | Pipeline permintaan dan respons ProxyEndpoint dan TargetEndpoint tempat kebijakan dapat dilampirkan. |
Kebijakan | File konfigurasi berformat XML yang sesuai dengan skema kebijakan Apigee. |
Resource | Skrip, file JAR, dan file XSLT yang dirujuk oleh kebijakan untuk menjalankan logika kustom. |
Konfigurasi dasar
/apiproxy/weatherapi.xml
Konfigurasi dasar untuk proxy API, yang menentukan nama proxy API. Nama dalam organisasi harus unik.
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
yang boleh Anda gunakan dalam nama memiliki batasan berikut:
A-Za-z0-9_- |
T/A | Ya |
revision |
Nomor revisi konfigurasi proxy API. Anda tidak perlu menetapkan nomor revisi secara eksplisit, karena Apigee akan 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 primaryVersion 4 dan minorVersion 0. Setelan ini dapat digunakan pada masa mendatang untuk mengaktifkan evolusi format proxy API. | 4.0 | Tidak |
Description |
Deskripsi tekstual proxy API. Jika disediakan, deskripsi akan ditampilkan di UI Apigee. | 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 jika proxy API dibuat menggunakan UI Apigee.
Ini hanyalah setelan manifes, yang dirancang untuk memberikan visibilitas ke dalam konten proxy API. |
T/A | Tidak |
ProxyEndpoints |
Daftar endpoint proxy dalam direktori /proxies proxy API ini. Biasanya, Anda hanya akan melihat elemen ini jika proxy API dibuat menggunakan UI Apigee. Ini hanyalah setelan manifes, yang dirancang untuk memberikan visibilitas ke dalam
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 jika proxy API
dibuat menggunakan UI Apigee. 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 ini ditetapkan ke URL atau jalur di penyimpanan spesifikasi. |
T/A | Tidak |
TargetServers |
Daftar server target yang dirujuk di endpoint target proxy API ini. Biasanya, Anda hanya akan melihat elemen ini jika proxy API dibuat menggunakan Apigee. Ini hanyalah setelan manifes, yang dirancang untuk memberikan visibilitas ke dalam konten proxy API. | T/A | Tidak |
TargetEndpoints |
Daftar endpoint target dalam direktori /targets proxy API ini. Biasanya, Anda hanya akan melihat elemen ini jika proxy API dibuat menggunakan UI Apigee. Ini hanyalah setelan manifes, yang dirancang untuk memberikan visibilitas ke dalam
konten proxy API. |
T/A | Tidak |
ProxyEndpoint
Gambar berikut menunjukkan alur permintaan/respons:
/apiproxy/proxies/default.xml
Konfigurasi ProxyEndpoint menentukan antarmuka masuk (menghadap klien) untuk proxy API. Saat mengonfigurasi endpoint proxy, Anda sedang menyiapkan konfigurasi jaringan yang menentukan 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> <Properties/> </HTTPProxyConnection> <FaultRules/> <DefaultFaultRule/> <RouteRule name="default"> <TargetEndpoint>default</TargetEndpoint> </RouteRule> </ProxyEndpoint>
Elemen konfigurasi yang diperlukan pada endpoint proxy dasar adalah:
Elemen konfigurasi ProxyEndpoint
Nama | Deskripsi | Default | Wajib? | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ProxyEndpoint |
||||||||||||||||||
name |
Nama endpoint proxy. Harus unik dalam konfigurasi proxy API, jika (dalam kasus yang jarang terjadi) beberapa endpoint proxy ditentukan. 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 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 terkait dengan proxy API. | |||||||||||||||||
BasePath |
String yang diperlukan dan secara unik mengidentifikasi jalur URI yang digunakan oleh Apigee untuk mengarahkan 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 jalur dasar. Misalnya, kode ini TIDAK didukung: |
/ | Ya | |||||||||||||||
Properties |
Serangkaian setelan konfigurasi HTTP opsional dapat ditentukan sebagai properti
<ProxyEndpoint> .
Gunakan properti <Property name= \ "request.queryparams.ignore.content.type.charset">true</>
Tabel berikut menunjukkan contoh output, bergantung pada setelan properti
|
T/A | Tidak | |||||||||||||||
FaultRules |
Menentukan bagaimana endpoint proxy bereaksi terhadap error. Aturan fault menentukan dua item:
Lihat Menangani kesalahan. |
T/A | Tidak | |||||||||||||||
DefaultFaultRule |
Menangani error (sistem, transportasi, 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 akan mengarah ke endpoint target yang diberi nama, IntegrationEndpoint, atau 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. Endpoint target bernama adalah endpoint target yang ditentukan dalam proxy API yang sama dalam direktori Dengan memberi nama endpoint target, Anda menunjukkan tempat pesan permintaan harus diteruskan setelah pemrosesan oleh pipeline permintaan ProxyEndpoint. Perhatikan bahwa ini adalah setelan opsional. Endpoint proxy dapat memanggil URL secara langsung. Misalnya, resource JavaScript atau Java, yang berfungsi dalam peran klien HTTP, dapat melakukan tugas dasar endpoint target, yaitu meneruskan permintaan ke layanan backend. |
T/A | Tidak | |||||||||||||||
URL |
String opsional yang menentukan alamat jaringan keluar yang dipanggil oleh
endpoint proxy, mengabaikan konfigurasi TargetEndpoint apa pun yang mungkin disimpan di
/targets |
T/A | Tidak |
Cara mengonfigurasi RouteRules
Endpoint target bernama mengacu pada file konfigurasi pada /apiproxy/targets
yang akan digunakan oleh RouteRule untuk meneruskan permintaan setelah diproses oleh endpoint proxy.
Misalnya, RouteRule berikut merujuk ke konfigurasi /apiproxy/targets/myTarget.xml
:
<RouteRule name="default"> <TargetEndpoint>myTarget</TargetEndpoint> </RouteRule>
Pemanggilan URL langsung
Endpoint proxy juga dapat langsung memanggil layanan backend. Pemanggilan URL langsung mengabaikan
konfigurasi TargetEndpoint tertentu pada /apiproxy/targets
). Karena alasan ini,
TargetEndpoint adalah konfigurasi proxy API opsional, meskipun pada praktiknya, pemanggilan langsung
dari endpoint proxy 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 pemilihan rute dinamis saat runtime. Permintaan masuk dapat diarahkan ke konfigurasi TargetEndpoint yang diberi nama, langsung ke URL, atau ke kombinasi keduanya, berdasarkan header HTTP, konten pesan, parameter kueri, atau informasi kontekstual, waktu, lokalitas, dsb.
RouteRules Bersyarat berfungsi seperti pernyataan kondisional lainnya di Apigee. Lihat Referensi kondisi dan Referensi variabel flow.
Misalnya, kombinasi RouteRule berikut mengevaluasi terlebih dahulu permintaan masuk untuk memverifikasi nilai header HTTP. Jika header HTTP routeTo
memiliki nilai
TargetEndpoint1
, permintaan akan diteruskan ke endpoint target 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 yang mana pesan permintaan tidak perlu diteruskan ke endpoint target. Hal ini berguna ketika endpoint proxy melakukan semua pemrosesan yang diperlukan, misalnya menggunakan JavaScript untuk memanggil layanan eksternal atau mengambil data dari pencarian ke key-value store Apigee.
Misalnya, kode berikut mendefinisikan 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 dirantai, sehingga Rute null bersyarat biasanya akan menjadi salah satu komponen dari kumpulan RouteRules yang dirancang untuk mendukung perutean bersyarat.
Penggunaan praktis Rute null bersyarat akan mendukung penyimpanan cache. Dengan menggunakan nilai variabel yang disetel 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
Endpoint target adalah yang setara dengan endpoint proxy. Endpoint target berfungsi sebagai klien bagi layanan backend atau API. Endpoint ini mengirim permintaan dan menerima respons.
Proxy API tidak perlu memiliki endpoint target. Endpoint proxy dapat dikonfigurasi untuk memanggil URL secara langsung. Proxy API tanpa endpoint target biasanya berisi endpoint proxy yang secara langsung memanggil layanan backend, atau yang dikonfigurasi untuk memanggil layanan menggunakan Java atau JavaScript.
Konfigurasi TargetEndpoint
/targets/default.xml
Endpoint target menentukan koneksi keluar dari Apigee ke layanan atau resource lainnya.
Berikut adalah contoh konfigurasi TargetEndpoint:
<TargetEndpoint name="default"> <PreFlow/> <Flows/> <PostFlow/> <HTTPTargetConnection> <URL>http://mocktarget.apigee.net</URL> <SSLInfo/> <Authentication/> </HTTPTargetConnection> <FaultRules/> <DefaultFaultRule/> <ScriptTarget/> <LocalTargetConnection/> </TargetEndpoint>
Elemen konfigurasi TargetEndpoint
Endpoint target dapat memanggil target dengan salah satu cara berikut:
- HTTPTargetConnection untuk panggilan HTTP atau HTTPS
- LocalTargetConnection untuk rantai proxy-to-proxy lokal
Hanya konfigurasikan salah satunya di endpoint target.
Nama | Deskripsi | Default | Wajib? |
---|---|---|---|
TargetEndpoint |
|||
name |
Nama endpoint target, yang harus unik dalam konfigurasi proxy API. Nama endpoint target digunakan dalam ProxyEndpoint RouteRule untuk
mengarahkan permintaan keluar untuk pemrosesan. 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 dari permintaan atau respons.
|
T/A | Ya |
PostFlow |
Menentukan kebijakan dalam alur PostFlow permintaan atau respons.
|
T/A | Ya |
HTTPTargetConnection |
Dengan elemen turunannya, menentukan resource backend yang dijangkau melalui HTTP. Jika Anda menggunakan HTTPTargetConnection, jangan konfigurasi jenis koneksi target lainnya (ScriptTarget atau LocalTargetConnection).
Anda dapat menggunakan elemen turunan |
||
URL |
Menentukan alamat jaringan layanan backend tempat endpoint target 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 server target untuk memisahkan konfigurasi proxy API dari URL endpoint layanan backend konkret. |
T/A | Tidak |
Properties |
Serangkaian setelan konfigurasi HTTP opsional dapat ditentukan sebagai properti
<TargetEndpoint> . |
T/A | Tidak |
SSLInfo |
Jika perlu, tentukan setelan TLS/SSL pada endpoint target 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, 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-sama. 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 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 endpoint proxy proxy target. | T/A | Tidak |
Path |
Menentukan jalur endpoint proxy API yang akan digunakan sebagai target untuk permintaan. Proxy target harus berada dalam organisasi dan lingkungan yang sama dengan permintaan pengiriman proxy. Ini adalah alternatif penggunaan APIProxy. | T/A | Tidak |
FaultRules |
Menentukan bagaimana endpoint target bereaksi terhadap error. Aturan fault menentukan dua item:
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 |
Penggunaan elemen <Authentication>
Penggunaan elemen <Authentication>
di <TargetEndpoint>
identik dengan penggunaan elemen <Authentication>
dalam kebijakan ServiceCallout. Dalam <TargetEndpoint>
dan ServiceCallout, <Authentication>
adalah subelemen <HttpTargetConnection>
. Untuk mengetahui detailnya, lihat Elemen Authentication
di referensi kebijakan ServiceCallout.
Referensi error elemen <Authentication>
Jika menggunakan elemen <Authentication>
, Anda dapat menemukan kemungkinan pesan error dan tips pemecahan masalah untuk error deployment dan runtime di bagian Error dalam dokumentasi kebijakan ServiceCallout.
Contoh elemen <Authentication>
Contoh berikut menunjukkan cara memanggil layanan yang di-deploy di Cloud Run sebagai target menggunakan elemen Authentication
untuk membuat token OpenID Connect yang diperlukan untuk mengautentikasi panggilan:
<TargetEndpoint name="TargetEndpoint-1"> <HTTPTargetConnection> <Properties/> <URL>https://cloudrun-hostname.a.run.app/test</URL> <Authentication> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app/test</Audience> </GoogleIDToken> </Authentication> </HTTPTargetConnection> </TargetEndpoint>
Contoh berikut menunjukkan cara memanggil TargetService yang mengarah ke Cloud Run menggunakan elemen Authentication
untuk membuat token OpenID Connect yang diperlukan untuk mengautentikasi panggilan. Elemen HeaderName
menambahkan token pembawa yang dihasilkan ke header bernama X-Serverless-Authorization
yang dikirim ke sistem target. Header Authorization
, jika ada, tidak diubah dan juga dikirim dalam permintaan.
<TargetEndpoint name="TargetEndpoint-1"> <HTTPTargetConnection> <Authentication> <HeaderName>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication> <LoadBalancer> <Server name="cloud-run-target" /> </LoadBalancer> </HTTPTargetConnection> </TargetEndpoint>
Contoh berikut menunjukkan cara memanggil TargetService yang mengarah ke layanan Secret Manager Google. Dalam contoh ini, elemen GoogleAccessToken dikonfigurasi untuk membuat Token Autentikasi Google guna mengautentikasi permintaan target:
<HTTPTargetConnection> <Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication> <URL> https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id </URL> </HTTPTargetConnection>
Contoh berikut menunjukkan cara menetapkan audiens GoogleIDToken secara otomatis. Jika useTargetUrl
adalah true
dan variabel yang direferensikan tidak di-resolve menjadi variabel yang valid, URL target (kecuali parameter kueri) akan digunakan sebagai audiens.
Misalkan
jalur permintaan adalah /foobar
dan URL server target adalah https://xyz.com
,
audiens GoogleIDToken akan otomatis ditetapkan ke https://xyz.com/foobar
.
<TargetEndpoint name="TargetEndpoint-1"> <HTTPTargetConnection> <Authentication> <GoogleIDToken> <Audience ref='myvariable' useTargetUrl="true"/> </GoogleIDToken> </Authentication> <LoadBalancer> <Server name="TS" /> </LoadBalancer> </HTTPTargetConnection> </TargetEndpoint>
Konfigurasi TargetEndpoint TLS/SSL
Endpoint target 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? |
---|---|---|---|
SSLInfo |
|||
Enabled |
Blok <SSLInfo> dapat digunakan untuk TLS/SSL satu arah dan dua arah.
Jika ditetapkan ke Nilai default |
true jika <URL> menentukan HTTPS |
Tidak |
Enforce |
Menerapkan SSL yang ketat antara Apigee dan backend target. Jika ditetapkan ke Jika tidak disetel, atau disetel ke |
false |
Tidak |
TrustStore |
Keystore yang berisi sertifikat server tepercaya. | T/A | Tidak |
ClientAuthEnabled |
Mengaktifkan TLS dua arah (juga dikenal sebagai TLS atau mTLS bersama) antara Apigee dan klien API, atau antara Apigee dan backend target. Mengaktifkan TLS dua arah biasanya mengharuskan Anda menyiapkan truststore di Apigee dan truststore. |
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) |
IgnoreValidationErrors |
Menunjukkan apakah error validasi diabaikan. Jika sistem backend menggunakan SNI dan menampilkan sertifikat dengan Nama yang Dibedakan (DN) subjek yang tidak cocok dengan nama host, error tersebut tidak dapat diabaikan dan koneksi akan gagal. Catatan: Jika |
false |
Tidak |
Ciphers |
Cipher yang didukung untuk TLS/SSL keluar. Jika tidak ada cipher yang ditentukan, maka 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, tentukan protokol secara eksplisit. Misalnya, untuk hanya mengizinkan TLS v1.2 atau TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols> |
T/A | Tidak |
CommonName |
Nama umum TLS untuk sertifikat | T/A | Tidak |
Contoh endpoint target dengan autentikasi klien keluar diaktifkan
<TargetEndpoint name="default"> <HttpTargetConnection> <URL>https://myservice.com</URL> <SSLInfo> <Enabled>true</Enabled> <Enforce>true</Enforce> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>myKeystore</KeyStore> <KeyAlias>myKey</KeyAlias> <TrustStore>myTruststore</TrustStore> </SSLInfo> </HttpTargetConnection> </TargetEndpoint>
Untuk petunjuk mendetail, lihat Opsi untuk mengonfigurasi TLS.
Menggunakan variabel alur untuk menetapkan nilai TLS/SSL secara dinamis
Anda juga dapat menetapkan detail TLS/SSL secara dinamis untuk mendukung persyaratan runtime fleksibel. Misalnya, jika proxy terhubung ke dua target yang berpotensi berbeda (target pengujian dan target produksi), Anda dapat menyetel proxy API secara terprogram mendeteksi lingkungan yang dipanggil dan secara dinamis menetapkan referensi ke keystore dan truststore yang sesuai. Artikel Dynamic SSLInfo untuk TargetEndpoint menggunakan referensi variabel Artikel Komunitas Apigee menjelaskan skenario ini secara lebih mendetail dan memberikan contoh proxy API yang dapat di-deploy.
Pada contoh cara menetapkan tag <SSLInfo>
dalam
konfigurasi TargetEndpoint berikut, nilai dapat diberikan pada saat runtime, misalnya, oleh Pemanggilan
Java, kebijakan JavaScript, atau kebijakanAssignMessage. Gunakan variabel pesan mana pun yang berisi nilai yang ingin Anda tetapkan.
Variabel hanya boleh ada 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 endpoint target yang menggunakan HTTPS, Anda harus mempertimbangkan kasus saat masa berlaku sertifikat TLS/SSL berakhir, atau perubahan pada konfigurasi sistem mengharuskan Anda memperbarui sertifikat.
Untuk informasi selengkapnya, lihat Menangani sertifikat yang habis masa berlakunya.
Namun, Anda dapat mengonfigurasi endpoint target secara opsional agar menggunakan referensi 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 Pemroses Pesan.
Misalnya, yang ditampilkan di bawah ini adalah endpoint target 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 "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -d '<ResourceReference name="keystoreref"> <Refers>myTestKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>'
Dengan $TOKEN
ditetapkan ke token akses OAuth 2.0, seperti yang dijelaskan dalam
Mendapatkan token akses OAuth 2.0. Untuk mengetahui informasi tentang opsi curl
yang digunakan dalam contoh ini, lihat
Menggunakan curl. Untuk deskripsi tentang variabel lingkungan yang digunakan, lihat Menetapkan variabel lingkungan untuk permintaan Apigee API.
Referensi tersebut menetapkan nama keystore dan jenisnya.
Gunakan panggilan GET API berikut untuk melihat referensi:
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \ -H "Authorization: Bearer $TOKEN"
Dengan $TOKEN
ditetapkan ke token akses OAuth 2.0, seperti yang dijelaskan dalam
Mendapatkan token akses OAuth 2.0. Untuk mengetahui informasi tentang opsi curl
yang digunakan dalam contoh ini, lihat
Menggunakan curl. Untuk deskripsi tentang variabel lingkungan yang digunakan, lihat Menetapkan variabel lingkungan untuk permintaan Apigee API.
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \ -H "Authorization: Bearer $TOKEN"
Dengan $TOKEN
ditetapkan ke token akses OAuth 2.0, seperti yang dijelaskan dalam
Mendapatkan token akses OAuth 2.0. Untuk mengetahui informasi tentang opsi curl
yang digunakan dalam contoh ini, lihat
Menggunakan curl. Untuk deskripsi tentang variabel lingkungan yang digunakan, lihat Menetapkan variabel lingkungan untuk permintaan Apigee API.
Untuk mengubah referensi nanti agar mengarah ke keystore yang berbeda, dengan memastikan bahwa alias memiliki nama yang sama, gunakan panggilan PUT berikut:
curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \ -X PUT \ -H "Authorization: Bearer $TOKEN" \ -d '<ResourceReference name="keystoreref"> <Refers>myNewKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>'
Dengan $TOKEN
ditetapkan ke token akses OAuth 2.0, seperti yang dijelaskan dalam
Mendapatkan token akses OAuth 2.0. Untuk mengetahui informasi tentang opsi curl
yang digunakan dalam contoh ini, lihat
Menggunakan curl. Untuk deskripsi tentang variabel lingkungan yang digunakan, lihat Menetapkan variabel lingkungan untuk permintaan Apigee API.
TargetEndpoint dengan load balancing target
Endpoint target mendukung load balancing di beberapa server target bernama menggunakan tiga algoritma load balancing.
Untuk mendapatkan petunjuk terperinci, lihat Load balancing di seluruh server backend.
IntegrationEndpoint
IntegrationEndpoint adalah endpoint target yang secara khusus menjalankan integrasi Apigee. Jika Anda telah mengonfigurasi IntegrationEndpoint, Apigee akan mengirimkan objek request ke Platform Integrasi Apigee untuk dieksekusi. Untuk menjalankan integrasi, selain mengonfigurasi IntegrationEndpoint, Anda juga harus menambahkan kebijakan SetIntegrationRequest dalam alur proxy.
Anda dapat mengonfigurasi integrasi untuk dijalankan secara sinkron atau asinkron dengan menetapkan elemen <AsyncExecution>
dalam konfigurasi IntegrationEndpoint. Untuk mengetahui informasi selengkapnya, lihat Eksekusi sinkron vs. Asinkron.
Setelah menjalankan integrasi, Apigee menyimpan respons dalam pesan respons.
Mengonfigurasi IntegrationEndpoint
Untuk mengonfigurasi endpoint integrasi sebagai endpoint target Anda, tambahkan elemen IntegrationEndpoint ke konfigurasi ProxyEndpoint Anda. Berikut adalah contoh konfigurasi ProxyEndpoint:
<ProxyEndpoint name="default"> <Description/> <FaultRules/> <PreFlow name="PreFlow"> <Request> <Step> <Name>my-set-integration-request-policy</Name> </Step> </Request> </PreFlow> <Flows/> <PostFlow name="PostFlow"/> <HTTPProxyConnection> <BasePath>/integration-endpoint-test</BasePath> <Properties/> </HTTPProxyConnection> <RouteRule name="default"> <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint> </RouteRule> </ProxyEndpoint>
Dalam contoh konfigurasi ProxyEndpoint, Apigee melakukan tugas berikut:
- Dalam PreFlow, jalankan kebijakan bernama
my-set-integration-request-policy
, yang menetapkan objek permintaan integrasi dan variabel alur integrasi. - Menggunakan
my-int-endpoint
sebagai endpoint target, seperti yang ditentukan dalamRouteRule
. - Membaca objek permintaan integrasi yang dibuat oleh
my-set-integration-request-policy
. - Mengirim permintaan ke Platform Integrasi Apigee menggunakan objek permintaan dan variabel alur yang ditetapkan oleh kebijakan SetIntegrationRequest.
- Menyimpan respons integrasi dalam pesan respons.
File XML yang berisi deklarasi <IntegrationEndpoint>
akan tersedia di
direktori APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/
. Jika Anda membuat proxy API menggunakan opsi Develop > API Proxies > CREATE NEW > Integration target
, Apigee akan menyimpan deklarasi dalam file /apiproxy/integration-endpoints/default.xml
. Jika
membuat XML endpoint integrasi dari UI, Anda dapat memberikan nama kustom untuk file XML.
Contoh berikut menunjukkan deklarasi elemen <IntegrationEndpoint>
dalam file XML:
<IntegrationEndpoint name="my-int-endpoint"> <AsyncExecution>false</AsyncExecution> </IntegrationEndpoint>
Elemen konfigurasi IntegrationEndpoint
Nama | Deskripsi | Default | Wajib? |
---|---|---|---|
IntegrationEndpoint |
|||
name |
Nama IntegrationEndpoint. Karakter yang dapat Anda gunakan dalam nama dibatasi untuk: A-Za-z0-9._\-$ % |
T/A | Ya |
AsyncExecution |
Nilai Boolean yang menentukan apakah integrasi harus berjalan dalam mode sinkron atau asinkron. Untuk mengetahui informasi selengkapnya, lihat Eksekusi sinkron vs. Asinkron. | false | Tidak |
Eksekusi sinkron vs Asinkron
Anda dapat mengonfigurasi integrasi untuk berjalan dalam mode sinkron atau asinkron. Untuk memahami perbedaan antara mode eksekusi sinkron dan asinkron, lihat <AsyncExecution>.
Gunakan elemen <AsyncExecution>
dalam </IntegrationEndpoint>
untuk menentukan eksekusi sinkron atau asinkron. Jika Anda menetapkan <AsyncExecution>
ke true
, integrasi akan berjalan secara asinkron. Dan jika Anda menetapkannya ke false
, integrasi akan berjalan secara sinkron.
Contoh berikut menetapkan AsyncExecution
ke true
:
<IntegrationEndpoint name="my-int-endpoint"> <AsyncExecution>true</AsyncExecution> </IntegrationEndpoint>
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? |
---|---|---|---|
Policy |
|||
name |
Nama internal kebijakan. Karakter yang dapat Anda gunakan dalam nama dibatasi
untuk: Secara opsional, gunakan elemen |
T/A | Ya |
enabled |
Setel ke Setel ke |
true |
Tidak |
continueOnError |
Setel ke Setel ke |
false |
Tidak |
async |
Jika ditetapkan ke Untuk menggunakan perilaku asinkron dalam 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 merujuk kebijakan yang akan diterapkan sebagai Langkah pemrosesan. Format lampiran kebijakan adalah sebagai berikut:
<Step><Name>MyPolicy</Name></Step>
Kebijakan diberlakukan sesuai urutan penerapannya ke Alur. Contoh:
<Step><Name>FirstPolicy</Name></Step> <Step><Name>SecondPolicy</Name></Step>
Elemen konfigurasi lampiran kebijakan
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 suatu kebijakan memiliki kondisi terkait, kebijakan hanya akan 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 conditional atau conditional opsional, dan sebuah PostFlow.
- PreFlow: Selalu dijalankan. Dieksekusi sebelum Flow kondisional.
- PostFlow: Selalu dijalankan. Dijalankan setelah Flow kondisional.
Selain itu, Anda dapat menambahkan PostClientFlow ke endpoint proxy, yang dieksekusi setelah respons ditampilkan ke aplikasi klien yang meminta. Hanya kebijakan MessageLogging yang dapat dilampirkan 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 awal dan akhir untuk pesan respons.
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:
- PraAlur Permintaan Proxy
- Alur Bersyarat Permintaan Proxy (Opsional)
- Pasca-Alur Permintaan Proxy
- Pra-Alur Permintaan Target
- Alur Bersyarat Permintaan Target (Opsional)
- Pasca-Alur Permintaan Target
Pipeline Respons:
- PraAlur Respons Target
- Flow Bersyarat Respons Target (Opsional)
- Pasca-Alur Respons Target
- PraAlur Respons Proxy
- Alur Bersyarat Respons Proxy (Opsional)
- Alur Pasca-Respons Proxy
- Respons PostClientFlow (Opsional)
Hanya Flow 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, 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
Endpoint proxy dan endpoint target mendukung alur bersyarat dalam jumlah yang tidak terbatas (juga dikenal sebagai alur bernama).
Proxy API menguji kondisi yang ditetapkan dalam alur kondisional dan, jika kondisi ini terpenuhi, langkah-langkah pemrosesan dalam alur kondisional akan dijalankan oleh proxy API. Jika kondisinya 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, alur kondisional berikut menentukan bahwa alur tersebut dijalankan hanya ketika
jalur resource permintaan adalah /accesstoken
. Setiap permintaan masuk dengan
jalur /accesstoken
menyebabkan alur ini dijalankan, bersama dengan kebijakan
yang terpasang pada alur. 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 flow
Nama | Deskripsi | Default | Wajib? |
---|---|---|---|
Flow |
Pipeline pemrosesan permintaan atau respons yang ditentukan oleh endpoint proxy atau endpoint target | ||
Name |
Nama unik Alur. | T/A | Ya |
Condition |
Pernyataan kondisional yang mengevaluasi pada atau beberapa variabel untuk dievaluasi ke benar (true) atau salah (false). Semua Flow selain jenis PreFlow dan PostFlow yang telah ditentukan 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 Flow kondisional diterapkan oleh Apigee. Flow Bersyarat
dijalankan dari atas ke bawah. Flow kondisional pertama yang kondisinya bernilai
true
akan dijalankan, dan hanya satu Flow kondisional yang dijalankan.
Misalnya, dalam konfigurasi Flow berikut, setiap permintaan masuk yang tidak menyertakan
akhiran jalur /first
atau /second
akan menyebabkan ThirdFlow
dijalankan, 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 ditambahkan ke Flow menggunakan kebijakan. Skrip ini muncul di bagian Skrip pada editor proxy API di UI Apigee.
Lihat Mengelola resource untuk jenis resource yang didukung.
Resource dapat disimpan di proxy API, lingkungan, atau organisasi. Dalam setiap kasus, resource dirujuk oleh nama dalam Policy. Apigee me-resolve nama ini dengan berpindah dari proxy API, ke lingkungan, ke level organisasi.
Resource yang disimpan di tingkat organisasi dapat dirujuk oleh Kebijakan di lingkungan apa pun. Resource yang disimpan di tingkat lingkungan dapat dirujuk oleh Kebijakan di lingkungan tersebut. Resource yang disimpan di level proxy API hanya dapat dirujuk oleh Kebijakan dalam proxy API tersebut.