Menggunakan variabel alur

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

Secara konseptual, variabel alur adalah objek yang dapat Anda akses dari dalam kebijakan atau utilitas (seperti alat Trace). Kebijakan ini memungkinkan Anda mempertahankan status yang terkait dengan transaksi API yang diproses oleh Apigee Edge.

Apa itu variabel alur?

Variabel flow ada dalam konteks flow proxy API, dan melacak status dalam transaksi API seperti cara variabel bernama melacak status dalam program software. Variabel alur menyimpan informasi seperti:

  • Alamat IP, header, jalur URL, dan payload yang dikirim dari aplikasi yang meminta
  • Informasi sistem seperti tanggal dan waktu saat Edge menerima permintaan
  • Data yang diperoleh saat kebijakan dijalankan. Misalnya, setelah kebijakan yang memvalidasi token OAuth dijalankan, Edge akan membuat variabel alur yang menyimpan informasi seperti nama aplikasi yang membuat permintaan.
  • Informasi tentang respons dari sistem target

Beberapa variabel "bawaan" Edge dan diisi secara otomatis setiap kali permintaan API diterima. Token ini tersedia di seluruh transaksi API. Anda juga dapat membuat variabel kustom sendiri menggunakan kebijakan seperti kebijakan AssignMessage, atau dalam kode JavaScript, Node.js, dan Java.

Seperti yang akan Anda lihat, variabel memiliki cakupan, dan tempat variabel dapat diakses sebagian bergantung pada waktu variabel dibuat dalam alur proxy API. Secara umum, saat variabel dibuat, variabel tersebut tersedia untuk semua kebijakan dan kode yang dieksekusi nanti dalam alur transaksi API.

Bagaimana variabel alur digunakan?

Variabel alur digunakan dalam kebijakan dan alur bersyarat:

  • Kebijakan dapat mengambil status dari variabel alur dan menggunakannya untuk melakukan tugasnya.

    Misalnya, kebijakan VerifyJWT dapat mengambil token yang akan diverifikasi dari variabel alur, lalu melakukan verifikasi padanya. Sebagai contoh lain, kebijakan JavaScript dapat mengambil variabel alur dan mengenkode data yang ada dalam variabel tersebut.

  • Flow bersyarat dapat mereferensikan variabel flow untuk mengarahkan flow API melalui Edge, mirip dengan cara kerja pernyataan switch dalam pemrograman.

    Misalnya, kebijakan untuk menampilkan error hanya dapat dieksekusi saat flow variable tertentu ditetapkan. Terakhir, Anda bisa mendapatkan dan menetapkan variabel alur di aplikasi target Node.js.

Mari kita lihat contoh penggunaan variabel dalam setiap konteks ini.

Variabel alur dalam kebijakan

Beberapa kebijakan menggunakan variabel aliran sebagai input.

Misalnya, kebijakan AssignMessage berikut mengambil nilai flow variable client.ip dan menempatkannya di header permintaan yang disebut My-Client-IP. Jika ditambahkan ke alur permintaan, kebijakan ini akan menetapkan header yang diteruskan ke target backend. Jika disetel pada alur response, header akan dikirim kembali ke aplikasi klien.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Sebagai contoh lain, saat kebijakan Kuota dijalankan, beberapa variabel alur diisi dengan nilai terkait kebijakan. Salah satu variabel ini disebut ratelimit.my-quota-policy.used.count (dengan my-quota-policy adalah nama kebijakan kuota yang Anda minati).

Anda dapat menjalankan alur bersyarat yang menyatakan "jika jumlah kuota saat ini di bawah 50% dari maksimum, dan antara pukul 09.00 hingga 17.00, terapkan kuota yang berbeda". Kondisi ini mungkin bergantung pada nilai jumlah kuota saat ini dan pada flow variable yang disebut system.time, yang merupakan salah satu variabel bawaan Edge.

Variabel alur dalam alur bersyarat

Alur bersyarat mengevaluasi variabel alur dan memungkinkan proxy berperilaku secara dinamis. Kondisi biasanya digunakan untuk mengubah perilaku alur, langkah, dan aturan rute.

Berikut adalah alur kondisional yang mengevaluasi nilai variabel request.verb dalam langkah alur proxy. Dalam hal ini, jika kata kerja permintaan adalah POST, kebijakan VerifyAPIKey akan dieksekusi. Ini adalah pola umum yang digunakan dalam konfigurasi proxy API.

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

Sekarang, Anda mungkin bertanya-tanya, dari mana variabel seperti request.verb, client.ip, dan system.time berasal? Kapan variabel tersebut di-instansiasi dan diisi dengan nilai? Untuk membantu Anda memahami kapan variabel dibuat dan kapan variabel tersedia untuk Anda, lihat Memahami cakupan variabel alur.

