Halaman ini diterjemahkan oleh Cloud Translation API.

Kondisi dengan variabel flow

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Pernyataan kondisional adalah struktur kontrol umum dalam semua bahasa pemrograman. Seperti bahasa pemrograman, konfigurasi proxy API mendukung pernyataan bersyarat untuk Flows, Policies, Steps, dan RouteRules. Dengan menentukan pernyataan bersyarat, Anda menentukan perilaku dinamis untuk API Anda. Perilaku dinamis ini memungkinkan Anda melakukan hal-hal seperti mengonversi XML menjadi JSON hanya untuk perangkat seluler, atau merutekan ke URL backend berdasarkan jenis konten atau kata kerja HTTP dari pesan permintaan.

Topik ini menunjukkan cara menggunakan kondisi untuk menerapkan fitur pengelolaan API secara dinamis saat runtime, tanpa menulis kode apa pun.

Video

Untuk mempelajari lebih lanjut variabel dan kondisi alur, tonton video berikut:

Mengonfigurasi pernyataan bersyarat

Perilaku bersyarat diterapkan di proxy API menggunakan kombinasi kondisi dan variabel. Pernyataan bersyarat dibuat menggunakan elemen Kondisi. Berikut adalah kondisi kosong:

<Condition></Condition>

Untuk membuat pernyataan bersyarat, tambahkan operator bersyarat dan variabel menggunakan sintaksis berikut:

<Condition>VARIABLE_NAME OPERATOR "VALUE"</Condition>

Contoh:

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

Operator bersyarat yang didukung mencakup = (sama dengan), != (tidak sama dengan), dan > (lebih besar dari). Agar mudah dibaca, Anda juga dapat menulis kondisi sebagai text: equals, notequals, greaterthan.

Saat bekerja dengan jalur URI, Anda dapat menggunakan ~/ atau MatchesPath. Anda juga dapat mencocokkan ekspresi reguler JavaRegex dengan operator ~~.

Catatan: Untuk contoh operator ~~, lihat rangkaian pesan komunitas berikut:

Bagaimana cara mengganti di akhir URL

Kondisi digunakan untuk menentukan alur bersyarat proxy API ke resource API backend, yang dijelaskan dalam Membuat alur bersyarat ke resource API backend. Untuk daftar lengkap kondisi, lihat Referensi kondisi.

Variabel

Kondisi melakukan tugasnya dengan mengevaluasi nilai variabel. Variabel adalah properti transaksi HTTP yang dieksekusi oleh proxy API, atau properti konfigurasi proxy API itu sendiri. Setiap kali proxy API menerima permintaan dari aplikasi, Apigee mengisi daftar panjang variabel yang terkait dengan hal-hal seperti waktu sistem, informasi jaringan aplikasi, header HTTP pada pesan, konfigurasi proxy API, eksekusi kebijakan, dan sebagainya. Tindakan ini akan membuat konteks lengkap yang dapat Anda gunakan untuk menyiapkan pernyataan bersyarat.

Variabel selalu menggunakan notasi titik. Misalnya, header HTTP pada pesan permintaan tersedia sebagai variabel yang disebut request.header.HEADER_NAME. Jadi, untuk mengevaluasi Content-type header, Anda dapat menggunakan variabel request.header.Content-type. Misalnya, request.header.Content-type = "application/json" menunjukkan bahwa jenis konten permintaan harus berupa JSON.

Bayangkan Anda perlu membuat pernyataan bersyarat yang akan menyebabkan kebijakan diterapkan hanya jika pesan permintaan adalah GET. Untuk membuat kondisi yang mengevaluasi kata kerja HTTP dari permintaan, Anda membuat pernyataan bersyarat di bawah. Variabel dalam kondisi ini adalah request.verb. Nilai variabelnya adalah GET. Operatornya adalah =.

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

Anda juga dapat menggunakan:

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

Apigee menggunakan pernyataan tersebut untuk mengevaluasi kondisi. Contoh di atas dievaluasi sebagai benar jika kata kerja HTTP yang terkait dengan permintaan adalah GET. Jika kata kerja HTTP yang terkait dengan permintaan adalah POST, maka pernyataan bernilai salah.

Catatan: Apigee secara otomatis menyimpan semua header HTTP dan parameter kueri sebagai variabel yang dapat diakses menggunakan awalan variabel request.header. dan request.queryparam..

Untuk mengaktifkan perilaku dinamis, Anda dapat melampirkan Kondisi ke Alur, Langkah, dan RouteRule.

Saat melampirkan kondisi ke Alur, Anda membuat Alur bersyarat. Alur bersyarat hanya dieksekusi jika kondisi bernilai benar (true). Anda dapat melampirkan Kebijakan sebanyak yang Anda inginkan ke Alur bersyarat. Alur bersyarat memungkinkan Anda membuat aturan pemrosesan yang sangat khusus untuk pesan permintaan atau respons yang memenuhi kriteria tertentu.

Misalnya, untuk membuat Flow yang hanya dieksekusi saat kata kerja permintaan adalah GET:

<Flows>
  <Flow name="ExecuteForGETs">
  <Condition>request.verb="GET"</Condition>
  </Flow>
</Flows>

Untuk membuat satu Flow untuk permintaan GET dan Flow lainnya untuk permintaan POST:

<Flows>
  <Flow name="ExecuteForGETs">
    <Condition>request.verb="GET"</Condition>
  </Flow>
  <Flow name="ExecuteForPOSTs">
    <Condition>request.verb="POST"</Condition>
  </Flow>
</Flows>

Seperti yang ditunjukkan dalam contoh di bawah, Anda dapat menerapkan kondisi ke Langkah Kebijakan itu sendiri. Kondisi berikut menyebabkan VerifyAPIKey policy diterapkan hanya jika pesan permintaan adalah POST.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Setelah menentukan Alur bersyarat tersebut, Anda dapat melampirkan Kebijakan ke Alur tersebut, sehingga memungkinkan proxy API menerapkan satu set kebijakan untuk permintaan GET, dan set kebijakan lainnya untuk permintaan POST.

Untuk informasi referensi yang komprehensif, lihat referensi berikut:

Contoh 1

Contoh berikut menunjukkan satu alur bersyarat bernama Convert-for-devices, yang dikonfigurasi dalam alur respons ProxyEndpoint. Tambahkan Kondisi sebagai elemen ke entity yang menerapkan kondisi. Dalam contoh ini, kondisi adalah komponen alur. Oleh karena itu, alur akan dieksekusi setiap kali pernyataan dievaluasi menjadi true.

<Flows>
  <Flow name="Convert-for-devices">
  <Condition>(request.header.User-Agent = "Mozilla")</Condition>
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

Untuk setiap permintaan yang diterima dari aplikasi, Apigee menyimpan nilai semua header HTTP yang ada sebagai variabel. Jika permintaan berisi header HTTP yang disebut User-Agent, header tersebut dan nilainya disimpan sebagai variabel yang disebut request.header.User-Agent.

Dengan konfigurasi ProxyEndpoint di atas, Apigee memeriksa nilai variabel request.header.User-Agent untuk melihat apakah kondisi dievaluasi ke benar (true).

Jika kondisi bernilai true, yaitu nilai variabel request.header.User-Agent sama dengan Mozilla, maka Flow bersyarat akan dieksekusi dan kebijakan XMLtoJSON yang disebut ConvertToJSON akan diterapkan. Jika tidak, Flow tidak dijalankan, dan respons XML ditampilkan tanpa diubah (dalam format XML) ke aplikasi yang meminta.

Contoh 2

Mari kita gunakan contoh spesifik saat Anda perlu mengubah pesan respons dari XML ke JSON—tetapi hanya untuk perangkat seluler. Pertama, buat kebijakan yang akan mengonversi respons berformat XML dari Weather API menjadi JSON:

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

Konfigurasi kebijakan di atas memberi tahu proxy API untuk mengambil pesan respons, melakukan konversi dari XML ke JSON dengan setelan default, lalu menulis hasilnya ke pesan respons baru. (Jika Anda mengonversi pesan permintaan dari XML ke JSON, Anda cukup menetapkan kedua nilai ini ke request.)

Karena Anda ingin mengonversi respons dari XML ke JSON, Anda perlu mengonfigurasi Flow respons bersyarat untuk melakukan konversi. Misalnya, untuk mengonversi semua respons dari XML ke JSON sebelum ditampilkan ke aplikasi klien, konfigurasi Flow respons ProxyEndpoint berikut.

<Flows>
  <Flow name="Convert-for-devices">
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

Saat Anda memanggil API menggunakan permintaan standar, respons diformat dalam JSON.

Namun, tujuan Anda adalah hanya mengonversi laporan Cuaca menjadi JSON jika klien yang meminta adalah perangkat seluler. Untuk mengaktifkan perilaku dinamis tersebut, Anda harus menambahkan pernyataan kondisional ke Flow.

Menguji alur bersyarat

Dalam contoh permintaan ini, header HTTP User-Agent disetel ke Mozilla, sehingga pernyataan bersyarat dievaluasi menjadi benar dan alur bersyarat Convert-for-devices dieksekusi.

curl -H "User-Agent:Mozilla" http://example.com/weather/forecastrss?w=12797282

atau, untuk mencetak dengan rapi jika Python tersedia:

curl -H "User-Agent:Mozilla" http://example.com/weather/forecastrss?w=12797282 | python -mjson.tool

Contoh Respons:

. . .

"yweather_forecast": [
   {
      "code": "11",
      "date": "12 Dec 2012",
      "day": "Wed",
      "high": "55",
      "low": "36",
      "text": "Showers"
    },
    {
      "code": "32",
      "date": "13 Dec 2012",
      "day": "Thu",
      "high": "56",
      "low": "38",
      "text": "Sunny"
    }
  ]
}

. . .

Permintaan yang dikirimkan tanpa header User-Agent, atau dengan nilai yang berbeda dari Mozilla, akan menghasilkan respons berformat XML.

$ curl http://example.com/weather/forecastrss?w=12797282

Respons XML yang tidak diubah akan ditampilkan.

Contoh Respons:

<yweather:forecast day="Wed" date="12 Dec 2012" low="36" high="55" text="Showers" code="11" /> <yweather:forecast day="Thu" date="13 Dec 2012" low="38" high="56" text="Sunny" code="32" />

Pencocokan pola

Bagian ini menjelaskan cara menggunakan pencocokan pola dengan kondisi dalam alur Apigee.

Bacaan Lebih Lanjut

Operator

Bagian ini menjelaskan cara menggunakan operator pencocokan pola berikut dalam pernyataan bersyarat:

Operator Matches: Pencocokan pola sederhana
Operator JavaRegex: Kontrol yang lebih baik atas pencocokan
Operator MatchesPath: Pencocokan fragmen jalur

Mencocokkan dengan

Mari kita lihat operator kondisional Matches atau ~ terlebih dahulu. Kedua operator ini sama — versi bahasa Inggris, Matches, dianggap sebagai opsi yang lebih mudah dibaca.

Ringkasan: Operator Matches memberi Anda dua kemungkinan. Mencocokkan string secara harfiah, atau mencocokkan karakter pengganti dengan *. Seperti yang Anda duga, karakter pengganti mencocokkan nol atau beberapa karakter. Mari kita lihat cara kerjanya.

Catatan: Operator Matches tidak cocok dengan ekspresi reguler. Jika Anda ingin menggunakan pencocokan ekspresi reguler, gunakan operator JavaRegex.

XML berikut menunjukkan kondisi Langkah. Kebijakan ini menjalankan kebijakan SomePolicy saat kondisi bernilai benar. Dalam contoh ini, kita menguji variabel proxy.pathsuffix, yaitu variabel bawaan di Apigee yang menyimpan akhiran jalur permintaan. Namun, perhatikan bahwa Anda dapat menguji nilai variabel alur yang berisi string. Jadi, dalam hal ini, jika jalur dasar permintaan masuk adalah /animals, dan permintaannya adalah /animals/cat, maka akhiran jalur adalah string literal /cat.

<PreFlow name="PreFlow">
  <Request>
    <Step>
      <Condition>(proxy.pathsuffix Matches "/cat")</Condition>
      <Name>SomePolicy</Name>
    </Step>
  </Request>
  <Response/>
</PreFlow>

Pertanyaan: Suffix jalur proxy apa yang akan menyebabkan SomePolicy dieksekusi? Hanya ada satu kemungkinan.

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Ya, karena akhiran jalur proxy sama persis dengan /cat. Tidak akan dieksekusi jika akhiran adalah /bat atau /dog atau / atau yang lainnya.

Sekarang, pertimbangkan pernyataan bersyarat ini di mana kita menggunakan karakter pengganti *:

<Condition>(proxy.pathsuffix Matches "/*at")</Condition>

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Ya, karena karakter pengganti cocok dengan karakter apa pun, dan "/cat" adalah kecocokan.

Panggilan API:

GET http://example.com/matchtest/bat

Apakah kebijakan dijalankan? Ya, karena karakter pengganti cocok dengan karakter apa pun, "/bat" adalah kecocokan.

Panggilan API:

GET http://example.com/matchtest/owl

Apakah kebijakan dijalankan? Tentu tidak — meskipun karakter pengganti cocok dengan o, huruf wl tidak cocok.

Sekarang, mari pindahkan karakter pengganti ke akhir sufiks:

<Condition>(proxy.pathsuffix Matches "/cat*")</Condition>

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Ya, karena karakter pengganti cocok dengan nol atau lebih karakter apa pun.

Panggilan API:

GET http://example.com/matchtest/bat

Apakah kebijakan dijalankan? Tidak, /bat tidak cocok.

Panggilan API:

GET http://example.com/matchtest/cat123

Apakah kebijakan dijalankan? Ya, karakter pengganti cocok dengan nol atau lebih karakter apa pun, sehingga 123 menghasilkan kecocokan.

Panggilan API:

GET http://example.com/matchtest/cat/bird/mouse

Apakah kebijakan dijalankan? Ya, karena karakter pengganti cocok dengan nol atau lebih karakter apa pun, jadi /bird/mouse menghasilkan kecocokan. Perhatikan bagaimana ekspresi seperti ini dapat menimbulkan masalah karena cocok dengan semua hal setelah karakter literal.

Pertanyaan: Apakah operator Matches peka huruf besar/kecil?

Ya. Misalkan Anda memiliki kondisi seperti ini:

<Condition>(proxy.pathsuffix Matches "/*At")</Condition>

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Tidak, karakter pengganti cocok dengan huruf apa pun (terlepas dari huruf besar/kecil), tetapi a huruf kecil tidak cocok dengan A.

Panggilan API:

GET http://example.com/matchtest/bAt

Apakah kebijakan dijalankan? Ya, kasusnya cocok.

Pertanyaan: Bagaimana cara menghindari karakter dengan operator Matches?

Gunakan karakter persen % untuk meng-escape karakter khusus. Contoh:

<Condition>(proxy.pathsuffix Matches "/c%*at")</Condition>

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Tidak, operator Matches mencari string literal c*at.

Panggilan API:

GET http://example.com/matchtest/c*at

Pertanyaan:Apakah kebijakan dijalankan?

Ya, jalur ini, meskipun agak tidak biasa, cocok.

JavaRegex

Seperti yang dapat Anda lihat, operator Matches sangat cocok untuk situasi sederhana. Namun, Anda dapat menggunakan operator lain, yaitu operator JavaRegex atau ~~. Keduanya adalah operator yang sama, tetapi JavaRegex dianggap lebih mudah dibaca. JavaRegex disebut demikian karena memungkinkan pencocokan pola ekspresi reguler, dan Apigee mengikuti aturan yang sama dengan class dalam paket java.util.regex dalam bahasa Java. Cara kerja operator JavaRegex sangat berbeda dengan operator Matches, jadi jangan sampai tertukar.

Catatan: Jika Anda terbiasa melakukan Regex dalam skrip Perl, penting untuk dicatat bahwa operator JavaRegex di Apigee menguji seluruh string subjek. Misalnya, jika subjeknya adalah abc dan ekspresi regulernya adalah [a-z] , tidak ada kecocokan karena [a-z] cocok dengan tepat satu karakter alfa. Ekspresi [a-z]+ akan berfungsi, begitu juga dengan [a-z]{3}. Pencocokan ini berbeda dengan penerapan ekspresi reguler yang biasa di alat seperti Perl atau grep atau mod_rewrite Apache. JavaRegex menggunakan java.util.regex.Pattern.matches(str), yang ditentukan untuk menampilkan nilai positif jika seluruh string (str) cocok dengan pola. Ekspresi reguler di Perl atau mod_rewrite diterapkan ke bagian mana pun dari string. Fungsi ini menampilkan nilai benar jika pola cocok di mana saja. Lihat contoh Mencocokkan string arbitrer dengan JavaRegex.

Catatan: Bagian ini tidak dimaksudkan sebagai pengantar mendetail untuk ekspresi reguler. Tujuan utamanya adalah untuk mengilustrasikan beberapa contoh sederhana, dan menyoroti perbedaan antara operator Matches dan JavaRegex. Jika Anda ingin mengetahui ekspresi reguler lebih lanjut, ada banyak referensi yang dapat Anda pelajari.

Ringkasan: Operator JavaRegex memungkinkan Anda menggunakan sintaksis ekspresi reguler dalam pernyataan bersyarat.

Kode berikut menunjukkan kondisi Langkah. Kebijakan SomePolicy akan dijalankan jika kondisi bernilai true. Dalam contoh ini, kita menguji variabel proxy.pathsuffix, variabel bawaan di Apigee yang menyimpan akhiran jalur permintaan. Jika jalur dasar permintaan masuk adalah /animals, dan permintaannya adalah /animals/cat, maka akhiran jalur adalah string literal /cat.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix JavaRegex "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Catatan: Penting untuk diingat bahwa variabel proxy.pathsuffix adalah string yang selalu dimulai dengan karakter garis miring (/), seperti /cat. Oleh karena itu, jika Anda mencocokkan /c*t, Anda mencocokkan seluruh string, termasuk /. / bukan bagian dari konstruksi ekspresi reguler. Jika Anda mencocokkan jenis variabel lain, seperti request.querystring, / tidak diperlukan (kecuali jika parameter kueri kebetulan dimulai dengan /).

Pertanyaan: Suffix jalur proxy apa yang akan menyebabkan SomePolicy dieksekusi? Sama seperti dengan operator Matches, hanya ada satu kemungkinan dalam kasus ini.

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Ya, karena akhiran jalur proxy sama persis dengan /cat. Tindakan ini tidak akan dijalankan jika akhiran adalah /bat atau /dog atau yang lainnya.

Sekarang, mari kita buat ekspresi reguler menggunakan pengukur *. Pengukur ini cocok dengan nol atau lebih karakter sebelumnya.

<Condition>(proxy.pathsuffix JavaRegex "/c*t")</Condition>

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Tidak! Pengukur * cocok dengan nol atau lebih karakter sebelumnya, yaitu c.

Panggilan API:

GET http://example.com/matchtest/ccccct

Apakah kebijakan dijalankan? Ya, karena karakter pengganti cocok dengan nol atau beberapa karakter sebelumnya.

Selanjutnya, kita menggunakan penghitung ?, yang mencocokkan karakter sebelumnya sekali, atau tidak sama sekali.

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Ya. Penghitung ? cocok dengan nol atau satu kemunculan karakter sebelumnya, yaitu a.

Panggilan API:

GET http://example.com/matchtest/ct

Apakah kebijakan dijalankan? Ya. Penghitung ? mencocokkan satu atau tidak ada karakter sebelumnya. Dalam hal ini, tidak ada karakter a, sehingga kondisi bernilai true.

Panggilan API:

GET http://example.com/matchtest/caat

Apakah kebijakan dijalankan? Tidak. Pengukur ? cocok dengan salah satu karakter sebelumnya, yaitu a.

Selanjutnya, kita akan menggunakan gaya ekspresi regex [abc] atau pengelompokan. Pola ini cocok dengan karakter a atau b atau c.

<Condition>(proxy.pathsuffix JavaRegex "/[cbr]at")</Condition>

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Ya. Di sini kita menggunakan ekspresi reguler, dan ekspresi [cbr] cocok dengan c, b, ATAU r. Panggilan ini juga cocok:

GET http://example.com/matchtest/bat

GET http://example.com/matchtest/rat

Namun, ini tidak cocok:

GET http://example.com/matchtest/mat

Pertanyaan: Apakah operator JavaRegex peka huruf besar/kecil?

Ya. Misalkan Anda memiliki kondisi seperti ini:

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

Panggilan API:

GET http://example.com/matchtest/cat

Apakah kebijakan dijalankan? Ya, ekspresi reguler cocok dengan nol atau satu karakter sebelumnya, yaitu a.

Panggilan API:

GET http://example.com/matchtest/cAt

Pertanyaan: Apakah kebijakan dijalankan?

Tidak, karena huruf besar A tidak cocok dengan huruf kecil a.

MatchesPath

Operator MatchesPath juga dapat ditentukan seperti ini ~/. Operator ini sedikit mirip dengan operator Matches (~) dan JavaRegex (~~). Namun, MatchesPath sama sekali berbeda.

Ingat saja bahwa operator ini melihat jalur sebagai serangkaian bagian. Oleh karena itu, jika jalur adalah: /animals/cats/wild, Anda dapat menganggap jalur tersebut terdiri dari bagian /animals, /cats, dan /wild.

Operator MatchesPath memungkinkan Anda menggunakan dua notasi karakter pengganti: satu tanda bintang (*) dan dua tanda bintang (**). Satu tanda bintang cocok dengan satu elemen jalur. Tanda bintang ganda cocok dengan satu atau banyak elemen jalur.

Mari perhatikan contoh berikut. Dalam contoh ini, kita menguji variabel proxy.pathsuffix, variabel bawaan di Apigee yang menyimpan akhiran jalur permintaan. Namun, perhatikan bahwa Anda dapat menguji nilai variabel alur apa pun yang berisi string.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Pertanyaan: Suffix jalur proxy apa yang akan menyebabkan SomePolicy dieksekusi?

Panggilan API:

GET http://example.com/matchtest/animals

Pertanyaan: Apakah kebijakan dijalankan?

Tidak, karena kondisi memerlukan elemen jalur lain setelah /animals, seperti yang ditentukan oleh /*.

Panggilan API:

GET http://example.com/matchtest/animals/

Apakah kebijakan dijalankan? Ya, jalur tersebut memiliki elemen jalur lain (bagian setelah /animals/), tetapi kosong.

Panggilan API:

GET http://example.com/matchtest/animals/cats

Apakah kebijakan dijalankan? Ya, karena jalur tersebut jelas memiliki elemen (/cats) yang muncul setelah /animals

Panggilan API:

GET http://example.com/matchtest/animals/cats/wild

Pertanyaan: Apakah kebijakan dijalankan?

Tidak, karena tanda bintang tunggal hanya cocok dengan satu elemen jalur, dan API ini memiliki lebih dari satu elemen setelah /animals.

Sekarang mari kita gunakan tanda bintang ganda:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Pertanyaan: Suffix jalur proxy apa yang akan menyebabkan SomePolicy dieksekusi?

Panggilan API:

GET http://example.com/matchtest/animals

Apakah kebijakan dijalankan? Tidak, karena kondisi memerlukan setidaknya satu elemen jalur berikutnya yang ditentukan oleh /**.

Panggilan API:

GET http://example.com/matchtest/animals/

Apakah kebijakan dijalankan?

Ya, jalur tersebut memiliki elemen jalur lain (bagian setelah /animals/), tetapi kosong.

Panggilan API:

GET http://example.com/matchtest/animals/cats

Apakah kebijakan dijalankan?

Ya, karena jalur memiliki setidaknya satu elemen yang muncul setelah /animals

Panggilan API:

GET http://example.com/matchtest/animals/cats/wild

Apakah kebijakan dijalankan?

Ya, karena jalur memiliki lebih dari satu elemen yang muncul setelah /animals

Mencampur tanda bintang

Anda dapat menggunakan kombinasi tanda bintang tunggal (*) dan ganda (**) untuk lebih menyempurnakan pencocokan jalur.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*/wild/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Panggilan API:

Semua panggilan API ini akan menghasilkan kecocokan:

GET http://example.com/matchtest/animals/cats/wild/

dan

GET http://example.com/matchtest/animals/dogs/wild/austrailian

dan

GET http://example.com/matchtest/animals/birds/wild/american/finches

Resource API

Layanan RESTful adalah kumpulan resource API. Resource API adalah fragmen jalur URI yang mengidentifikasi beberapa entitas yang dapat diakses developer dengan memanggil API Anda. Misalnya, jika layanan Anda menyediakan laporan cuaca dan prakiraan cuaca, layanan backend Anda dapat menentukan dua resource API:

http://mygreatweatherforecast.com/reports
http://mygreatweatherforecast.com/forecasts

Bacaan Lebih Lanjut

Saat membuat proxy API (seperti yang ditunjukkan dalam Membangun proxy API pertama Anda), minimal Anda membuat URL dasar alias yang dipetakan ke layanan backend Anda. Contoh:

URL dasar backend	URL proxy API baru/setara
`http://mygreatweatherforecast.com`	`http://example.com/mygreatweatherforecast`

Pada tahap ini, Anda dapat melakukan panggilan API ke backend menggunakan salah satu URL dasar. Namun, saat Anda menggunakan URL proxy API, semuanya akan menjadi menarik.

Selain analisis API yang mulai dikumpulkan Apigee saat Anda menggunakan proxy API, proxy juga memungkinkan Anda menentukan alur bersyarat yang dipetakan ke resource di backend. Pada dasarnya, Jika panggilan GET masuk ke resource /reports, Apigee harus melakukan sesuatu.

Gambar berikut menunjukkan perbedaan perilaku antara dua URL yang pada akhirnya mengakses backend yang sama. Salah satunya adalah URL resource yang tidak di-proxy, dan yang lainnya adalah proxy API Apigee dengan alur bersyarat ke resource backend yang sama. Kita akan menjelaskan alur bersyarat secara lebih mendetail di bawah.

Untuk URL proxy API Apigee dengan alur bersyarat, respons akan mengonversi XML menjadi JSON
dan mengumpulkan analisis.

Cara proxy API dipetakan ke resource backend tertentu

