API キーの作成と管理

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

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

始める前に

このページでは、curl と Google Cloud CLI を使用して API Keys 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"}'

成功すると、このメソッドはレスポンスで長時間実行オペレーションを返します。長時間実行オペレーションのポーリングで説明したように、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 キーの一意の識別子が含まれます。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

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

次のステップ