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

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

Berikut adalah 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, isi keranjang belanja.
  • Konfigurasi (seperti aturan pemilihan rute dan tabel penelusuran): 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 meng-hardcode URL di proxy API, Anda dapat membuatnya mendeteksi lingkungan tempatnya berada, menjalankan kebijakan KeyValueMapOperations terkait, dan mengambil URL target yang benar dari KVM yang sesuai.

    Selanjutnya, jika satu atau kedua target Anda berubah, Anda cukup memperbarui KVM dengan URL baru. Proxy API akan mengambil nilai baru; tidak diperlukan deployment ulang.

  • 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 kebijakan JavaCallout 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 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:

  • Bagian 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.

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

Tentang cakupan KVM

Cakupan menentukan tempat KVM tersedia. KVM dapat dibuat pada cakupan berikut:

Cakupan Deskripsi
Proxy API Hanya proxy API yang dapat mengakses KVM.
Lingkungan Semua proxy API di 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 di produksi, buat KVM paralel yang dicakup ke lingkungan prod.
Organisasi Semua proxy API di semua lingkungan dapat mengakses KVM.

Tentang enkripsi KVM

Di Apigee, semua entri KVM untuk cakupan proxy API, organisasi, dan lingkungan 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.

Tentang penyamaran KVM

Secara default, nilai KVM ditampilkan sebagai teks biasa. Anda dapat mengaktifkan penyamaran KVM untuk menyamarkan nilai dengan tanda bintang (*****). Untuk mengaktifkan atau menonaktifkan penyamaran KVM, gunakan setelan Samarkan nilai di UI atau tanda maskedValues dalam permintaan API Anda.

Nilai disamarkan di tingkat KVM. Anda tidak dapat menyamarkan entri KVM individual; semua nilai dalam KVM disamarkan, atau tidak ada yang disamarkan.

Catatan: Penyamaran KVM tidak akan otomatis diaktifkan untuk KVM yang ada. Anda harus memperbarui KVM yang ada secara eksplisit untuk menggunakan masking KVM.

Membuat KVM

Buat KVM seperti yang dijelaskan di bagian berikut.

Apigee di Konsol Cloud

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

  1. Di konsol Google Cloud , buka halaman Management > Environments.

    Buka Environments

  2. Pilih lingkungan yang ingin Anda edit dari daftar lingkungan yang tersedia.
  3. Klik tab Key value maps di halaman Environment details.

    Halaman Peta nilai kunci menampilkan daftar KVM yang ada. Jika Anda belum membuat KVM, daftar akan kosong.

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

    Dialog Create key value map akan terbuka.

  5. 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. Nama ini tidak boleh berisi spasi atau karakter khusus lainnya. Contoh: my-kvm-1

  6. Klik Masking nilai untuk menyamarkan semua nilai. Jika tidak dipilih, nilai KVM akan ditampilkan dalam teks biasa. Lihat Tentang penyamaran KVM untuk mengetahui informasi selengkapnya.
  7. Klik Buat.

    KVM baru akan ditampilkan dalam daftar.

Apigee API

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

Kebijakan KVM

Untuk membuat KVM saat runtime dan memperbaruinya di proxy API, gunakan kebijakan KeyValueMapOperations. 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. Pasangan nilai kunci baru ditambahkan ke KVM yang ada bersama dengan pasangan nilai kunci yang ada.

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

Debug

Saat Anda menggunakan kebijakan KeyValueMapOperations untuk mengambil nilai KVM terenkripsi, Anda memberikan nama variabel untuk menyimpan nilai. Karena semua nilai KVM dienkripsi, Anda perlu menambahkan awalan private. ke nama variabel, yang mencegah pasangan nilai/kunci KVM muncul di sesi Debug.

Mendapatkan KVM

Gunakan Apigee API untuk mendapatkan KVM untuk cakupan berikut:

Misalnya, untuk mendapatkan KVM yang tercakup dalam proxy API, masukkan permintaan GET ke URL berikut:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Memperbarui KVM

Gunakan Apigee API untuk memperbarui KVM untuk cakupan berikut:

Misalnya, untuk mendapatkan KVM yang tercakup dalam proxy API, masukkan permintaan GET ke URL berikut:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

Mengelola nilai KVM

Anda dapat mengelola nilai KVM menggunakan API atau kebijakan KeyValueMapOperations, seperti yang dijelaskan di bagian berikut.

Mengelola nilai KVM menggunakan API

Gunakan Apigee API untuk mengelola nilai KVM untuk cakupan berikut:

Mengelola nilai KVM menggunakan kebijakan KeyValueMapOperations

Gunakan kebijakan KeyValueMapOperations untuk menambahkan, mendapatkan, atau menghapus nilai dari KVM.

Tambahkan kunci dan nilai KVM menggunakan elemen <Put> dari kebijakan KeyValueMapOperations. Elemen <Put> membuat KVM baru jika belum ada, dan membuat kunci dengan satu atau beberapa nilai. Jika KVM sudah ada, pasangan nilai/kunci akan ditambahkan (atau diperbarui jika kunci sudah ada). Anda dapat menggunakan beberapa elemen <Put> dalam kebijakan KVM. Untuk mengetahui informasi selengkapnya, lihat elemen <Put>.

Dapatkan nilai 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>.

Hapus nilai KVM menggunakan elemen <Delete> dari kebijakan KeyValueMapOperations. Untuk mengetahui informasi selengkapnya, lihat elemen <Delete>.

Menghapus KVM

Hapus KVM seperti yang dijelaskan di bagian berikut.

Apigee di Konsol Cloud

Untuk menghapus KVM:

  1. Di konsol Google Cloud , buka halaman Management > Environments.

    Buka Environments

  2. Pilih nama lingkungan yang ingin Anda edit dari daftar lingkungan yang tersedia.
  3. Klik tab Key value maps di halaman Environment details.

    Halaman Peta nilai kunci menampilkan daftar KVM yang ada.

  4. Cari baris KVM yang ingin Anda hapus.
  5. Klik di kolom Tindakan.
  6. Klik Hapus Peta Nilai Kunci di dialog untuk mengonfirmasi operasi.

    KVM dihapus dan dikeluarkan dari daftar.

UI Apigee Klasik

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. Posisikan kursor Anda di atas KVM yang ingin Anda hapus.
  5. Klik Delete.
  6. Klik Hapus untuk mengonfirmasi operasi.

    KVM dihapus dan dikeluarkan dari daftar.

Apigee API

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