Mengontrol proxy API dengan flow

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Flow adalah elemen penyusun dasar proxy API. Flow memungkinkan Anda memprogram perilaku API dengan memungkinkan Anda mengonfigurasi urutan eksekusi kebijakan dan kode oleh proxy API.

Flow adalah tahapan 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 akan menambahkan kondisi ke flow.

Contoh konfigurasi alur berikut menentukan alur tempat kebijakan VerifyAPIKey dijalankan if 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> flow 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 agar logika dapat dieksekusi dalam urutan yang benar di sepanjang jalur pemrosesan.

Catatan: Lihat Membangun proxy API pertama Anda untuk tutorial sederhana tentang cara membuat flow. Untuk mengetahui detail-detail terkait konfigurasi flow, lihat Mengonfigurasi flow.

Saat memutuskan tempat untuk menambahkan logika, pertama-tama Anda harus memilih 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 flow, seperti yang dijelaskan di sini:

Jenis endpoint	Deskripsi	Flow yang didukung
ProxyEndpoint	Berisi alur proxy API yang terdekat dengan klien. Menyediakan tempat bagi logika untuk bertindak terlebih dahulu atas permintaan dari klien, lalu terakhir pada respons terhadap klien.	PreFlow, alur bersyarat, PostFlow, PostClientFlow
TargetEndpoint	Berisi alur proxy API yang terdekat dengan resource backend. Menyediakan tempat logika untuk menyiapkan permintaan, lalu menangani respons dari, resource backend.	PreFlow, flow kondisional, PostFlow

Anda mengonfigurasi alur dengan XML yang menentukan apa yang harus terjadi dan urutannya. Ilustrasi berikut menunjukkan bagaimana alur diurutkan secara berurutan dalam endpoint proxy dan endpoint target:

Endpoint proxy dan endpoint target masing-masing berisi alur yang dapat Anda atur sesuai urutan berikut:

Posisi	Jenis alur	Deskripsi
1	PreFlow	Berguna jika Anda perlu memastikan bahwa kode tertentu dieksekusi sebelum hal lain terjadi. Jika PreFlow berada di endpoint target, PreFlow akan dijalankan setelah PostFlow endpoint proxy.
2	Alur Bersyarat	Tempat untuk logika bersyarat. Dijalankan setelah PreFlow dan sebelum PostFlow. Hanya satu alur bersyarat yang dijalankan per segmen--alur pertama yang kondisinya bernilai 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 ada sesuatu yang terjadi saat memproses permintaan, dan sebagainya. Mengeksekusi setelah flow bersyarat dan PreFlow. Jika PostFlow berada di endpoint proxy, dan ada endpoint target, endpoint proxy PostFlow akan dijalankan sebelum PreFlow endpoint target.
4	PostClientFlow (hanya alur proxy)	Alur untuk mencatat pesan setelah respons ditampilkan ke klien.

Meminta kode dijalankan terlebih dahulu dengan PreFlow

PreFlow berguna jika 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 PreFlow mulai bersiap untuk mengirim permintaan ke target backend, PreFlow cocok 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 demikian, Anda tidak perlu khawatir tentang kondisi yang gagal dievaluasi dalam alur kondisional berikutnya. Kebijakan dalam alur ini akan selalu dijalankan sebelum pemrosesan lainnya dilakukan.

Dalam contoh berikut, kebijakan SpikeArrest dan Quota dieksekusi sebelum pemrosesan diteruskan ke flow kondisional.

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

Meminta kode agar dieksekusi secara bersyarat dengan flow kondisional

Di antara PreFlow dan PostFlow, Anda dapat memiliki alur yang dieksekusi secara bersyarat. Dengan ini, Anda berkesempatan 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. Eksekusi ini secara efektif bercabang berdasarkan kondisi. Misalnya, Anda mungkin ingin mengonversi XML ke JSON hanya saat aplikasi yang meminta sedang berjalan di perangkat seluler.

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

Di sini, batasan kuota diterapkan hanya jika permintaan adalah permintaan GET dengan pola URI /issue/** (/issue/ dengan apa pun dalam 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 dapat menggunakan variabel alur untuk menentukan kondisi. Untuk informasi selengkapnya tentang cara menggunakan variabel dalam kondisi, lihat Kondisi dengan variabel alur.

Untuk contoh penggunaan pencocokan pola dalam kondisi, lihat Pencocokan pola.

Membuat kode dijalankan 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 flow bersyarat dan PreFlow.

PostFlow adalah tempat yang baik untuk mencatat log beberapa data, mengirim notifikasi bahwa sesuatu telah terjadi, mengubah format pesan respons, dan sebagainya.

Dalam contoh berikut, kebijakanAssignMessage yang disebut SetResponseHeaders menetapkan header pesan respons sebelum Apigee mengirimkan respons kembali ke klien.

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

Meminta kode dieksekusi setelah klien menerima respons proxy dengan PostClientFlow

PostClientFlow hanya dapat menyertakan kebijakan berikut. Tidak ada kebijakan lain yang dapat digunakan di PostClientFlow:

• Kebijakan FlowCallout^*
• Kebijakan MessageLogging
• Kebijakan InfoService

^* 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 untuk dijalankan, yang dieksekusi setelah respons dikirim ke klien.

PostClientFlow bagus untuk pencatatan akhir. Selain itu, Anda juga bisa mencatat stempel waktu mulai dan berakhir 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 informasi selengkapnya, lihat Referensi konfigurasi proxy API.

Menambahkan logika ke flow

Saat menambahkan logika ke proxy, Anda melakukannya dengan menambahkan kebijakan ke alur proxy. Sama seperti flow dieksekusi secara berurutan (PreFlow lalu Flow kemudian PostFlow, seperti yang dijelaskan dalam topik ini), konten flow dieksekusi secara berurutan.

Catatan: Untuk informasi selengkapnya tentang kebijakan, termasuk cara menambahkannya dengan konsol dan dalam kode, lihat Apa yang dimaksud dengan kebijakan? Untuk mengetahui detail tentang cara melampirkan kebijakan ke flow, lihat Flow kondisional.

Contoh konfigurasi alur berikut merujuk pada 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 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 cukup menggunakan kondisi kata kerja:

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

Alur proses debug

Alat debug menyediakan cara grafis untuk melihat bagaimana logika di proxy API Anda dijalankan setelah permintaan. Alat ini menggambarkan pemrosesan antara permintaan dan respons. Diagram ini tidak secara khusus menggambarkan pemisahan antara PreFlow, alur bersyarat, dan PostFlow.

Untuk informasi selengkapnya tentang proses debug proxy, lihat Menggunakan alat Debug.

Menangani error dalam flow

Anda dapat melaporkan kesalahan dari berbagai tempat dalam proxy API, termasuk dari flow.

Contoh berikut adalah stanza respons dari PreFlow di endpoint target—dengan kata lain, ini adalah kode yang dieksekusi langsung setelah menerima respons dari target backend. Dalam contoh ini, kesalahan dimunculkan 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 informasi selengkapnya tentang penanganan error, lihat Menangani kesalahan.