建立及管理 API 金鑰

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

如要瞭解如何在呼叫 Google Cloud API 時使用 API 金鑰，請參閱「使用 API 金鑰」。

事前準備

這個頁面會使用 curl 和 Google Cloud CLI，將要求傳送至 API 金鑰 API。如要瞭解如何設定 API 實驗環境，請參閱「開始使用 API 金鑰」一文。

正在建立 API 金鑰

您可以使用 CreateKey 方法建立 API 金鑰。這個方法需要 Key 參數。您只能指定 Key 物件的 displayName 和 restrictions 欄位。CreateKey 不是同步方法。而是當您對 CreateKey 發出呼叫時，會啟動長時間執行的作業。下列範例會發出 CreateKey 呼叫，建立沒有限制的 API 金鑰：

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

如果成功，這個方法會在回應中傳回長時間執行的作業。如「輪詢長時間執行的作業」一節所述，您會使用 name 欄位的值，重複發出 operations.get 呼叫。如果 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 金鑰的專屬 ID。您可以在其他需要鍵名的 方法中，使用 name 欄位中的值。這個值不會顯示在 Google Cloud 控制台中，但您可以呼叫 ListKeys 方法，取得所有 API 金鑰的 names。「Key.name」欄位一律採用下列格式：projects/PROJECT_NUMBER/locations/global/keys/KEY_ID。
  • displayName 欄位會對應至Google Cloud 控制台中的 Name 欄位，因此您可能想在呼叫 CreateKey 時提供 displayName。
  • keyString 欄位包含您傳送至需要 API 金鑰的 API 的字串。keyString 會對應至Google Cloud 控制台中的 API key 欄位。您可以呼叫 GetKeyString 方法，取得 API 金鑰的 keyString。
  • etag 欄位包含伺服器根據金鑰目前值計算的總和檢查碼。呼叫 UpdateKey 和 DeleteKey 方法時，請傳遞 etag 值。

使用者指定的金鑰 ID

您可以為 CreateKey 方法指定 keyId 做為查詢參數。指定後，該值會成為 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 金鑰的 displayName，或為沒有 displayName 的 API 金鑰新增 displayName，請呼叫 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 會包含 Key 物件，其中含有更新後的 displayName。

刪除 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 金鑰無法使用，但也不會完全從系統中移除。如要列出仍存在但標示為 DELETED 的 API 金鑰，請將 ListKeys 方法的 show_deleted 設為 true：

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

30 天後，系統就會永久刪除 API 金鑰。

還原 API 金鑰

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

以下範例說明如何呼叫 UndeleteKey：

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

後續步驟