Mengontrol proxy API dengan flow

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Flow adalah elemen penyusun dasar proxy API. Flow memungkinkan Anda memprogram perilaku dengan memungkinkan Anda mengonfigurasi urutan kebijakan dan kode yang dijalankan oleh API {i>proxy<i}.

Flow adalah tahapan berurutan di sepanjang jalur pemrosesan permintaan API. Ketika Anda menambahkan logika proxy, seperti untuk memverifikasi kunci API, Anda menambahkan logika sebagai langkah dalam urutan yang ditentukan oleh flow. Saat Anda menentukan kondisi untuk menetapkan apakah dan kapan logika dieksekusi, Anda menambahkan kondisi tersebut ke sebuah aliran.

Contoh konfigurasi alur berikut menentukan alur tempat kebijakan VerifyAPIKey dijalankan jika jalur permintaan masuk diakhiri dengan / dan permintaan HTTP kata kerjanya 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 ditayangkan 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 flow

Anda membuat struktur flow sehingga Anda dapat menjalankan logika dalam urutan yang benar di sepanjang jalur pemrosesan.

Catatan: Lihat Membangun proxy API pertama Anda untuk perintah tutorial tentang cara membuat alur. Untuk informasi khusus tentang cara mengonfigurasi alur, lihat Mengonfigurasi alur.

