Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Apa
Menyediakan akses berbasis kebijakan ke penyimpanan peta nilai kunci (KVM) yang tersedia di Apigee.
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.)
Kebijakan ini merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.
Video: Video berikut memberikan pengantar umum tentang KVM.
Sampel
PUT KVM dengan literal
Saat dijalankan, kebijakan berikut akan membuat KVM terenkripsi bernama FooKVM
, lalu membuat kunci bernama FooKey_1
dengan dua nilai yang ditetapkan dengan string literal foo
dan bar
(tidak ditetapkan dengan nilai yang diekstrak dari variabel). Saat GET
kunci di contoh berikutnya, Anda menetapkan nomor indeks untuk mengambil nilai yang diinginkan.
<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
. Ini berarti Anda dapat melihat KVM di UI pengelolaan di bagian APIs > Environment Configuration > Key Value Maps. KVM yang ditampilkan di halaman tersebut tercakup dalam lingkungan yang dipilih.
DAPATKAN KVM dari literal
Kebijakan ini melihat peta FooKVM
dari contoh sebelumnya, mendapatkan nilai kedua (index="2") dari kunci FooKey_1
, dan menyimpannya dalam variabel bernama 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 ini mendapatkan ID KVM dari variabel flow. Perhatikan bahwa atribut 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 KVM yang berguna adalah layanan penyingkatan URL. KVM dapat dikonfigurasi untuk menyimpan URL yang disingkat beserta URL lengkap yang terkait.
Contoh kebijakan ini akan membuat KVM. Kebijakan ini menggunakan perintah PUT
untuk menempatkan
kunci dengan dua nilai terkait
ke dalam 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 dihasilkan oleh kode (misalnya JavaScript atau Java), lalu disimpan dalam variabel ini, tempat kebijakan KeyValueMapOperations dapat mengaksesnya.
Dua nilai disimpan untuk setiap kunci, requesturl.hashed
:
- Konten variabel kustom bernama
urlencoding.longurl.encoded
- Konten variabel
request.queryparam.url
yang telah ditentukan
Misalnya, jika kebijakan dieksekusi saat runtime, nilai variabelnya mungkin sebagai berikut:
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 dicakupkan ke proxy API yang melampirkan kebijakan:
{ "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 seluruh instance Apigee yang menjalankan cloud.
GET KVM dari variabel
Contoh sederhana KVM yang berguna adalah layanan penyingkatan URL. KVM dapat dikonfigurasi untuk menyimpan URL yang disingkat beserta URL lengkap yang terkait.
Untuk mengambil nilai entri KVM, seperti yang tercakup di 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 diterapkan, jika nilai variabel
urlencoding.requesturl.hashed
adalah
ed24e12820f2f900ae383b7cc4f2b31c402db1be
, variabel kustom bernama
urlencoding.shorturl
akan disetel dengan nilai
http://tinyurl.com/38lwmlr
.
Setelah data diambil, kebijakan dan kode lain dapat mengaksesnya dengan mengekstrak nilai dari variabel tersebut.
GET nilai dari KVM
Gunakan atribut private.
dengan semua variabel saat mengakses KVM dengan
perintah GET
untuk menyembunyikan informasi KVM dalam sesi Debug. Jika atribut
private.
tidak digunakan, KVM masih dienkripsi; namun, informasi KVM
akan tampak didekripsi dalam sesi Debug dan tidak ada pengecualian yang akan ditampilkan.
Dalam contoh ini, variabel private.encryptedVar
menyimpan nilai kunci foo
KVM yang didekripsi.
<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.
<KeyValueMapOperations>
Menyediakan akses berbasis kebijakan ke peta nilai kunci (KVM).
Sintaksis
<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>
Atribut <KeyValueMapOperations>
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 |
T/A | Opsional |
Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
T/A | Diperlukan |
continueOnError |
Setel ke Setel ke |
false | Opsional |
enabled |
Setel ke Setel ke |
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 |
---|---|
Kehadiran | Opsional |
Jenis | String |
Elemen turunan
Bagian ini menjelaskan elemen dan atribut kebijakan KeyValueMapOperations:
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 root atau dengan elemen <MapName>
. Contoh:
<Delete> <Key> <Parameter>KEY_NAME_LITERAL</Parameter> </Key> </Delete>
Default | T/A |
---|---|
Kehadiran | Wajib jika <Get> atau <Put> tidak ada. |
Jenis | T/A |
Elemen <Entry>
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 |
Elemen <ExclusiveCache>
Tidak digunakan lagi. Sebagai gantinya, gunakan elemen <Scope>
.
Elemen <ExpiryTimeInSecs>
Menentukan durasi dalam detik setelah Apigee memuat ulang nilai yang disimpan dalam cache dari KVM yang ditentukan.
Nilai 0 atau -1, atau tidak termasuk elemen ini, berarti nilai default 300 detik digunakan. 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 performa, Apigee 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 durasi penyimpanan kunci/nilai
yang digunakan dalam kebijakan dalam cache sebelum di-refresh lagi 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
atau elemen <MapName>
) dimuat ke dalam cache, dan disimpan untuk operasi GET
berikutnya hingga salah satu
hal berikut terjadi:
- Jumlah detik yang ditentukan dalam
<ExpiryTimeInSecs>
akan berakhir.
atau - Operasi
PUT
dalam kebijakan KVM menimpa nilai yang ada (akan dijelaskan selanjutnya).
PUT
- Operasi PUT
menulis kunci/nilai ke KVM yang ditentukan. Jika PUT
menulis ke kunci yang sudah ada di cache, cache tersebut akan langsung dimuat ulang dan sekarang memiliki nilai baru selama jumlah detik yang ditentukan dalam elemen <ExpiryTimeInSecs>
kebijakan. Namun, menggunakan PUT
hanya akan memperbarui cache
dalam node runtime tunggal yang melayani permintaan. Untuk memuat ulang cache di setiap node runtime terdistribusi,
gunakan elemen <ExpiryTimeInSecs>
untuk menentukan interval refresh bagi setiap node.
Contoh - Menyimpan KVM ke dalam cache
- Operasi
GET
mengambil nilai "rating", yang menambahkan nilai "10" ke cache.<ExpiryTimeInSecs>
pada kebijakan adalah 60. - 30 detik kemudian, kebijakan
GET
akan dijalankan lagi dan mengambil10
dari cache. - 5 detik kemudian, kebijakan
PUT
akan memperbarui nilairating
menjadi10
, dan<ExpiryTimeInSecs>
pada kebijakanPUT
adalah 20. Cache langsung dimuat ulang dengan nilai baru, yang sekarang disetel untuk tetap berada dalam cache selama 20 detik. (JikaPUT
tidak terjadi, cache yang awalnya diisi olehGET
pertama akan tetap ada selama 30 detik berikutnya, yang tersisa dari 60 detik awal.) - 15 detik kemudian,
GET
lainnya akan dieksekusi dan mengambil nilai8
.
Elemen <Get>
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 mengetahui detailnya, lihat Tentang kunci enkripsi. Saat menggunakan <Get>
, Apigee mendekripsi data yang disimpan dan menetapkannya ke variabel dalam konteks pesan. Nama variabel ditentukan menggunakan
atribut assignTo
.
Pastikan untuk menentukan nama KVM dengan atribut mapIdentifier
pada elemen root atau dengan elemen <MapName>
.
Anda dapat menyertakan beberapa blok Get
dalam kebijakan untuk mengambil beberapa item
dari KVM.
Default | T/A |
---|---|
Kehadiran | Wajib jika <Put> atau <Delete> tidak
ada. |
Jenis | T/A |
Atribut
Tabel berikut menjelaskan atribut elemen <Get>:
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
assignTo |
Variabel tempat nilai yang diambil harus ditetapkan. |
T/A | Diperlukan |
index |
Nomor indeks (dalam indeks berbasis 1) item yang akan diambil dari kunci multi-nilai.
Misalnya, menentukan Sebagai contoh, lihat tab Get Value from KVM di Sample. |
T/A | Opsional |
Mendapatkan satu item dari KVM
Dengan contoh konfigurasi langkah ini, kebijakan membaca dan mendekripsi nilai satu 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. Agar data yang diambil tidak muncul dalam sesi Debug, gunakan awalan private.
pada nama variabel yang ditetapkan dalam atribut assignTo
. Jika Anda tidak menggunakan
awalan private.
, data yang diambil dari KVM akan muncul dalam
cleartext, pada setiap sesi Debug yang Anda buat.
Dengan contoh konfigurasi langkah ini, kebijakan membaca dan mendekripsi nilai yang terkait dengan satu kunci di KVM dan menetapkan nilai tersebut ke sebuah variabel. Penetapan tidak akan muncul dalam 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 menyimpan daftar film terpopuler sepanjang masa, KVM menyimpan nama sutradara untuk semua film besar.
Kunci | Nilai |
---|---|
top_movies | Pengantin Putri,Sang Dewa,Warga Negara Kane |
Warga Negara Kane | Sumur Orson |
Pengantin Putri | Rob Reiner |
The Godfather | Francis Ford Coppola |
Anda akan melihat nilai yang terkait dengan kunci top_movies
berisi beberapa nama film yang dipisahkan dengan koma.
Dengan contoh konfigurasi ini, kebijakan akan mengambil film teratas 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, Apigee akan membuat variabel berikut dengan nilai yang sesuai, yang dapat 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
1.
Kemudian, elemen <Get>
kedua menggunakan nilai yang ditetapkan ke top.movie.pick
sebagai kunci untuk mengambil nilai ke dalam movie.director
.
Elemen <InitialEntries>
Nilai seed untuk KVM, yang diisi di KVM saat diinisialisasi.
Pastikan untuk menentukan nama KVM dengan atribut mapIdentifier
pada 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>
Ketika menggunakan elemen ini, ketika Anda menyimpan kebijakan di UI Apigee pada versi proxy API yang di-deploy, atau men-deploy paket proxy API yang berisi kebijakan dengan elemen ini, kunci tersebut akan otomatis dibuat di KVM. Jika nilai dalam kebijakan berbeda dengan nilai di KVM, nilai di KVM akan ditimpa saat proxy API di-deploy. Semua kunci/nilai baru akan 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 |
Elemen <Key>
Menentukan kunci dalam entri KVM. Elemen ini muncul sebagai turunan dari <Get>
,
<Put>
, atau <Delete>
, atau
sebagai turunan dari elemen <Entry>
yang merupakan turunan dari <InitialEntries>
.
Berikut ini contoh kunci tetap:
<Key> <Parameter>KEY_NAME_LITERAL</Parameter> </Key>
Kunci dapat bersifat gabungan, dengan elemen dinamis, yang berarti lebih dari satu <Parameter>
dapat ditambahkan untuk membuat kunci. Misalnya, isi variabel userID
dan role
dapat digabungkan untuk membuat kunci dinamis. Berikut adalah contoh konfigurasi langkah yang menentukan kunci gabungan yang ditentukan secara dinamis:
<Key> <Parameter ref='userID'/> <Parameter ref='role'/> </Key>
Pastikan Anda melihat elemen <Parameter>
untuk mengetahui detail tentang cara menetapkan nama kunci.
Ukuran kunci dibatasi hingga 2 KB.
Default | T/A |
---|---|
Kehadiran | Opsional |
Jenis | T/A |
Elemen <MapName>
Elemen <MapName>
memungkinkan kebijakan mengidentifikasi KVM mana yang akan digunakan secara dinamis, pada saat runtime.
Kemampuan untuk memilih KVM secara dinamis memberi Anda fleksibilitas untuk mendesain satu kebijakan KeyValueMapOperations
yang dapat mengakses
KVM berbeda, bergantung pada konteks tempat kebijakan dijalankan.
Contohnya antara lain:
<!-- 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 mendapatkan nama dari variabel alur. Di baris ketiga, jika variabel flow me-resolve ke nilai kosong, string literal akan digunakan sebagai gantinya.
Jangan tentukan atribut mapIdentifier
jika Anda menggunakan
<MapName>
dalam kebijakan Anda. Lihat atribut kebijakan untuk mengetahui informasi selengkapnya.
Jika peta tidak ada saat proxy di-deploy, peta tidak akan dibuat dan Apigee akan menampilkan error runtime saat kebijakan dijalankan. Jika variabel flow disediakan, elemen
<InitialEntries>
tidak diizinkan. Anda akan mendapatkan error validasi selama deployment.
Elemen <Parameter>
Menentukan komponen kunci dalam key-value pair. Elemen ini menentukan nama saat membuat, memperbarui, mengambil, atau menghapus key-value pair.
Anda dapat menentukan nama tersebut 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 literal dan referensi variabel
<Key> <Parameter>targeturl</Parameter> <Parameter ref="apiproxy.name"/> <Parameter>weight</Parameter> </Key>
Jika elemen <Key>
menyertakan beberapa elemen <Parameter>
, string kunci yang efektif adalah
penyambungan nilai dari setiap parameter, yang digabungkan dengan garis bawah ganda. Misalnya, dalam contoh di atas, jika variabel apiproxy.name
memiliki nilai abc1
, maka kunci yang efektif adalah targeturl__abc1__weight
.
Baik Anda mendapatkan, mengupdate, atau menghapus entri kunci/nilai, nama kunci harus sama dengan nama kunci di KVM. Lihat Menentukan dan mengambil nama kunci untuk panduan.
Default | T/A |
---|---|
Kehadiran | Diperlukan |
Jenis | String |
Atribut
Tabel berikut menjelaskan atribut elemen <Parameter>
:
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
referensi | Menentukan nama variabel yang nilainya berisi nama persis kunci yang ingin Anda buat, dapatkan, atau hapus. | T/A | Wajib jika tidak ada nilai literal yang diberikan di antara tag pembuka dan penutup. |
Elemen <Put>
Menulis key-value pair ke KVM. Jika KVM yang ditentukan dalam atribut mapIdentifier
pada elemen root tidak ada dan jika elemen <MapName>
tidak digunakan, peta akan dibuat secara otomatis. Jika peta nilai kunci sudah ada, kunci/nilai akan ditambahkan ke peta tersebut.
Untuk membuat KVM menggunakan UI atau API, lihat:
- Menggunakan KVM dengan UI Apigee untuk membuat KVM dengan cakupan lingkungan terenkripsi di UI
- API peta nilai kunci cakupan organisasi
- Maps API nilai kunci cakupan lingkungan
- API nilai kunci cakupan proxy API
<Put override="false"> <Key> <Parameter ref="mykeyvar"/> </Key> <Value ref="myvalvar1"/> </Put>
Default | T/A |
---|---|
Kehadiran | Wajib jika <Get> atau <Delete> tidak
ada. |
Jenis | T/A |
Atribut
Tabel berikut menjelaskan atribut elemen <Put>
:
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
abaikan |
Jika ditetapkan ke
|
true |
Opsional |
Elemen <Scope>
Menentukan batas aksesibilitas untuk KVM. Cakupan defaultnya adalah environment
, yang berarti bahwa secara default entri peta dibagikan oleh semua proxy API yang berjalan di suatu lingkungan (misalnya, pengujian atau produksi). Jika Anda menetapkan cakupan ke apiproxy
, entri dalam KVM hanya dapat diakses oleh proxy API yang menulis nilai tersebut ke peta.
Perhatikan bahwa saat mengakses peta atau entri peta, Anda harus menentukan 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, menerapkan perubahan, atau menghapus entri.
<Scope>environment</Scope>
Default | environment |
---|---|
Kehadiran | Opsional |
Jenis | String |
Nilai valid |
|
Elemen <Value>
Menentukan nilai kunci. Anda dapat menentukan nilai sebagai string literal atau, dengan 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 saat runtime.
Pada contoh berikut, dua kunci ditambahkan ke KVM:
- Kunci
k1
dengan nilaiv1,v2
- Kunci
k2
dengan nilaiv3,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 nilaibar,test
<Put> <Key> <Parameter ref="organization.name"/> </Key> <Value ref="apiproxy.name"/> <Value ref="environment.name"/> </Put>
Default | T/A |
---|---|
Kehadiran | Diperlukan |
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 tetapkan. | T/A | Wajib jika tidak ada nilai literal yang diberikan di antara tag pembuka dan 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 |
build |
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.
|
build |
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 .
|
build |
ValueIsMissing |
Error ini terjadi jika elemen <Value> tidak ada di bawah elemen <Entry> dari elemen <InitialEntries> kebijakan KeyValueMapOperations . |
build |
Skema
Catatan penggunaan
Untuk ringkasan KVM, lihat Menggunakan peta nilai kunci.
Dengan UI Apigee, Anda dapat menentukan KVM hanya pada cakupan lingkungan, seperti yang dijelaskan dalam Menggunakan KVM dengan UI Apigee. Dengan Apigee API, Anda dapat menentukan KVM di organisasi, lingkungan, atau cakupan proxy API, seperti yang dijelaskan di bagian berikut:
- API peta nilai kunci cakupan organisasi
- Maps API nilai kunci cakupan lingkungan
- API nilai kunci cakupan proxy API
Penyimpanan KVM menyediakan mekanisme persistensi ringan untuk data yang diformat sebagai key-value pair. Anda dapat mengaksesnya pada 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. KVM dapat menyimpan banyak entri.
Misalnya, Anda perlu menyimpan daftar alamat IP yang terkait dengan berbagai lingkungan backend. Anda dapat membuat KVM bernama ipAddresses
yang berisi
daftar key-value pair sebagai entri. Misalnya, JSON ini dapat menampilkan 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 guna menerapkan daftar IP yang diizinkan/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 pada beberapa transaksi permintaan/respons.
KVM dapat dimanipulasi melalui kebijakan KeyValueMapOperations, atau secara langsung melalui Apigee API. Anda dapat menggunakan API ini, misalnya, untuk mengupload set data besar ke key-value store, atau membuat skrip untuk mengelola entri peta nilai kunci. Anda harus membuat KVM 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 ini adalah dua contoh.
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 instance pertama, nilai literal KEY_NAME_LITERAL
disimpan di 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
.
Untuk mengambil kunci dan nilai kunci dengan operasi GET
(atau menghapusnya dengan operasi DELETE
), nilai elemen <Parameter>
harus cocok dengan nama kunci di KVM. Misalnya, jika nama kunci dalam KVM adalah my_key
, Anda dapat
menentukan nilai literal dengan <Parameter>my_key</Parameter>
atau menentukan
variabel yang berisi nilai persis mny_key
, seperti ini:
<Parameter ref="variable.containing.foo"/>
.
Topik terkait
Lihat topik berikut untuk informasi lebih lanjut tentang KVM:
- Menggunakan peta nilai kunci
- API peta nilai kunci cakupan organisasi
- Maps API nilai kunci cakupan lingkungan
- API nilai kunci cakupan proxy API