Kebijakan KeyValueMapOperations

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Ikon Operasi Peta Nilai Kunci dari UI Apigee

Apa

Memberikan akses berbasis kebijakan ke penyimpanan key value map (KVM) yang tersedia di Apigee. Key-value pair dapat disimpan, diambil, dan dihapus dari peta bernama yang sudah ada dengan mengonfigurasi Kebijakan KeyValueMapOperations yang menentukan PUT, GET, atau DELETE. (Setidaknya salah satu dari operasi ini harus dijalankan oleh kebijakan.)

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

Video: Video berikut memberikan pengantar KVM secara umum.

Sampel

PUT KVM dengan literal

Ketika dijalankan, kebijakan berikut akan membuat KVM terenkripsi yang bernama FooKVM, lalu membuat kunci bernama FooKey_1 dengan dua nilai yang ditetapkan dengan string literal foo dan bar (not set dengan nilai yang diekstrak dari variabel). Jika 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. Itu berarti Anda dapat melihat KVM di bagian manajemen UI di bagian APIs > Konfigurasi Lingkungan > Peta Nilai Kunci. KVM yang ditampilkan di halaman tersebut mencakup semua 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 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 flow. Elemen memperoleh ID KVM dari variabel {i>flow<i}. Perhatikan bahwa 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 dari KVM yang berguna adalah layanan pemendekan URL. KVM dapat dikonfigurasi untuk menyimpan URL singkat beserta URL lengkap yang sesuai.

Contoh kebijakan ini membuat KVM. Kebijakan ini menggunakan perintah PUT untuk menempatkan kunci dengan dua nilai terkait ke 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, untuk misalnya) lalu disimpan dalam variabel ini, tempat kebijakan KeyValueMapOperations dapat mengakses anotasi.

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

  • Konten variabel khusus bernama urlencoding.longurl.encoded
  • Konten variabel yang telah ditetapkan request.queryparam.url

Misalnya, jika kebijakan dieksekusi pada runtime, nilai variabel mungkin sebagai berikut ini:

  • 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 kunci/nilai Apigee dan yang dicakupkan 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 kunci/nilai didistribusikan di instance Apigee yang menjalankan cloud.

MENDAPATKAN KVM dari variabel

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

Untuk mengambil nilai entri KVM, seperti yang dibahas pada Tab PUT KeyValueMapOperations, konfigurasikan kebijakan ke 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, lalu variabel kustom bernama urlencoding.shorturl akan ditetapkan dengan nilai http://tinyurl.com/38lwmlr.

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

Memperoleh nilai dari KVM

Gunakan atribut private. dengan semua variabel saat mengakses KVM dengan GET untuk menyembunyikan informasi KVM dalam sesi Debug. Jika Atribut private. tidak digunakan, KVM masih dienkripsi; Namun, KVM informasi akan tampak didekripsi dalam sesi Debug dan tidak ada pengecualian yang akan ditampilkan.

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

<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.

&lt;KeyValueMapOperations&gt;

Memberikan akses berbasis kebijakan ke key value map (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>

&lt;KeyValueMapOperations&gt; atribut

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

Atribut Deskripsi Default Kehadiran
mapIdentifier

Menentukan ID yang memberi tahu kebijakan KVM mana yang harus diakses.

Jika ID ini dan <MapName> tidak ada, digunakan KVM bernama kvmap. Anda tidak dapat menggunakan atribut ini jika menentukan elemen <MapName>.

 T/A Opsional

Tabel berikut menjelaskan atribut yang sama 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.

Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

 T/A Diperlukan
continueOnError

Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:

 false Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.

 true Opsional
async

Atribut ini sudah tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language 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 KeyValueMapOperations kebijakan:

&lt;Delete&gt; elemen

Menghapus key-value pair 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 diisi jika <Get> atau <Put> tidak ada.
Jenis T/A

&lt;Entry&gt; elemen

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

&lt;ExclusiveCache&gt; elemen

Tidak digunakan lagi. Sebagai gantinya, gunakan elemen <Scope>.

&lt;ExpiryTimeInSecs&gt; elemen

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

Nilai 0 atau -1, atau tidak termasuk elemen ini, berarti nilai {i>default<i} 300 detik adalah data 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. Karena itu, membaca dari KVM saat runtime berpotensi memperlambat performa proxy. Untuk meningkatkan , Apigee memiliki mekanisme bawaan untuk menyimpan kunci/nilai KVM ke dalam 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 di {i> cache<i} sebelum disegarkan kembali dari KVM. Namun, ada beberapa perbedaan antara pengaruh operasi GET dan PUT terhadap masa berlaku cache.

GET - Saat pertama kali operasi GET KVM dijalankan, jenis kunci/nilai dari KVM (yang namanya ditentukan dalam root kebijakan mapIdentifier atau elemen <MapName>) dimuat ke dalam cache, yang akan tetap disimpan selama operasi GET berikutnya hingga salah satu hal berikut akan terjadi:

  • Jumlah detik yang ditentukan dalam <ExpiryTimeInSecs> berakhir.
    atau
  • Operasi PUT dalam kebijakan KVM akan menimpa nilai yang sudah ada (dijelaskan selanjutnya).

PUT - Operasi PUT menulis kunci/nilai ke KVM yang ditentukan. Jika PUT menulis ke kunci yang sudah ada dalam cache, cache tersebut segera diperbarui dan menyimpan nilai baru untuk jumlah detik yang ditentukan dalam elemen <ExpiryTimeInSecs>. Namun, menggunakan PUT hanya akan memuat ulang cache dalam satu node runtime yang melayani permintaan. Untuk memuat ulang cache di setiap node runtime terdistribusi, gunakan elemen <ExpiryTimeInSecs> untuk menentukan interval pembaruan bagi setiap node.

Contoh - Menyimpan KVM ke dalam cache

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

&lt;Get&gt; elemen

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 detailnya, lihat Tentang kunci enkripsi. Saat menggunakan <Get>, Apigee akan mendekripsi data yang disimpan dan menetapkannya ke variabel dalam konteks pesan. Nama variabel ditetapkan menggunakan metode Atribut assignTo.

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

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

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

Atribut

Tabel berikut menjelaskan atribut <Get> :

Atribut Deskripsi Default Kehadiran
assignTo

Variabel yang harus diberi nilai yang diambil.

 T/A Wajib
index

Nomor indeks (dalam indeks berbasis 1) item yang akan diambil dari kunci multi-nilai. Misalnya, menentukan index=1 akan menampilkan nilai pertama dan menetapkannya ke variabel assignTo. Jika tidak ada nilai indeks yang ditentukan, semua nilai entri tersebut ditetapkan ke variabel sebagai java.util.List.

Sebagai contoh, lihat tab Mendapatkan Nilai dari KVM di Sample.

 T/A Opsional

Mendapatkan satu item dari KVM

Dengan contoh konfigurasi langkah ini, kebijakan membaca dan mendekripsi nilai sebuah 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 agar tidak muncul dalam 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 di cleartext, dalam sesi Debug apa pun yang Anda buat.

Dengan contoh konfigurasi langkah ini, kebijakan membaca dan mendekripsi nilai yang terkait dengan sebuah kunci di KVM dan menetapkan nilai itu ke sebuah variabel. Tugas 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

Pada contoh berikut, asumsikan KVM dengan kunci dan nilai berikut. Selain itu hingga menyimpan daftar film paling populer sepanjang masa, toko KVM nama sutradara untuk semua film besar.

Kunci Nilai
top_movies Princess Bride,Sang Dewa,Citizen Kane
Warga Negara Kane Sumur Orson
Pengantin Putri Rob{i> <i}Reiner
The Godfather Francis Ford Coppola

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

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

<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 akan membuat variabel berikut dengan nilai yang sesuai, yang bisa 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.

&lt;InitialEntries&gt; elemen

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

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 yang di-deploy proxy API, atau deploy paket proxy API yang berisi kebijakan dengan elemen ini, kunci otomatis dibuat di KVM. Jika nilai dalam kebijakan berbeda daripada nilai dalam KVM, nilai dalam KVM akan ditimpa ketika proxy API di-deploy. Apa saja 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

&lt;Key&gt; elemen

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

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

Suatu kunci dapat digabungkan, dengan elemen dinamis, yang berarti bahwa lebih dari satu <Parameter> dapat ditambahkan untuk membuat kunci. Misalnya, konten dari variabel userID dan role dapat digabungkan untuk membuat tombol dinamis. Berikut adalah contoh konfigurasi langkah yang menetapkan konfigurasi kunci yang ditentukan:

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

Pastikan Anda melihat elemen <Parameter> untuk secara spesifik tentang cara mengatur nama kunci.

Ukuran kunci dibatasi hingga 2 KB.

Default T/A
Kehadiran Opsional
Jenis T/A

&lt;MapName&gt; elemen

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

Beberapa contohnya:

<!-- 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 diberi nama dari variabel flow. Di baris ketiga, jika variabel flow di-resolve menjadi nilai kosong, string literal akan digunakan sebagai gantinya.

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

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

Elemen <Parameter>

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

Anda dapat menetapkan nama dengan menggunakan:

  • String literal

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

  • Variabel yang akan diambil pada waktu proses, menggunakan atribut ref

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

  • Kombinasi dari referensi literal dan 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 dari setiap parameter, digabungkan dengan garis bawah ganda. Misalnya, di contoh di atas, jika variabel apiproxy.name memiliki nilai abc1, maka kunci efektif adalah targeturl__abc1__weight.

Baik Anda mendapatkan, memperbarui, atau menghapus entri kunci/nilai, nama kunci harus cocok dengan nama kunci dalam KVM. Lihat Menentukan dan mengambil nama kunci untuk panduan.

Default T/A
Kehadiran Wajib
Jenis String

Atribut

Tabel berikut menjelaskan atribut elemen <Parameter>:

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

&lt;Put&gt; elemen

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

Untuk membuat KVM menggunakan UI atau API, lihat:

<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>
Default T/A
Kehadiran Wajib ada jika <Get> atau <Delete> tidak saat ini.
Jenis T/A

Atribut

Tabel berikut menjelaskan atribut elemen <Put>:

Atribut Deskripsi Default Kehadiran
abaikan

Jika ditetapkan ke true, nilai tersebut akan menggantikan nilai untuk kunci.

<Put override="false"> akan menulis jika dan hanya jika tidak ada kunci tersebut disimpan di penyimpanan KVM untuk kunci itu.

true Opsional

&lt;Scope&gt; elemen

Menentukan batasan aksesibilitas untuk KVM. Cakupan default-nya adalah environment, artinya, secara default, entri peta digunakan bersama oleh semua proxy API yang berjalan di suatu lingkungan (misalnya, test atau prod). Jika Anda menetapkan cakupan ke apiproxy, entri dalam kolom KVM hanya dapat diakses oleh proxy API yang menulis nilai ke peta.

Perhatikan bahwa saat mengakses entri peta atau 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, membuat perubahan, atau menghapus entri.

<Scope>environment</Scope>
Default environment
Kehadiran Opsional
Jenis String
Nilai valid
  • organization
  • environment
  • apiproxy
  • policy (revisi proxy API)

&lt;Value&gt; elemen

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

<!-- 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 multi-bagian dengan sejumlah nilai. Nilai digabungkan pada waktu proses.

Dua kunci ditambahkan ke KVM berikut ini:

  • 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. Mari kita asumsikan namanya adalah foo_org, nama proxy API adalah bar, dan lingkungannya 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 atur. T/A Wajib diisi jika tidak ada nilai literal yang diberikan antara pembukaan dan tag penutup. Dilarang jika nilai literal diberikan.

Referensi error

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

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab Perbaikan
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.

Nama error Penyebab Perbaikan
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 bilangan bulat nol atau negatif dianggap tidak valid.
KeyIsMissing Error ini terjadi jika elemen <Key> tidak ada sama sekali atau elemen <Parameter> tidak ada dalam elemen <Key> di bawah <Entry> elemen <InitialEntries> dalam kebijakan KeyValueMapOperations.
ValueIsMissing Error ini terjadi jika elemen <Value> tidak ada di bawah elemen <Entry> dari elemen <InitialEntries> kebijakan KeyValueMapOperations.

Skema

Catatan penggunaan

Untuk ringkasan KVM, lihat Menggunakan peta nilai kunci.

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

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

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

Misalnya, Anda perlu menyimpan daftar alamat IP yang terkait dengan berbagai backend lingkungan fleksibel App Engine. Anda dapat membuat KVM bernama ipAddresses yang berisi daftar pasangan kunci/nilai 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 yang diizinkan/ditolak IP, untuk memilih target backend secara dinamis dan sebagainya. Biasanya, kebijakan KeyValueMapOperations digunakan untuk menyimpan atau mengambil informasi berumur panjang yang perlu digunakan kembali pada beberapa transaksi permintaan/respons.

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

Menetapkan dan mengambil nama kunci

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

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

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

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

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

Topik terkait

Lihat topik berikut untuk informasi lebih lanjut tentang KVM: