Kondisi dengan variabel alur

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Pernyataan bersyarat adalah struktur kontrol yang umum di semua bahasa pemrograman. Seperti bahasa pemrograman, konfigurasi proxy API mendukung pernyataan bersyarat untuk Flow, Policy, Step, dan RouteRules. Dengan menentukan pernyataan bersyarat, Anda menentukan perilaku dinamis untuk API Anda. Perilaku dinamis ini memungkinkan Anda melakukan hal-hal seperti mengonversi XML ke JSON hanya untuk perangkat seluler, atau pemilihan rute ke URL backend berdasarkan jenis konten atau kata kerja HTTP permintaan untuk membuat pesan email baru.

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

Video

Catatan: Video berikut menampilkan Proxy Editor klasik di bagian UI Apigee. Apigee memperkenalkan Proxy versi baru Editor, yang memiliki desain berbeda dari versi klasik yang ditampilkan dalam video.

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

Mengonfigurasi pernyataan bersyarat

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

<Condition></Condition>

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

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

Contoh:

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

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

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

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

Bagaimana apakah Anda mengganti di akhir URL

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

Variabel

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

Variabel selalu menggunakan notasi bertitik. 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. Sebagai contoh request.header.Content-type = "application/json" menunjukkan bahwa konten jenis permintaan harus 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 permintaan, Anda membuat pernyataan kondisional di bawah ini. Variabel dalam kondisi ini adalah request.verb. Nilai variabelnya adalah GET. Operatornya adalah =.

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

Anda juga bisa menggunakan:

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

Apigee menggunakan pernyataan tersebut untuk mengevaluasi kondisi. Contoh di atas bernilai benar (true) 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 request.header. dan Awalan variabel request.queryparam..

Untuk mengaktifkan perilaku dinamis, Anda dapat melampirkan Kondisi ke Flow, Langkah, dan RouteRules.

Saat melampirkan kondisi ke Flow, Anda akan membuat Alur bersyarat. Alur bersyarat dieksekusi hanya jika kondisi bernilai benar (true). Anda dapat melampirkan sebanyak mungkin Kebijakan Flow kondisional. Flow kondisional 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 lainnya untuk POST permintaan:

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

Seperti yang ditunjukkan pada contoh di bawah, Anda dapat menerapkan kondisi ke Langkah Kebijakan itu sendiri. Tujuan Kondisi berikut menyebabkan kebijakan VerifyAPIKey hanya diterapkan 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 bersyarat tersebut, sehingga mengaktifkan API proxy menerapkan satu kumpulan kebijakan untuk permintaan GET, dan kumpulan kebijakan lainnya untuk POST permintaan.

Untuk informasi referensi yang komprehensif, lihat referensi berikut:

• Referensi variabel flow
• Referensi kondisi

Contoh 1

Contoh berikut menunjukkan satu alur bersyarat bernama Convert-for-devices, yang dikonfigurasi di alur respons ProxyEndpoint. Tambahkan Kondisi sebagai elemen ke entity untuk mana kondisi yang berlaku. Dalam contoh ini, kondisinya adalah komponen alur. Oleh karena itu, flow akan dieksekusi setiap kali pernyataan bernilai 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 tampilkan sebagai variabel. Jika permintaan berisi header HTTP bernama User-Agent, header tersebut dan nilainya disimpan sebagai variabel yang disebut request.header.User-Agent.

Dengan konfigurasi ProxyEndpoint di atas, Apigee memeriksa nilai request.header.User-Agent untuk melihat apakah kondisi tersebut bernilai benar.

Jika kondisinya bernilai true, artinya nilai variabel request.header.User-Agent sama dengan Mozilla, maka Flow kondisional dijalankan dan kebijakan XMLtoJSON yang disebut ConvertToJSON diterapkan. Jika tidak, Flow tidak dieksekusi, dan respons XML ditampilkan tanpa dimodifikasi (dalam format XML) terhadap permintaan .

Contoh 2

Mari kita gunakan contoh khusus di mana Anda perlu mengubah pesan respons dari XML menjadi JSON—tetapi hanya untuk perangkat seluler. Pertama, buat kebijakan yang akan mengonversi Respons berformat XML dari Weather API ke 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 tulis hasilnya ke respons baru untuk membuat pesan email baru. (Jika Anda mengonversi pesan request dari XML ke JSON, cukup setel kedua nilai ini menjadi request.)

Tips: Jenis Kebijakan XMLtoJSON menentukan kumpulan IP yang wajar default, yang berarti Anda hanya perlu menambahkan elemen konfigurasi untuk membuat XML ke struktur JSON.

Karena Anda ingin mengonversi respons dari XML ke JSON, Anda perlu mengonfigurasi kondisional Alur respons untuk melakukan konversi. Misalnya, untuk mengonversi semua respons dari XML ke JSON sebelum dikembalikan ke aplikasi klien, konfigurasikan respons ProxyEndpoint berikut Alur.

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

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

Namun, tujuan Anda adalah hanya mengonversi laporan Cuaca ke JSON saat klien yang meminta diminta adalah perangkat seluler. Untuk memungkinkan perilaku dinamis tersebut, Anda harus menambahkan pernyataan kondisional ke Alur.

Menguji kondisional alur

Dalam contoh permintaan ini, header User-Agent HTTP disetel ke Mozilla, menyebabkan pernyataan bersyarat bernilai benar dan bersyarat alur Convert-for-devices untuk mengeksekusi.

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

atau, untuk mencetak indah di mana 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 dikirim 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 dimodifikasi 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 di Apigee alur kerja.

Sumber referensi tambahan

• Referensi kondisi
• "Proxy kondisi-pola-pencocokan" di repositori api-platform-samples kami di GitHub

Operator

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

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

Mencocokkan dengan

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

Ringkasan: Operator Matches memberi Anda dua kemungkinan. Cocok dengan string secara harfiah, atau melakukan pencocokan karakter pengganti dengan *. Seperti yang mungkin Anda ketahui, karakter pengganti cocok dengan angka nol karakter atau lebih. Mari kita lihat cara kerjanya.

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

XML berikut menunjukkan kondisi Langkah. Menjalankan kebijakan tertentu pada saat kondisi akan mengevaluasi ke true. Dalam contoh ini, kita menguji variabel proxy.pathsuffix, variabel bawaan di Apigee yang menyimpan akhiran jalur permintaan. Namun, perlu diperhatikan bahwa Anda dapat menguji nilai variabel flow apa pun yang berisi string. Jadi, dalam hal ini, jika jalur dasar dari permintaan masuk adalah /animals, dan permintaannya adalah /animals/cat, lalu 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: Akhiran jalur proxy apa yang akan menyebabkan Beberapa Kebijakan dijalankan? Ada hanya ada satu kemungkinan.

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya, karena akhiran jalur proxy cocok dengan /cat dengan tepat. Fungsi ini tidak akan dijalankan jika akhirannya adalah /bat, /dog, atau / atau apa pun.

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

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

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya, karena {i>wildcard <i} cocok dengan karakter apa pun, dan "/cat inci cocok dengan.

Panggilan API:

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

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

Panggilan API:

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

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

Sekarang, mari pindahkan karakter pengganti ke akhir akhiran:

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

Panggilan API:

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

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

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Tidak, /bat tidak cocok.

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya, karakter pengganti cocok dengan nol atau beberapa karakter apa pun, oleh karena itu 123 menghasilkan kecocokan.

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya, karena karakter pengganti cocok dengan nol atau beberapa karakter apa pun, jadi /bird/mouse menghasilkan kecocokan. Perhatikan bagaimana ekspresi seperti ini bisa membuat Anda kesulitan karena cocok dengan semua karakter setelah karakter literal!

Pertanyaan: Apakah operator Matches peka huruf besar/kecil?

Ya. Asumsikan Anda memiliki kondisi seperti ini:

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

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Tidak, {i>wildcard <i}cocok dengan huruf apa pun (apa pun kapitalisasinya), tetapi huruf kecil a tidak cocok dengan A.

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya, kasusnya cocok.

Pertanyaan: Bagaimana cara meng-escape karakter dengan operator Matches?

Gunakan karakter persen % untuk meng-escape karakter yang dikhususkan. Contoh:

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

Panggilan API:

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

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

Panggilan API:

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

Pertanyaan:Apakah kebijakan dapat dijalankan?

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

JavaRegex

Seperti yang Anda lihat, operator Matches sangat tepat untuk situasi sederhana. Tetapi Anda dapat menggunakan operator, JavaRegex atau operator ~~. Keduanya adalah operator yang sama, kecuali JavaRegex adalah dianggap lebih mudah dibaca. Ini disebut JavaRegex karena memungkinkan ekspresi reguler pencocokan pola, dan Apigee mengikuti aturan yang sama dengan class dalam java.util.regex dalam bahasa Java. Cara kerja operator JavaRegex sangat berbeda dengan Operator Matches, jadi jangan sampai tertukar antara keduanya.

Catatan: Jika Anda terbiasa melakukan Regex dalam skrip Perl, penting untuk perhatikan bahwa operator JavaRegex di Apigee menguji seluruh string subjek. Sebagai Misalnya, jika subjeknya adalah abc dan ekspresi regulernya adalah [a-z] , tidak ada kecocokan karena [a-z] cocok dengan satu karakter alfa. Ekspresi [a-z]+ akan berfungsi, seperti halnya [a-z]{3}. Pencocokan ini berbeda dari penerapan ekspresi reguler biasa dalam alat seperti Perl atau {i>grep<i} atau {i>mod_rewrite<i} Apache. JavaRegex menggunakan java.util.regex.Pattern.matches(str), yang didefinisikan untuk mengembalikan positif jika seluruh {i>string<i} (str) cocok dengan pola. Ekspresi reguler di Perl atau mod_rewrite diterapkan ke setiap bagian {i>string<i}. Nilai tersebut mengembalikan benar ({i>true<i}) jika polanya cocok di mana saja. Lihat contoh Mencocokkan string arbitrer dengan JavaRegex.

Catatan: Bagian ini tidak dimaksudkan sebagai pengantar mendetail ekspresi reguler. Tujuan utamanya adalah untuk menggambarkan beberapa contoh sederhana, dan menyoroti perbedaan antara operator Matches dan JavaRegex. Jika Anda ingin tahu lebih banyak tentang ekspresi tersebut, banyak sumber daya yang tersedia untuk Anda jelajahi.

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

Kode berikut menunjukkan kondisi Step. Mengeksekusi kebijakan tertentu jika kondisi tersebut bernilai true. Dalam contoh ini, kita menguji variabel proxy.pathsuffix, sebuah komponen di Apigee yang menyimpan akhiran jalur permintaan. Jika jalur dasar dari permintaan masuk adalah /animals, dan permintaannya adalah /animals/cat, lalu 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 diawali dengan karakter garis miring (/), seperti /cat. Oleh karena itu, jika Anda mencocokkan /c*t, Anda mencocokkan seluruh string, termasuk /. / bukan bagian dari paket pembuatan ekspresi. Jika Anda mencocokkan beberapa jenis variabel lain, seperti request.querystring / tidak diperlukan (kecuali jika parameter kueri dimulai dengan /).

Pertanyaan: Akhiran jalur proxy apa yang akan menyebabkan Beberapa Kebijakan dijalankan? Sama seperti dengan operator Matches, dalam kasus ini hanya ada satu kemungkinan.

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya, karena akhiran jalur proxy cocok dengan /cat dengan tepat. Fungsi ini tidak akan dijalankan jika akhirannya adalah /bat atau /dog atau apa pun lain.

Sekarang, mari kita buat ekspresi reguler menggunakan penghitung *. Perhitungan ini cocok dengan angka nol atau karakter sebelumnya.

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

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Tidak! Perhitungan * cocok dengan nol atau beberapa nilai karakter mendahului, yang merupakan c.

Panggilan API:

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

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

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

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

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya. Penghitungan ? cocok dengan nol atau satu kemunculan karakter sebelumnya, yang merupakan a.

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya. Perhitungan ? cocok dengan satu atau tak satu pun dari karakter sebelumnya. Dalam hal ini, tidak ada karakter a, sehingga kondisi bernilai true.

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Tidak. Penghitungan ? cocok dengan salah satu dari perhitungan sebelumnya karakter, yaitu a.

Selanjutnya, kita menggunakan gaya [abc] atau pengelompokan ekspresi reguler. Pencocokan ini cocok dengan karakter a, b, atau c.

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

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya. Kita menggunakan ekspresi reguler di sini, dan Ekspresi [cbr] cocok dengan c, b, OR r. Panggilan ini juga cocok dengan:

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. Asumsikan Anda memiliki kondisi seperti ini:

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

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya, ekspresi reguler cocok dengan nol atau salah satu karakter sebelumnya, adalah a.

Panggilan API:

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

Pertanyaan: Apakah kebijakan dapat dijalankan?

Tidak, karena huruf besar A tidak sama dengan huruf kecil di a.

MatchesPath

Operator MatchesPath juga dapat ditentukan seperti ~/ ini. Ini terlihat agak seperti operator Matches (~) dan JavaRegex (~~). Tapi MatchesPath sama sekali berbeda.

Ingatlah bahwa operator ini melihat suatu jalur sebagai serangkaian bagian. Oleh karena itu, jika jalur adalah: /animals/cats/wild, Anda bisa menganggap jalur ini terdiri dari bagian-bagian /animals, /cats, dan /wild.

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

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

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

Pertanyaan: Akhiran jalur proxy apa yang akan menyebabkan Beberapa Kebijakan dijalankan?

Panggilan API:

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

Pertanyaan: Apakah kebijakan dapat dijalankan?

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

Panggilan API:

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

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

Panggilan API:

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

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

Panggilan API:

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

Pertanyaan: Apakah kebijakan dapat dijalankan?

Tidak, karena satu tanda bintang 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: Akhiran jalur proxy apa yang akan menyebabkan Beberapa Kebijakan dijalankan?

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Tidak, karena kondisi memerlukan setidaknya satu elemen jalur berikut ditentukan oleh /**.

Panggilan API:

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

Apakah kebijakan tersebut berlaku?

Ya, jalur memang memiliki elemen jalur lain (bagian setelah /animals/), namun kosong.

Panggilan API:

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

Apakah kebijakan tersebut berlaku?

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

Panggilan API:

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

Apakah kebijakan tersebut berlaku?

Ya, karena jalur memiliki lebih dari satu elemen yang mengikuti setelahnya /animals

Mencampur tanda bintang

Anda dapat menggunakan kombinasi dari 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 jalur URI fragmen yang mengidentifikasi beberapa entitas yang dapat diakses developer dengan memanggil API Anda. Misalnya, jika layanan Anda menyediakan laporan cuaca dan prakiraan cuaca, layanan backend mungkin menentukan dua resource API:

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

Sumber referensi tambahan

• Tonton video singkat ini untuk mengetahui hubungan antara RESTful Anda resource backend dan resource proxy Apigee, atau alur bersyarat.
• Membangun proxy API pertama Anda

Saat membuat proxy API (seperti yang ditampilkan dalam Membangun proxy API pertama Anda), setidaknya 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. Tapi ketika Anda menggunakan URL proxy API, namun hal-hal mulai menjadi menarik.

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

Gambar berikut menunjukkan perbedaan perilaku antara dua URL yang pada akhirnya mengakses backend yang sama. Satu adalah URL resource yang tidak di-proxy-kan, yang lainnya adalah proxy Apigee API dengan yang mengalir bersyarat ke resource backend yang sama. Kami akan menjelaskan alur bersyarat secara lebih mendetail di bawah ini.

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 /reports dan /forecasts resource yang disebutkan sebelumnya.

Misalnya Anda ingin Apigee melakukan sesuatu saat ada panggilan masuk ke /reports atau /forecasts. Pada tahap ini, Anda tidak memberi tahu Apigee apa yang harus dilakukan, hanya saja aplikasi tersebut harus memproses panggilan ke resource tersebut. Anda yang harus melakukannya dengan beberapa kondisi. Di proxy Apigee API, Anda dapat membuat alur kondisional untuk /reports dan /forecasts. Untuk tujuan konseptual, API berikut XML proxy akan menunjukkan seperti apa 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>

Ketentuan tersebut menyatakan, Jika permintaan GET masuk dengan /reports dan /forecasts di URL, Apigee akan melakukan apa pun yang Anda (developer API) minta, memeriksa kebijakan yang Anda lampirkan ke alur tersebut.

Berikut adalah contoh yang memberi tahu Apigee apa yang harus dilakukan saat suatu kondisi terpenuhi. Di API berikut XML proxy, jika permintaan GET dikirim ke https://example.com/mygreatweatherforecast/reports, Apigee dijalankan 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 bersyarat opsional tersebut, setiap proxy API juga dilengkapi dengan dua flow: <PreFlow> yang dieksekusi sebelum flow kondisional, dan <PostFlow> dieksekusi setelah alur kondisional Anda. Berguna untuk mengeksekusi kebijakan saat setiap panggilan 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 pada <PreFlow>. Untuk informasi selengkapnya tentang alur, lihat Mengonfigurasi alur.

Membuat alur bersyarat ke resource backend

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

Anda akan bisa:

• Menerapkan pengelolaan dengan cara yang mencerminkan semantik model API Anda
• Menerapkan kebijakan dan perilaku dengan skrip ke setiap jalur resource (URI)
• Kumpulkan metrik terperinci untuk Layanan Analytics

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

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

Catatan: Apigee memperkenalkan Proxy versi baru Editor, yang akan mempermudah pengelolaan proxy.

Petunjuk pada dua tab pertama di bawah ini menjelaskan cara gunakan Editor Proxy baru atau Editor Proxy klasik.

Editor Proxy Baru

Untuk menambahkan alur bersyarat:

1. Pilih tab Develop di Proxy Editor.
2. Pilih Proxy endpoint > default di panel sebelah kiri.

   

3. Klik tombol + di atas panel Response.

   

4. Dalam dialog Add Conditional Flow, masukkan konfigurasi berikut:
   • Nama alur: Developers
   • Jenis Kondisi: Path
   • Jalur: /developers

   

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

5. Sekarang tambahkan flow kondisional untuk /apps, dan asumsikan Anda ingin kondisi tersebut dipicu pada URI maupun kata kerja POST dalam permintaan. Konfigurasi melibatkan pengaturan berikut ini:
   • Nama Alur: Apps
   • Jenis Kondisi: Path and Verb
   • Jalur: /apps
   • Kata kerja: POST

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

Alur yang ditambahkan ditampilkan di panel Response:

Editor Proxy Klasik

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

Di jendela New Conditional Flow, masukkan konfigurasi utama berikut:

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

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

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

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

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

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

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

<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 bisa Anda lihat, resource API hanyalah Flow kondisional yang mengevaluasi jalur URI permintaan masuk. (Variabel proxy.pathsuffix mengidentifikasi URI permintaan yang mengikuti BasePath yang dikonfigurasi di konfigurasi ProxyEndpoint.)

Setiap resource API yang Anda tentukan akan diimplementasikan oleh alur kondisional 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 ke true, dan alur ini, beserta semua elemen terkait kebijakan apa pun, akan dieksekusi.

Contoh kondisi berikut menggunakan ekspresi reguler Java untuk mengenali panggilan yang dilakukan ke /apps resource dengan atau tanpa garis miring (/apps atau /apps/**):

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

Untuk informasi selengkapnya tentang jenis kondisi ini, lihat Cara mencocokkan tanpa melihat apakah ada tanda "/" di akhir ... di Komunitas Apigee.

Pemodelan URI hierarki

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

/developers/DEVELOPER_EMAIL/apps

Anda mungkin memiliki resource tempat ID unik dibuat untuk setiap entity dalam koleksi, yang kadang-kadang dianotasi sebagai berikut:

/genus/:id/species

Jalur ini berlaku juga 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

Ini akan mengatasi URI hierarki sebagai resource API dengan tepat.

Dalam beberapa kasus, terutama untuk API yang sangat hierarkis, Anda mungkin ingin menyelesaikan semua 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 me-resolve jalur URI berikut:

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

Berikut adalah tampilan kondisi alur bersyarat dalam definisi proxy API:

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

Contoh lainnya

Kondisi 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 pada 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>

Operator contoh dalam kondisi

Berikut adalah 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 di akhir jalur, dan Anda harus bisa menanganinya dalam kondisional pernyataan pribadi Anda. Kasus penggunaan yang sama persis ini telah dibahas di cara mencocokkan, terlepas apakah ada tanda '/' di akhir di URL....

Jika mau, Anda dapat melakukan ini 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 pilihan yang baik. Jelas dan dapat dibaca.

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

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

Panggilan API:

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

Apakah kebijakan tersebut dapat dijalankan? Ya. Perhatikan bahwa dalam ekspresi reguler, ? karakter berarti: mencocokkan dengan nol atau salah satu karakter sebelumnya. Oleh karena itu, baik /cat dan /cat/ cocok.

Panggilan API:

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

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

Mencocokkan string arbitrer dengan JavaRegex

Dalam semua contoh dalam topik ini, kami menunjukkan cara mencocokkan salah satu variabel alur bawaan: proxy.pathsuffix. Ada baiknya mengetahui bahwa Anda dapat melakukan pencocokan pola pada sembarang {i>string<i} atau variabel flow, baik itu variabel alur bawaan seperti proxy.pathsuffix atau bukan.

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

Mari lihat satu contoh konkret. Misalkan server otentikasi menampilkan daftar peran sebagai string yang dipisahkan koma: editor, author, guest.

Untuk menguji keberadaan peran editor, konstruksi ini tidak akan berfungsi, karena editor adalah hanya sebagian dari keseluruhan {i>string<i}.

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

Namun, konstruksi ini akan berfungsi:

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

Cara ini berhasil karena memperhitungkan jeda kata dan bagian lain dari {i>string<i} dengan Awalan dan akhiran .*.

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

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

Namun, dalam kasus di mana Anda membutuhkan lebih banyak presisi, JavaRegex sering kali merupakan pilihan yang lebih baik.

Meng-escape tanda kutip ganda dalam ekspresi JavaRegex

Sintaks Condition memerlukan ekspresi JavaRegex untuk digabungkan dalam tanda kutip ganda; Oleh karena itu, jika Anda memiliki ekspresi reguler yang menyertakan tanda kutip ganda, Anda membutuhkan cara alternatif untuk mencocokkannya. Jawabannya adalah {i>Unicode<i}. Misalnya, Anda meneruskan header yang menyertakan tanda kutip ganda, seperti berikut:

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

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

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

Solusinya adalah mengganti tanda kutip ganda berbasis ASCII dengan padanan Unicode-nya, \u0022. Misalnya, ekspresi berikut valid dan memberikan hasil yang diharapkan:

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