Kondisi dengan variabel flow

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

Pernyataan bersyarat adalah struktur kontrol yang umum dalam semua bahasa pemrograman. Seperti bahasa pemrograman, konfigurasi proxy API mendukung pernyataan bersyarat untuk Flow, Kebijakan, Langkah, dan RouteRules. Dengan menentukan pernyataan kondisional, Anda menentukan perilaku dinamis untuk API Anda. Dengan perilaku dinamis ini, Anda dapat 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 perlu menulis kode apa pun.

Mengonfigurasi pernyataan bersyarat

Perilaku kondisional diterapkan di proxy API menggunakan kombinasi kondisi dan variabel. Pernyataan bersyarat dibuat menggunakan elemen {i>Condition<i}. Berikut ini adalah kondisi kosong:

<Condition></Condition>

Untuk membuat pernyataan kondisional, tambahkan operator bersyarat dan variabel untuk membuat struktur berikut:

<Condition>{variable.name}{operator}{"value"}</Condition>

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

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

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

Variabel

Kondisi melakukan tugasnya dengan mengevaluasi nilai variabel. Variabel adalah properti transaksi HTTP yang dijalankan oleh proxy API, atau properti konfigurasi proxy API itu sendiri. Setiap kali proxy API mendapatkan permintaan dari aplikasi, Apigee Edge akan 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. Cara ini menghasilkan konteks yang beragam yang dapat Anda gunakan untuk menyiapkan pernyataan bersyarat.

Variabel selalu menggunakan notasi titik-titik. Misalnya, header HTTP pada pesan permintaan tersedia sebagai variabel yang disebut request.header.{header_name}. Jadi, untuk mengevaluasi header Jenis konten, 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 kondisional yang akan menyebabkan kebijakan diterapkan hanya jika pesan permintaan adalah GET. Untuk membuat kondisi yang mengevaluasi kata kerja HTTP dari sebuah permintaan, buat 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 dapat menggunakan:
<Condition>request.verb equals "GET"</Condition>

Edge menggunakan pernyataan seperti itu untuk mengevaluasi kondisi. Contoh di atas bernilai true (benar) jika kata kerja HTTP yang terkait dengan permintaan adalah GET. Jika kata kerja HTTP yang terkait dengan permintaan adalah POST, pernyataan akan bernilai false (salah).

Untuk mengaktifkan perilaku dinamis, Anda dapat menyertakan Kondisi ke Alur, Langkah, dan RouteRules.

Saat melampirkan kondisi ke Flow, Anda akan membuat 'Alur bersyarat'. Flow Bersyarat hanya dijalankan jika kondisi bernilai true (benar). Anda dapat menambahkan Kebijakan sebanyak yang diinginkan ke Flow bersyarat. 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 jika kata kerja permintaan adalah GET:

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

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

<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. Kondisi berikut menyebabkan Kebijakan VerifyApiKey diterapkan hanya jika pesan permintaan berupa POST.

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

Setelah menentukan Flow kondisional tersebut, Anda dapat menyertakan Kebijakan ke dalamnya, mengaktifkan proxy API untuk menerapkan satu kumpulan kebijakan untuk permintaan GET, dan kumpulan kebijakan lainnya untuk permintaan POST.

Untuk mendapatkan 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 tempat kondisi berlaku. Dalam contoh ini, kondisi merupakan komponen alur. Oleh karena itu, flow akan dieksekusi setiap kali pernyataan bernilai benar (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, Edge menyimpan nilai semua header HTTP yang ada sebagai variabel. Jika permintaan berisi header HTTP yang disebut User-Agent, header tersebut dan nilainya akan disimpan sebagai variabel bernama request.header.User-Agent.

Mengingat konfigurasi ProxyEndpoint di atas, Edge akan memeriksa nilai variabel request.header.User-Agent untuk melihat apakah kondisi tersebut bernilai true (benar).

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

Contoh 2

Mari kita gunakan contoh khusus yang mengharuskan Anda mengubah pesan respons dari XML ke 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 menulis hasilnya ke pesan respons baru. (Jika Anda mengonversi pesan request dari XML ke JSON, cukup tetapkan kedua nilai ini ke request.)

Karena ingin mengonversi respons dari XML ke JSON, Anda harus mengonfigurasi Alur respons kondisional untuk melakukan konversi. Misalnya, untuk mengonversi semua respons dari XML ke JSON sebelum ditampilkan ke aplikasi klien, konfigurasikan Alur 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 ke JSON jika klien yang meminta adalah perangkat seluler. Untuk mengaktifkan perilaku dinamis tersebut, Anda harus menambahkan pernyataan bersyarat ke Flow.

Menguji alur bersyarat

Dalam contoh permintaan ini, header User-Agent HTTP disetel ke Mozilla, yang menyebabkan pernyataan kondisional dievaluasi ke benar (true) dan alur kondisional Convert-for-devices akan dijalankan.

$ curl -H "User-Agent:Mozilla" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

atau, untuk cukup mencetak di mana Python tersedia:

$ curl -H "User-Agent:Mozilla" http://{org_name}-test.apigee.net/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 dengan Mozilla, akan menghasilkan respons berformat XML.

$ curl http://{org_name}-test.apigee.net/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 dalam alur Apigee.

Operator

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

Kecocokan

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

Ringkasan: Operator "Kecocokan" memberi Anda dua kemungkinan. Cocok dengan string secara harfiah, atau lakukan pencocokan karakter pengganti dengan "*". Seperti yang Anda harapkan, karakter pengganti cocok dengan nol atau beberapa karakter. Mari kita lihat cara kerjanya.

XML berikut menunjukkan kondisi Langkah. Fitur ini menjalankan kebijakan MultiplePolicy saat kondisi bernilai true (benar). Dalam contoh ini, kami menguji variabel proxy.pathsuffix, variabel bawaan di Edge yang menyimpan akhiran jalur permintaan. Namun, perhatikan bahwa Anda dapat menguji nilai variabel flow yang berisi string. Jadi, dalam hal ini, jika jalur dasar permintaan masuk adalah /animals, dan permintaannya adalah /animals/cat, maka akhiran jalurnya 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 MultiplePolicy dijalankan? Hanya ada satu kemungkinan.

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat

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

Sekarang, pertimbangkan pernyataan kondisional ini saat kita menggunakan karakter pengganti "*":

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/bat

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/owl

Apakah kebijakan tersebut 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://artomatic-test.apigee.net/matchtest/cat

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/bat

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat123

Apakah kebijakan tersebut dijalankan? Ya, karakter pengganti cocok dengan nol atau beberapa karakter apa pun sehingga "123" akan menghasilkan kecocokan.

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat/bird/mouse

Apakah kebijakan tersebut dijalankan? Ya, karena karakter pengganti cocok dengan nol atau beberapa karakter apa pun, sehingga "/bird/mouse" menghasilkan kecocokan. Perhatikan bagaimana ekspresi seperti ini dapat menyebabkan masalah karena ekspresi ini cocok dengan semuanya setelah karakter literal.

Pertanyaan: Apakah operator Pencocokan peka huruf besar/kecil?

Ya. Asumsikan Anda memiliki kondisi seperti ini:

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/bAt

Apakah kebijakan tersebut dijalankan? Ya, {i>case<i} tersebut cocok.

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

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

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat

Apakah kebijakan tersebut dijalankan? Tidak, operator Pencocokan mencari string literal "c*at".

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/c*at

Pertanyaan:Apakah kebijakan ini berlaku?

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

JavaRegex

Seperti yang Anda lihat, operator "Kecocokan" sangat bagus untuk situasi sederhana. Namun, Anda dapat menggunakan operator lain, operator "JavaRegex" atau "~~". Keduanya adalah operator yang sama, hanya saja JavaRegex dianggap lebih mudah dibaca. Class ini disebut JavaRegex karena memungkinkan pencocokan pola ekspresi reguler, dan Edge mengikuti aturan yang sama dengan class dalam paket java.util.regex dalam bahasa Java. Cara kerja operator JavaRegex sangat berbeda dengan operator Pencocokan, jadi jangan salah membedakan keduanya.

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

Kode berikut menunjukkan kondisi Langkah. Kebijakan ini menjalankan kebijakan MultiplePolicy jika kondisinya bernilai true (benar). Dalam contoh ini, kami menguji variabel proxy.pathsuffix, variabel bawaan di Edge 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>

Pertanyaan: Akhiran jalur proxy apa yang akan menyebabkan MultiplePolicy dijalankan? Sama seperti operator Kecocokan, hanya ada satu kemungkinan dalam kasus ini.

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat

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

Sekarang, mari kita buat ekspresi reguler menggunakan pengukur "*". Penghitung ini cocok dengan nol atau beberapa karakter sebelumnya.

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat

Apakah kebijakan tersebut dijalankan? Tidak! Penghitung "*" cocok dengan nol atau beberapa karakter sebelumnya, yang merupakan "c".

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/ccccct

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

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

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/ct

Apakah kebijakan tersebut dijalankan? Ya. Penghitungan "?" cocok dengan satu atau tidak satu pun karakter sebelumnya. Dalam hal ini, tidak ada karakter "a", sehingga kondisi bernilai true (benar).

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/caat

Apakah kebijakan tersebut dijalankan? Tidak. Penghitung "?" cocok dengan salah satu karakter sebelumnya, yang merupakan "a".

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

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat

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

GET http://artomatic-test.apigee.net/matchtest/bat

GET http://artomatic-test.apigee.net/matchtest/rat

Namun, ini tidak cocok:

GET http://artomatic-test.apigee.net/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://artomatic-test.apigee.net/matchtest/cat

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cAt

Pertanyaan: Apakah kebijakan tersebut berlaku?

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

Jalur Pencocokan

Operator MatchesPath juga dapat ditentukan seperti "~/" ini. Operator ini terlihat sedikit seperti Matches (~) dan operator Java (~~). Namun MatchesPath sama sekali berbeda.

Ingatlah bahwa operator ini melihat jalur sebagai serangkaian bagian. Oleh karena itu, jika jalurnya 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 tanda bintang ganda (**). Tanda bintang tunggal cocok dengan satu elemen jalur. Tanda bintang ganda cocok dengan satu atau banyak elemen jalur.

Perhatikan contoh berikut. Dalam contoh ini, kami menguji variabel proxy.pathsuffix, variabel bawaan di Edge yang menyimpan akhiran jalur permintaan. Namun, perhatikan bahwa Anda dapat menguji nilai variabel flow 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 MultiplePolicy dijalankan?

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/animals

Pertanyaan: Apakah kebijakan tersebut berlaku?

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/animals/

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/animals/cats

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild

Pertanyaan: Apakah kebijakan tersebut berlaku?

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 MultiplePolicy dijalankan?

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/animals

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/animals/

Apakah kebijakan tersebut berlaku?

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/animals/cats

Apakah kebijakan tersebut berlaku?

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild

Apakah kebijakan tersebut berlaku?

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

Menggabungkan tanda bintang

Anda dapat menggunakan kombinasi tanda bintang (*) tunggal dan ganda (**) untuk lebih mempersempit 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://artomatic-test.apigee.net/matchtest/animals/cats/wild/

dan

GET http://artomatic-test.apigee.net/matchtest/animals/dogs/wild/austrailian

dan

GET http://artomatic-test.apigee.net/matchtest/animals/birds/wild/american/finches

Resource API

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

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

Saat membuat proxy API (seperti yang ditunjukkan dalam Membuat proxy API pertama Anda), setidaknya Anda membuat URL dasar alias yang memetakan ke layanan backend Anda. Contoh:

URL dasar backend URL proxy API baru/setara
http://mygreatweatherforecast.com http://{organisasi_Anda}-{lingkungan}.apigee.net/mygreatweatherforecast

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

Selain analisis API yang mulai dikumpulkan Edge saat Anda menggunakan proxy API, proxy juga memungkinkan Anda menentukan alur bersyarat yang dipetakan ke resource di backend. Intinya, "Jika panggilan GET masuk ke resource /reports, Edge 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-kan, satunya lagi adalah proxy Edge API dengan flow kondisional ke resource backend yang sama. Kami akan menjelaskan alur bersyarat secara lebih mendetail di bawah.

Cara proxy API dipetakan ke resource backend tertentu

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

Misalnya Anda ingin membuat Edge "melakukan sesuatu" saat panggilan masuk ke resource /reports atau /forecasts. Pada tahap ini, Anda tidak memberi tahu Edge apa yang harus dilakukan, hanya saja aplikasi harus memproses panggilan ke resource tersebut. Anda melakukan ini dengan kondisi. Di proxy Edge API, Anda dapat membuat flow kondisional untuk /reports dan /forecasts. Untuk tujuan konseptual, XML proxy API berikut menunjukkan 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, "Ketika permintaan GET masuk dengan /reports dan /forecasts di URL, Edge akan melakukan apa pun yang Anda (developer API) memintanya, melalui kebijakan yang Anda lampirkan ke alur tersebut.

Berikut adalah contoh untuk memberi tahu Edge apa yang harus dilakukan saat suatu kondisi terpenuhi. Dalam XML proxy API berikut, saat permintaan GET dikirim ke https://yourorg-test.apigee.net/mygreatweatherforecast/reports, Edge akan mengeksekusi 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 flow kondisional opsional tersebut, setiap proxy API juga dilengkapi dengan dua flow default: <PreFlow> dieksekusi sebelum flow kondisional dan <PostFlow> dieksekusi setelah flow kondisional Anda. Panggilan tersebut berguna untuk mengeksekusi 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 Verifikasi Kunci API di <PreFlow>. Untuk mengetahui informasi selengkapnya tentang flow, lihat Mengonfigurasi flow.

Membuat flow kondisional ke resource backend

Penentuan flow kondisional ke resource backend dalam proxy API sepenuhnya bersifat opsional. Namun, alur kondisional tersebut memberi Anda kemampuan untuk menerapkan pengelolaan dan pemantauan yang terperinci.

Anda akan dapat:

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

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

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

Pada tampilan Develop panel Navigator proxy proxy API, klik ikon + di sebelah default di Proxy Endpoints.

Di jendela "Alur Kondisional Baru", Anda akan memasukkan konfigurasi utama berikut:

  • Nama alur: Developer
  • Jenis Kondisi: Jalur
  • Jalur: /developers

Kondisi ini akan dipicu (dan kebijakan akan dijalankan) 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 dan kata kerja POST dalam permintaan. Konfigurasi ini melibatkan penetapan hal berikut:

  • Nama Alur: Aplikasi
  • Jenis Kondisi: Jalur dan Kata Kerja
  • Jalur: /apps
  • Kata kerja: POST

Kondisi ini 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 Apps dan Developers.

Pilih salah satu flow untuk melihat konfigurasi flow kondisional dalam 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 Flow kondisional 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 Flow bersyarat di proxy API. (Lihat Mengonfigurasi flow.)

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

http://{org_name}-test.apigee.net/{proxy_path}/apps

akan menyebabkan kondisi dievaluasi ke true (benar), dan alur ini, beserta kebijakan terkait, akan dijalankan.

Contoh kondisi 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 ketentuan ini, lihat Cara mencocokkan meskipun ... di Komunitas Apigee.

Pemodelan URI hierarkis

Dalam beberapa kasus, Anda akan memiliki resource API hierarkis. Misalnya, Developer Services API 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 entity dalam koleksi, yang terkadang dianotasikan 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

akan menyelesaikan URI hierarkis ini sebagai resource API dengan tepat.

Dalam beberapa kasus, terutama untuk API yang sangat hierarkis, Anda mungkin hanya ingin menyelesaikan semua yang berada di bawah fragmen URI tertentu. Untuk melakukannya, gunakan karakter pengganti tanda bintang ganda dalam definisi resource. Misalnya, jika Anda menetapkan 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 adalah tampilan kondisi flow kondisional 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>

Ketentuan 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 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 edge 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 Anda. Kasus penggunaan persis ini telah dibahas di Komunitas Apigee.

Jika Anda mau, Anda dapat mencapainya 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 regex pernyataan, tetapi tidak wajib.

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat
or

GET http://artomatic-test.apigee.net/matchtest/cat/

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

Panggilan API:

GET http://artomatic-test.apigee.net/matchtest/cat/spotted

Apakah kebijakan tersebut dijalankan? Tidak. Regular expression cocok dengan nol atau hanya satu kemunculan karakter sebelumnya, dan tidak ada hal lain yang diizinkan.

Mencocokkan string arbitrer dengan JavaRegex

Dalam semua contoh dalam topik ini, kami menunjukkan cara mencocokkan salah satu variabel alur bawaan: proxy.pathsuffix. Penting untuk diketahui bahwa Anda dapat melakukan pencocokan pola pada string arbitrer atau variabel flow apa pun, terlepas dari apakah variabel alur bawaan seperti proxy.pathsuffix tersebut atau bukan.

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 yang cocok 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 yang cocok, karena "[a-z]" cocok dengan satu karakter alfa. Ekspresi "[a-z]+" berfungsi, seperti halnya "[a-z]*", dan "[a-z]{3}.

Mari lihat satu contoh konkret. Misalkan server autentikasi menampilkan daftar peran sebagai string yang dipisahkan koma: "editor, penulis, tamu".

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

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

Namun, konstruksi ini akan berfungsi:

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

Fungsi ini berfungsi karena memperhitungkan jeda kata dan bagian lain dari string dengan awalan dan akhiran .*.

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

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

Namun, jika Anda membutuhkan lebih banyak presisi, JavaRegex sering kali merupakan pilihan yang lebih baik.

Meng-escape tanda kutip ganda dalam ekspresi JavaRegex

Sintaksis Condition mengharuskan ekspresi JavaRegex digabungkan dalam tanda kutip ganda; oleh karena itu, jika memiliki ekspresi Regex yang menyertakan tanda kutip ganda, Anda memerlukan cara alternatif untuk mencocokkannya. Jawabannya adalah Unicode. Misalnya, Anda meneruskan header yang menyertakan tanda kutip ganda, seperti berikut:
 -H 'content-type:multipart/related; type="application/xop+xml"'
Jika mencoba mencocokkan header tersebut dalam kondisi Regex, Anda akan mendapatkan error Kondisi Tidak Valid karena ekspresi menyertakan tanda kutip ganda:
request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"
Solusinya adalah mengganti tanda kutip ganda berbasis ASCII dengan Unicode yang setara, \u0022. Misalnya, ekspresi berikut valid dan memberikan hasil yang diharapkan:
request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"