このページでは、API Keys API を使用して API キーを作成、管理する方法について説明します。
Google Cloud API の呼び出しで API キーを使用する方法については、API キーの使用をご覧ください。
始める前に
このページでは、oauth2l コマンドライン ツールで curl を使用して、API キーの API にリクエストを送信します。API を試すための詳細については、API キーを使ってみるをご覧ください。
API キーを作成する
API キーを作成するには、CreateKey メソッドを使用します。このメソッドには Key パラメータが必要です。Key オブジェクトの displayName フィールドと restrictions フィールドのみ指定できます。CreateKey は同期メソッドではありません。代わりに、CreateKey の呼び出しを行うと、長時間実行オペレーションが開始されます。次の例は、制限なしで API キーを作成する CreateKey 呼び出しを発行します。
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
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 キーのクローン作成
同じ 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 を変更する場合、またはキーなしで作成された 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 には更新された 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 キーは使用できませんが、Google のシステムから完全に削除されていない 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 キーを復元するには、UndeleteKey メソッドを呼び出します。UndeleteKey を呼び出すと、キーを ACTIVE としてマークする、長時間実行オペレーションが開始されます。
次の例は、UndeleteKey を呼び出す方法を示しています。
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete -X POST