本頁面說明如何使用 API 金鑰 API 建立及管理 API 金鑰。
如要瞭解如何將 API 金鑰與 Google Cloud API 呼叫搭配使用，請參閱使用 API 金鑰。
事前準備
頁面使用 curl 搭配 oauth2l 指令列工具，將要求傳送至 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"}'
成功時，這個方法會在回應中傳回長時間執行作業。如
輪詢長時間執行的作業，您必須重複執行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 金鑰的names。Key.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欄位包含伺服器根據金鑰目前值計算得出的檢查碼。請在呼叫UpdateKey和DeleteKey方法時傳送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 時，會啟動長時間執行的作業，以建立與原始金鑰相同的 displayName 和 restrictions 金鑰，但會新增 name 和 keyString 值。
以下範例說明如何呼叫 CloneKey：
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:clone -X POST
當 operations.get 的回應中包含 "done": true 時，response 包含新的 Key 物件。
新金鑰擁有與原始金鑰相同的 displayName 和 restrictions，但新的 name 和 keyString。
更新顯示名稱
如要變更 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 會包含包含已更新 displayName 的 Key 物件。
刪除 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