Bekerja dengan peta nilai kunci

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

Terkadang, Anda ingin menyimpan data untuk diambil saat runtime—data yang tidak kedaluwarsa yang tidak boleh di-hardcode dalam logika proxy API Anda. Peta nilai kunci (KVM) sangat ideal untuk hal ini. A KVM adalah kumpulan pasangan String kunci/nilai kustom yang dienkripsi atau tidak dienkripsi. Berikut ini dua contohnya:

Untuk mempelajari jenis persistensi lainnya, lihat Menambahkan penyimpanan dalam cache dan persistensi.

Skenario KVM

Berikut beberapa situasi saat 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 meng-hardcode URL di proxy Anda, Anda dapat membuat proxy mendeteksi lingkungan tempatnya berada, menjalankan kebijakan Operasi Peta Nilai Kunci terkait, dan mengambil URL target yang benar dari salah satu KVM yang Anda buat. Kemudian, jika satu atau kedua target Anda berubah, Anda cukup memperbarui KVM dengan URL baru. Proxy akan mengambil nilai baru, dan tidak ada redeployment proxy yang diperlukan.
  • Anda ingin menyimpan kredensial, kunci pribadi, atau token—seperti token untuk layanan eksternal layanan, kredensial yang diperlukan untuk membuat token OAuth, atau kunci pribadi yang digunakan di Panggilan Java atau JavaScript untuk enkripsi atau penandatanganan Token Web JSON (JWT). Daripada meneruskan kredensial, kunci, atau token dalam permintaan, atau meng-hardcode-nya dalam logika proxy, Anda dapat menyimpannya dalam KVM (selalu dienkripsi) dan mengambilnya secara dinamis dalam panggilan ke target yang memerlukannya.

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

  • Tempat tertentu dalam kode Anda memerlukan nilai yang berbeda saat runtime.
  • Data sensitif perlu diteruskan tanpa di-hardcode.
  • Anda ingin menyimpan nilai yang tidak kedaluwarsa seperti cache.

KVM memiliki cakupan

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

Misalnya, jika hanya satu proxy API yang memerlukan data dalam KVM, Anda dapat membuat KVM dalam 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 dalam cakupan lingkungan. Proxy yang di-deploy di lingkungan "prod" tidak dapat mengakses KVM dalam cakupan lingkungan "test". Jika Anda ingin kunci KVM yang sama tersedia dalam produksi, buat KVM paralel yang dicakup ke lingkungan "prod".

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

Tentang KVM terenkripsi

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

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

UI Edge

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

Management API

Di management API, nilai terenkripsi ditampilkan dengan ditutupi. Berikut adalah contoh respons management API pada panggilan KVM terenkripsi Get:

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

Pelacakan dan proses debug

Saat menggunakan kebijakan Operasi Peta Nilai Kunci untuk mengambil nilai KVM terenkripsi, Anda akan memberikan nama variabel untuk menyimpan nilai. Untuk mendapatkan nilai terenkripsi, Anda harus menambahkan awalan "private." ke nama variabel, yang mencegah kunci/nilai KVM muncul di sesi Pelacakan dan proses debug.

Batas

Di organisasi dengan Core Persistence Services (CPS) 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 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 menyebabkan penurunan performa. Oleh karena itu, Anda harus membagi KVM monolitik yang besar menjadi KVM yang lebih kecil untuk meningkatkan performa.

Mengelola dan menggunakan KVM

Anda dapat membuat, mengelola, dan menggunakan KVM dengan berbagai cara. Bagian ini menjelaskan berbagai opsi untuk membuat, lalu mengambil, KVM terenkripsi dan tidak terenkripsi.

Membuat dan memperbarui 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 Kunci. (Dalam kebijakan, Anda menentukan nama KVM dalam atribut mapIdentifier pada elemen induk.)

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

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

  • Management API

    Management API digunakan untuk menggunakan KVM sebagai administrator, bukan selama runtime di proxy API Anda. Misalnya, Anda mungkin memiliki skrip internal yang menggunakan management API untuk menghapus dan membuat ulang KVM di lingkungan pengujian, atau Anda mungkin ingin mereset nilai kunci di KVM agar dapat diambil oleh semua proxy. (Untuk manipulasi KVM runtime, gunakan kebijakan Operasi Peta Nilai Kunci di proxy Anda).

    Management API Peta Kunci/Nilai memungkinkan Anda membuat, memperbarui, dan menghapus KVM terenkripsi dan kunci/nilai di semua cakupan (organisasi, lingkungan, dan apiproxy).

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

  • UI Pengelolaan

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

Mengambil KVM

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

  • Kebijakan: Gunakan elemen <Get> dalam kebijakan Operasi Peta Nilai Kunci untuk mengambil KVM terenkripsi dan tidak terenkripsi. Satu-satunya perbedaan kecil adalah mengambil nilai terenkripsi dengan kebijakan, tempat Anda harus menambahkan awalan "private." ke nama variabel yang akan berisi nilai yang diambil, seperti yang dijelaskan di bagian Operasi Get pada topik referensi. Awalan tersebut menyembunyikan nilai dari sesi Pelacakan dan proses debug saat Anda melakukan proses 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 management API. 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 (Edge Klasik) atau Admin > Environments > Key Value Maps (Edge Baru).

Contoh KVM

Untuk contoh penggunaan KVM untuk mengisi nilai dalam URL, lihat Membuat template URL target dengan KVM berdasarkan lingkungan.