Saat menentukan tempat untuk menambahkan logika, pertama-tama Anda harus memilih apakah akan menambahkannya ke endpoint proxy atau endpoint target. Proxy API membagi kodenya di antara kode yang berinteraksi dengan klien (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 didukung
ProxyEndpoint	Berisi alur proxy API yang paling dekat dengan klien. Menyediakan tempat bagi logika untuk bertindak pertama atas permintaan dari klien, kemudian terakhir pada respons ke klien.	{i>PreFlow<i}, alur bersyarat, {i>PostFlow<i}, {i>PostClientFlow<i}
TargetEndpoint	Berisi alur proxy API yang paling dekat dengan resource backend. Menyediakan tempat untuk logika untuk menyiapkan permintaan, lalu menangani respons dari, resource backend.	Aliran Awal, alur bersyarat, PostFlow

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

Endpoint proxy dan endpoint target masing-masing berisi alur yang dapat Anda atur di berikut ini:

Posisi	Jenis alur	Deskripsi
1	PreFlow	Berguna saat Anda perlu memastikan bahwa kode tertentu dijalankan sebelum hal lainnya terjadi. Jika PreFlow berada di endpoint target, fungsi ini akan dijalankan setelah {i>PostFlow<i}.
2	Alur Bersyarat	Tempat untuk logika bersyarat. Dieksekusi setelah PreFlow dan sebelum {i>PostFlow<i}. Hanya satu alur bersyarat yang dijalankan per segmen--alur pertama yang kondisinya akan dievaluasi ke true. Itu berarti Anda dapat memiliki satu alur bersyarat yang dieksekusi sebagai bagian dari masing-masing: Pipeline permintaan ProxyEndpoint Pipeline permintaan TargetEndpoint Pipeline respons ProxyEndpoint Pipeline respons TargetEndpoint
3	PostFlow	Tempat yang baik untuk mencatat data, mengirim notifikasi bahwa sesuatu terjadi saat memproses permintaan, dan sebagainya. Dieksekusi setelah flow bersyarat dan PreFlow. Jika PostFlow berada di endpoint proxy, dan ada endpoint target, PostFlow endpoint dijalankan sebelum PreFlow endpoint target.
4	PostClientFlow (hanya alur proxy)	Alur untuk mencatat pesan setelah respons dikembalikan ke klien.

Meminta kode dieksekusi pertama dengan PreFlow

PreFlow berguna saat Anda perlu memastikan bahwa kode tertentu dieksekusi sebelum hal lainnya terjadi.

Di endpoint proxy, PreFlow adalah tempat yang tepat untuk kode yang mengautentikasi klien dan membatasi lalu lintas data dari klien. Di endpoint target, yang mulai mempersiapkan untuk mengirim permintaan ke target backend, PreFlow bagus untuk langkah pertama dalam mempersiapkan pengiriman permintaan.

Misalnya, Anda biasanya tidak ingin melayani klien yang telah melebihi kuotanya. Kepada mendukung persyaratan ini, Anda menempatkan kebijakan keamanan dan kuota dalam segmen PreFlow. Dengan begitu, Anda tidak perlu khawatir tentang kondisi yang gagal dievaluasi dalam alur kondisional berikutnya. Tujuan kebijakan dalam alur ini akan selalu dijalankan sebelum pemrosesan lainnya berlangsung.

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

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

Memiliki kode dieksekusi secara bersyarat dengan alur bersyarat

Di antara PreFlow dan PostFlow, Anda dapat memiliki alur yang dieksekusi secara bersyarat. Hal ini memberikan Anda memiliki kesempatan untuk mengonfigurasi beberapa urutan logika, tetapi hanya memiliki satu eksekusi berdasarkan status proxy Anda. Alur kondisional bersifat opsional jika Anda dapat mengeksekusi semua logika di PreFlow atau PostFlow dan tidak ada kondisi yang diperlukan (dengan kata lain, hanya satu jalur melalui endpoint didukung).

Setiap alur menetapkan kondisi yang menguji berbagai nilai status. Hal ini secara efektif dan eksekusi cabang berdasarkan kondisi. Misalnya, Anda mungkin ingin mengonversi XML ke JSON saja saat aplikasi yang meminta berjalan di perangkat seluler.

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

Di sini, batasan kuota diterapkan hanya jika permintaannya adalah permintaan GET dengan Pola URI /issue/** (/issue/ dengan apa pun di URI setelah penerusan terakhir garis miring).

<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 informasi lebih lanjut tentang menggunakan variabel dalam kondisi, lihat Kondisi dengan variabel alur.

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

Memiliki kode mengeksekusi 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 beberapa data, mengirim notifikasi bahwa sesuatu telah mengubah format pesan respons, dan seterusnya.

Dalam contoh berikut, kebijakan MenetapkanMessage yang disebut 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 menyertakan kebijakan berikut. Tidak ada kebijakan lain yang dapat digunakan di PostClientFlow:

• Kebijakan FlowInfo^*
• Kebijakan MessageLogging
• Kebijakan ServiceInfo

^* Kebijakan Flowcallout hanya dapat memanggil alur bersama yang dengan sendirinya memenuhi untuk berada di PostClientFlow (yaitu, hanya berisi kebijakan yang kompatibel).

Jika Anda menyertakannya, PostClientFlow akan menjadi alur terakhir untuk dieksekusi, dieksekusi setelah respons dikirim ke metode dengan klien besar.

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 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 alur yang dieksekusi secara berurutan (PreFlow kemudian Flow kemudian PostFlow, seperti yang dijelaskan dalam topik ini), isi alur 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 alur, lihat Alur bersyarat.

Contoh konfigurasi alur berikut merujuk pada tiga kebijakan (dikonfigurasi di tempat lain dalam file XML-nya sendiri). Kebijakan yang direferensikan 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 cukup menggunakan kata kerja kondisi:

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

Men-debug alur

Alat debug menyediakan cara grafis untuk melihat cara logika di proxy API Anda dieksekusi mengikuti permintaan. Alat ini mengilustrasikan pemrosesan antara permintaan dan respons. Ini tidak secara khusus menggambarkan pemisahan antara {i> PreFlow<i}, alur bersyarat, dan {i>PostFlow<i}.

Untuk 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 flow.

Contoh berikut adalah stanza respons dari PreFlow di endpoint target—di bagian kata, ini adalah kode yang dijalankan segera setelah menerima respons dari target backend. Dalam contoh, fault akan 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.