Mengontrol cara proxy dijalankan dengan flow

Anda melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Setiap model pemrograman aplikasi mencakup cara untuk mengontrol alur pemrosesan. Di proxy API, hal ini dilakukan dengan alur. Anda menambahkan logika, pernyataan kondisi, penanganan error, dan sebagainya ke alur. Anda menggunakan alur untuk mengontrol apa yang terjadi, dan kapan.

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 alur.

Contoh konfigurasi alur berikut menentukan alur tempat kebijakan VerifyAPIKey dieksekusi jika jalur permintaan masuk berakhir 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 logika dapat dieksekusi dalam urutan yang tepat di sepanjang jalur pemrosesan.

Saat memutuskan tempat untuk menambahkan logika, Anda akan 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 alur, seperti yang dijelaskan di sini:

Jenis endpoint Deskripsi Alur 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 kepada klien. PreFlow, alur kondisional, PostFlow, PostClientFlow
TargetEndpoint Berisi alur proxy API yang paling dekat dengan resource backend. Menyediakan tempat bagi logika untuk 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 alur diurutkan secara berurutan dalam endpoint proxy dan endpoint target:

Permintaan dari klien HTTP yang melewati Endpoint Proxy ke Endpoint Target di backend untuk menjangkau layanan HTTP. Setiap panel permintaan dan respons menampilkan alur awal, alur bersyarat, dan alur akhir. Selain itu, contoh endpoint proxy dan endpoint target juga diberikan.

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 Kondisional

Tempat untuk logika kondisional. Dieksekusi setelah PreFlow dan sebelum the PostFlow.

Hanya satu alur kondisional yang dieksekusi per segmen--alur pertama yang kondisinya bernilai benar. Artinya, Anda dapat menjalankan satu alur kondisional 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 (hanya alur proxy) Alur untuk mencatat pesan setelah respons ditampilkan ke klien.

Membuat kode dieksekusi 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, tempatnya mulai bersiap mengirim permintaan ke target backend, PreFlow cocok untuk langkah pertama dalam bersiap mengirim permintaan.

Misalnya, Anda biasanya tidak ingin melayani klien yang telah melebihi 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 dieksekusi sebelum pemrosesan lainnya terjadi.

Dalam 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>

Membuat kode dieksekusi secara kondisional dengan alur kondisional

Antara PreFlow dan PostFlow, Anda dapat memiliki alur yang dieksekusi secara kondisional. Hal ini memberi Anda peluang untuk mengonfigurasi beberapa urutan logika, tetapi hanya satu yang dieksekusi 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 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.

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 dieksekusi setelah alur kondisional dan PreFlow.

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

Dalam contoh berikut, kebijakan AssignMessage yang disebut SetResponseHeaders menetapkan header pesan respons sebelum Apigee Edge 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 dapat mencakup kebijakan berikut:

* Kebijakan FlowCallout hanya dapat memanggil alur bersama yang memenuhi kriteria untuk berada di PostClientFlow (yaitu, hanya berisi kebijakan yang kompatibel).

Jika Anda menyertakan satu, PostClientFlow akan menjadi alur terakhir yang dieksekusi, yang dieksekusi setelah a 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.

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

Video: Tonton video pendek ini yang menunjukkan cara membuat PostClientFlow menggunakan kebijakan MessageLogging dari seri Four Minute Video For Developers (4MV4D).

Untuk informasi selengkapnya, lihat:

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, lalu Flow, lalu PostFlow, seperti yang dijelaskan dalam topik ini), konten alur dieksekusi dalam urutan.

Contoh konfigurasi alur berikut mereferensikan tiga kebijakan (dikonfigurasi di tempat lain di file XML-nya sendiri). Kebijakan yang direferensikan oleh Verify-API-Key dieksekusi sebelum kebijakan yang direferensikan oleh Remove-API-Key; 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>Remove-API-Key</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Konsol Apigee Edge menampilkan urutan kebijakan ini sebagai baris ikon dengan setiap ikon mewakili kebijakan.

Konsol Apigee Edge menampilkan urutan kebijakan ini sebagai baris ikon yang setiap ikonnya merepresentasikan kebijakan. Ikon yang ditampilkan di jalur permintaan mencakup: Verifikasi kunci API, Hapus kunci API, dan Kuota

Proses debug alur

Alat Trace Apigee Edge menyediakan cara grafis untuk melihat cara logika dalam proxy API Anda dieksekusi setelah permintaan. Alat ini mengilustrasikan pemrosesan antara permintaan dan respons. Alat ini tidak secara khusus mengilustrasikan pemisahan antara PreFlow, alur kondisional, dan PostFlow.

Untuk mengetahui informasi selengkapnya tentang pelacakan proxy, lihat Menggunakan alat Trace.

Menangani error dalam alur

Anda dapat memunculkan error dari berbagai tempat di proxy API, termasuk dari alur.

Contoh berikut adalah stanza respons dari PreFlow di endpoint target -- dengan kata lain, kode yang dieksekusi segera setelah menerima respons dari target backend. Dalam contoh ini, 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.