Variabel alur dalam kode JavaScript yang dipanggil dengan kebijakan JavaScript

Dengan kebijakan JavaScript, Anda dapat mengeksekusi kode JavaScript dari dalam konteks alur proxy API. JavaScript yang dieksekusi oleh kebijakan ini menggunakan model objek JavaScript Apigee, yang memberikan akses kode kustom Anda ke objek permintaan, respons, dan konteks yang terkait dengan alur proxy API tempat kode Anda dieksekusi. Misalnya, kode ini menetapkan header respons dengan nilai yang diperoleh dari flow variable target.name.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Teknik penggunaan JavaScript untuk membaca dan menyetel variabel ini mirip dengan pekerjaan yang dapat Anda lakukan dengan kebijakan AssignMessage (yang ditunjukkan sebelumnya). Ini hanyalah cara lain untuk melakukan hal yang sama di Edge. Yang perlu diingat adalah JavaScript yang dieksekusi oleh kebijakan JavaScript memiliki akses ke semua variabel alur yang ada dan berada dalam cakupan dalam alur proxy API.

Variabel alur dalam kode Node.js

Dengan mewajibkan modul apigee-access, Anda dapat menyetel dan mengakses variabel alur dari dalam kode Node.js yang di-deploy ke Edge.

Berikut adalah contoh sederhana saat variabel bernama custom.foo ditetapkan ke nilai Bar. Setelah ditetapkan, variabel baru ini akan tersedia untuk kebijakan atau kode lain yang terjadi dalam alur proxy setelah kode Node.js dieksekusi.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Anda dapat membaca selengkapnya tentang penggunaan apigee-access untuk menangani variabel di Mengakses variabel alur di Node.js.

Memahami cakupan variabel alur

Cakupan variabel terkait dengan alur atau keseluruhan "siklus proses" panggilan proxy API.

Memvisualisasikan alur proxy API

Untuk memahami cakupan flow variable, penting untuk memahami atau memvisualisasikan cara pesan mengalir melalui Proxy API. Proxy API terdiri dari serangkaian langkah pemrosesan pesan yang disusun sebagai alur. Di setiap langkah dalam alur proxy, proxy mengevaluasi informasi yang tersedia dan memutuskan apa yang harus dilakukan selanjutnya. Selama prosesnya, proxy dapat mengeksekusi kode kebijakan atau melakukan pencabangan bersyarat.

Gambar berikut menggambarkan urutan alur ini. Perhatikan bagaimana alur terdiri dari empat segmen utama: request ProxyEndpoint, request TargetEndpoint, response TargetEndpoint, dan response ProxyEndpoint.

Ingatlah struktur alur ini saat kita mulai mempelajari variabel alur di bagian lain topik ini.

Hubungan antara cakupan variabel dengan alur proxy

Segera setelah Anda dapat memvisualisasikan alur pesan melalui proxy, seperti yang dijelaskan sebelumnya, Anda dapat mulai memahami cakupan variabel. Menurut cakupan, yang kami maksud adalah titik dalam siklus proses alur proxy saat variabel pertama kali di-instantiate.

Misalnya, jika Anda memiliki kebijakan yang dilampirkan ke segmen permintaan ProxyEndpoint, kebijakan tersebut tidak akan dapat mengakses variabel apa pun yang dicakup ke segmen permintaan TargetEndpoint. Hal ini karena segmen permintaan TargetEndpoint dalam alur belum dieksekusi, sehingga proxy API belum berkesempatan untuk mengisi variabel dalam cakupan tersebut.

Tabel berikut mencantumkan kumpulan lengkap cakupan variabel dan menunjukkan kapan variabel tersebut tersedia dalam alur proxy.

Cakupan variabel Tempat variabel ini diisi
permintaan proxy Segmen permintaan ProxyEndpoint
permintaan target Segmen permintaan TargetEndpoint
respons target Segmen respons TargetEndpoint
respons proxy Segmen respons ProxyEndpoint
selalu tersedia Segera setelah proxy menerima permintaan. Variabel ini tersedia di seluruh siklus proses proxy.

Misalnya, ada variabel Edge bawaan yang disebut client.ip. Variabel ini memiliki cakupan "permintaan proxy". Kolom ini otomatis diisi dengan alamat IP klien yang memanggil proxy. Variabel ini diisi saat permintaan pertama kali mencapai ProxyEndpoint dan tetap tersedia selama siklus proses alur proxy.

Ada variabel bawaan lain yang disebut target.url. Cakupan variabel ini adalah "permintaan penargetan". Bagian permintaan TargetEndpoint ini diisi dengan URL permintaan yang dikirim ke target backend. Jika Anda mencoba mengakses target.url di segmen permintaan ProxyEndpoint, Anda akan menerima nilai NULL. Jika Anda mencoba menyetel variabel ini sebelum berada dalam cakupan, proxy tidak melakukan apa pun—tidak menghasilkan error dan tidak menyetel variabel.

Berikut adalah contoh sederhana yang menunjukkan cara memahami cakupan variabel. Misalnya, Anda ingin menyalin seluruh konten objek permintaan (header, parameter, isi) dan menetapkannya ke payload respons untuk dikirim kembali ke aplikasi yang memanggil. Anda dapat menggunakan kebijakan AssignMessage untuk tugas ini. Kode kebijakan akan terlihat seperti ini:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Kebijakan ini hanya menyalin objek request dan menetapkannya ke objek response. Namun, di mana kebijakan ini harus ditempatkan dalam alur proxy? Jawabannya adalah bahwa variabel tersebut harus ditempatkan pada respons TargetEndpoint, karena cakupan variabel respons adalah "target response".

Mereferensikan variabel alur

Semua variabel bawaan di Apigee Edge mengikuti konvensi penamaan notasi titik. Konvensi ini memudahkan penentuan tujuan variabel. Misalnya system.time.hour dan request.content.

Apigee mencadangkan berbagai awalan untuk mengatur variabel yang relevan dengan tepat. Awalan ini mencakup:

  • request
  • response
  • system
  • target

Untuk mereferensikan variabel dalam kebijakan, sertakan dalam tanda kurung kurawal. Misalnya, kebijakan AssignMessage berikut mengambil nilai variabel client.ip dan menempatkannya di header permintaan yang disebut Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Dalam alur bersyarat, tanda kurung kurawal tidak diperlukan. Kondisi contoh berikut mengevaluasi variabel request.header.accept:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Anda juga dapat mereferensikan variabel alur dalam kode JavaScript dan Java. Untuk informasi selengkapnya, lihat:

Jenis data variabel alur

Setiap properti flow variable memiliki jenis data yang ditentukan dengan baik, seperti String, Long, Integer, Boolean, atau Kumpulan. Anda dapat menemukan jenis data yang tercantum dalam Referensi variabel alur. Untuk variabel yang dibuat oleh kebijakan, lihat topik referensi kebijakan tertentu untuk mengetahui informasi jenis data.

Variabel yang Anda buat secara manual mengasumsikan jenis yang diberikan saat dibuat, dan bergantung pada jenis nilai yang diizinkan. Misalnya, variabel yang dibuat dalam kode Node.js dibatasi ke Number, String, Boolean, null, atau undefined.

Menggunakan variabel alur dalam kebijakan

Banyak kebijakan membuat variabel alur sebagai bagian dari eksekusi normalnya. Dokumen Referensi kebijakan mencantumkan semua variabel khusus kebijakan ini.

Saat Anda menggunakan proxy dan kebijakan, pastikan untuk melihat referensi kebijakan untuk mengetahui variabel mana yang dibuat dan untuk apa variabel tersebut digunakan. Misalnya, Kebijakan kuota membuat serangkaian variabel yang berisi informasi tentang jumlah dan batas kuota, waktu habis masa berlaku, dan sebagainya.

Beberapa variabel kebijakan berguna untuk men-debug. Misalnya, Anda dapat menggunakan alat Trace tool untuk melihat variabel mana yang ditetapkan pada instance tertentu dalam alur proxy.

Kebijakan ExtractVariables memungkinkan Anda mengisi variabel kustom dengan data yang diekstrak dari pesan. Anda dapat mengekstrak parameter kueri, header, dan data lainnya. Misalnya, Anda dapat mengurai pesan permintaan dan respons menggunakan pola untuk mengekstrak data tertentu dari pesan.

Dalam contoh berikut, Extract Variables mengurai pesan respons dan menyimpan data tertentu yang diambil dari respons. Kebijakan membuat dua variabel kustom, geocoderesponse.latitude dan geocoderesponse.longitude, serta menetapkan nilai ke variabel tersebut.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Sekali lagi, perlu diketahui bahwa banyak kebijakan otomatis membuat variabel. Anda dapat mengakses variabel tersebut dalam konteks alur proxy, dan variabel tersebut didokumentasikan dalam referensi Kebijakan di setiap topik kebijakan.

Menggunakan variabel alur dalam kode JavaScript

Anda dapat mengakses dan menetapkan variabel langsung dalam kode JavaScript yang dieksekusi dalam konteks proxy API. Melalui model objek JavaScript Apigee, JavaScript yang dieksekusi di Edge memiliki akses langsung ke variabel alur proxy.

Untuk mengakses variabel dalam kode JavaScript, panggil metode getter/setter pada salah satu objek berikut:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Seperti yang dapat Anda lihat, referensi objek ini dipetakan ke segmen model alur proxy yang sudah dikenal seperti yang dijelaskan sebelumnya dalam Memvisualisasikan alur proxy API.

Objek context sesuai dengan variabel yang tersedia "secara global", seperti variabel sistem. Misalnya, Anda dapat memanggil getVariable() pada objek context untuk mendapatkan tahun saat ini:

var year = context.getVariable('system.time.year');

Demikian pula, Anda dapat memanggil setVariable() untuk menetapkan nilai variabel kustom atau untuk variabel bawaan dapat ditulis. Di sini, kita membuat variabel kustom bernama organization.name.myorg dan menetapkan nilai padanya.

var org = context.setVariable('organization.name.myorg', value);

Karena variabel ini dibuat dengan objek context, variabel ini akan tersedia untuk semua segmen alur (pada dasarnya, ini seperti membuat variabel global).

Anda juga dapat mendapatkan/menetapkan variabel alur proxy dalam kode Java yang Anda jalankan dengan kebijakan JavaCallout.

Mengakses variabel alur di aplikasi Node.js

Anda dapat mengambil, menyetel, dan menghapus variabel alur dari kode Node.js yang di-deploy ke Edge. Yang perlu Anda lakukan adalah "memerlukan" modul apigee-access dalam kode Anda. Untuk mengetahui detailnya, lihat Mengakses variabel alur di Node.js.

Yang perlu Anda ingat

Berikut beberapa hal penting yang perlu diingat tentang variabel alur:

  • Beberapa variabel "langsung pakai" di-instansiasi dan diisi secara otomatis oleh proxy itu sendiri. Hal ini didokumentasikan dalam Referensi variabel alur.
  • Anda dapat membuat variabel kustom yang tersedia untuk digunakan dalam alur proxy. Anda dapat membuat variabel menggunakan kebijakan seperti kebijakan AssignMessage dan kebijakan JavaScript, dan di kode Node.js.
  • Variabel memiliki cakupan. Misalnya, beberapa variabel diisi secara otomatis saat proxy pertama menerima permintaan dari aplikasi. Variabel lainnya diisi di segmen alur respons proxy. Variabel respons ini tetap tidak ditentukan hingga segmen respons dieksekusi.
  • Saat dijalankan, kebijakan dapat membuat dan mengisi variabel khusus kebijakan. Dokumentasi untuk setiap kebijakan mencantumkan semua variabel spesifik per kebijakan yang relevan ini.
  • Alur bersyarat biasanya mengevaluasi satu atau beberapa variabel. Anda perlu memahami variabel jika ingin membuat alur bersyarat.
  • Banyak kebijakan menggunakan variabel sebagai input atau output. Mungkin variabel yang dibuat oleh satu kebijakan kemudian digunakan oleh kebijakan lain.
  • Anda dapat mengambil dan menyetel banyak variabel alur dari dalam Node.js menggunakan JavaScript langsung (dan model objek JavaScript kami) atau kebijakan JavaCallout, yang menjalankan kode di Edge.

Contoh kode terkait

Contoh proxy API ada di GitHub dan mudah didownload serta digunakan. Lihat Menggunakan proxy API contoh untuk informasi tentang cara mendownload dan menggunakan contoh. Lihat Daftar contoh untuk mengetahui deskripsi contoh proxy API dan fungsinya.

Contoh proxy yang menampilkan penggunaan variabel dan pemrosesan variabel meliputi:

  • variables - Menunjukkan cara mengekstrak dan menetapkan variabel berdasarkan konten pesan JSON dan XML serta transport.
  • policy-mashup-cookbook - Aplikasi lengkap yang menggunakan komposisi kebijakan untuk memanggil dua API publik, menggabungkan hasil, dan membuat respons yang lebih baik untuk aplikasi klien. Untuk mengetahui informasi selengkapnya tentang contoh ini, lihat Menggunakan komposisi kebijakan.
  • conditional-policy - Menerapkan penerapan kebijakan bersyarat sederhana berdasarkan nilai variabel.

Topik terkait

  • Semua variabel yang otomatis diisi di proxy API tercantum dalam Referensi variabel alur. Referensi ini juga mencantumkan jenis dan cakupan setiap variabel.
  • Jika Anda ingin mengetahui variabel mana yang diisi oleh kebijakan tertentu, lihat topik referensi untuk kebijakan tersebut. Misalnya, lihat Variabel alur dalam referensi Kebijakan kuota.