Kebijakan KeyValueMapOperations

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Apa

Menyediakan akses berbasis kebijakan ke penyimpanan peta nilai kunci (KVM) yang tersedia di Apigee. Key/value pair dapat disimpan, diambil, dan dihapus dari peta bernama yang ada dengan mengonfigurasi kebijakan KeyValueMapOperations yang masing-masing menentukan operasi PUT, GET, atau DELETE. (Setidaknya salah satu operasi ini harus dilakukan oleh kebijakan.)

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Catatan: Mulai dari rilis Apigee Hybrid versi 1.4.0, Apigee mengenkripsi semua KVM secara default. Gunakan atribut private. dengan semua variabel saat mengakses KVM dengan perintah GET untuk menyembunyikan informasi KVM dalam sesi Debug. Jika atribut private. tidak digunakan, KVM tetap dienkripsi; namun, informasi KVM akan muncul dalam bentuk yang didekripsi di sesi Debug dan tidak ada pengecualian yang akan ditampilkan.

Video: Video berikut memberikan pengantar tingkat tinggi tentang KVM.

Sampel

PUT KVM dengan literal

Saat kebijakan berikut dijalankan, kebijakan tersebut akan membuat KVM terenkripsi bernama FooKVM, lalu membuat kunci bernama FooKey_1 dengan dua nilai yang ditetapkan dengan string literal foo dan bar (tidak ditetapkan dengan nilai yang diekstrak dari variabel). Saat Anda GET kunci dalam contoh berikutnya, Anda menentukan nomor indeks untuk mengambil nilai yang Anda inginkan.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

Perhatikan bahwa cakupannya adalah environment. Artinya, Anda dapat melihat KVM di UI pengelolaan di bagian APIs > Environment Configuration > Key Value Maps. KVM yang ditampilkan di halaman tersebut semuanya dicakup ke lingkungan yang dipilih.

MENDAPATKAN KVM dari literal

Kebijakan ini melihat peta FooKVM dari contoh sebelumnya, mendapatkan nilai kedua (index="2") dari kunci FooKey_1, dan menyimpannya dalam variabel yang disebut foo_variable.

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

Mengakses KVM secara dinamis

Kebijakan ini menggunakan elemen <MapName> untuk mereferensikan KVM secara dinamis dengan variabel alur. Elemen mendapatkan ID KVM dari variabel alur. Perhatikan bahwa atribut mapIdentifier dihilangkan; Anda tidak dapat menggunakan <MapName> dengan atribut mapIdentifier.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <MapName ref="flow.variable"/>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

PUT KVM dengan variabel

Contoh sederhana KVM yang berguna adalah layanan pemendek URL. KVM dapat dikonfigurasi untuk menyimpan URL yang disingkat beserta URL lengkap yang sesuai.

Contoh kebijakan ini membuat KVM. Kebijakan ini menggunakan perintah PUT untuk menempatkan kunci dengan dua nilai terkait ke dalam KVM bernama urlMapper.

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
  <Scope>apiproxy</Scope>
  <Put override="true">
    <Key>
      <Parameter ref="urlencoding.requesturl.hashed"/>
    </Key>
    <Value ref="urlencoding.longurl.encoded"/>
    <Value ref="request.queryparam.url"/>
  </Put>
</KeyValueMapOperations>

Kunci dalam contoh ini, urlencoding.requesturl.hashed, adalah contoh variabel kustom. URL permintaan yang di-hash akan dibuat oleh kode (JavaScript atau Java, misalnya), lalu disimpan dalam variabel ini, tempat kebijakan KeyValueMapOperations dapat mengaksesnya.

Untuk setiap kunci, requesturl.hashed, dua nilai disimpan:

• Isi variabel kustom bernama urlencoding.longurl.encoded
• Isi variabel standar request.queryparam.url

Misalnya, saat kebijakan dijalankan pada waktu proses, nilai variabel mungkin sebagai berikut:

• urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
• urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
• request.queryparam.url: http://apigee.com

KVM dan entri berikut akan dibuat di penyimpanan nilai/kunci Apigee dan dicakup ke proxy API tempat kebijakan dilampirkan:

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

Entri akan tetap ada hingga dihapus. Entri penyimpanan key/value didistribusikan di seluruh instance Apigee yang menjalankan cloud.

