建立及管理 API 金鑰

本頁面說明如何使用 API 金鑰 API 建立及管理 API 金鑰。

如要瞭解如何將 API 金鑰與 Google Cloud API 呼叫搭配使用,請參閱使用 API 金鑰

事前準備

頁面使用 curl 搭配 oauth2l 指令列工具,將要求傳送至 API 金鑰的 API。如要進一步瞭解如何設定 API 實驗,請參閱開始使用 API 金鑰

建立 API 金鑰

您可以使用 CreateKey 方法建立 API 金鑰。該方法需要 Key 參數。您只能指定 Key 物件的 displayNamerestrictions 欄位。CreateKey 不是同步方法。而是會在呼叫 CreateKey 時啟動長時間執行作業。以下範例會發出 CreateKey 呼叫以建立沒有限制的 API 金鑰:

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

成功時,這個方法會在回應中傳回長時間執行作業。如 輪詢長時間執行的作業,您必須重複執行operations.get 值與name。當 operations.get 的回應中包含 "done": true 時,response 物件會包含 Key 類似,如下所示:

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

response 物件中:

  • name 欄位包含 API 金鑰的唯一識別碼。在其他需要金鑰名稱的方法中,您會使用 name 欄位中的值。這個值不會顯示在 Google Cloud Console 中,不過您可以呼叫 ListKeys 方法以取得所有 API 金鑰的 namesKey.name 欄位一律採用以下格式:projects/PROJECT_NUMBER/locations/global/keys/KEY_ID
  • displayName 欄位對應至 Cloud Console 中的 Name 欄位,因此您在呼叫 CreateKey 時可能會提供 displayName
  • keyString 欄位包含要傳送到 API 金鑰的 API 字串。keyString 會對應至 Cloud Console 中的 API key 欄位。您可以呼叫 GetKeyString 方法以取得 API 金鑰的 keyString
  • etag 欄位包含伺服器根據金鑰目前值計算得出的檢查碼。請在呼叫 UpdateKeyDeleteKey 方法時傳送 etag 值。

使用者指定的金鑰 ID

您可以將 keyId 指定為 CreateKey 方法的查詢參數。如果有指定,該值就會成為 Key.name 的最終元件。

舉例來說,請參照 CreateKey 的呼叫:

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

在這個範例中,Key.name 欄位有以下值:

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

複製 API 金鑰

如要在相同 Cloud 專案中複製 API 金鑰,請使用 CloneKey 方法。當您呼叫 CloneKey 時,會啟動長時間執行的作業,以建立與原始金鑰相同的 displayNamerestrictions 金鑰,但會新增 namekeyString 值。

以下範例說明如何呼叫 CloneKey

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

operations.get 的回應中包含 "done": true 時,response 包含新的 Key 物件。

新金鑰擁有與原始金鑰相同的 displayNamerestrictions,但新的 namekeyString

更新顯示名稱

如要變更 API 金鑰的 displayName,或是將 displayName 新增至尚未建立 API 金鑰的呼叫,請呼叫 UpdateKey 方法。當您呼叫 UpdateKey 時,您會啟動長時間執行作業以更新金鑰。

以下範例說明如何呼叫 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"}'

operations.get 的回應中包含 "done": true 時,response 會包含包含已更新 displayNameKey 物件。

刪除 API 金鑰

如要刪除 API 金鑰,請使用 DeleteKey 方法。當您呼叫 DeleteKey 時,您會啟動長時間執行的作業,並將金鑰標示為 DELETED

以下範例說明如何呼叫 DeleteKey

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

operations.get 的回應包含 "done": true 時,response 會如下所示:

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

標示為 DELETED 的 API 金鑰無法使用,但請勿將金鑰從我們的系統中完全移除。30 天過後,API 金鑰就會永久刪除。您可以在 ListKeys 方法中新增篩選器,傳回標示為 DELETED 的 API 金鑰:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?filter=state:DELETED

還原 API 金鑰

如要在永久刪除 API 之前永久刪除 API 金鑰,請呼叫 UndeleteKey 方法。當您呼叫 UndeleteKey 時,您會啟動長時間執行的作業,並將金鑰標示為 ACTIVE

以下範例說明如何呼叫 UndeleteKey

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

後續步驟