Kebijakan KeyValueMapOperations

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

Ikon Operasi Peta Nilai Kunci dari UI Edge

Apa

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

Video

Tonton video berikut untuk mempelajari KVM lebih lanjut.

Video Deskripsi
Alasan Nilai Kunci Maps? Pelajari mengapa Anda membutuhkan KVM dan cara kerjanya.
Buat KVM menggunakan UI dan mengambil KVM saat runtime Membuat KVM, mengambil nilainya menggunakan kebijakan KVM, dan memasukkan nilainya ke dalam API permintaan menggunakan variabel alur.
Membuat dan memperbarui KVM di runtime API Buat KVM pada runtime API menggunakan kebijakan KVM.
Cache KVM ke meningkatkan performa Meningkatkan performa Kebijakan KVM dengan meng-cache data.
Simpan terenkripsi KVM Simpan informasi sensitif di KVM dalam format terenkripsi dan ambil nilainya runtime yang menggunakan kebijakan KVM dan variabel pribadi.
Kelola akses menggunakan cakupan KVM Membatasi KVM ke organisasi, lingkungan, proxy API, atau revisi proxy API menggunakan KVM kebijakan cakupan.
Hapus KVM entri pada runtime API Hapus entri KVM saat runtime API menggunakan operasi DELETE kebijakan KVM.

Contoh

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>

PUT KVM dengan variabel

Contoh sederhana peta nilai kunci yang berguna adalah layanan pemendekan URL. Peta nilai kunci dapat dikonfigurasi untuk menyimpan URL singkat beserta URL lengkap yang sesuai.

Contoh kebijakan ini membuat peta nilai kunci. Kebijakan PUT kunci dengan dua nilai terkait ke peta kunci/nilai 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

Peta kunci/nilai dan entri berikut akan dibuat di penyimpanan kunci/nilai Edge 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 Edge yang menjalankan cloud.

MENDAPATKAN KVM dari variabel

Contoh sederhana peta nilai kunci yang berguna adalah 'pemendekan' URL layanan. Peta nilai kunci dapat dikonfigurasi untuk menyimpan URL singkat beserta URL lengkap yang sesuai.

Untuk mengambil nilai entri peta kunci/nilai, seperti yang dibahas pada Tab PUT KeyValueMapOperations, konfigurasi kebijakan untuk MENDAPATKAN peta nilai kunci:

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

GET nilai terenkripsi dari KVM

Jika peta nilai kunci dienkripsi, ambil nilai menggunakan "private." di nilai atribut assignTo. Dalam contoh ini, variabel private.encryptedVar menyimpan nilai yang didekripsi dari peta nilai kunci Tombol foo. Untuk informasi tentang pembuatan peta nilai kunci terenkripsi, lihat dokumentasi "create" topik Peta Kunci/Nilai Google Cloud Management API.

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

Referensi elemen

Referensi elemen menjelaskan elemen dan atribut KeyValueMapOperations kebijakan:

<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>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

&lt;KeyValueMapOperations&gt; atribut

Contoh berikut menunjukkan atribut pada tag <KeyValueMapOperations>:

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

Tabel berikut menjelaskan atribut khusus untuk tag <KeyValueMapOperations>:

Atribut Deskripsi Default Ketersediaan
mapIdentifier

Menentukan ID yang akan digunakan saat mengakses peta yang dibuat oleh entitas ini kebijakan atau di UI pengelolaan.

Nama KVM peka huruf besar/kecil dengan Apigee Edge for Public Cloud. Misalnya, foobar berbeda dengan FooBar.

Jika Anda mengecualikan atribut ini, KVM bernama kvmap akan digunakan.

Dalam cakupan organisasi/environment/apiproxy, Anda dapat menggunakan Atribut mapIdentifier untuk menentukan nama peta Anda sendiri.

 T/A Opsional

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

Atribut Deskripsi Default Ketersediaan
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 kebijakan di editor proxy UI pengelolaan dengan nama natural language yang berbeda.

 T/A Wajib
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur dapat dilanjutkan bahkan setelah kebijakan gagal.

 salah Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan ini tidak akan ditegakkan meskipun tetap terikat pada alur.

 true Opsional
async

Atribut ini tidak digunakan lagi.

 salah Tidak digunakan lagi

&lt;DisplayName&gt; elemen

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI dengan nama natural language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan menjadi data
Ketersediaan Opsional
Jenis String

&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 induk. Contoh:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>
Default T/A
Ketersediaan Wajib diisi jika <Get> atau <Put> tidak ada.
Jenis T/A

&lt;Entry&gt; elemen

Nilai seed untuk peta nilai kunci, yang diisi di peta nilai kunci saat diinisialisasi.

Untuk Edge for Public Cloud, 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
Ketersediaan 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 Edge 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)
Ketersediaan 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 , Edge memiliki mekanisme bawaan untuk menyimpan cache kunci/nilai KVM 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 bagaimana operasi GET dan PUT memengaruhi akhir masa berlaku cache.

GET - Saat pertama kali operasi GET KVM dijalankan, permintaan kunci/nilai dari KVM (yang namanya ditentukan dalam root kebijakan mapIdentifier ) dimuat ke dalam cache, di mana mereka tetap ada untuk operasi GET berikutnya hingga salah satu hal berikut akan terjadi:

  • Jumlah detik yang ditentukan dalam <ExpiryTimeInSecs> berakhir.
    atau
  • Operasi PUT dalam kebijakan KVM menimpa nilai yang 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>.

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 dijalankan lagi dan mengambil "10" dari cache.
  3. 5 detik kemudian, kebijakan PUT memperbarui nilai "rating" ke "8", 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.

Pastikan untuk menentukan nama KVM dengan atribut mapIdentifier pada elemen induk.

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

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

Mendapatkan satu item dari KVM

<Get assignTo="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

Berikut adalah konfigurasi kebijakan KVM yang dapat digunakan untuk mengambil film terpopuler 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, Edge akan membuat kode variabel yang dapat Anda gunakan dalam alur proxy API:

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

Atribut

Tabel berikut menjelaskan atribut elemen <Get>:

Atribut Deskripsi Default Ketersediaan
assignTo

Variabel yang harus diberi nilai yang diambil.

Jika peta nilai kunci dienkripsi, mulai tetapkan nama assignTo dengan "private.". Contoh:

<Get assignTo="private.myvar">

Kebijakan ini akan menampilkan error jika Anda mencoba mengambil peta nilai kunci yang dienkripsi tanpa menggunakan awalan. Awalan, yang diperlukan untuk tujuan keamanan dasar selama proses debug, menyembunyikan nilai terenkripsi dari Trace proxy API dan sesi debug.

Untuk informasi tentang pembuatan peta nilai kunci terenkripsi, lihat dokumentasi "create" topik dari Pengelolaan Maps Kunci/Nilai API dan Membuat dan mengedit peta nilai kunci lingkungan.

 T/A Wajib
indeks

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 dokumentasi "Mendapatkan Nilai Terenkripsi dari KVM" di Sample.

 T/A Opsional

&lt;InitialEntries&gt; elemen

Nilai seed untuk peta nilai kunci, yang diisi dalam peta nilai kunci saat diinisialisasi. Pastikan untuk menentukan nama KVM dengan atribut mapIdentifier di elemen induk. misalnya:

<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 pengelolaan pada versi yang di-deploy proxy, atau terapkan paket proxy API yang berisi kebijakan dengan elemen ini, kunci otomatis dibuat di KVM (sebagai tidak dienkripsi). Jika nilai dalam kebijakan berbeda daripada nilai-nilai dalam KVM, nilai-nilai dalam KVM akan ditimpa ketika proxy 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 bagi Edge untuk Public Cloud dan Edge untuk Pribadi Bisa. Nilai KVM dibatasi hingga 2 KB.

Untuk membuat KVM terenkripsi, gunakan Key/Value Maps Management API.

Default T/A
Ketersediaan Opsional
Jenis T/A

&lt;Key&gt; elemen

Menentukan kunci dalam entri peta kunci/nilai. Sebuah kunci dapat berupa komposit, yang berarti bahwa lebih dari satu parameter dapat ditambahkan untuk membuat kunci. Misalnya, userID dan role mungkin digabungkan untuk membuat key. Contoh:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

Pastikan untuk melihat elemen &lt;Parameter&gt; untuk informasi spesifik tentang cara tetapkan nama kunci.

Dengan Edge for Public Cloud, ukuran kunci dibatasi hingga 2 KB. Lihat Perbedaan antara Edge untuk Public Cloud API dan Private Cloud API untuk mengetahui lebih lanjut.

Default T/A
Ketersediaan Opsional
Jenis T/A

&lt;Parameter&gt; elemen

Menentukan kunci dalam pasangan kunci/nilai. Elemen ini menentukan nama saat membuat, menempatkan, 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>

Ketika elemen Key mencakup beberapa elemen Parameter, string kunci yang 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 pada peta nilai kunci. Lihat Menentukan dan mengambil nama kunci untuk panduan.

Default T/A
Ketersediaan Wajib
Jenis String

Atribut

Tabel berikut menjelaskan atribut elemen <Parameter>:

Atribut Deskripsi Default Ketersediaan
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. Dilarang jika nilai literal diberikan.

&lt;Put&gt; elemen

Menulis pasangan kunci/nilai ke peta nilai kunci, baik peta nilai kunci dienkripsi maupun tidak dienkripsi. Jika peta nilai kunci ditentukan dalam atribut mapIdentifier di elemen induk tidak ada, peta akan otomatis dibuat (sebagai tidak dienkripsi). Jika nilai kunci peta sudah ada, kunci/nilai ditambahkan ke dalamnya.

Untuk membuat peta nilai kunci terenkripsi, gunakan Key/Value Maps management API; atau lihat Membuat dan mengedit peta nilai kunci lingkungan untuk membuat KVM terenkripsi dengan cakupan lingkungan di UI.

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

Atribut

Tabel berikut menjelaskan atribut elemen <Put>:

Atribut Deskripsi Default Ketersediaan
penggantian

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

 false Opsional

&lt;Scope&gt; elemen

Mendefinisikan batas aksesibilitas untuk peta nilai kunci. Cakupan default-nya adalah environment, artinya, secara default, entri peta digunakan bersama oleh semua proxy API yang berjalan di suatu lingkungan (misalnya, uji atau produksi). Jika Anda mengatur ruang lingkup ke apiproxy, maka entri dalam peta nilai kunci 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
Ketersediaan 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
Ketersediaan Wajib
Jenis String

Atribut

Tabel berikut menjelaskan atribut elemen <Value>:

Atribut Deskripsi Default Ketersediaan
referensi 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

Error yang ditampilkan dari kebijakan Edge mengikuti format yang konsisten seperti yang dijelaskan dalam Referensi kode error.

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.keyvaluemapoperations.SetVariableFailed 500

This error occurs if you try to retrieve a value from an encrypted key value map and set the value to a variable whose name does not have the prefix private. The prefix, which is required for basic security purposes during debugging, hides the encrypted values from API proxy Trace and debug sessions.
steps.keyvaluemapoperations.UnsupportedOperationException 500

This error occurs if the mapIdentifier attribute is set to empty string in the Key Value Map Operations policy.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidIndex If the index attribute specified in the <Get> element of Key Value Map Operations policy is zero or a negative number, then the deployment of the API proxy fails. The index starts from 1, so an index of zero or negative integer is considered as invalid.
KeyIsMissing This error occurs if the <Key> element is completely missing or <Parameter> element is missing within <Key> element underneath the <Entry> of the <InitialEntries> element of the Key Value Map Operations policy.
ValueIsMissing This error occurs if the <Value> element is missing underneath the <Entry> element of the <InitialEntries> element of the Key Value Map Operations policy.

Skema

Catatan penggunaan

Untuk ringkasan peta nilai kunci, lihat Menggunakan peta nilai kunci.

Penyimpanan peta nilai kunci menyediakan mekanisme persistensi yang ringan untuk data yang diformat sebagai 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. Peta nilai kunci dapat menyimpan banyak entri.

Berikut adalah contoh penggunaan peta nilai kunci. Misalkan Anda perlu menyimpan daftar alamat IP yang terkait dengan berbagai backend lingkungan fleksibel App Engine. Anda dapat membuat peta nilai kunci 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 atau 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.

Peta kunci/nilai dapat dimanipulasi melalui kebijakan KeyValueMapOperations, atau secara langsung melalui API pengelolaan Apigee Edge. Lihat referensi API pengelolaan untuk mengetahui detail tentang API peta nilai/kunci organisasi. Anda dapat menggunakan API ini untuk misalnya, mengupload set data besar ke penyimpanan kunci/nilai, atau membuat skrip untuk mengelola kunci/nilai entri peta. Anda harus membuat peta kunci/nilai 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 contoh 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 diberi nama "foo".

Saat Anda ingin mengambil kunci dan nilai kunci dengan operasi GET (atau hapus dengan DELETE), <Parameter> harus sesuai dengan nama kunci di KVM. Sebagai jika nama kunci dalam KVM adalah "{i>foo<i}, Anda dapat menentukan nilai literal dengan <Parameter>foo</Parameter> atau tentukan variabel yang berisi variabel yang tepat "foo", seperti ini: <Parameter ref="variable.containing.foo"/>.

Topik terkait