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 akan habis masa berlakunya dan tidak boleh dikodekan secara permanen dalam logika proxy API. 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.

    Nanti, jika salah satu atau kedua target Anda berubah, Anda cukup memperbarui KVM dengan URL baru. Proxy API akan mengambil nilai baru; tidak perlu men-deploy 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 tidak ingin proxy API yang di-deploy di lingkungan prod 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.

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 Lingkungan

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

    KVM baru akan ditampilkan dalam daftar.

UI Apigee Klasik

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

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

    Halaman Key Value Maps menampilkan daftar KVM yang ada. Jika Anda belum membuat KVM, daftar 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. Nama ini tidak boleh berisi spasi atau karakter khusus lainnya. Contoh: my-kvm-1

  6. Klik Tambahkan.

    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.

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 Konsol Cloud

Untuk menghapus KVM:

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

    Buka Lingkungan

  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 daftar 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: