Mengontrol cara proxy dijalankan dengan flow

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

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

Flow adalah tahapan berurutan di sepanjang jalur pemrosesan permintaan API. Saat menambahkan logika proxy, misalnya untuk memverifikasi kunci API, Anda harus menambahkan logika sebagai langkah dalam urutan yang ditentukan oleh alur. Saat menentukan kondisi untuk menentukan apakah dan kapan logika dieksekusi, tambahkan 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 flow sehingga Anda dapat menjalankan logika dalam urutan yang benar di sepanjang jalur pemrosesan.

Saat memutuskan tempat untuk menambahkan logika, pertama-tama Anda perlu 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 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 terhadap klien. PraFlow, alur bersyarat, 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. {i>PreFlow<i}, {i>conditional flow<i} (alur bersyarat), PostFlow

Anda mengonfigurasi alur dengan XML yang menentukan apa yang harus terjadi dan bagaimana urutannya. Ilustrasi berikut menunjukkan bagaimana 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 preflow, flow kondisional, dan post flow. Selain itu, contoh titik akhir proxy dan titik akhir target disediakan.

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. Dieksekusi setelah PreFlow dan sebelum PostFlow.

Hanya satu alur bersyarat yang dijalankan per segmen--alur pertama yang kondisinya bernilai benar (true). Artinya, Anda dapat menjalankan satu flow 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 ke dalam log, mengirim notifikasi bahwa terjadi sesuatu saat memproses permintaan, dan sebagainya. Dieksekusi setelah flow bersyarat dan PreFlow.

Jika PostFlow berada di endpoint proxy, dan ada endpoint target, endpoint proxy PostFlow dijalankan sebelum PreFlow endpoint target.

4 PostClientFlow (hanya alur proxy) Alur untuk mencatat pesan setelah respons ditampilkan ke klien.

Meminta eksekusi kode terlebih dahulu dengan PreFlow

PreFlow berguna ketika 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. Pada endpoint target, yaitu ketika ia mulai bersiap mengirim permintaan ke target backend, PreFlow cocok untuk langkah pertama dalam mempersiapkan pengiriman permintaan.

Misalnya, Anda biasanya tidak ingin melayani klien yang telah melebihi kuotanya. Untuk mendukung persyaratan ini, Anda menetapkan kebijakan keamanan dan kuota di segmen PreFlow. Dengan demikian, Anda tidak perlu khawatir akan kondisi yang gagal dievaluasi dalam alur kondisional berikutnya. Kebijakan dalam alur ini akan selalu dieksekusi sebelum pemrosesan lainnya dilakukan.

Pada 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 eksekusi kode secara bersyarat dengan alur bersyarat

Antara PraFlow dan PostFlow, Anda dapat memiliki alur yang dieksekusi secara bersyarat. Dengan demikian, Anda memiliki kesempatan untuk mengonfigurasi beberapa urutan logika, tetapi hanya satu eksekusi berdasarkan status proxy Anda. Alur bersyarat bersifat opsional jika Anda dapat menjalankan semua logika dalam 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 berbagai nilai status. Langkah ini secara efektif membuat cabang eksekusi berdasarkan kondisi. Misalnya, Anda mungkin ingin mengonversi XML ke JSON hanya ketika aplikasi permintaan berjalan di perangkat seluler.

Di sini, batasan kuota hanya diberlakukan jika permintaannya 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 menetapkan kondisi. Untuk informasi selengkapnya tentang penggunaan variabel dalam kondisi, lihat Kondisi dengan variabel alur.

Untuk mengetahui 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 flow bersyarat dan PreFlow.

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

Pada contoh berikut, kebijakan Tetapkan Pesan yang disebut SetResponseHeaders menetapkan header pesan respons sebelum Apigee Edge mengirimkan respons kembali ke klien.

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

Meminta eksekusi kode setelah klien menerima respons proxy Anda dengan PostClientFlow

PostClientFlow dapat menyertakan kebijakan berikut:

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

PostClientFlow cocok untuk logging akhir. Selain itu, Anda dapat mencatat stempel waktu awal dan akhir untuk pesan respons.

Berikut adalah contoh PostClientFlow dengan kebijakan MessageLogging yang terlampir.

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

Video: Tonton video singkat ini yang menunjukkan cara membuat PostClientFlow menggunakan kebijakan MessageLogging dari seri Video Empat Menit untuk Developer (4MV4D).

Untuk informasi selengkapnya, lihat:

Menambahkan logika ke flow

Saat menambahkan logika ke proxy, Anda melakukannya dengan menambahkan kebijakan ke alur proxy. Sama seperti flow yang dijalankan secara berurutan (PreFlow lalu Flow lalu PostFlow, seperti yang dijelaskan dalam topik ini), konten flow 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 dijalankan sebelum kebijakan yang dirujuk 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 menyajikan urutan kebijakan ini sebagai deretan ikon dengan setiap ikon merepresentasikan kebijakan.

Konsol Apigee Edge menyajikan urutan kebijakan ini sebagai baris ikon dengan setiap ikon merepresentasikan kebijakan. Ikon yang ditampilkan di jalur permintaan meliputi: Verify API key, Remove API key, dan Quota

Men-debug alur

Alat Apigee Edge Trace menyediakan cara grafis untuk melihat bagaimana logika di proxy API Anda dijalankan mengikuti permintaan. Alat ini menggambarkan pemrosesan antara permintaan dan respons. DA ini tidak secara khusus menggambarkan pemisahan antara PreFlow, flow kondisional, dan PostFlow.

Untuk informasi selengkapnya tentang melacak proxy, lihat Menggunakan alat Trace.

Menangani error dalam alur

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

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