Membuat dan mengelola kunci API

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

Untuk mengetahui informasi tentang cara menggunakan kunci API dengan panggilan ke Google Cloud API, lihat Menggunakan kunci API.

Sebelum memulai

Halaman ini menggunakan curl dan Google Cloud CLI untuk mengirim permintaan ke API Kunci API. Lihat Memulai 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 a Key parameter. Anda hanya dapat menentukan kolom displayName dan restrictions dari objek Key. CreateKey bukan metode sinkron. Sebagai gantinya, saat Anda membuat panggilan ke CreateKey, Anda akan memulai operasi yang berjalan lama operation. Contoh berikut membuat 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 membuat operations.get panggilan dengan nilai dari kolom name. Jika respons dari operations.get berisi "done": true, objek response akan 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=="
  }
}

Dalam 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 Google Cloud konsol, 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 Google Cloud konsol, jadi sebaiknya berikan displayName saat Anda memanggil CreateKey.
  • Kolom keyString berisi string yang Anda kirim ke API yang memerlukan kunci API. The keyString dipetakan ke kolom API key di Google Cloud konsol. Anda dapat memanggil GetKeyString metode 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 CreateKey metode. Jika ditentukan, nilai tersebut akan menjadi komponen akhir 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 nama, panggil metode UpdateKey. Saat Anda memanggil UpdateKey, Anda akan 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 akan 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 mirip dengan berikut:

{
  "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 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