Membuat dan mengelola kunci API

Halaman ini menjelaskan cara membuat dan mengelola kunci API menggunakan API Keys API.

Untuk mengetahui informasi tentang cara menggunakan kunci API dengan panggilan ke Cloud de Confiance by S3NS API, lihat Menggunakan kunci API.

Sebelum memulai

Halaman ini menggunakan curl dan Google Cloud CLI untuk mengirim permintaan ke API Keys API. Lihat Mulai menggunakan API Kunci API untuk mengetahui detail tentang cara menyiapkan eksperimen dengan API.

Membuat kunci API

Anda dapat membuat kunci API menggunakan metode CreateKey. Metode ini memerlukan parameter Key. Anda hanya dapat menentukan kolom displayName dan restrictions dari objek Key. CreateKey bukan metode sinkron. Sebagai gantinya, saat Anda melakukan panggilan ke CreateKey, Anda akan memulai operasi yang berjalan lama. Contoh berikut mengeluarkan panggilan CreateKey untuk membuat kunci API tanpa batasan:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys -X POST -d '{"displayName" : "Example API key"}'

Jika berhasil, metode ini akan menampilkan operasi yang berjalan lama dalam respons. Seperti yang dijelaskan dalam Polling operasi yang berjalan lama, Anda berulang kali melakukan panggilan operations.get dengan nilai dari kolom name. Jika respons dari operations.get berisi "done": true, objek response berisi Key, mirip dengan berikut:

{
  "name": "operations/akmf.p7-103621867718-06f94db2-7e91-4c58-b826-e6b80e4dc3eb",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key",
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

Di objek response:

  • Kolom name berisi ID unik untuk kunci API. Anda menggunakan nilai di kolom name dalam metode lain yang memerlukan nama kunci. Nilai ini tidak ditampilkan di konsol Cloud de Confiance , tetapi Anda dapat memanggil metode ListKeys untuk mendapatkan names untuk semua kunci API Anda. Kolom Key.name selalu dalam format berikut: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • Kolom displayName dipetakan ke kolom Name di konsol Cloud de Confiance , jadi sebaiknya Anda memberikan displayName saat memanggil CreateKey.
  • Kolom keyString berisi string yang Anda kirim ke API yang memerlukan kunci API. keyString dipetakan ke kolom API key di konsolCloud de Confiance . Anda dapat memanggil metode GetKeyString untuk mendapatkan keyString untuk kunci API.
  • Kolom etag berisi checksum yang dihitung oleh server berdasarkan nilai kunci saat ini. Teruskan nilai etag saat Anda memanggil metode UpdateKey dan DeleteKey.

ID kunci yang ditentukan pengguna

Anda dapat menentukan keyId sebagai parameter kueri untuk metode CreateKey. Jika ditentukan, nilai akan menjadi komponen terakhir dari Key.name.

Misalnya, pertimbangkan panggilan berikut ke CreateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1 -X POST -d '{"displayName" : "Example API key"}'

Untuk contoh ini, kolom Key.name memiliki nilai berikut: 

    "name": "projects/PROJECT_NUMBER/locations/global/keys/my-test-key1"

Memperbarui nama tampilan

Untuk mengubah displayName kunci API atau menambahkan displayName ke kunci API yang dibuat tanpa displayName, panggil metode UpdateKey. Saat Anda memanggil UpdateKey, Anda memulai operasi yang berjalan lama yang memperbarui kunci.

Contoh berikut mengilustrasikan cara memanggil UpdateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName -X PATCH -d '{"displayName": "New display name", "etag" : "ETAG"}'

Jika respons dari operations.get berisi "done": true, response berisi objek Key dengan displayName yang diperbarui.

Menghapus kunci API

Untuk menghapus kunci API, gunakan metode DeleteKey. Saat Anda memanggil DeleteKey, Anda akan memulai operasi yang berjalan lama yang menandai kunci sebagai DELETED.

Contoh berikut mengilustrasikan cara memanggil DeleteKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?etag="ETAG" -X DELETE

Jika respons dari operations.get berisi "done": true, response akan mirip dengan berikut ini:

{
  "name": "operations/akmf.cdabc4df-cbff-4420-8c7e-65dc832c945d",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key"
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "deleteTime": "2021-03-24T22:35:37.290544Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

Kunci API yang ditandai sebagai DELETED tidak dapat digunakan, tetapi juga tidak sepenuhnya dihapus dari sistem kami. Untuk mencantumkan kunci API yang masih ada tetapi ditandai sebagai DELETED, tetapkan show_deleted ke benar (true) untuk metode ListKeys:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true

Setelah 30 hari, kunci API akan dihapus secara permanen.

Memulihkan kunci API

Untuk memulihkan kunci API sebelum dihapus secara permanen, panggil metode UndeleteKey. Saat Anda memanggil UndeleteKey, Anda akan memulai operasi yang berjalan lama yang menandai kunci sebagai ACTIVE.

Contoh berikut mengilustrasikan cara memanggil UndeleteKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete -X POST

Langkah berikutnya