Bekerja dengan peta nilai kunci

Anda sedang 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 dikodekan secara permanen dalam logika proxy API Anda. Peta nilai kunci (KVM) sangat ideal untuk hal ini. KVM adalah kumpulan pasangan String nilai/kunci kustom yang dienkripsi atau tidak dienkripsi. Berikut ini dua contoh:

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

Skenario KVM

Berikut beberapa situasi yang membuat KVM berguna:

  • Anda memiliki proxy API yang perlu memanggil satu URL target (atau Panggilan Layanan) di lingkungan pengujian dan URL target lain di lingkungan produksi. Daripada meng-hardcode URL di proxy, 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 penyiapan ulang proxy yang diperlukan.
  • 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 dalam Java Callout atau JavaScript untuk enkripsi atau penandatanganan Token Web JSON (JWT). Daripada meneruskan kredensial, kunci, atau token dalam permintaan, atau melakukan hardcode di logika proxy, Anda dapat menyimpannya di KVM (selalu dienkripsi) dan mengambilnya secara dinamis dalam panggilan ke target yang memerlukannya.

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

  • Tempat tertentu dalam kode Anda memerlukan nilai yang berbeda saat runtime.
  • Data sensitif harus diteruskan tanpa melakukan hard-coding.
  • Anda ingin menyimpan nilai yang tidak akan habis masa berlakunya seperti cache.

KVM memiliki cakupan

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

Misalnya, jika hanya satu proxy API yang memerlukan data dalam KVM, Anda dapat membuat KVM di 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, yang dalam hal ini Anda akan membuat peta nilai kunci di 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 di produksi, buat KVM paralel yang dicakup ke lingkungan "prod".

Jika Anda ingin semua proxy di semua lingkungan mengakses KVM yang sama, buat KVM di 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 disamarkan dengan tanda bintang di UI (*****). Misalnya:

Management API

Di Management API, nilai terenkripsi ditampilkan dengan disamarkan. Berikut adalah contoh respons API pengelolaan pada panggilan Get encrypted KVM:

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

Melacak dan men-debug

Saat menggunakan kebijakan Operasi Peta Nilai Kunci untuk mengambil nilai KVM terenkripsi, Anda 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 Layanan Persistensi Inti (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 menyebabkan penurunan performa. Oleh karena itu, Anda harus membagi KVM monolitik yang besar menjadi beberapa 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 update KVM saat runtime oleh proxy API Anda, gunakan kebijakan Operasi Key Value Map. (Dalam kebijakan, Anda menentukan nama KVM di atribut mapIdentifier pada elemen induk.)

    Elemen <InitialEntries> memungkinkan Anda membuat dan mengisi set entri dasar di KVM baru segera setelah Anda menyimpan kebijakan di UI atau men-deploy proxy API (jika Anda mengembangkannya secara offline). Jika nilai berubah dalam kebijakan, nilai yang ada akan ditimpa. Setiap kunci/nilai baru 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 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 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 saat runtime, gunakan kebijakan Operasi Peta Nilai Kunci di proxy Anda).

    API pengelolaan Peta Nilai Kunci memungkinkan Anda membuat, memperbarui, dan menghapus KVM terenkripsi serta 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 Anda membuatnya. 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 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 sedikit perbedaan 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, di mana Anda harus menambahkan awalan "private." ke nama variabel yang akan berisi nilai yang diambil, seperti yang dijelaskan di bagian Get operation dalam topik referensi. Awalan tersebut menyembunyikan nilai dari sesi debug dan rekaman aktivitas 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 Management API. Namun, perlu diketahui bahwa nilai terenkripsi ditampilkan sebagai ***** dalam respons API.
  • UI Pengelolaan: Anda dapat melihat KVM yang tercakup dalam 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 guna mengisi nilai dalam URL, lihat Templatize target URL with KVM by environment.