Dengan URL proxy API yang dipetakan ke URL dasar layanan backend (saat Anda membuat proxy), Anda dapat menambahkan alur bersyarat ke resource tertentu, seperti resource /reports dan /forecasts yang disebutkan sebelumnya.

Misalnya, Anda ingin Apigee melakukan sesuatu saat panggilan masuk ke resource /reports atau /forecasts. Pada tahap ini, Anda tidak memberi tahu Apigee apa yang harus dilakukan, hanya bahwa Apigee harus memproses panggilan ke resource tersebut. Anda melakukannya dengan kondisi. Di proxy API Apigee, Anda dapat membuat alur bersyarat untuk /reports dan /forecasts. Untuk tujuan konseptual, XML proxy API berikut menunjukkan kemungkinan tampilan kondisi tersebut.

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
    </Flow>
    <Flow name="forecasts">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/forecasts") and (request.verb = "GET")</Condition>
    </Flow>
</Flows>

Kondisi tersebut menyatakan, Saat permintaan GET masuk dengan /reports dan /forecasts di URL, Apigee akan melakukan apa pun yang Anda (developer API) perintahkan, melalui kebijakan yang Anda lampirkan ke alur tersebut.

Sekarang, berikut contoh cara memberi tahu Apigee apa yang harus dilakukan saat suatu kondisi terpenuhi. Dalam XML proxy API berikut, saat permintaan GET dikirim ke https://example.com/mygreatweatherforecast/reports, Apigee akan menjalankan kebijakan XML-to-JSON-1 dalam respons.

<Flows>
  <Flow name="reports">
    <Description/>
    <Request/>
    <Response>
      <Step>
        <Name>XML-to-JSON-1</Name>
      </Step>
    </Response>
  <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
</Flow>

Selain alur kondisional opsional tersebut, setiap proxy API juga dilengkapi dengan dua alur default: <PreFlow> yang dieksekusi sebelum alur kondisional Anda, dan <PostFlow> yang dieksekusi setelah alur kondisional Anda. Kebijakan tersebut berguna untuk menjalankan kebijakan saat panggilan apa pun dilakukan ke proxy API. Misalnya, jika Anda ingin memverifikasi kunci API aplikasi dengan setiap panggilan, terlepas dari resource backend yang diakses, Anda dapat menempatkan kebijakan Verify API Key di <PreFlow>. Untuk mengetahui informasi selengkapnya tentang alur, lihat Mengonfigurasi alur.

Membuat aliran bersyarat ke resource backend

Menentukan alur bersyarat ke resource backend di proxy API sepenuhnya bersifat opsional. Namun, alur bersyarat tersebut memberi Anda kemampuan untuk menerapkan pengelolaan dan pemantauan terperinci.

Anda akan dapat:

Terapkan pengelolaan dengan cara yang mencerminkan semantik model API Anda
Menerapkan kebijakan dan perilaku yang di-script ke jalur resource (URI) individual
Mengumpulkan metrik terperinci untuk Layanan Analytics

Misalnya, bayangkan Anda perlu menerapkan berbagai jenis logika ke resource backend /developers hingga /apps.

Untuk melakukannya, Anda menambahkan dua alur kondisional di proxy API: /developers dan /apps.

Editor Proxy Baru

Untuk menambahkan alur kondisional:

Pilih tab Develop di Editor Proxy.
Pilih Proxy endpoints > default di panel kiri.
Klik tombol + di atas panel Respons.
Pada dialog Add Conditional Flow, masukkan konfigurasi berikut:
- Nama alur: Developers
- Jenis Kondisi: Path
- Jalur: /developers
Kondisi akan dipicu (dan kebijakan akan dijalankan) jika panggilan dikirim ke proxy dengan /developers di akhir URI.
Sekarang tambahkan alur kondisional untuk /apps, dan asumsikan Anda ingin kondisi dipicu pada URI dan kata kerja POST dalam permintaan. Konfigurasi ini melibatkan penetapan berikut:
- Nama Alur: Apps
- Jenis Kondisi: Path and Verb
- Jalur: /apps
- Kata kerja: POST
Kondisi akan dipicu (dan kebijakan akan dijalankan) jika panggilan dikirim ke proxy dengan /apps di akhir URI dan kata kerja POST.

Alur yang ditambahkan ditampilkan di panel Response:

Dialog tambahkan alur bersyarat.

Editor Proxy Klasik

Di panel Develop pada editor proxy API, klik di samping default di Proxy Endpoints.

Saat Anda menahan pointer di atas tanda plus di samping default, teks saat mengarahkan kursor akan bertuliskan Tambahkan
Alur Baru.

Di jendela New Conditional Flow, masukkan konfigurasi utama berikut:

Nama alur: Developers
Jenis Kondisi: Path
Jalur: /developers

Di panel New Conditional Flow, alur bernama Developers dikonfigurasi dengan
deskripsi "App developers registered with Developer Services".

Kondisi akan dipicu (dan kebijakan akan dijalankan) jika panggilan dikirim ke proxy dengan /developers di akhir URI.

Sekarang tambahkan alur kondisional untuk /apps, dan asumsikan Anda ingin kondisi dipicu pada URI dan kata kerja POST dalam permintaan. Konfigurasi ini melibatkan penetapan berikut:

Nama Alur: Apps
Jenis Kondisi: Path and Verb
Jalur: /apps
Kata kerja: POST

Di panel New Conditional Flow, alur bernama Apps dikonfigurasi dengan
deskripsi "Aplikasi developer yang terdaftar di Layanan Developer".

Kondisi akan dipicu (dan kebijakan akan dijalankan) jika panggilan dikirim ke proxy dengan /apps di akhir URI dan kata kerja POST.

Di panel Navigator, Anda akan melihat alur baru untuk Aplikasi dan Developer.

Alur baru untuk Aplikasi dan Developer ditampilkan di panel Navigator di bagian Proxy
Endpoints.

Pilih salah satu alur untuk melihat konfigurasi alur bersyarat di tampilan kode editor proxy API:

<Flow name="Apps">
    <Description>Developer apps registered in Developer Services</Description>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/apps") and (request.verb = "POST")</Condition>
</Flow>

Seperti yang dapat Anda lihat, resource API hanyalah Alur bersyarat yang mengevaluasi jalur URI permintaan masuk. (Variabel proxy.pathsuffix mengidentifikasi URI permintaan yang mengikuti BasePath yang dikonfigurasi dalam konfigurasi ProxyEndpoint.)

Setiap resource API yang Anda tentukan diimplementasikan oleh alur bersyarat di proxy API. (Lihat Mengonfigurasi alur.)

Setelah Anda men-deploy proxy API ke lingkungan pengujian, permintaan berikut:

http://example.com/PROXY_PATH/apps

akan menyebabkan kondisi dievaluasi menjadi true, dan alur ini, beserta kebijakan terkait, akan dieksekusi.

