Kebijakan KeyValueMapOperations

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

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 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 KVM lebih lanjut.

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 sama untuk semua elemen induk kebijakan:

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>

Elemen <Delete>

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>

Elemen <Entry>

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>

Elemen <ExclusiveCache>

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

Elemen <ExpiryTimeInSecs>

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

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

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

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 performa, Edge memiliki mekanisme bawaan untuk meng-cache kunci/nilai KVM dalam memori selama runtime. Kebijakan Operasi KVM ini selalu membaca dari cache untuk operasi GET.

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

GET - Saat pertama kali operasi GET KVM dieksekusi, kunci/nilai yang diminta dari KVM (yang namanya ditentukan dalam atribut mapIdentifier root kebijakan) akan dimuat ke dalam cache, tempat kunci/nilai tersebut tetap berada untuk operasi GET berikutnya hingga salah satu dari hal berikut terjadi:

• Jumlah detik yang ditentukan dalam <ExpiryTimeInSecs> akan 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 melakukan operasi tulis ke kunci yang sudah ada dalam cache, cache tersebut akan langsung dimuat ulang dan sekarang menyimpan nilai baru selama jumlah detik yang ditentukan dalam elemen <ExpiryTimeInSecs> kebijakan.

Contoh - Menyimpan cache KVM

1. Operasi GET mengambil nilai "rating", yang menambahkan nilai "10" ke cache. <ExpiryTimeInSecs> pada kebijakan adalah 60.
2. 30 detik kemudian, kebijakan GET dijalankan kembali dan mengambil "10" dari cache.
3. 5 detik kemudian, kebijakan PUT akan memperbarui nilai "rating" menjadi "8", dan <ExpiryTimeInSecs> pada kebijakan PUT adalah 20. Cache akan langsung diperbarui dengan nilai baru, yang kini disetel agar tetap berada dalam cache selama 20 detik. (Jika PUT tidak terjadi, cache yang awalnya diisi oleh GET pertama akan tetap ada selama 30 detik berikutnya, yang tersisa dari 60 detik yang asli.)
4. 15 detik kemudian, GET lain dieksekusi 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

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

Berikut adalah konfigurasi kebijakan KVM yang dapat kita gunakan untuk mengambil film paling populer 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 di 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>

Ketika menggunakan elemen ini, ketika 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 otomatis dibuat di KVM (sebagai tidak dienkripsi). Jika nilai dalam kebijakan berbeda dengan nilai di KVM, nilai dalam KVM akan ditimpa 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 literal. Misalnya, <Parameter ref="request.queryparam.key"> tidak didukung dalam elemen ini.

Ukuran kunci dibatasi hingga 2 KB untuk Edge untuk Cloud Publik dan Edge untuk Private Business. 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 bersifat gabungan, artinya 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 Anda melihat elemen <Parameter> untuk mengetahui hal-hal spesifik tentang cara menetapkan 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 informasi selengkapnya.

Elemen <Parameter>

Menentukan kunci dalam key-value pair. Elemen ini menentukan nama saat membuat, menempatkan, mengambil, atau menghapus key-value pair.

Anda dapat menentukan nama menggunakan:

• Sebuah {i>string<i} literal

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

• Variabel yang akan diambil pada waktu proses, 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 penyambungan nilai setiap parameter, yang digabungkan dengan garis bawah ganda. Misalnya, dalam contoh di atas, jika variabel apiproxy.name memiliki nilai "abc1", kunci yang efektif adalah targeturl__abc1__weight.

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

Atribut

Tabel berikut menjelaskan atribut elemen <Parameter>:

Elemen <Put>

Menulis key-value pair ke peta nilai kunci, baik peta nilai kunci dienkripsi maupun tidak. Jika peta nilai kunci yang ditentukan dalam atribut mapIdentifier pada elemen induk tidak ada, peta akan otomatis dibuat (sebagai tidak dienkripsi). Jika peta nilai kunci sudah ada, kunci/nilai tersebut akan 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 cakupan lingkungan terenkripsi 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 defaultnya adalah environment, artinya, secara default, entri peta digunakan bersama oleh semua proxy API yang berjalan di lingkungan (misalnya, pengujian atau produksi). Jika Anda menetapkan 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 menetapkan nilai cakupan yang sama dengan yang digunakan saat peta dibuat. Misalnya, jika peta dibuat dengan cakupan apiproxy, Anda harus menggunakan cakupan apiproxy saat mengambil nilainya, menempatkan 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 pada 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 pada 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>

Pada contoh berikut, satu kunci dibuat dengan dua nilai. Anggaplah nama organisasinya adalah foo_org, nama proxy API-nya 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 apa pun 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. Misalkan Anda perlu menyimpan daftar alamat IP yang terkait dengan berbagai lingkungan backend. Anda dapat membuat peta nilai kunci bernama ipAddresses yang berisi daftar key-value pair sebagai entri. Misalnya, JSON ini dapat merepresentasikan peta berikut:

{
  "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 ditolak, untuk memilih alamat target backend secara dinamis, dan sebagainya. Biasanya, kebijakan KeyValueMapOperations digunakan untuk menyimpan atau mengambil informasi berumur panjang yang perlu digunakan kembali melalui beberapa transaksi permintaan/respons.

Peta kunci/nilai dapat dimanipulasi melalui kebijakan KeyValueMapOperations, atau langsung melalui API pengelolaan Apigee Edge. Lihat referensi API pengelolaan untuk mengetahui detail tentang API peta/kunci organisasi. Anda dapat menggunakan API untuk, misalnya, mengupload set data besar ke penyimpanan kunci/nilai, atau membuat skrip untuk mengelola entri peta kunci/nilai. Anda harus membuat peta kunci/nilai dengan API sebelum mengaksesnya dengan kebijakan KeyValueMapOperations.

Menentukan dan mengambil nama kunci

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

Elemen Parameter perlu disebutkan secara khusus, karena menentukan nama kunci yang dibuat, serta nama kunci yang ingin diambil atau dihapus. Berikut adalah dua contohnya. Yang pertama menentukan nama kunci secara harfiah, dan yang kedua menentukan nama kunci menggunakan variabel. Anggaplah 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 nama kunci. Pada instance kedua, nilai apa pun yang ada dalam key.name.variable akan menjadi nama kunci di KVM. Misalnya, jika key.name.variable berisi nilai foo, kunci akan diberi nama "foo".

Jika 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 dalam KVM adalah "foo", Anda dapat menentukan nilai literal dengan <Parameter>foo</Parameter> atau menentukan variabel yang berisi nilai persis "foo", seperti ini: <Parameter ref="variable.containing.foo"/>.

Topik terkait

• API peta kunci/nilai organisasi