Bekerja dengan peta nilai kunci

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

Ada kalanya Anda ingin menyimpan data untuk diambil saat runtime—data yang tidak akan habis masa berlakunya yang tidak boleh di-hard code dalam logika proxy API Anda. Peta nilai kunci (KVM) sangat ideal untuk hal ini. KVM adalah kumpulan kustom pasangan String kunci/nilai yang dienkripsi atau tidak dienkripsi. Berikut ini dua contohnya:

Untuk mempelajari jenis persistensi lainnya, lihat Menambahkan caching dan persistensi.

Skenario KVM

Berikut adalah beberapa situasi di mana KVM berguna:

  • Anda memiliki proxy API yang perlu memanggil satu URL target (atau Panggilan Layanan) di lingkungan pengujian dan URL target lainnya di lingkungan produksi. Daripada melakukan hard-coding URL di proxy, Anda dapat membuat proxy mendeteksi lingkungan tempat proxy tersebut berada, menjalankan kebijakan Key Value Map Operations yang terkait, dan mengambil URL target yang benar dari salah satu KVM yang Anda buat. Kemudian, jika salah satu atau kedua target berubah, Anda cukup mengupdate KVM dengan URL baru. Proxy akan mengambil nilai baru, dan tidak diperlukan deployment ulang proxy.
  • Anda ingin menyimpan kredensial, kunci pribadi, atau token—seperti token untuk layanan eksternal, kredensial yang diperlukan untuk membuat token OAuth, atau kunci pribadi yang digunakan di Pemanggilan Java atau JavaScript untuk enkripsi atau penandatanganan JSON Web Token (JWT). Daripada meneruskan kredensial, kunci, atau token dalam permintaan, atau meng-hardcode-nya dalam logika proxy, Anda dapat menyimpannya di KVM (selalu dienkripsi) dan mengambilnya secara dinamis dalam panggilan ke target yang memerlukannya.

Anda juga akan melihat situasi lain di mana penyimpanan pasangan String kunci/nilai berguna. Secara umum, pertimbangkan untuk menggunakan KVM saat:

  • Tempat tertentu dalam kode memerlukan nilai yang berbeda pada runtime.
  • Data sensitif harus diteruskan tanpa melakukan hard code.
  • Anda ingin menyimpan nilai yang tidak kedaluwarsa seperti cache.

KVM memiliki ruang lingkup

Cakupan berarti "tempat KVM tersedia." KVM dapat dibuat pada cakupan berikut: organization, environment, dan apiproxy.

Misalnya, jika hanya satu proxy API yang memerlukan data di KVM, Anda dapat membuat KVM pada cakupan apiproxy, tempat hanya proxy API tersebut yang dapat mengakses data.

Atau, Anda mungkin ingin semua proxy API di lingkungan pengujian memiliki akses ke peta nilai kunci, dalam hal ini Anda akan membuat peta nilai kunci pada cakupan lingkungan. Proxy yang di-deploy di lingkungan "prod" tidak dapat mengakses KVM dalam cakupan lingkungan "pengujian". Jika Anda ingin kunci KVM yang sama tersedia dalam produksi, buat KVM paralel yang dicakupkan ke lingkungan "prod".

Jika Anda ingin semua proxy di semua lingkungan mengakses KVM yang sama, buat KVM pada cakupan organization.

Tentang KVM terenkripsi

KVM terenkripsi dienkripsi dengan kunci cipher AES-128 yang dihasilkan Apigee. Kunci yang digunakan untuk mengenkripsi KVM disimpan dalam cakupan KVM. Misalnya, dalam suatu organisasi, semua KVM terenkripsi yang Anda buat di cakupan lingkungan dibuat menggunakan kunci cakupan lingkungan yang sama.

Edge menangani tampilan nilai terenkripsi dengan cara berikut. (Lihat Mengelola dan menggunakan KVM untuk informasi tentang cara membuat KVM terenkripsi.)

UI Edge

Peta nilai kunci terenkripsi menampilkan nilai yang disamarkan dengan tanda bintang di UI (*****). Misalnya:

Management API

Di Management API, nilai terenkripsi ditampilkan. Berikut adalah contoh respons API pengelolaan pada panggilan Dapatkan enkripsi KVM:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Melacak dan men-debug

Saat menggunakan kebijakan Key Value Map Operations untuk mengambil nilai KVM terenkripsi, Anda harus memberikan nama variabel untuk menyimpan nilai. Untuk mendapatkan nilai terenkripsi, Anda perlu menambahkan awalan "private." ke nama variabel, yang mencegah kunci/nilai KVM muncul di sesi Trace dan debug.

Batas

Di organisasi yang mengaktifkan Core Persistence Services (CPS):

  • Nama/ID KVM peka huruf besar/kecil.
  • Ukuran kunci dibatasi hingga 2 KB.
  • Ukuran nilai dibatasi hingga 10 KB.

Untuk Apigee Edge untuk Private Cloud, setiap KVM tidak boleh melebihi 15 MB (ini adalah ukuran gabungan kunci dan nilai). Jika Anda melebihi batas ini, Apigee Edge untuk Private Cloud akan menampilkan error. Untuk menentukan ukuran KVM, Anda dapat menggunakan perintah nodetool cfstats.

KVM yang lebih besar dapat mengakibatkan penurunan performa. Oleh karena itu, Anda harus membagi KVM monolitik berukuran besar menjadi yang lebih kecil untuk meningkatkan performa.

Mengelola dan menggunakan KVM

Anda dapat membuat, mengelola, dan menggunakan KVM dalam berbagai cara. Bagian ini menjelaskan berbagai opsi untuk membuat, lalu mengambil KVM yang dienkripsi dan tidak dienkripsi.

Membuat dan mengupdate KVM

Anda dapat membuat dan mengupdate KVM dengan cara berikut:

  • Kebijakan Operasi Peta Nilai Kunci (tanpa enkripsi)

    Untuk pembuatan dan pembaruan KVM runtime melalui proxy API Anda, gunakan kebijakan Operasi Peta Nilai Kunci. (Dalam kebijakan ini, Anda menentukan nama KVM di atribut mapIdentifier pada elemen induk.)

    Elemen <InitialEntries> memungkinkan Anda membuat dan mengisi kumpulan entri dasar pengukuran di KVM baru segera setelah Anda menyimpan kebijakan di UI atau men-deploy proxy API (jika Anda mengembangkannya secara offline). Jika nilai tersebut berubah dalam kebijakan, nilai yang sudah ada akan ditimpa. Semua kunci/nilai baru ditambahkan ke KVM yang ada bersama dengan kunci/nilai yang sudah ada.

    Elemen <Put> akan membuat KVM baru jika belum ada, dan membuat kunci dengan satu atau beberapa nilai. Jika KVM sudah ada, kunci/nilai tersebut akan ditambahkan (atau diupdate jika kunci tersebut sudah ada). Anda dapat menggunakan beberapa elemen <Put> dalam kebijakan KVM.

  • Management API

    Management API digunakan untuk bekerja dengan KVM sebagai administrator, bukan selama runtime di proxy API Anda. Misalnya, Anda mungkin memiliki skrip internal yang menggunakan API pengelolaan untuk menghapus dan membuat ulang KVM di lingkungan pengujian, atau Anda mungkin ingin mereset nilai kunci di KVM agar dapat diambil semua proxy. (Untuk manipulasi runtime KVM, gunakan kebijakan Key Value Map Operations di proxy Anda).

    Key/Value Maps Management API memungkinkan Anda membuat, memperbarui, dan menghapus KVM dan kunci/nilai terenkripsi di semua cakupan (organisasi, lingkungan, dan apiproxy).

    Untuk membuat KVM terenkripsi dengan API pengelolaan, tambahkan "encrypted" : "true" ke payload JSON. Anda hanya dapat mengenkripsi KVM saat membuatnya. Anda tidak dapat mengenkripsi KVM yang ada.

  • UI Pengelolaan

    Di UI pengelolaan Edge, Anda dapat membuat dan mengupdate KVM cakupan lingkungan, yang merupakan satu-satunya cakupan KVM yang muncul di UI. UI pengelolaan adalah cara yang baik dalam mengelola data KVM secara manual untuk proxy API saat runtime. Lihat Membuat dan mengedit peta nilai kunci lingkungan untuk informasi selengkapnya.

Mengambil KVM

Anda mengambil peta nilai kunci yang dienkripsi dan tidak dienkripsi dengan cara yang sama, dengan satu variasi kecil saat mengambilnya dengan kebijakan Operasi Peta Nilai Kunci.

  • Kebijakan: Gunakan elemen <Get> di kebijakan Key Value Map Operations untuk mengambil KVM yang dienkripsi dan tidak dienkripsi. Satu perbedaan kecil adalah mengambil nilai terenkripsi dengan kebijakan, di mana Anda harus menambahkan awalan "private." ke nama variabel yang akan berisi nilai yang diambil, seperti yang dijelaskan di bagian Operasi mendapatkan topik referensi. Awalan tersebut menyembunyikan nilai dari sesi Trace dan debug saat Anda men-debug proxy API.
  • Management API: Untuk tujuan pengelolaan administratif, Anda dapat menggunakan Membuat dan mengedit peta nilai kunci lingkungan untuk mendapatkan KVM dan kunci/nilai. Misalnya, jika Anda ingin mencadangkan KVM dengan mendapatkan dan menyimpan definisi JSON, gunakan API pengelolaan. Namun, perlu diketahui bahwa nilai terenkripsi ditampilkan sebagai ***** dalam respons API.
  • UI Pengelolaan: Anda dapat melihat KVM cakupan lingkungan di UI pengelolaan dengan membuka APIs > Environment Configuration > Key Value Maps (classic Edge) atau Admin > Environments > Key Value Maps (New Edge).

Contoh KVM

Untuk contoh penggunaan KVM dalam mengisi nilai di URL, lihat https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.