Halaman ini berlaku untuk Apigee dan Apigee hybrid.
Lihat dokumentasi
Apigee Edge.
Alur adalah elemen penyusun dasar proxy API. Alur memungkinkan Anda memprogram perilaku API dengan mengonfigurasi urutan eksekusi kebijakan dan kode oleh proxy API.
Alur adalah tahap berurutan di sepanjang jalur pemrosesan permintaan API. Saat menambahkan logika proxy, seperti untuk memverifikasi kunci API, Anda menambahkan logika sebagai langkah dalam urutan yang ditentukan oleh alur. Saat menentukan kondisi untuk menentukan apakah dan kapan logika dieksekusi, Anda menambahkan kondisi ke flow.
Contoh konfigurasi alur berikut menentukan alur tempat kebijakan VerifyAPIKey
dijalankan if jalur permintaan yang masuk diakhiri dengan / dan kata kerja HTTP
permintaan adalah GET.
<Flow name="Get Food Carts">
<Description>Get Food Carts</Description>
<Request>
<Step>
<Name>Verify-API-Key</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>Nilai Verify-API-Key dalam elemen <Name> alur berfungsi untuk menyertakan kebijakan yang dikonfigurasi di tempat lain dalam proxy dengan XML seperti berikut:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
<DisplayName>Verify API Key</DisplayName>
<Properties/>
<APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>Mendesain urutan eksekusi alur
Anda menyusun alur sehingga dapat menjalankan logika dalam urutan yang benar di sepanjang jalur pemrosesan.
Saat memutuskan tempat untuk menambahkan logika, Anda harus memilih terlebih dahulu apakah akan menambahkannya ke endpoint proxy atau endpoint target. Proxy API membagi kodenya antara kode yang berinteraksi dengan klien proxy (endpoint proxy) dan kode opsional yang berinteraksi dengan target backend proxy, jika ada (endpoint target).
Kedua endpoint berisi alur, seperti yang dijelaskan di sini:
| Jenis endpoint | Deskripsi | Flow yang didukung |
|---|---|---|
| ProxyEndpoint | Berisi alur proxy API yang paling dekat dengan klien. Memberikan tempat bagi logika untuk bertindak terlebih dahulu pada permintaan dari klien, lalu terakhir pada respons kepada klien. | PreFlow, alur kondisional, PostFlow, PostClientFlow |
| TargetEndpoint | Berisi alur proxy API yang paling dekat dengan resource backend. Menyediakan tempat untuk logika guna menyiapkan permintaan, lalu menangani respons dari resource backend. | PreFlow, alur kondisional, PostFlow |
Anda mengonfigurasi alur dengan XML yang menentukan apa yang harus terjadi dan dalam urutan apa. Ilustrasi berikut menunjukkan cara urutan alur secara berurutan dalam endpoint proxy dan endpoint target:
Endpoint proxy dan endpoint target masing-masing berisi alur yang dapat Anda atur dalam urutan berikut:
| Posisi | Jenis alur | Deskripsi |
|---|---|---|
| 1 | PreFlow |
Berguna saat Anda perlu memastikan bahwa kode tertentu dijalankan sebelum hal lain terjadi. Jika berada di endpoint target, PreFlow akan dieksekusi setelah PostFlow endpoint proxy. |
| 2 | Alur Bersyarat |
Tempat untuk logika kondisional. Dieksekusi setelah PreFlow dan sebelum PostFlow. Hanya satu alur kondisional yang dieksekusi per segmen, yaitu alur pertama yang kondisinya dievaluasi sebagai benar. Artinya, Anda dapat memiliki satu alur bersyarat yang dijalankan sebagai bagian dari setiap:
|
| 3 | PostFlow |
Tempat yang tepat untuk mencatat data, mengirim notifikasi bahwa terjadi sesuatu saat memproses permintaan, dan sebagainya. Dieksekusi setelah alur kondisional dan PreFlow. Jika PostFlow berada di endpoint proxy, dan ada endpoint target, PostFlow endpoint proxy akan dijalankan sebelum PreFlow endpoint target. |
| 4 | PostClientFlow (khusus alur proxy) | Alur untuk mencatat pesan ke dalam log setelah respons ditampilkan ke klien. |
Menjalankan kode terlebih dahulu dengan PreFlow
PreFlow berguna saat Anda perlu memastikan bahwa kode tertentu dieksekusi sebelum hal lain terjadi.
Di endpoint proxy, PreFlow adalah tempat yang tepat untuk kode yang mengautentikasi klien dan membatasi traffic dari klien. Di endpoint target, tempat endpoint mulai bersiap untuk mengirim permintaan ke target backend, PreFlow bagus untuk langkah pertama dalam mempersiapkan pengiriman permintaan.
Misalnya, Anda biasanya tidak ingin melayani klien yang telah melampaui kuotanya. Untuk mendukung persyaratan ini, Anda menempatkan kebijakan keamanan dan kuota di segmen PreFlow. Dengan begitu, Anda tidak perlu khawatir jika kondisi gagal dievaluasi dalam alur kondisional berikutnya. Kebijakan dalam alur ini akan selalu dijalankan sebelum pemrosesan lainnya dilakukan.
Pada contoh berikut, kebijakan SpikeArrest dan Kuota dieksekusi sebelum pemrosesan diteruskan ke alur kondisional.
<PreFlow name="MyPreFlow">
<Request>
<Step>
<Name>Spike-Arrest</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
</PreFlow>Memiliki kode yang dieksekusi secara kondisional dengan alur kondisional
Antara PreFlow dan PostFlow, Anda dapat memiliki alur yang dieksekusi secara kondisional. Hal ini memberi Anda kesempatan untuk mengonfigurasi beberapa urutan logika, tetapi hanya memiliki satu eksekusi berdasarkan status proxy Anda. Alur bersyarat bersifat opsional jika Anda dapat menjalankan semua logika di PreFlow atau PostFlow dan tidak ada kondisi yang diperlukan (dengan kata lain, hanya satu jalur melalui endpoint yang didukung).
Setiap alur menentukan kondisi yang menguji nilai status yang berbeda. Hal ini secara efektif membuat cabang eksekusi berdasarkan kondisi. Misalnya, Anda mungkin ingin mengonversi XML ke JSON hanya saat aplikasi yang meminta berjalan di perangkat seluler.
Di sini, batasan kuota hanya diterapkan jika permintaan adalah permintaan GET dengan pola URI /issue/** (/issue/ dengan apa pun di URI setelah garis miring depan terakhir).
<Flow name="MyFlow">
<Description/>
<Request>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
<Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>Anda menggunakan variabel alur untuk menentukan kondisi. Untuk mengetahui informasi selengkapnya tentang penggunaan variabel dalam kondisi, lihat Kondisi dengan variabel alur.
Untuk contoh penggunaan pencocokan pola dalam kondisi, lihat Pencocokan pola.
Mengeksekusi kode setelah logika inti dengan PostFlow
PostFlow adalah tempat yang tepat untuk melakukan tindakan setelah logika inti endpoint, dan sebelum pemrosesan endpoint selesai. PostFlow dieksekusi setelah alur kondisional dan PreFlow.
PostFlow adalah tempat yang tepat untuk mencatat beberapa data, mengirim notifikasi bahwa sesuatu telah terjadi, mengubah format pesan respons, dan sebagainya.
Dalam contoh berikut, kebijakan AssignMessage yang disebut SetResponseHeaders menetapkan header pesan respons sebelum Apigee mengirim respons kembali ke klien.
<PostFlow>
<Response>
<Step>
<Name>SetResponseHeaders</Name>
</Step>
</Response>
</PostFlow>Menjalankan kode setelah klien menerima respons proxy Anda dengan PostClientFlow
PostClientFlow hanya dapat menyertakan kebijakan berikut. Tidak ada kebijakan lain yang dapat digunakan di PostClientFlow:
* Kebijakan FlowCallout hanya dapat memanggil alur bersama yang memenuhi kriteria untuk berada di PostClientFlow (yaitu, hanya berisi kebijakan yang kompatibel).
Jika Anda menyertakannya, PostClientFlow akan menjadi alur terakhir yang dieksekusi, yang dieksekusi setelah respons dikirim ke klien.
PostClientFlow bagus untuk logging akhir. Selain itu, Anda dapat mencatat stempel waktu awal dan akhir untuk pesan respons.
Berikut adalah contoh PostClientFlow dengan kebijakan MessageLogging yang dilampirkan.
<ProxyEndpoint name="endpoint1">
...
<PostFlow name="PostFlow">
<Request/>
<Response/>
</PostFlow>
<PostClientFlow>
<Response>
<Step>
<Name>Message-Logging-1</Name>
</Step>
</Response>
</PostClientFlow>
...
</ProxyEndpoint>
Untuk informasi selengkapnya, lihat referensi konfigurasi proxy API.
Menambahkan logika ke alur
Saat menambahkan logika ke proxy, Anda melakukannya dengan menambahkan kebijakan ke alur proxy. Sama seperti alur yang dieksekusi secara berurutan (PreFlow, lalu Flow, lalu PostFlow, seperti yang dijelaskan dalam topik ini), konten alur juga dieksekusi secara berurutan.
Contoh konfigurasi alur berikut mereferensikan tiga kebijakan (dikonfigurasi di tempat lain dalam file XML-nya sendiri). Kebijakan yang dirujuk oleh Verify-API-Key dieksekusi sebelum
kebijakan yang dirujuk oleh Assign-Message; keduanya diikuti oleh kebijakan yang direpresentasikan oleh
Quota.
<Flow name="Get Food Cart Menus">
<Description>Get Food Cart Menus</Description>
<Request>
<Step>
<Name>Verify-API-Key</Name>
</Step>
<Step>
<Name>Assign-Message</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>Men-debug flow
Alat debug menyediakan cara grafis untuk melihat cara logika di proxy API Anda dieksekusi setelah permintaan. Alat ini mengilustrasikan pemrosesan antara permintaan dan respons. Diagram ini tidak secara khusus menggambarkan pemisahan antara PreFlow, alur kondisional, dan PostFlow.
Untuk mengetahui informasi selengkapnya tentang proses debug proxy, lihat Menggunakan alat Debug.
Menangani error dalam alur
Anda dapat melaporkan error dari berbagai tempat di proxy API, termasuk dari alur.
Contoh berikut adalah stanza respons dari PreFlow di endpoint target—dengan kata lain, ini adalah kode yang langsung dieksekusi setelah menerima respons dari target backend.
Dalam contoh, error akan muncul jika respons dari target bukan 200 (berhasil).
<PreFlow name="PreFlow">
<Response>
<Step>
<Name>RaiseFault</Name>
<Condition>(response.status.code GreaterThan "200")</Condition>
</Step>
</Response>
</PreFlow>Untuk mengetahui informasi selengkapnya tentang penanganan error, lihat Menangani error.