Menggunakan variabel alur

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

Secara konseptual, variabel flow adalah objek yang dapat diakses dari dalam kebijakan atau utilitas (seperti alat alat Trace). Fungsi ini memungkinkan Anda mempertahankan status yang terkait dengan Transaksi API diproses oleh Apigee Edge.

Apa itu variabel alur?

Variabel alur ada dalam konteks alur proxy API, dan variabel ini melacak status di API transaksi dengan cara variabel bernama melacak status dalam program perangkat lunak. Penyimpanan variabel flow informasi pribadi, 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 dieksekusi yang memvalidasi token OAuth, Edge membuat variabel alur yang menyimpan informasi seperti nama permintaan aplikasi.
• Informasi tentang respons dari sistem target

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

Seperti yang akan Anda lihat, variabel memiliki cakupan, dan tempat variabel tersebut dapat diakses sebagian bergantung pada kapan variabel tersebut dapat diakses dibuat di alur proxy API. Secara umum, ketika variabel dibuat, variabel itu tersedia untuk semua kebijakan dan kode yang nantinya dijalankan dalam alur transaksi API.

Bagaimana variabel alur digunakan?

Variabel flow digunakan dalam kebijakan dan alur bersyarat:

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

  Misalnya, kebijakan VerifikasiJWT dapat mengambil token yang akan diverifikasi dari variabel {i>flow<i} dan kemudian melakukan verifikasi terhadapnya. Sebagai contoh lain, Kebijakan JavaScript dapat mengambil variabel alur dan mengenkode data yang terdapat dalam variabel-variabel tersebut.

• Alur bersyarat dapat mereferensikan variabel alur untuk mengarahkan alur API melalui Edge, seperti cara kerja pernyataan {i>switch<i} dalam pemrograman.

  Misalnya, kebijakan untuk mengembalikan kesalahan mungkin dieksekusi hanya ketika variabel {i>flow<i} tertentu atur. Terakhir, Anda bisa mendapatkan dan menetapkan variabel alur dalam aplikasi target Node.js.

Mari kita lihat contoh bagaimana variabel digunakan dalam masing-masing konteks.

Variabel alur dalam kebijakan

Beberapa kebijakan berjalan variabel sebagai input.

Misalnya, kebijakan MenetapkanMessage berikut mengambil nilai variabel flow client.ip dan menempatkannya dalam header permintaan disebut My-Client-IP. Jika ditambahkan ke alur permintaan, kebijakan ini akan menetapkan header yang diteruskan ke target backend. Jika ditetapkan 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>

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

Anda mungkin nanti dapat mengeksekusi alur bersyarat yang mengatakan "jika jumlah kuota saat ini di bawah 50% dari maksimum, dan antara pukul 9 pagi dan 5 sore, menerapkan kuota yang berbeda." Kondisi ini mungkin bergantung pada nilai jumlah kuota saat ini dan pada variabel flow yang disebut system.time, yang merupakan salah satu Edge bawaan variabel.

Variabel flow dalam kondisional alur

Alur bersyarat mengevaluasi variabel alur dan memungkinkan {i>proxy<i} berperilaku dinamis. Kondisi yang biasanya digunakan untuk mengubah perilaku alur, langkah, dan aturan rute.

Berikut ini adalah alur kondisional yang mengevaluasi nilai variabel request.verb dalam langkah alur proxy. Dalam hal ini, jika kata kerja permintaan adalah POST, kebijakan VerifyAPIKey dijalankan. Ini adalah pola yang umum 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, di mana letak variabel seperti request.verb, client.ip, dan system.time berasal? Kapan mereka dibuat instance-nya dan diisi dengan nilai? Untuk membantu Anda memahami kapan variabel dibuat dan kapan variabel tersebut dibuat yang tersedia untuk Anda, lihat Memahami variabel alur cakupan.

Variabel alur dalam kode JavaScript yang dipanggil dengan JavaScript kebijakan

Dengan kebijakan JavaScript, Anda dapat mengeksekusi kode JavaScript dari dalam konteks Alur proxy API. JavaScript yang dijalankan oleh kebijakan ini menggunakan Apigee model objek JavaScript, yang menyediakan 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 variabel flow target.name.

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

Teknik menggunakan JavaScript untuk membaca dan menetapkan variabel ini mirip dengan pekerjaan yang dapat Anda lakukan dengan kebijakan TetapkanMessage (ditampilkan sebelumnya). Ini hanyalah cara lain untuk melakukan hal yang sama di Edge. Kunci yang perlu diingat adalah JavaScript yang dijalankan oleh kebijakan JavaScript memiliki akses ke semua variabel alur yang ada dan berada dalam cakupan dalam alur proxy API.

Variabel flow dalam kode Node.js

Dengan mewajibkan modul apigee-access, Anda dapat menetapkan 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 lainnya yang terjadi di 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 cara menggunakan apigee-access untuk menangani variabel dalam Mengakses variabel alur di Node.js.

Memahami cakupan variabel flow

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

Memvisualisasikan alur proxy API

Untuk memahami cakupan variabel alur, penting untuk memahami atau memvisualisasikan cara pesan melalui proxy API. Proxy API terdiri dari serangkaian langkah pemrosesan pesan diatur sebagai alur. Pada setiap langkah dalam alur {i>proxy<i}, {i>proxy<i} mengevaluasi informasi yang tersedia untuk dan memutuskan apa yang harus dilakukan selanjutnya. Dalam prosesnya, proxy dapat mengeksekusi kode kebijakan atau menjalankan percabangan bersyarat.

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

Ingatlah struktur alur ini saat kita mulai mengeksplorasi variabel aliran melalui topik ini.

Cara cakupan variabel terkait dengan alur proxy

Segera setelah Anda bisa memvisualisasikan bagaimana pesan mengalir melalui {i>proxy<i}, seperti yang dijelaskan sebelumnya, Anda dapat mulai memahami ruang lingkup variabel. Yang kami maksud dengan cakupan adalah titik dalam siklus proses alur proxy ketika variabel pertama kali dibuatkan instance-nya.

Misalnya, jika Anda memiliki kebijakan yang dilampirkan pada segmen permintaan ProxyEndpoint, kebijakan tersebut tidak akan dapat mengakses variabel yang yang tercakup dalam segmen permintaan TargetEndpoint. Alasannya adalah bahwa TargetEndpoint segmen permintaan alur belum dieksekusi, sehingga proxy API belum memiliki kesempatan mengisi variabel-variabel dalam cakupan itu.

Tabel berikut mencantumkan rangkaian lengkap cakupan variabel dan menunjukkan kapan berada di proxy yang tersedia.

Misalnya, ada variabel Edge bawaan yang disebut client.ip. Variabel ini memiliki "permintaan proxy" ruang lingkup proyek. Secara otomatis, alamat IP klien yang yang disebut {i>proxy<i}. Kolom ini diisi saat permintaan pertama kali mencapai ProxyEndpoint dan tetap tersedia di seluruh siklus proses aliran proxy.

Ada variabel bawaan lain yang disebut target.url. Cakupan variabel ini adalah "permintaan target". Kolom ini diisi di segmen permintaan TargetEndpoint dengan URL permintaan yang dikirim ke target back-end. Jika Anda mencoba mengakses target.url di permintaan ProxyEndpoint Anda akan menerima nilai NULL. Jika Anda mencoba menetapkan variabel ini sebelum berada dalam ruang lingkup, proxy tidak melakukan apa pun—tidak menghasilkan error dan tidak menetapkan variabel.

Berikut adalah contoh sederhana yang menunjukkan cara berpikir tentang ruang lingkup variabel. Misalnya Anda ingin untuk menyalin seluruh konten objek permintaan (header, parameter, isi) dan menetapkannya ke payload respons untuk dikirim kembali ke aplikasi pemanggil. Anda dapat menggunakan kebijakan TetapkanMessage untuk untuk melakukan 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? Tujuan jawabannya harus ditempatkan pada respons TargetEndpoint, karena cakupan variabel responsnya adalah "respons target".

Mereferensikan variabel alur

Semua variabel bawaan di Apigee Edge mengikuti konvensi penamaan notasi titik. Konvensi ini membuatnya lebih mudah untuk menentukan tujuan variabel. Misalnya system.time.hour dan request.content.

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

• request
• response
• system
• target

Untuk mereferensikan variabel dalam kebijakan, sertakan variabel dalam tanda kurung kurawal. Misalnya, kebijakan MenetapkanMessage berikut mengambil nilai variabel client.ip dan memasukkannya ke 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. Contoh kondisi 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 JavaScript dan kode Java. Untuk informasi selengkapnya, lihat:

• Menggunakan variabel di JavaScript
• Mengakses variabel alur di Node.js
• Kebijakan JavaScript

Jenis data variabel aliran

Setiap properti variabel alur memiliki tipe data yang terdefinisi dengan baik, seperti String, Panjang, Bilangan Bulat, Boolean, atau Koleksi. Anda dapat menemukan tipe data yang tercantum pada Referensi variabel flow. Untuk variabel yang dibuat oleh kebijakan, lihat topik referensi kebijakan tertentu untuk informasi jenis data.

Variabel yang Anda buat mengasumsikan jenis yang diberikan secara manual saat dibuat, dan bergantung jenis nilai yang diizinkan. Misalnya, variabel yang dibuat di kode Node.js terbatas pada Number, String, Boolean, null, atau undefined (tidak ditentukan).

Menggunakan variabel alur dalam kebijakan

Banyak kebijakan membuat variabel alur sebagai bagian dari eksekusi normalnya. Dokumen Referensi kebijakan semua variabel spesifik per kebijakan ini.

Saat Anda bekerja dengan {i>proxy<i} dan kebijakan, pastikan untuk berkonsultasi referensi kebijakan untuk mengetahui variabel mana yang dibuat dan untuk apa penggunaannya. Sebagai misalnya, Kebijakan kuota membuat kumpulan variabel yang berisi informasi tentang jumlah kuota batas waktu, tanggal habis masa berlaku, dan seterusnya.

Beberapa variabel kebijakan berguna untuk proses debug. Anda dapat menggunakan alat alat Trace, misalnya, untuk melihat variabel mana yang ditetapkan pada {i>instance <i}tertentu dalam alur {i>proxy<i}.

Kebijakan ExtractVariables memungkinkan Anda mengisi variabel kustom dengan data yang diekstrak dari pesan. Anda dapat mengekstrak kueri parameter, {i>header<i}, 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 ini membuat dua variabel kustom, geocoderesponse.latitude dan geocoderesponse.longitude, dan menetapkan nilai kepada mereka.

<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, perhatikan bahwa ada banyak kebijakan yang secara otomatis membuat variabel. Anda dapat mengaksesnya variabel dalam konteks alur proxy, dan didokumentasikan dalam referensi Kebijakan di setiap topik kebijakan.

Bekerja dengan variabel alur dalam kode JavaScript

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

Untuk mengakses variabel dalam kode JavaScript, panggil metode pengambil/penyetel 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 di Memvisualisasikan alur proxy API.

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

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

Demikian pula, Anda dapat memanggil setVariable() untuk menetapkan nilai variabel khusus atau untuk variabel siap pakai yang dapat ditulis. Di sini, kita membuat variabel khusus yang disebut organization.name.myorg, lalu tetapkan nilai pada kolom tersebut.

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

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

Anda juga bisa mendapatkan/menyetel variabel alur proxy dalam kode Java yang Anda eksekusi dengan Kebijakan JavaKeterangan.

Mengakses variabel alur di aplikasi Node.js

Anda bisa mendapatkan, menyetel, dan menghapus variabel alur dari kode Node.js yang di-deploy ke Edge. Semua yang Anda butuhkan harus dilakukan adalah "{i>require<i}" modul akses-apigee dalam kode Anda. Untuk mengetahui detailnya, lihat Mengakses variabel alur di Node.js.

Yang perlu Anda ingat

Berikut adalah beberapa hal penting yang perlu diingat tentang variabel alur:

• Beberapa hal yang "siap pakai" variabel dibuat instance-nya dan diisi secara otomatis oleh proxy itu sendiri. Hal ini didokumentasikan dalam Referensi variabel flow.
• Anda dapat membuat variabel kustom yang tersedia untuk digunakan dalam alur proxy. Sangat mungkin untuk membuat variabel menggunakan kebijakan seperti kebijakan TetapkanMessage dan kebijakan JavaScript, serta dalam kode Node.js.
• Variabel memiliki ruang lingkup. Misalnya, beberapa variabel diisi secara otomatis saat {i>proxy<i} pertama menerima permintaan dari aplikasi. Variabel lain diisi dalam alur respons segmen {i>proxy<i}. Variabel respons ini tetap tidak terdefinisi sampai segmen respons akan dijalankan.
• Saat dijalankan, kebijakan dapat membuat dan mengisi variabel khusus kebijakan. Tujuan dokumentasi untuk setiap kebijakan mencantumkan semua variabel spesifik per kebijakan yang relevan.
• 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 kebijakan tersebut kemudian digunakan oleh pihak lain.
• Anda dapat memperoleh dan menetapkan banyak variabel alur dari dalam Node.js menggunakan JavaScript langsung (dan model objek JavaScript) atau kebijakan Java callout, yang menjalankan kode di Edge.

Contoh kode terkait

Contoh proxy API ada di GitHub dan mudah didownload serta gunakan. Lihat Menggunakan proxy API contoh untuk informasi tentang mengunduh dan menggunakan contoh. Lihat Daftar contoh untuk deskripsi API contoh {i>proxy<i} dan apa yang mereka lakukan.

{i>Proxy<i} contoh yang menampilkan penggunaan variabel dan pemrosesan variabel meliputi:

• variabel - Mendemonstrasikan cara mengekstrak dan menetapkan variabel berdasarkan transpor serta pesan JSON dan XML saat ini.
• policy-mashup-cookbook - Aplikasi lengkap yang menggunakan komposisi kebijakan untuk memanggil dua API publik, menggabungkan hasil, dan menghasilkan respons yang diperkaya untuk klien . Untuk informasi selengkapnya tentang contoh ini, lihat Menggunakan kebijakan komposisi.
• kebijakan-kondisional - Menerapkan penerapan kebijakan bersyarat sederhana berdasarkan nilai variabel.

Topik terkait

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