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

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

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

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

<DisplayName> elemen

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

<DisplayName>Policy Display Name</DisplayName>

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

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

<ExclusiveCache> elemen

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

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

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.

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.

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

<Get assignTo="private.myvar">

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

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

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

Atribut

Tabel berikut menjelaskan atribut elemen <Parameter>:

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

Atribut

Tabel berikut menjelaskan atribut elemen <Put>:

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

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

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

• API peta nilai/kunci organisasi