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 habis masa berlakunya yang tidak boleh di-hardcode dalam logika proxy API Anda. Peta nilai kunci (KVM) sangat ideal untuk hal ini. KVM adalah kumpulan kustom pasangan String nilai kunci terenkripsi.

Berikut adalah tiga kasus penggunaan umum untuk menyimpan data di KVM:

  • Data sesi pengguna: Data yang dibuat dan dihapus hanya oleh runtime; Anda tidak dapat melihat atau mengelola entri KVM di luar runtime. Misalnya, konten keranjang belanja.
  • Konfigurasi (seperti aturan pemilihan rute dan tabel pencarian): 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 Info Layanan) di lingkungan pengujian dan URL target lain di lingkungan produksi. Daripada melakukan hard code URL di proxy API, Anda dapat memintanya untuk mendeteksi lingkungan tempatnya berada, menjalankan kebijakan KeyValueMapOperations terkait, dan mengambil URL target yang benar dari KVM yang sesuai.

    Kemudian, jika salah 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 di Java Callouts atau JavaScript untuk enkripsi atau penandatanganan Token Web JSON (JWT). Daripada meneruskan kredensial, kunci, atau token dalam permintaan, atau melakukan hard code dalam logika proxy, Anda dapat menyimpannya di KVM 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:

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

Dalam beberapa kasus, kumpulan 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 dalam produksi, buat KVM paralel yang dicakup untuk lingkungan prod.
Organisasi Semua proxy API di semua lingkungan dapat mengakses KVM.

Tentang enkripsi KVM

Di Apigee, semua entri KVM untuk proxy API, cakupan organisasi, dan lingkungan dilindungi menggunakan kunci Cloud KMS yang disediakan 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, organisasi, dan lingkungan API. 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. Buka UI Apigee di Cloud Console di browser.
  2. Di panel navigasi sebelah kiri, klik Pengelolaan > Lingkungan.
  3. Pilih lingkungan yang ingin diedit dari daftar lingkungan yang tersedia.
  4. 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.

  5. Untuk membuat KVM baru (kosong), klik + Buat Peta Nilai Kunci.

    Dialog Tambahkan peta nilai kunci 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. Nama tidak boleh berisi spasi atau karakter khusus lainnya. Contoh: my-kvm-1

  7. Klik Create.

    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 menu drop-down lingkungan, pilih lingkungan tempat Anda ingin membuat KVM.

    Halaman Peta Nilai Kunci menampilkan daftar KVM yang ada. Jika Anda belum membuat KVM, daftar akan kosong.

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

    Dialog Tambahkan peta nilai kunci akan terbuka.

  5. Masukkan nama untuk KVM di kolom Name.

    Nama hanya boleh berisi huruf, angka, dan tanda hubung. Nama 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 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 berubah dalam kebijakan, nilai yang ada akan ditimpa. Setiap pasangan nilai kunci baru akan 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, key-value pair akan ditambahkan (atau diperbarui jika kunci sudah ada). Anda dapat menggunakan beberapa elemen <Put> dalam kebijakan KVM.

Debug

Saat 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 dalam 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. Buka UI Apigee di Cloud Console di browser.
  2. Di panel navigasi sebelah kiri, klik Pengelolaan > Lingkungan.
  3. Pilih nama lingkungan yang ingin diedit dari daftar lingkungan yang tersedia.
  4. Klik tab Key Value Maps di halaman Environment details.

    Halaman Peta Nilai Kunci menampilkan daftar KVM yang ada.

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

    KVM akan dihapus dan dihapus 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 tempat Anda ingin menghapus KVM.

    Halaman Peta Nilai Kunci menampilkan daftar KVM yang ada.

  4. Posisikan kursor di atas KVM yang ingin dihapus.
  5. Klik Delete.
  6. Klik Hapus untuk mengonfirmasi operasinya.

    KVM akan dihapus dan dihapus dari daftar.

Apigee API

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