Kebijakan KeyValueMapOperations

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

Apa

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

Video

Tonton video berikut untuk mempelajari lebih lanjut KVM.

Contoh

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

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

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

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

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

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

Referensi elemen

Referensi elemen menjelaskan elemen dan atribut kebijakan KeyValueMapOperations:

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

Atribut <KeyValueMapOperations>

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

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

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

Elemen <Delete>

Menghapus pasangan kunci/nilai 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>

Elemen <Entry>

Nilai awal untuk peta nilai kunci, yang diisi dalam peta nilai kunci saat diinisialisasi.

Untuk Edge untuk 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>

Elemen <ExclusiveCache>

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

Elemen <ExpiryTimeInSecs>

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

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

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

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, Edge 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 penyimpanan kunci/nilai yang digunakan dalam kebijakan di cache sebelum diperbarui lagi dari KVM. Namun, ada beberapa perbedaan antara pengaruh operasi GET dan PUT terhadap 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) 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 berakhir.
  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.

Contoh - Menyimpan KVM ke dalam cache

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 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 dijalankan dan mengambil nilai "8".

Elemen <Get>

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 blok Get dalam kebijakan untuk mengambil beberapa item dari KVM.

Mendapatkan satu item dari KVM

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

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

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

Atribut

Tabel berikut menjelaskan atribut elemen <Get>:

<Get assignTo="private.myvar">

Elemen <InitialEntries>

Nilai awal untuk peta nilai kunci, yang diisi dalam peta nilai kunci saat diinisialisasi. Pastikan untuk menentukan nama KVM dengan atribut mapIdentifier pada 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 proxy yang di-deploy, atau men-deploy paket proxy API yang berisi kebijakan dengan elemen ini, kunci akan dibuat secara otomatis di KVM (sebagai tidak terenkripsi). Jika nilai dalam kebijakan berbeda dengan nilai dalam KVM, nilai dalam KVM akan diganti saat proxy 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 untuk Edge untuk Public Cloud dan Edge untuk Private Cloud. Nilai KVM dibatasi hingga 2 KB.

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

Elemen <Key>

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

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

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

Dengan Edge untuk Public Cloud, ukuran kunci dibatasi hingga 2 KB. Lihat Perbedaan antara Edge untuk API Cloud Publik dan API Cloud Pribadi untuk mengetahui informasi selengkapnya.

Elemen <Parameter>

Menentukan kunci dalam pasangan kunci/nilai. Elemen ini menentukan nama saat membuat, menempatkan, 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 Kunci menyertakan beberapa elemen Parameter, string kunci yang efektif adalah penggabungan 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 dalam peta nilai kunci. Lihat Menentukan dan mengambil nama kunci untuk mengetahui panduannya.

Atribut

Tabel berikut menjelaskan atribut elemen <Parameter>:

Elemen <Put>

Menulis key-value pair ke peta nilai kunci, baik peta nilai kunci dienkripsi maupun tidak dienkripsi. Jika peta nilai kunci yang ditentukan dalam atribut mapIdentifier pada elemen induk tidak ada, peta akan dibuat secara otomatis (sebagai tidak dienkripsi). Jika peta nilai kunci sudah ada, kunci/nilai akan ditambahkan ke peta tersebut.

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 yang tercakup dalam lingkungan di UI.

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

Atribut

Tabel berikut menjelaskan atribut elemen <Put>:

Elemen <Scope>

Menentukan batas aksesibilitas untuk peta nilai kunci. Cakupan default adalah environment, yang berarti bahwa, secara default, entri peta dibagikan oleh semua proxy API yang berjalan di lingkungan (misalnya, test atau prod). Jika Anda menyetel cakupan ke apiproxy, entri dalam peta nilai kunci 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>

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>

Atribut

Tabel berikut menjelaskan atribut elemen <Value>:

Referensi error

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

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

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Error saat deployment

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

Skema

Catatan penggunaan

Untuk ringkasan peta nilai kunci, lihat Bekerja dengan peta nilai kunci.

Penyimpanan peta nilai kunci 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.

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. Peta nilai kunci dapat menyimpan banyak entri.

Berikut adalah contoh penggunaan peta nilai kunci. Misalnya, Anda perlu menyimpan daftar alamat IP yang terkait dengan berbagai lingkungan backend. Anda dapat membuat peta nilai kunci yang disebut 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 atau tidak diizinkan, 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.

Peta key/value dapat dimanipulasi melalui kebijakan KeyValueMapOperations, atau langsung melalui Apigee Edge Management API. Lihat referensi API Management untuk mengetahui detail tentang Organization key/value maps API API. Anda dapat menggunakan API untuk, misalnya, mengupload set data besar ke penyimpanan key/value, atau membuat skrip untuk mengelola entri peta key/value. Anda harus membuat peta nilai/kunci 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 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 dalam 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".

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

Topik terkait

• API peta nilai kunci organisasi