API キーの作成と管理

このページでは、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