Kondisi contoh berikut menggunakan ekspresi reguler Java untuk mengenali panggilan yang dilakukan ke resource /apps dengan atau tanpa garis miring di akhir (/apps atau /apps/**):

<Condition>(proxy.pathsuffix JavaRegex "/apps(/?)") and (request.verb = "POST")</Condition>

Untuk mengetahui informasi selengkapnya tentang jenis kondisi ini, lihat Cara mencocokkan terlepas dari apakah ada "/" di akhir ... di Komunitas Apigee.

Membuat model URI hierarkis

Dalam beberapa kasus, Anda akan memiliki resource API hierarkis. Misalnya, API daftar aplikasi developer menyediakan metode untuk mencantumkan semua aplikasi milik developer. Jalur URI adalah:

/developers/DEVELOPER_EMAIL/apps

Anda mungkin memiliki resource dengan ID unik yang dibuat untuk setiap entitas dalam koleksi, yang terkadang diberi anotasi sebagai berikut:

/genus/:id/species

Jalur ini berlaku sama untuk dua URI berikut:

/genus/18904/species
/genus/17908/species

Untuk merepresentasikan struktur ini dalam resource API, Anda dapat menggunakan karakter pengganti. Contoh:

/developers/*/apps
/developers/*example.com/apps
/genus/*/species

Hal ini akan menyelesaikan URI hierarkis sebagai resource API dengan tepat.

Dalam beberapa kasus, terutama untuk API hierarkis yang dalam, Anda mungkin hanya ingin menyelesaikan semua hal di bawah fragmen URI tertentu. Untuk melakukannya, gunakan karakter pengganti tanda bintang ganda dalam definisi resource Anda. Sebagai contoh, jika Anda menentukan resource API berikut:

/developers/**

Resource API tersebut akan menyelesaikan jalur URI berikut:

/developers/DEVELOPER_EMAIL/apps
/developers/DEVELOPER_EMAIL/keys
/developers/DEVELOPER_EMAIL/apps/APP_ID/keys

Berikut tampilan kondisi alur bersyarat dalam definisi proxy API:

<Condition>(proxy.pathsuffix MatchesPath "/developers/**") and (request.verb = "POST")</Condition>

Contoh lainnya

Kondisi yang dilampirkan ke RouteRule

<RouteRule name="default">
  <!--this routing executes if the header indicates that this is an XML call. If true, the
    call is routed to the endpoint XMLTargetEndpoint-->
  <Condition>request.header.content-type = "text/xml"</Condition>
  <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>

Kondisi yang dilampirkan ke kebijakan

<Step>
  <!--the policy MaintenancePolicy only executes if the response status code is exactly 503 -->
  <Condition>response.status.code = 503</Condition>
  <Name>MaintenancePolicy</Name>
</Step>

Alur Bersyarat

<!-- this entire flow is executed only if the request verb is a GET-->
<Flow name="GetRequests">
  <Condition>request.verb="GET"</Condition>
  <Request>
    <Step>
<!-- this policy only executes if request path includes a term like statues-->
<Condition>request.path ~ "/statuses/**"</Condition>
      <Name>StatusesRequestPolicy</Name>
    </Step>
  </Request>
  <Response>
    <Step>
<!-- this condition has multiple expressions. The policy executes if the response code status is exactly 503 or 400-->
<Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
      <Name>MaintenancePolicy</Name>
    </Step>
  </Response>
</Flow>

Contoh operator dalam kondisi

Berikut beberapa contoh operator yang digunakan untuk membuat kondisi:

request.header.content-type = text/xml
request.header.content-length < 4096 && request.verb = PUT
response.status.code = 404 || response.status.code = 500
request.uri MatchesPath /*/statuses/**
request.queryparam.q0 NotEquals 10

Contoh praktis: Abaikan `/` di akhir jalur

Developer Apigee biasanya ingin menangani kedua akhiran jalur ini: /cat dan /cat/. Hal ini karena beberapa pengguna atau klien mungkin memanggil API Anda dengan garis miring tambahan di akhir jalur, dan Anda harus dapat menanganinya dalam pernyataan bersyarat. Kasus penggunaan yang sama persis ini telah dibahas dalam cara mencocokkan terlepas dari apakah ada '/' di akhir URL....

Jika mau, Anda dapat melakukannya tanpa menggunakan Regex seperti ini:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix = "/cat") OR (proxy.pathsuffix = "/cat/")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Ini adalah opsi yang baik. Jelas dan dapat dibaca.

Anda dapat melakukan hal yang sama dengan Regex, seperti ini. Tanda kurung digunakan untuk mengelompokkan bagian regex dari pernyataan, tetapi tidak diperlukan.

<Condition>(proxy.pathsuffix JavaRegex "/cat(/?)"</Condition>

Panggilan API:

GET http://example.com/matchtest/cat
atau GET http://example.com/matchtest/cat/

Apakah kebijakan dijalankan? Ya. Perhatikan bahwa dalam ekspresi reguler, karakter ? berarti: cocokkan nol atau satu karakter sebelumnya. Oleh karena itu, /cat dan /cat/ cocok.

Panggilan API:

GET http://example.com/matchtest/cat/spotted

Apakah kebijakan dijalankan? Tidak. Ekspresi reguler cocok dengan nol atau hanya satu kemunculan karakter sebelumnya, dan tidak ada yang lain yang diizinkan.

Mencocokkan string arbitrer dengan JavaRegex

Dalam semua contoh di topik ini, kami menunjukkan cara mencocokkan salah satu variabel alur bawaan: proxy.pathsuffix. Anda dapat melakukan pencocokan pola pada string atau variabel alur arbitrer, baik itu variabel alur bawaan seperti proxy.pathsuffix atau tidak.

Misalnya, jika Anda memiliki kondisi yang menguji string arbitrer, mungkin string yang ditampilkan dalam payload backend, atau string yang ditampilkan dari pencarian server autentikasi, Anda dapat menggunakan operator pencocokan untuk mengujinya. Jika Anda menggunakan JavaRegex, ekspresi reguler akan dibandingkan dengan seluruh string subjek. Jika subjeknya adalah abc dan ekspresi regulernya adalah [a-z], tidak ada kecocokan, karena [a-z] cocok dengan satu karakter alfa. Ekspresi [a-z]+ berfungsi, begitu juga dengan [a-z]*, dan [a-z]{3}.

Mari kita lihat contoh konkretnya. Misalkan server autentikasi menampilkan daftar peran sebagai string yang dibatasi koma: editor, author, guest.

Untuk menguji keberadaan peran editor, konstruksi ini tidak akan berfungsi, karena editor hanya bagian dari seluruh string.

<Condition>returned_roles ~~ "editor"</Condition>

Namun, konstruksi ini akan berfungsi:

<Condition>(returned_roles ~~ ".*\beditor\b.*")</Condition>

Fungsi ini berfungsi karena mempertimbangkan pemisahan kata dan bagian string lainnya dengan awalan dan akhiran .*.

Dalam contoh ini, Anda juga dapat menguji editor dengan operator Matches:

<Condition>(returned_roles ~~ "*editor*")</Condition>

Namun, jika Anda memerlukan presisi yang lebih tinggi, JavaRegex sering kali menjadi pilihan yang lebih baik.

Mengganti karakter kutip ganda dalam ekspresi JavaRegex

Sintaksis Kondisi memerlukan ekspresi JavaRegex yang diapit dalam tanda kutip ganda; oleh karena itu, jika Anda memiliki ekspresi regex yang menyertakan tanda kutip ganda, Anda memerlukan cara alternatif untuk mencocokkannya. Jawabannya adalah Unicode. Misalnya, Anda meneruskan header yang menyertakan tanda petik ganda, seperti berikut:

 -H 'content-type:multipart/related; type="application/xop+xml"'

Jika Anda mencoba mencocokkan header tersebut dalam kondisi regex, Anda akan mendapatkan error Invalid Condition karena ekspresi mencakup tanda kutip ganda:

request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"

Solusinya adalah mengganti tanda kutip ganda berbasis ASCII dengan tanda kutip ganda yang setara dalam Unicode, \u0022. Misalnya, ekspresi berikut valid dan menghasilkan hasil yang diharapkan:

request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"

Kondisi dengan variabel flow Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Video

Mengonfigurasi pernyataan bersyarat

Variabel

Contoh 1

Contoh 2

Menguji alur bersyarat

Pencocokan pola

Bacaan Lebih Lanjut

Operator

Mencocokkan dengan

JavaRegex

MatchesPath

Mencampur tanda bintang

Resource API

Bacaan Lebih Lanjut

Cara proxy API dipetakan ke resource backend tertentu

Membuat aliran bersyarat ke resource backend

Editor Proxy Baru

Editor Proxy Klasik

Membuat model URI hierarkis

Contoh lainnya

Kondisi yang dilampirkan ke RouteRule

Kondisi yang dilampirkan ke kebijakan

Alur Bersyarat

Contoh operator dalam kondisi

Contoh praktis: Abaikan / di akhir jalur

Mencocokkan string arbitrer dengan JavaRegex

Mengganti karakter kutip ganda dalam ekspresi JavaRegex

Kondisi dengan variabel flow

Contoh praktis: Abaikan `/` di akhir jalur