MENDAPATKAN KVM dari variabel

Contoh sederhana KVM yang berguna adalah layanan pemendekan URL. KVM dapat dikonfigurasi untuk menyimpan URL yang disingkat beserta URL lengkap yang sesuai.

Untuk mengambil nilai entri KVM, seperti yang dibahas di tab KeyValueMapOperations PUT, konfigurasi kebijakan untuk GET KVM:

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
  <Scope>apiproxy</Scope>
  <Get assignTo="urlencoding.shorturl" index='1'>
    <Key>
      <Parameter ref="urlencoding.requesturl.hashed"/>
    </Key>
  </Get>
</KeyValueMapOperations>

Saat kebijakan ini dijalankan, jika nilai variabel urlencoding.requesturl.hashed adalah ed24e12820f2f900ae383b7cc4f2b31c402db1be, maka variabel kustom bernama urlencoding.shorturl akan disetel dengan nilai http://tinyurl.com/38lwmlr.

Setelah data diambil, kebijakan dan kode lain dapat mengaksesnya dengan mengekstrak nilai dari variabel tersebut.

MENDAPATKAN nilai dari KVM

Gunakan atribut private. dengan semua variabel saat mengakses KVM dengan perintah GET untuk menyembunyikan informasi KVM dalam sesi Debug. Jika atribut private. tidak digunakan, KVM akan tetap dienkripsi; namun, informasi KVM akan muncul dalam bentuk yang didekripsi di sesi Debug dan tidak ada pengecualian yang akan ditampilkan.

Dalam contoh ini, variabel private.encryptedVar menyimpan nilai yang didekripsi dari kunci foo KVM.

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
  <Scope>apiproxy</Scope>
  <Get assignTo="private.encryptedVar" index='1'>
    <Key>
      <Parameter>foo</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

Setelah data diambil, kebijakan dan kode lain dapat mengaksesnya dengan mengekstrak nilai dari variabel tersebut.

<KeyValueMapOperations>

Menyediakan akses berbasis kebijakan ke peta nilai kunci (KVM).

Sintaks

<KeyValueMapOperations async="false" continueOnError="false"
    enabled="true" name="Key-Value-Map-Operations-1"
    mapIdentifier="urlMapper" >
  <DisplayName>Key Value Map Operations 1</DisplayName>
  <Scope>environment</Scope>
  <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
  <InitialEntries>
    <Entry>
      <Key>
        <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
    </Entry>
    <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
      <Value>VALUE_LITERAL</Value>
    </Entry>
  </InitialEntries>
  <Put override="BOOLEAN">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Put>
  <Get assignTo="VARIABLE_NAME" index="INDEX_NUMBER">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Get>
  <Delete>
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Delete>
</KeyValueMapOperations>

Atribut <KeyValueMapOperations>

Contoh berikut menunjukkan atribut elemen <KeyValueMapOperations>:

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

Tabel berikut menjelaskan atribut elemen <KeyValueMapOperations>:

Catatan: Atribut mapIdentifier menentukan nama KVM yang ingin Anda ajak berinteraksi. Anda juga dapat menentukan KVM secara dinamis dengan elemen <MapName>.

Atribut	Deskripsi	Default	Kehadiran
mapIdentifier	Menentukan ID yang memberi tahu kebijakan KVM mana yang harus diakses. Jika ID ini dan <MapName> tidak ada, KVM bernama kvmap akan digunakan. Anda tidak dapat menggunakan atribut ini jika Anda menentukan elemen <MapName>.	T/A	Opsional

Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:

Atribut	Deskripsi	Default	Kehadiran
name	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.	T/A	Wajib
continueOnError	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini	false	Opsional
enabled	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.	benar	Opsional
async	Atribut ini tidak digunakan lagi.	false	Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Default	T/A Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran	Opsional
Jenis	String

Elemen turunan

Bagian ini menjelaskan elemen dan atribut kebijakan KeyValueMapOperations:

Elemen <Delete>

Menghapus pasangan nilai/kunci yang ditentukan. Setidaknya salah satu dari <Get>, <Put>, atau <Delete> harus digunakan.

Pastikan untuk menentukan nama KVM dengan atribut mapIdentifier pada elemen root atau dengan elemen <MapName>. Contoh:

<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>

Default	T/A
Kehadiran	Wajib jika <Get> atau <Put> tidak ada.
Jenis	T/A

Elemen <Entry>

Nilai seed untuk KVM, yang diisi di KVM saat diinisialisasi. Untuk Apigee, ukuran kunci dibatasi hingga 2 KB.

Contoh:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Default	T/A
Kehadiran	Opsional
Jenis	T/A

Elemen <ExclusiveCache>

Tidak digunakan lagi. Gunakan elemen <Scope> sebagai gantinya.

Elemen <ExpiryTimeInSecs>

Menentukan durasi dalam detik setelah Apigee memperbarui nilai yang di-cache dari KVM yang ditentukan.

Nilai 0 atau -1, atau tidak menyertakan elemen ini, berarti nilai default 300 detik akan digunakan. Contoh:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Default	300 (5 menit)
Kehadiran	Opsional
Jenis	Bilangan bulat

KVM adalah mekanisme persistensi jangka panjang yang menyimpan kunci dan nilai dalam database NoSQL. Oleh karena itu, membaca dari KVM saat runtime berpotensi memperlambat performa proxy. Untuk meningkatkan performa, Apigee memiliki mekanisme bawaan untuk menyimpan kunci/nilai KVM dalam cache di memori selama runtime. Kebijakan Operasi KVM ini selalu membaca dari cache untuk operasi GET.

Elemen <ExpiryTimeInSecs> memungkinkan Anda mengontrol durasi kunci/nilai yang digunakan dalam kebijakan disimpan dalam cache sebelum di-refresh lagi dari KVM. Namun, ada beberapa perbedaan antara cara operasi GET dan PUT memengaruhi masa berlaku cache.

GET - Saat operasi GET KVM dijalankan untuk pertama kalinya, kunci/nilai yang diminta dari KVM (yang namanya ditentukan dalam atribut mapIdentifier root kebijakan atau elemen <MapName>) dimuat ke dalam cache, tempat kunci/nilai tersebut tetap berada untuk operasi GET berikutnya hingga salah satu hal berikut terjadi:

• Jumlah detik yang ditentukan dalam <ExpiryTimeInSecs> telah habis.
  atau
• Operasi PUT dalam kebijakan KVM akan menggantikan nilai yang ada (dijelaskan berikutnya).

PUT - Operasi PUT menulis kunci/nilai ke KVM yang ditentukan. Jika PUT menulis ke kunci yang sudah ada dalam cache, cache tersebut akan segera di-refresh dan kini menyimpan nilai baru selama beberapa detik yang ditentukan dalam elemen <ExpiryTimeInSecs> kebijakan. Namun, penggunaan PUT hanya akan memperbarui cache di satu node runtime yang melayani permintaan. Untuk memperbarui cache di setiap node runtime terdistribusi, gunakan elemen <ExpiryTimeInSecs> untuk menentukan interval pembaruan untuk setiap node.

Contoh - Meng-cache KVM

1. Operasi GET mengambil nilai "rating", yang menambahkan nilai "10" ke cache. The <ExpiryTimeInSecs> pada kebijakan adalah 60.
2. 30 detik kemudian, kebijakan GET dijalankan lagi dan mengambil 10 dari cache.
3. 5 detik kemudian, kebijakan PUT memperbarui nilai rating menjadi 8, dan <ExpiryTimeInSecs> pada kebijakan PUT adalah 20. Cache akan segera diperbarui dengan nilai baru, yang kini ditetapkan untuk tetap berada dalam cache selama 20 detik. (Jika PUT tidak terjadi, cache yang awalnya diisi oleh GET pertama akan tetap ada selama 30 detik lagi, sisa dari 60 detik awal.)
4. 15 detik kemudian, GET lain dieksekusi dan mengambil nilai 8.

Catatan

• Untuk performa terbaik, seimbangkan waktu habis masa berlaku cache dengan jumlah traffic API yang Anda harapkan. Dengan lalu lintas yang padat, misalnya, Anda mungkin ingin menetapkan interval masa berlaku cache yang lebih lama untuk menghindari refresh yang sering dari database.
• Tidak ada cara untuk mereset cache KVM secara manual. Namun, Anda dapat membuat kebijakan sementara yang menjalankan operasi PUT satu kali dengan <ExpiryTimeInSecs> singkat. Tindakan ini akan mereset cache, yang berisi nilai yang Anda PUT, selama jumlah detik yang Anda tentukan.
• Memperbarui KVM dengan UI atau API Apigee tidak akan mereset cache KVM.
• Anda dapat menggunakan beberapa operasi dalam kebijakan yang sama. Jika Anda melakukannya, kebijakan akan menjalankan operasi secara berurutan. Jika Anda menggunakan PUT yang diikuti dengan GET dalam kebijakan yang sama menggunakan kunci yang sama, PUT, saat menulis, akan secara implisit mereset masa berlaku cache.

Elemen <Get>

Mengambil nilai untuk kunci yang ditentukan. Setidaknya salah satu dari <Get>, <Put>, atau <Delete> harus digunakan.

Apigee mengenkripsi semua data yang disimpan di KVM. Untuk mengetahui detailnya, lihat Tentang kunci enkripsi. Saat menggunakan <Get>, Apigee mendekripsi data yang disimpan dan menetapkan data tersebut ke variabel dalam konteks pesan. Nama variabel ditentukan menggunakan atribut assignTo.

Pastikan untuk menentukan nama KVM dengan atribut mapIdentifier pada elemen root atau dengan elemen <MapName>.

Anda dapat menyertakan beberapa blok Get dalam kebijakan untuk mengambil beberapa item dari KVM.

Catatan: Anda dapat menggunakan beberapa operasi dalam kebijakan yang sama. Jika Anda melakukannya, kebijakan akan menjalankan operasi secara berurutan. Jika Anda menggunakan PUT yang diikuti dengan GET dalam kebijakan yang sama menggunakan kunci yang sama, PUT, saat menulis, akan secara implisit mereset masa berlaku cache. Lihat elemen ExpiryTimeInSecs untuk mengetahui informasi selengkapnya.

Default	T/A
Kehadiran	Wajib jika <Put> atau <Delete> tidak ada.
Jenis	T/A

Atribut

Tabel berikut menjelaskan atribut elemen <Get>:

Atribut	Deskripsi	Default	Kehadiran
assignTo	Variabel yang akan diberi nilai yang diambil.	T/A	Wajib
index	Nomor indeks (dalam indeks berbasis 1) item yang akan diambil dari kunci bernilai ganda. Misalnya, menentukan index=1 akan menampilkan nilai pertama dan menetapkannya ke variabel assignTo. Jika tidak ada nilai indeks yang ditentukan, semua nilai entri tersebut akan ditetapkan ke variabel sebagai java.util.List. Sebagai contoh, lihat tab Get Value from KVM di Samples.	T/A	Opsional

Mendapatkan satu item dari KVM

Dengan konfigurasi langkah contoh ini, kebijakan membaca dan mendekripsi nilai satu kunci di KVM dan menetapkan nilai yang didekripsi ke variabel bernama myvar.

<Get assignTo="myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

Mengecualikan data yang diambil dari Sesi Debug

Dalam beberapa kasus, data yang disimpan di KVM bersifat sensitif. Untuk mencegah data yang diambil muncul di Sesi debug, gunakan awalan private. pada nama variabel yang ditentukan dalam atribut assignTo. Jika Anda tidak menggunakan awalan private., data yang diambil dari KVM akan muncul dalam teks biasa, di sesi Debug yang Anda buat.

Dengan konfigurasi langkah contoh ini, kebijakan membaca dan mendekripsi nilai yang terkait dengan satu kunci di KVM dan menetapkan nilai tersebut ke variabel. Penetapan tidak akan muncul di sesi Debug.

<Get assignTo="private.myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

Mendapatkan beberapa item dari KVM

Dalam contoh berikut, asumsikan KVM dengan kunci dan nilai berikut. Selain menyimpan daftar film terpopuler sepanjang masa yang terus diperbarui, KVM menyimpan nama sutradara untuk semua film besar.

Kunci	Nilai
top_movies	The Princess Bride,The Godfather,Citizen Kane
Citizen Kane	Orson Welles
Princess Bride	Rob Reiner
The Godfather	Francis Ford Coppola

Anda akan melihat bahwa nilai yang terkait dengan kunci top_movies berisi beberapa nama film, yang dipisahkan dengan koma.

Dengan konfigurasi contoh ini, kebijakan akan mengambil film teratas saat ini dan nama sutradaranya:

<Get assignTo="top.movie.pick" index="1">
  <Key>
    <Parameter>top_movies</Parameter>
  </Key>
</Get>
<Get assignTo="movie.director">
  <Key>
    <Parameter ref="top.movie.pick"/>
  </Key>
</Get>

Saat proxy API dipanggil, Apigee membuat variabel berikut dengan nilai yang sesuai, yang dapat digunakan nanti dalam alur proxy API:

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

Nilai untuk top.movie.pick hanyalah item pertama dalam daftar yang dipisahkan koma, karena elemen <Get> pertama menggunakan atribut index sebesar 1. Kemudian, elemen <Get> kedua menggunakan nilai yang ditetapkan ke top.movie.pick sebagai kunci untuk mengambil nilai ke dalam movie.director.

Elemen <InitialEntries>

Nilai seed untuk KVM, yang diisi di KVM saat diinisialisasi. Pastikan untuk menentukan nama KVM dengan atribut mapIdentifier pada elemen root.

Catatan: <InitialEntries> tidak diizinkan jika elemen <MapName> digunakan.

Contoh:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_VARIABLE</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Saat menggunakan elemen ini, saat Anda menyimpan kebijakan di UI Apigee pada versi proxy API yang di-deploy, atau men-deploy paket proxy API yang berisi kebijakan dengan elemen ini, kunci akan otomatis dibuat di KVM. Jika nilai dalam kebijakan berbeda dengan nilai dalam KVM, nilai dalam KVM akan diganti saat proxy API di-deploy. Setiap kunci/nilai baru ditambahkan ke KVM yang ada bersama dengan kunci/nilai yang ada.

Kunci dan nilai yang diisi oleh elemen ini harus berupa literal. Misalnya, <Parameter ref="request.queryparam.key"> tidak didukung dalam elemen ini.

Ukuran kunci dibatasi hingga 2 KB.

Default	T/A
Kehadiran	Opsional
Jenis	T/A

Elemen <Key>

Menentukan kunci dalam entri KVM. Elemen ini muncul sebagai turunan dari <Get>, <Put>, atau <Delete>, atau sebagai turunan dari elemen <Entry> yang merupakan turunan dari <InitialEntries>. Berikut adalah contoh kunci tetap:

<Key>
  <Parameter>KEY_NAME_LITERAL</Parameter>
</Key>

Kunci dapat berupa gabungan, dengan elemen dinamis, yang berarti lebih dari satu <Parameter> dapat ditambahkan untuk membuat kunci. Misalnya, konten variabel userID dan role dapat digabungkan untuk membuat kunci dinamis. Berikut adalah contoh konfigurasi langkah yang menentukan kunci gabungan yang ditentukan secara dinamis:

<Key>
  <Parameter ref='userID'/>
  <Parameter ref='role'/>
</Key>

Pastikan untuk melihat elemen <Parameter> untuk mengetahui secara spesifik cara menetapkan nama kunci.

Ukuran kunci dibatasi hingga 2 KB.

Catatan: Nama ratelimit sudah dicadangkan. Untuk informasi selengkapnya, lihat postingan Komunitas Apigee ini.

Default	T/A
Kehadiran	Opsional
Jenis	T/A

Elemen <MapName>

Elemen <MapName> memungkinkan kebijakan mengidentifikasi KVM mana yang akan digunakan secara dinamis, saat runtime. Kemampuan untuk memilih KVM secara dinamis memberi Anda fleksibilitas untuk mendesain satu kebijakan KeyValueMapOperations yang dapat mengakses KVM yang berbeda, bergantung pada konteks saat kebijakan dijalankan.

Beberapa contoh:

<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>

Baris pertama menentukan nama KVM sebagai string literal. Baris kedua mendapatkan nama dari variabel alur. Pada baris ketiga, jika variabel alur diselesaikan ke nilai kosong, string literal akan digunakan sebagai gantinya.

Jangan tentukan atribut mapIdentifier jika Anda menggunakan <MapName> dalam kebijakan Anda. Lihat atribut kebijakan untuk mengetahui informasi selengkapnya.

Jika peta tidak ada saat proxy di-deploy, peta tidak akan dibuat dan Apigee akan menampilkan error runtime saat kebijakan dijalankan. Jika variabel alur diberikan, elemen <InitialEntries> tidak diizinkan. Anda akan mendapatkan error validasi selama deployment.

Elemen <Parameter>

Menentukan komponen kunci dalam pasangan nilai kunci. Elemen ini menentukan nama saat membuat, memperbarui, mengambil, atau menghapus pasangan nilai/kunci.

Anda dapat menentukan nama menggunakan:

• String literal

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• Variabel yang akan diambil saat runtime, menggunakan atribut ref

  <Key>
    <Parameter ref="variable_name"/>
  </Key>

• Kombinasi literal dan referensi variabel

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

Jika elemen <Key> menyertakan beberapa elemen <Parameter>, string kunci efektif adalah gabungan nilai setiap parameter, yang digabungkan dengan garis bawah ganda. Misalnya, pada contoh di atas, jika variabel apiproxy.name memiliki nilai abc1, maka kunci efektifnya adalah targeturl__abc1__weight.

Baik Anda mengambil, memperbarui, atau menghapus entri nilai/kunci, nama kunci harus cocok dengan nama kunci di KVM. Lihat Menentukan dan mengambil nama kunci untuk mengetahui panduannya.

Default	T/A
Kehadiran	Wajib
Jenis	String

Atribut

Tabel berikut menjelaskan atribut elemen <Parameter>:

Atribut	Deskripsi	Default	Kehadiran
ref	Menentukan nama variabel yang nilainya berisi nama persis kunci yang ingin Anda buat, dapatkan, atau hapus.	T/A	Wajib diisi jika tidak ada nilai literal yang diberikan di antara tag pembuka dan penutup.

Elemen <Put>

Menulis pasangan nilai kunci ke KVM. Jika KVM yang ditentukan dalam atribut mapIdentifier pada elemen root tidak ada dan jika elemen <MapName> tidak digunakan, peta akan dibuat secara otomatis. Jika peta nilai kunci sudah ada, kunci/nilai akan ditambahkan ke peta tersebut.

Untuk membuat KVM menggunakan UI atau API, lihat:

• Menggunakan KVM dengan UI Apigee untuk membuat KVM dengan cakupan lingkungan yang dienkripsi di UI
• API peta nilai kunci cakupan organisasi
• API peta nilai kunci cakupan lingkungan
• API peta nilai kunci cakupan proxy API

Catatan:Anda dapat menggunakan beberapa operasi dalam kebijakan yang sama. Jika Anda melakukannya, kebijakan akan menjalankan operasi secara berurutan. Jika Anda menggunakan PUT yang diikuti dengan GET dalam kebijakan yang sama menggunakan kunci yang sama, PUT, saat menulis, akan secara implisit mereset masa berlaku cache. Lihat elemen ExpiryTimeInSecs untuk mengetahui informasi selengkapnya.

Ukuran kunci dibatasi hingga 2 KB.

<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>

Default	T/A
Kehadiran	Wajib jika <Get> atau <Delete> tidak ada.
Jenis	T/A

Peringatan: Jika kebijakan menggunakan perintah PUT untuk menempatkan pasangan kunci/nilai di KVM menggunakan kunci null, kunci berikut akan dibuat secara otomatis: __$$_EDGE_KVM_EMPTY_KEY_$$__

Situasi ini akan terjadi, misalnya, jika Anda mengisi kunci menggunakan referensi variabel dan variabel yang dirujuk adalah null. Saat perintah PUT baru dengan kunci null dicoba, hanya kunci tersebut yang digunakan, sehingga nilai yang ada untuk kunci tersebut berpotensi ditimpa setiap kali kebijakan dijalankan.

Atribut

Tabel berikut menjelaskan atribut elemen <Put>:

Atribut	Deskripsi	Default	Kehadiran
mengganti	Jika disetel ke true, nilai ini akan menggantikan nilai untuk kunci. <Put override="false"> akan menulis jika dan hanya jika tidak ada entri yang saat ini dipertahankan di penyimpanan KVM untuk kunci tersebut.	true	Opsional

Elemen <Scope>

Menentukan batas aksesibilitas untuk KVM. Cakupan default adalah environment, yang berarti, secara default, entri peta dibagikan oleh semua proxy API yang berjalan di lingkungan (misalnya, test atau prod). Jika Anda menyetel cakupan ke apiproxy, entri di KVM hanya dapat diakses oleh proxy API yang menulis nilai ke peta.

Perhatikan bahwa saat mengakses peta atau entri peta, Anda harus menentukan nilai cakupan yang sama dengan yang Anda gunakan saat peta dibuat. Misalnya, jika peta dibuat dengan cakupan apiproxy, Anda harus menggunakan cakupan apiproxy saat mengambil nilainya, menerapkan perubahan, atau menghapus entri.

<Scope>environment</Scope>

Default	environment
Kehadiran	Opsional
Jenis	String
Nilai valid	organization environment apiproxy policy (revisi proxy API)

Jika Anda perlu menggunakan KVM yang sama di beberapa Proxy, pertimbangkan untuk menambahkan kebijakan KVM ke SharedFlow dan menggunakan SharedFlow di Proxy.

Elemen <Value>

Menentukan nilai kunci. Anda dapat menentukan nilai sebagai string literal atau, menggunakan atribut ref, sebagai variabel yang akan diambil saat runtime:

<!-- Specify a literal value -->
<Value>literal<Value>

atau:

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

Anda juga dapat menyertakan beberapa elemen <Value> untuk menentukan nilai multi-bagian. Nilai digabungkan saat runtime.

Dalam contoh berikut, dua kunci ditambahkan ke KVM:

• Kunci k1 dengan nilai v1,v2
• Kunci k2 dengan nilai v3,v4

<InitialEntries>
  <Entry>
    <Key>
      <Parameter>k1</Parameter>
    </Key>
    <Value>v1</Value>
    <Value>v2</Value>
  </Entry>
  <Entry>
    <Key>
      <Parameter>k2</Parameter>
    </Key>
    <Value>v3</Value>
    <Value>v4</Value>
  </Entry>
</InitialEntries>

Dalam contoh berikut, satu kunci dibuat dengan dua nilai. Misalkan nama organisasi adalah foo_org, nama proxy API adalah bar, dan lingkungannya adalah test:

• Kunci foo_org dengan nilai bar,test

<Put>
  <Key>
    <Parameter ref="organization.name"/>
  </Key>
  <Value ref="apiproxy.name"/>
  <Value ref="environment.name"/>
</Put>

Default	T/A
Kehadiran	Wajib
Jenis	String

Atribut

Tabel berikut menjelaskan atribut elemen <Value>:

Atribut	Deskripsi	Default	Kehadiran
ref	Menentukan nama variabel yang nilainya berisi nilai kunci yang ingin Anda tetapkan.	T/A	Wajib diisi jika tidak ada nilai literal yang diberikan di antara tag pembuka dan penutup. Dilarang jika nilai literal diberikan.

Referensi error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Tips: Perlu bantuan untuk mengatasi error? Klik di kolom Perbaiki untuk mendapatkan informasi pemecahan masalah mendetail.

Kode kerusakan	Status HTTP	Penyebab	Perbaiki
steps.keyvaluemapoperations.UnsupportedOperationException	500	Error ini terjadi jika atribut mapIdentifier disetel ke string kosong dalam kebijakan KeyValueMapOperations.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Tips: Perlu bantuan untuk mengatasi error? Klik di kolom Perbaiki untuk mengetahui informasi pemecahan masalah mendetail.

Nama error	Penyebab	Perbaiki
InvalidIndex	Jika atribut index yang ditentukan dalam elemen <Get> kebijakan KeyValueMapOperations adalah nol atau angka negatif, deployment proxy API akan gagal. Indeks dimulai dari 1, sehingga indeks nol atau bilangan bulat negatif dianggap tidak valid.
KeyIsMissing	Error ini terjadi jika elemen <Key> benar-benar tidak ada atau elemen <Parameter> tidak ada dalam elemen <Key> di bawah <Entry> elemen <InitialEntries> kebijakan KeyValueMapOperations.
ValueIsMissing	Error ini terjadi jika elemen <Value> tidak ada di bawah elemen <Entry> dari elemen <InitialEntries> kebijakan KeyValueMapOperations.

Skema

Contoh: Lihat contoh skema terbaru di repositori GitHub kami.

Catatan penggunaan

Untuk ringkasan KVM, lihat Menggunakan peta nilai kunci.

Dengan UI Apigee, Anda hanya dapat menentukan KVM pada cakupan lingkungan, seperti yang dijelaskan dalam Menggunakan KVM dengan UI Apigee. Dengan Apigee API, Anda dapat menentukan KVM di cakupan organisasi, lingkungan, atau proxy API, seperti yang dijelaskan di bagian berikut:

• API peta nilai kunci cakupan organisasi
• API peta nilai kunci cakupan lingkungan
• API peta nilai kunci cakupan proxy API

Penyimpanan KVM menyediakan mekanisme persistensi ringan untuk data yang diformat sebagai key-value pair. Anda dapat mengaksesnya saat runtime melalui kebijakan atau kode. Peta berisi data arbitrer dalam format key=value.

Catatan: Ukuran kunci dibatasi hingga 2 KB.

Misalnya, localhost=127.0.0.1, zip_code=94110, atau first_name=felix. Pada contoh pertama, localhost adalah kunci, dan 127.0.0.1 adalah nilai. Setiap key-value pair disimpan sebagai entri dalam peta nilai kunci. KVM dapat menyimpan banyak entri.

Misalnya, Anda perlu menyimpan daftar alamat IP yang terkait dengan berbagai lingkungan backend. Anda dapat membuat KVM bernama ipAddresses yang berisi daftar key-value pair sebagai entri. Misalnya, JSON ini dapat merepresentasikan peta tersebut:

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

Anda dapat menggunakan struktur ini untuk membuat penyimpanan alamat IP yang dapat digunakan oleh kebijakan saat runtime untuk menerapkan daftar IP yang diizinkan/ditolak, untuk memilih alamat target backend secara dinamis, dan sebagainya. Biasanya, kebijakan KeyValueMapOperations digunakan untuk menyimpan atau mengambil informasi yang berjalan lama yang perlu digunakan kembali di beberapa transaksi permintaan/respons.

KVM dapat dimanipulasi melalui kebijakan KeyValueMapOperations, atau langsung melalui Apigee API. Anda dapat menggunakan API untuk, misalnya, mengupload set data besar ke penyimpanan nilai/kunci, atau membuat skrip untuk mengelola entri peta nilai kunci. Anda harus membuat KVM dengan API sebelum mengaksesnya dengan kebijakan KeyValueMapOperations.

Menentukan dan mengambil nama kunci

Dengan elemen <Parameter> dan <Value>, Anda dapat menentukan nilai literal (dengan nilai di antara tag pembuka dan penutup) atau menggunakan atribut ref untuk menentukan nama variabel yang nilainya harus digunakan saat runtime.

Elemen <Parameter> layak disebutkan secara khusus, karena elemen ini menentukan nama kunci yang dibuat, serta nama kunci yang ingin Anda ambil atau hapus. Berikut adalah dua contohnya. Yang pertama menentukan nama kunci secara harfiah, dan yang kedua menentukan nama kunci menggunakan variabel. Anggaplah hal berikut digunakan untuk membuat kunci di KVM:

<Parameter>KEY_NAME_LITERAL</Parameter>
<Parameter ref="key.name.variable"/>

Pada instance pertama, nilai literal KEY_NAME_LITERAL disimpan di KVM sebagai nama kunci. Pada instance kedua, nilai apa pun yang ada di key.name.variable akan menjadi nama kunci di KVM. Misalnya, jika key.name.variable berisi nilai foo, kunci akan diberi nama foo.

Untuk mengambil kunci dan nilai kunci dengan operasi GET (atau menghapus dengan operasi DELETE), nilai elemen <Parameter> harus cocok dengan nama kunci di KVM. Misalnya, jika nama kunci di KVM adalah my_key, Anda dapat menentukan nilai literal dengan <Parameter>my_key</Parameter> atau menentukan variabel yang berisi nilai persis mny_key, seperti ini: <Parameter ref="variable.containing.foo"/>.

Catatan: Nama ratelimit sudah dicadangkan. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Kuota - Pengecualian NullPointerException.

Topik terkait

Lihat topik berikut untuk mengetahui informasi selengkapnya tentang KVM:

• Menggunakan peta nilai kunci
• API peta nilai kunci cakupan organisasi
• API peta nilai kunci cakupan lingkungan
• API peta nilai kunci cakupan proxy API