Mengontrol proxy API dengan alur

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Flow adalah elemen penyusun dasar proxy API. Alur memungkinkan Anda memprogram perilaku API dengan mengizinkan Anda mengonfigurasi urutan kebijakan dan kode yang dieksekusi 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 dijalankan, Anda menambahkan kondisi ke flow.

Contoh konfigurasi flow berikut menentukan flow yang kebijakan VerifyAPIKey-nya dijalankan jika jalur permintaan 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 Anda dapat menjalankan logika dalam urutan yang tepat di sepanjang jalur pemrosesan.

Catatan: Lihat Membangun proxy API pertama Anda untuk tutorial sederhana tentang cara membuat alur. Untuk mengetahui secara spesifik cara mengonfigurasi alur, lihat Mengonfigurasi alur.

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. Menyediakan tempat bagi logika untuk bertindak terlebih dahulu pada permintaan dari klien, lalu terakhir pada respons ke klien.	PreFlow, alur bersyarat, PostFlow, PostClientFlow
TargetEndpoint	Berisi alur proxy API yang paling dekat dengan resource backend. Menyediakan tempat untuk logika guna menyiapkan permintaan untuk, lalu menangani respons dari, resource backend.	PreFlow, alur bersyarat, PostFlow

Anda mengonfigurasi alur dengan XML yang menentukan apa yang harus terjadi dan dalam urutan apa. Ilustrasi berikut menunjukkan cara pengurutan 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 dieksekusi sebelum hal lain terjadi. Jika PreFlow 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 bersyarat yang dieksekusi per segmen--alur pertama yang kondisinya dievaluasi sebagai benar. Artinya, Anda dapat menjalankan satu alur bersyarat sebagai bagian dari setiap: Pipeline permintaan ProxyEndpoint Pipeline permintaan TargetEndpoint Pipeline respons ProxyEndpoint Pipeline respons TargetEndpoint
3	PostFlow	Tempat yang tepat untuk mencatat data, mengirim notifikasi bahwa sesuatu terjadi 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 dieksekusi sebelum PreFlow endpoint target.
4	PostClientFlow (khusus alur proxy)	Alur untuk mencatat pesan setelah respons dikembalikan 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 cocok untuk langkah pertama dalam bersiap mengirim 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 kondisi gagal dievaluasi dalam alur kondisional berikutnya. Kebijakan dalam alur ini akan selalu dijalankan sebelum pemrosesan lainnya dilakukan.

Pada contoh berikut, kebijakan SpikeArrest dan Quota dijalankan sebelum pemrosesan diteruskan ke alur bersyarat.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

Membuat kode dieksekusi secara bersyarat dengan alur bersyarat

Di antara PreFlow dan PostFlow, Anda dapat memiliki alur yang dijalankan secara kondisional. Hal ini memberi Anda kesempatan untuk mengonfigurasi beberapa urutan logika, tetapi hanya satu yang dijalankan 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 mencabangkan eksekusi berdasarkan kondisi. Misalnya, Anda mungkin ingin mengonversi XML ke JSON hanya saat aplikasi yang meminta berjalan di perangkat seluler.

Catatan: Dalam alur bersyarat, kondisi dievaluasi dalam permintaan dan respons. Anda tidak dapat memiliki kondisi terpisah untuk permintaan dan respons. Hanya satu alur kondisional yang dijalankan--alur pertama yang kondisinya bernilai benar.

Di sini, batasan kuota hanya diterapkan jika permintaan adalah permintaan GET dengan pola URI /issue/** (/issue/ dengan apa pun di URI setelah garis miring 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.

Membuat kode dieksekusi setelah logika inti dengan PostFlow

PostFlow adalah tempat yang tepat untuk melakukan tindakan setelah logika inti endpoint Anda, dan sebelum pemrosesan endpoint selesai. PostFlow dijalankan setelah alur bersyarat 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 bernama SetResponseHeaders menetapkan header pesan respons sebelum Apigee mengirimkan respons kembali ke klien.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

Membuat kode dieksekusi setelah klien menerima respons proxy Anda dengan PostClientFlow

PostClientFlow hanya dapat mencakup kebijakan berikut. Tidak ada kebijakan lain yang dapat digunakan dalam PostClientFlow:

• Kebijakan FlowCallout^*
• Kebijakan MessageLogging
• Kebijakan ServiceCallout

^* 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 cocok untuk logging akhir. Selain itu, Anda dapat mencatat stempel waktu mulai dan akhir untuk pesan respons.

Berikut adalah contoh PostClientFlow dengan kebijakan MessageLogging terlampir.

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

Untuk mengetahui 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 dalam urutan (PreFlow, Flow, lalu PostFlow, seperti yang dijelaskan dalam topik ini), isi alur dieksekusi dalam urutan.

Catatan: Untuk mengetahui informasi selengkapnya tentang kebijakan, termasuk cara menambahkannya dengan konsol dan dalam kode, lihat Apa itu kebijakan? Untuk mengetahui detail tentang melampirkan kebijakan ke alur, lihat Alur bersyarat.

Konfigurasi alur contoh berikut mereferensikan tiga kebijakan (dikonfigurasi di tempat lain dalam file XML-nya sendiri). Kebijakan yang dirujuk oleh Verify-API-Key dijalankan sebelum kebijakan yang dirujuk oleh Assign-Message; keduanya diikuti oleh kebijakan yang diwakili 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>

Catatan: Dalam kode di atas, kondisi jalur, (proxy.pathsuffix MatchesPath "/"), selalu benar karena "/" selalu cocok. Jadi, Anda dapat menghapusnya dari elemen Condition dan hanya menggunakan kondisi kata kerja:

    <Condition>request.verb = "GET"</Condition>

Proses debug flow

Alat debug menyediakan cara grafis untuk melihat cara logika dalam proxy API Anda dieksekusi setelah permintaan. Alat ini mengilustrasikan pemrosesan antara permintaan dan respons. Kebijakan ini tidak secara khusus menggambarkan pemisahan antara PreFlow, alur bersyarat, dan PostFlow.

Untuk mengetahui informasi selengkapnya tentang men-debug proxy, lihat Menggunakan alat Debug.

Menangani error dalam alur

Anda dapat memunculkan kesalahan 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 dieksekusi segera setelah menerima respons dari target backend. Dalam contoh ini, kesalahan 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 kesalahan.