Menggunakan variabel alur

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Variabel flow adalah objek yang dapat Anda akses dari dalam kebijakan atau utilitas (seperti Alat debug). API ini memungkinkan Anda mempertahankan status yang terkait dengan transaksi API yang diproses oleh Apigee.

Mulai Cepat: Untuk mengetahui daftar lengkap semua variabel alur dan propertinya, lihat Referensi variabel flow.

Video

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

Video berikut memberikan pengantar variabel alur:

Apa yang dimaksud dengan variabel alur?

Variabel alur tersedia dalam konteks alur proxy API, dan variabel tersebut melacak status dalam transaksi API dengan 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 Apigee menerima permintaan
• Data yang diperoleh saat kebijakan dieksekusi. Contohnya, setelah kebijakan yang memvalidasi token OAuth dieksekusi, Apigee akan membuat variabel alur yang menyimpan informasi seperti nama aplikasi yang meminta.
• Informasi tentang respons dari sistem target

Beberapa variabel merupakan bawaan pada Apigee dan diisi secara otomatis setiap kali permintaan API diterima. Fitur ini tersedia di seluruh transaksi API. Anda juga dapat membuat variabel kustom sendiri menggunakan kebijakan seperti kebijakanAssignMessage, atau dalam kode JavaScript dan Java.

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

Bagaimana variabel alur digunakan?

Variabel alur digunakan dalam kebijakan dan alur kondisional:

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

  Misalnya, kebijakan VerifyJWT dapat mengambil token yang akan diverifikasi dari variabel flow, lalu melakukan verifikasi pada token tersebut. Sebagai contoh lainnya, kebijakan JavaScript dapat mengambil variabel alur dan mengenkode data yang terdapat dalam variabel tersebut.

• Alur bersyarat dapat mereferensikan variabel alur untuk mengarahkan alur API melalui Apigee, mirip dengan cara kerja pernyataan switch dalam pemrograman.

  Misalnya, kebijakan untuk menampilkan kesalahan mungkin hanya dijalankan jika variabel alur tertentu ditetapkan.

Mari kita lihat contoh bagaimana variabel digunakan di setiap konteks ini.

Variabel alur dalam kebijakan

Beberapa kebijakan menggunakan variabel alur sebagai input.

Misalnya, kebijakanAssignMessage berikut mengambil nilai variabel alur client.ip dan memasukkannya ke header permintaan yang disebut My-Client-IP. Jika ditambahkan ke alur request, 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 terkait kebijakan. Salah satu variabel ini disebut ratelimit.my-quota-policy.used.count (dengan my-quota-policy adalah nama kebijakan Kuota yang Anda minati).

Kemudian, Anda dapat menjalankan alur kondisional yang mengatakan "jika jumlah kuota saat ini di bawah 50% dari maksimum, dan saat ini antara pukul 09.00 dan 17.00, terapkan kuota yang berbeda". Kondisi ini mungkin bergantung pada nilai jumlah kuota saat ini dan pada variabel alur yang disebut system.time, yang merupakan salah satu variabel Apigee bawaan.

Variabel flow 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 bersyarat 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 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 asal variabel seperti request.verb, client.ip, dan system.time? Kapan instance dan diisi dengan nilai? Untuk membantu memahami kapan variabel dibuat dan kapan variabel tersedia untuk Anda, lihat Memvisualisasikan alur proxy API.

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 dijalankan oleh kebijakan ini menggunakan model objek JavaScript Apigee, yang memberi Anda akses kode kustom ke objek permintaan, respons, dan konteks yang terkait dengan alur proxy API tempat kode Anda dijalankan. Misalnya, kode ini menetapkan header respons dengan nilai yang diperoleh dari variabel alur target.name.

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

Teknik menggunakan JavaScript untuk membaca dan menetapkan variabel ini mirip dengan cara kerja yang dapat Anda lakukan dengan kebijakanAssignMessage (ditampilkan sebelumnya). Ini hanyalah cara lain untuk melakukan hal yang sama di Apigee. 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.

Memvisualisasikan alur proxy API

Untuk memahami cakupan variabel alur, penting untuk memahami atau memvisualisasikan cara pesan mengalir melalui proxy API. Proxy API terdiri dari serangkaian langkah pemrosesan pesan yang disusun sebagai alur. Pada setiap langkah dalam alur proxy, proxy akan mengevaluasi informasi yang tersedia untuknya dan memutuskan tindakan yang harus dilakukan selanjutnya. Selama prosesnya, proxy dapat mengeksekusi kode kebijakan atau melakukan percabangan bersyarat.

Gambar berikut mengilustrasikan 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 untuk menelusuri seluruh topik ini.

Bacaan Lebih Lanjut Jika Anda ingin membaca struktur alur proxy secara lebih mendetail, lihat Mengonfigurasi flow.

Bagaimana cakupan variabel terkait dengan alur proxy

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

Misalnya, jika Anda memiliki kebijakan yang disertakan pada segmen permintaan ProxyEndpoint, kebijakan tersebut tidak akan dapat mengakses variabel apa pun yang dicakupkan ke segmen permintaan TargetEndpoint. Alasannya adalah karena segmen permintaan TargetEndpoint dari alur belum dijalankan, sehingga proxy API belum berkesempatan mengisi variabel dalam cakupan tersebut.

Tabel berikut berisi daftar lengkap cakupan variabel dan menunjukkan kapan variabel tersebut akan tersedia dalam alur proxy.

Catatan: Setelah variabel flow diisi dalam cakupan yang diberikan, variabel tersebut akan tetap tersedia hingga sisa siklus proses alur proxy. Jika mencoba mengakses variabel yang belum berada dalam cakupan, Anda akan menerima error atau nilai NULL.

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

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

Catatan: Cakupan untuk semua variabel Apigee bawaan dicantumkan dalam Referensi variabel flow.

Ada variabel bawaan lain bernama 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 segmen permintaan ProxyEndpoint, Anda akan menerima nilai NULL. Jika Anda mencoba menetapkan variabel ini sebelum berada dalam cakupan, proxy tidak akan melakukan apa pun—tidak menghasilkan error dan tidak menyetel variabel tersebut.

Catatan: Beberapa kebijakan dapat dikonfigurasi agar memunculkan error atau menampilkan NULL saat variabel yang tidak ditentukan diakses. Lihat masing-masing halaman referensi kebijakan untuk mengetahui detailnya.

Berikut adalah contoh sederhana yang menunjukkan bagaimana memikirkan tentang ruang lingkup variabel. Misalkan Anda ingin menyalin seluruh konten objek permintaan (header, parameter, isi) dan menetapkannya ke payload respons untuk dikirim kembali ke aplikasi pemanggil. Anda dapat menggunakan kebijakanAssignMessage 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. Tetapi di mana kebijakan ini harus ditempatkan dalam alur {i>proxy<i}? Jawabannya adalah harus ditempatkan pada respons TargetEndpoint, karena cakupan variabel respons adalah target respons.

Mereferensikan variabel alur

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

Praktik Terbaik: Google merekomendasikan agar Anda menggunakan konvensi penamaan notasi titik saat membuat variabel alur kustom. Sebaiknya gunakan titik untuk mengatur hierarki variabel kustom Anda.

Misalnya, approval.code dan approval.status mungkin merujuk pada fitur persetujuan dalam alur.

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

• request
• response
• system
• target

Untuk mereferensikan variabel dalam kebijakan, apit variabel tersebut dalam tanda kurung kurawal. Misalnya, kebijakanAssignMessage 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 kode JavaScript dan Java. Untuk informasi selengkapnya, lihat:

• Menangani variabel alur dalam kode JavaScript
• Kebijakan JavaScript

Jenis data variabel alur

Setiap properti variabel flow memiliki jenis data yang terdefinisi dengan baik, seperti String, Long, Integer, Boolean, atau Collection. Anda dapat menemukan jenis data yang tercantum di Referensi variabel flow. Untuk variabel yang dibuat oleh kebijakan, lihat topik referensi kebijakan tertentu untuk informasi jenis data.

Variabel yang Anda buat secara manual mengasumsikan jenis yang diberikan saat dibuat, dan bergantung pada jenis nilai yang diizinkan.

Menggunakan variabel alur dalam kebijakan

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

Saat Anda bekerja dengan proxy dan kebijakan, pastikan untuk membaca referensi kebijakan guna mengetahui variabel mana yang dibuat dan tujuan penggunaannya. Misalnya, Kebijakan kuota membuat sekumpulan variabel yang berisi informasi tentang jumlah dan batas kuota, waktu habis masa berlaku, dan sebagainya.

Beberapa variabel kebijakan berguna untuk proses debug. Misalnya, Anda dapat menggunakan Alat debug), 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.

Pada contoh berikut, kebijakan ExtractVariables akan mengurai pesan respons dan menyimpan data spesifik yang diambil dari respons. Kebijakan ini membuat dua variabel kustom, geocoderesponse.latitude dan geocoderesponse.longitude, lalu menetapkan nilai pada 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, perhatikan bahwa banyak kebijakan membuat variabel secara otomatis. Anda dapat mengakses variabel tersebut dalam konteks alur proxy, dan variabel tersebut didokumentasikan dalam referensi Kebijakan pada masing-masing topik kebijakan.

Bekerja dengan variabel alur dalam kode JavaScript

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

Catatan: Anda dapat memanggil JavaScript dari proxy menggunakan kebijakan JavaScript.

Untuk mengakses variabel dalam kode JavaScript, panggil metode pengambil/penyetel pada salah satu objek ini:

• 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 berjalan:

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

Demikian pula, Anda dapat memanggil setVariable() untuk menetapkan nilai variabel kustom atau untuk variabel bawaan apa pun yang dapat ditulis. Di sini, kita membuat variabel kustom yang disebut organization.name.myorg dan menetapkan nilai pada variabel 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).

Catatan: Referensi variabel flow menunjukkan variabel mana yang dapat ditulis dan mana yang bersifat hanya baca. Untuk mengetahui informasi selengkapnya, lihat model objek JavaScript.

Anda juga bisa mendapatkan atau menetapkan variabel alur proxy dalam kode Java yang dijalankan dengan kebijakan JavaCallout.

Yang perlu diingat

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

• Beberapa variabel out-of-the-box 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 di alur proxy. Anda dapat membuat variabel menggunakan kebijakan seperti kebijakanAssignMessage dan kebijakan JavaScript.
• Variabel memiliki ruang lingkup. Misalnya, beberapa variabel akan diisi secara otomatis saat proxy pertama menerima permintaan dari aplikasi. Variabel lainnya akan diisi di segmen alur respons proxy. Variabel respons ini tetap tidak ditentukan hingga segmen respons dieksekusi.
• Saat dijalankan, kebijakan dapat membuat dan mengisi variabel spesifik per kebijakan. Dokumentasi untuk setiap kebijakan mencantumkan semua variabel khusus kebijakan yang relevan ini.
• Alur bersyarat biasanya mengevaluasi satu atau beberapa variabel. Anda perlu memahami variabel jika ingin membuat flow bersyarat.
• Banyak kebijakan menggunakan variabel sebagai input atau output. Mungkin variabel yang dibuat oleh satu kebijakan nantinya digunakan oleh kebijakan lain.

Tips: Anda akan menemukan sejumlah sampel yang menggunakan variabel dengan berbagai cara. Cari variabel yang menggunakan kebijakan ExtractVariables, yang biasa digunakan untuk memproses variabel dalam alur proxy.

Topik terkait

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