建立及管理 API 金鑰

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

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

正在建立 API 金鑰

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

如果成功，這個方法會在回應中傳回長時間執行的作業。如「輪詢長時間執行的作業」一文所述，您會使用 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

您可以指定 keyId 做為 CreateKey 方法的查詢參數。指定後，該值會成為 Key.name 的最終元件。

舉例來說，請看以下對 CreateKey 的呼叫：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key with user-specified ID"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1'

在本例中，Key.name 欄位的值如下：

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

更新顯示名稱

如要變更 API 金鑰的 displayName，或是為沒有 displayName 的 API 金鑰新增 displayName，請呼叫 UpdateKey 方法。呼叫 UpdateKey 時，您會啟動更新金鑰的長時間執行作業。

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName": "New display name",
          "etag" : "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName'

如果 operations.get 的回應包含 "done": true，則 response 會包含 Key 物件，其中含有更新後的 displayName。

刪除 API 金鑰

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

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

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H 'If-Match: "ETAG"' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID'

如果 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：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true'

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

還原 API 金鑰

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

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete'

後續步驟