Menggunakan peta nilai kunci

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Bagian ini membahas cara menggunakan peta nilai kunci (KVM).

Ringkasan

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 terenkripsi.

Berikut ini daftar tiga kasus penggunaan umum untuk menyimpan data di KVM:

  • Data sesi pengguna: Data yang dibuat dan dihapus oleh runtime saja; Anda tidak dapat melihat atau mengelola entri KVM di luar runtime. Misalnya, konten keranjang belanja.
  • Konfigurasi (seperti aturan perutean dan pencarian tabel): Data yang biasanya dibuat di luar runtime, tetapi dibaca oleh runtime. Data ini dikonfigurasi menggunakan UI atau API, lalu disediakan untuk gateway (sebagai variabel atau konten hanya-baca).

    Misalnya: 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 API, Anda dapat membuatnya mendeteksi lingkungan tempat proxy tersebut berada, menjalankan kebijakan KeyValueMapOperations terkait, dan mengambil URL target yang benar dari KVM yang sesuai.

    Kemudian, jika salah satu atau kedua target berubah, Anda cukup mengupdate KVM dengan URL baru. Proxy API mengambil nilai baru; deployment ulang tidak diperlukan.

  • Kredensial: Menyimpan kredensial, kunci pribadi, atau token—seperti token untuk layanan eksternal, kredensial yang diperlukan untuk membuat token OAuth, atau kunci pribadi yang digunakan dalam 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 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:

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

Dalam beberapa kasus, set properti adalah alternatif yang baik untuk KVM karena lebih mudah digunakan. Untuk mengetahui informasi selengkapnya, lihat Menggunakan kumpulan properti.

Tentang cakupan KVM

Cakupan menentukan di mana KVM tersedia. KVM dapat dibuat pada cakupan berikut:

Cakupan Deskripsi
Proxy API Hanya proxy API yang dapat mengakses KVM.
Lingkungan Semua proxy API dalam lingkungan tertentu dapat mengakses KVM. Misalnya, Anda mungkin ingin proxy API yang di-deploy di lingkungan prod tidak memiliki akses ke KVM di lingkungan test. Jika Anda ingin kunci KVM yang sama tersedia dalam produksi, buat KVM paralel yang dicakupkan ke lingkungan prod.
Organisasi Semua proxy API di semua lingkungan dapat mengakses KVM.

Tentang enkripsi KVM

Di Apigee, semua entri KVM untuk cakupan proxy, organisasi, dan lingkungan API dilindungi menggunakan kunci Cloud KMS yang diberikan saat organisasi Apigee disediakan (lihat kolom runtimeDatabaseEncryptionKey di resource Organization). Apigee menggunakan AES256 sebagai standar enkripsi.

Di Apigee Hybrid, Anda dapat memberikan kunci enkripsi terpisah untuk semua entri KVM untuk cakupan proxy API, organisasi, dan lingkungan. Apigee menerima ukuran cipher AES128, AES196, atau AES256 sebagai standar enkripsi.

Membuat KVM

Buat KVM seperti yang dijelaskan di bagian berikut.

Apigee di Cloud Console

Untuk membuat KVM baru (kosong) atau melihat daftar KVM:

  1. Buka UI Apigee di Cloud Console pada browser.
  2. Di panel navigasi sebelah kiri, klik Management > Environments.
  3. Pilih lingkungan yang ingin Anda edit dari daftar lingkungan yang tersedia.
  4. Klik tab Key Value Maps di halaman Environment details.

    Halaman Key Value Maps menampilkan daftar KVM yang ada. Jika Anda belum membuat KVM apa pun, daftar ini akan kosong.

  5. Untuk membuat KVM baru (kosong), klik + Create Key Value Map.

    Dialog Add key value map akan terbuka.

  6. Masukkan nama untuk KVM di kolom Key value map name.

    Nama hanya boleh berisi huruf, angka, dan tanda hubung, serta tidak boleh lebih dari 255 karakter. Teks tidak boleh berisi spasi atau karakter khusus lainnya. Contoh: my-kvm-1

  7. Klik Create.

    KVM baru akan ditampilkan dalam daftar.

UI Apigee

Untuk membuat KVM baru (kosong) atau melihat daftar KVM:

  1. Login ke UI Apigee.
  2. Pilih Admin > Environments > Key Value Maps.
  3. Dari menu drop-down lingkungan, pilih lingkungan tempat Anda ingin membuat KVM.

    Halaman Key Value Maps menampilkan daftar KVM yang ada. Jika Anda belum membuat KVM apa pun, daftar ini akan kosong.

  4. Untuk membuat KVM baru (kosong), klik +Key value map.

    Dialog Add key value map akan terbuka.

  5. Masukkan nama untuk KVM di kolom Name.

    Nama hanya boleh berisi huruf, angka, dan tanda hubung. Teks tidak boleh berisi spasi atau karakter khusus lainnya. Contoh: my-kvm-1

  6. Klik Tambahkan.

    KVM baru akan ditampilkan dalam daftar.

API Apigee

Gunakan Apigee API untuk membuat, mencantumkan, dan menghapus KVM untuk cakupan berikut:

Kebijakan KVM

Untuk membuat KVM saat runtime dan memperbaruinya di proxy API Anda, gunakan kebijakan KeyValueMapOperations. Dalam kebijakan ini, tentukan nama KVM dalam 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 key-value pair baru ditambahkan ke KVM yang ada bersama dengan key-value pair yang ada.

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

Debug

Saat menggunakan kebijakan KeyValueMapOperations untuk mengambil nilai KVM terenkripsi, Anda harus memberikan nama variabel untuk menyimpan nilai. Karena semua nilai KVM dienkripsi, Anda perlu menambahkan awalan private. ke nama variabel, yang mencegah key-value pair KVM muncul di sesi Debug.

Mengambil KVM

Ambil KVM menggunakan elemen <Get> dari kebijakan KeyValueMapOperations. Karena semua nilai KVM dienkripsi, tambahkan awalan private. ke nama variabel yang akan berisi nilai yang diambil. Awalan tersebut menyembunyikan nilai dari sesi debug saat Anda men-debug proxy API. Untuk mengetahui informasi selengkapnya, lihat elemen<Get>.

Menghapus KVM

Hapus KVM seperti yang dijelaskan di bagian berikut.

Apigee di Cloud Console

Untuk menghapus KVM:

  1. Buka UI Apigee di Cloud Console pada browser.
  2. Di panel navigasi sebelah kiri, klik Management > Environments.
  3. Pilih nama lingkungan yang ingin Anda edit dari daftar lingkungan yang tersedia.
  4. Klik tab Key Value Maps di halaman Environment details.

    Halaman Key Value Maps menampilkan daftar KVM yang ada.

  5. Cari baris KVM yang ingin dihapus.
  6. Klik di kolom Tindakan.
  7. Klik Delete Key Value Map dalam dialog untuk mengonfirmasi operasi.

    KVM akan dihapus dan dihapus dari daftar.

UI Apigee

Untuk menghapus KVM:

  1. Login ke UI Apigee.
  2. Pilih Admin > Environments > Key Value Maps.
  3. Dari menu drop-down lingkungan, pilih lingkungan yang KVM-nya ingin Anda hapus.

    Halaman Key Value Maps menampilkan daftar KVM yang ada.

  4. Arahkan kursor ke KVM yang ingin dihapus.
  5. Klik Delete.
  6. Klik Hapus untuk mengonfirmasi operasi.

    KVM akan dihapus dan dihapus dari daftar.

API Apigee

Gunakan salah satu Apigee API berikut untuk menghapus KVM berdasarkan cakupannya: