API キーの作成と管理

このページでは、API Keys API を使用して API キーを作成および管理する方法について説明します。

API の呼び出しで API キーを使用する方法については、 Google Cloud APIs, API キーを使用するをご覧ください。

始める前に

このページでは、curl と Google Cloud CLI を使用して API Keys API にリクエストを送信します。API を試すための設定方法について詳しくは、 API Keys のスタートガイド をご覧ください。

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 コンソールには表示されませんが、 ListKeys メソッドを呼び出して、 すべての API キーの names を取得できます。Key.name フィールドは常に 次の形式です: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • displayName フィールドはコンソールの Name フィ 101Google Cloud ールドにマッピングされるため、displayName を呼び出すときに CreateKey を指定することをおすすめします。
  • keyString フィールドには、API キーを必要とする API に送信する文字列が含まれます。keyString は、API key フィールドに Google Cloud マッピングされます。 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 には更新された 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 キーは使用できませんが、システムから完全に削除されるわけではありません。まだ存在しているが 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

次のステップ