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. Peta nilai kunci (KVM) ideal untuk hal ini. J KVM adalah kumpulan pasangan String kunci/nilai khusus yang dienkripsi atau tidak dienkripsi. Berikut ini dua contoh:

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 Info Layanan) dalam pengujian dan URL target lain dalam lingkungan produksi. Alih-alih melakukan {i>hard-coding <i}URL di {i>proxy<i}, Anda dapat membuat {i>proxy<i} mendeteksi di lingkungan mana, menjalankan {i>Key<i} yang terkait kebijakan Operasi Peta Nilai, dan mengambil URL target yang benar dari salah satu KVM yang Anda dibuat. Kemudian, jika salah satu atau kedua target berubah, Anda cukup memperbarui KVM URL baru. Proxy mengambil nilai baru, dan tidak diperlukan deployment ulang proxy.
  • Anda ingin menyimpan kredensial, kunci pribadi, atau token—seperti token untuk layanan, kredensial yang diperlukan untuk membuat token OAuth, atau kunci pribadi digunakan di Java Keterangans atau JavaScript untuk enkripsi atau penandatanganan JSON Web Token (JWT). Daripada fokus pada meneruskan kredensial, kunci, atau token dalam permintaan, atau melakukan {i>hard-coding<i} pada logika proxy Anda, Anda dapat menyimpannya di KVM (selalu terenkripsi) dan mengambilnya secara dinamis dalam target yang memerlukannya.

Anda akan menemukan situasi lain ketika penyimpanan pasangan String kunci/nilai berguna. Di beberapa umum, pertimbangkan untuk menggunakan KVM saat:

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

KVM memiliki cakupan

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

Misalnya, jika hanya satu proxy API yang memerlukan data dalam KVM, Anda dapat membuat KVM apiproxy cakupan, 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, di dalam hal ini, Anda akan membuat peta nilai kunci di lingkup lingkungan. {i>Proxy<i} yang di-deploy di "prod" lingkungan tidak dapat mengakses KVM di "test" {i>environment scope<i}. Jika Anda menginginkan KVM yang sama kunci agar tersedia dalam produksi, buat KVM paralel yang dicakupkan ke "prod" lingkungan fleksibel App Engine.

Jika Anda ingin semua {i>proxy<i} di semua lingkungan mengakses KVM yang sama, buat KVM di organization cakupan.

Tentang KVM terenkripsi

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

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 (*****). Sebagai contoh:

Management API

Di API pengelolaan, nilai yang dienkripsi ditampilkan dengan disamarkan. Berikut ini adalah contoh pengelolaan Respons API pada panggilan KVM yang dienkripsi:

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

Rekaman aktivitas dan debug

Saat Anda menggunakan kebijakan Operasi Peta Nilai Kunci untuk mengambil nilai KVM terenkripsi, Anda memberikan nama variabel untuk menyimpan dengan sejumlah nilai. Untuk mendapatkan nilai terenkripsi, Anda perlu menambahkan "private." awalan pada nama variabel, yang mencegah kunci/nilai KVM muncul di sesi Trace dan debug.

Batas

Di organisasi dengan Inti Persistence Services (CPS) yang diaktifkan:

  • 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 dari kunci dan nilai). Jika Anda melebihi batas ini, Apigee Edge untuk Private Cloud akan menampilkan error. Untuk menentukan ukuran KVM Anda, Anda dapat menggunakan perintah nodetool cfstats.

KVM yang lebih besar dapat menyebabkan penurunan performa. Akibatnya, Anda harus membaginya menjadi KVM monolitik menjadi ukuran yang lebih kecil untuk meningkatkan performa.

Mengelola dan menggunakan KVM

Anda dapat membuat, mengelola, dan menggunakan KVM dalam berbagai cara. Bagian ini menjelaskan berbagai pilihan untuk membuat, kemudian mengambil, KVM yang terenkripsi dan tidak terenkripsi.

Membuat dan mengupdate KVM

Anda dapat membuat dan memperbarui KVM dengan cara berikut:

  • Kebijakan Operasi Peta Nilai Kunci (tanpa enkripsi)

    Untuk pembuatan dan pembaruan KVM runtime oleh proxy API Anda, gunakan Kebijakan Operasi Peta Nilai Utama. (Di kebijakan, Anda menentukan nama KVM yang atribut mapIdentifier pada induk element.)

    Elemen <InitialEntries> memungkinkan Anda membuat dan mengisi set dasar entri di KVM baru segera setelah Anda menyimpan kebijakan di UI atau men-deploy Proxy API (jika Anda mengembangkannya secara offline). Jika nilainya berubah dalam kebijakan, berarti atribut nilai akan ditimpa. Setiap kunci/nilai baru akan ditambahkan ke KVM yang ada bersama kunci/nilai yang sudah ada.

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

  • Management API

    API pengelolaan digunakan untuk bekerja dengan KVM sebagai administrator, bukan selama runtime di proxy API Anda. Misalnya, Anda mungkin memiliki skrip internal yang menggunakan skrip API untuk menghapus dan membuat ulang KVM di lingkungan pengujian, atau Anda mungkin ingin mereset nilai kunci di KVM agar semua {i> proxy<i} dapat diambil. (Untuk manipulasi {i>runtime<i} KVM, gunakan Kebijakan Operasi Peta Nilai Utama di proxy Anda).

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

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

  • UI Pengelolaan

    Di UI pengelolaan Edge, Anda dapat membuat dan memperbarui KVM cakupan lingkungan, yang merupakan satu-satunya cakupan KVM akan muncul di UI. UI pengelolaan adalah cara yang baik untuk mengelola data KVM secara manual untuk API menggunakan proxy pada 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 sedikit variasi saat mengambil data dengan kebijakan Operasi Peta Nilai Kunci.

  • Kebijakan: Gunakan elemen <Get> di Kebijakan Operasi Peta Nilai Kunci untuk mengambil KVM terenkripsi dan tidak terenkripsi. Satu perbedaan kecil adalah mengambil nilai terenkripsi dengan kebijakan, yang mengharuskan Anda menambahkan "private." pada nama variabel yang akan berisi nilai yang diambil, seperti yang dijelaskan dalam Bagian mendapatkan operasi topik referensi. Awalan tersebut menyembunyikan nilai dari 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 cadangkan KVM dengan mendapatkan dan menyimpan definisi JSON, menggunakan API pengelolaan. Perlu diketahui, meskipun, nilai yang dienkripsi akan ditampilkan sebagai ***** dalam respons API.
  • UI Pengelolaan: Anda dapat melihat KVM cakupan lingkungan di bagian pengelolaan UI dengan membuka APIs > Konfigurasi Lingkungan > Peta Nilai Kunci (Edge Klasik) atau Admin > Lingkungan > Peta Nilai Kunci (Edge Baru).

Contoh KVM

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