API キーの作成と管理

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

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

API キーを作成する

CreateKey メソッドを使用して API キーを作成できます。このメソッドには Key パラメータが必要です。 Key オブジェクトの displayName フィールドと restrictions フィールドのみを指定できます。CreateKey は同期メソッドではありません。代わりに、 を呼び出すと、長時間実行 オペレーションが開始されます。CreateKey次の例では、制限のない API キーを作成するために CreateKey 呼び出しを発行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

成功すると、このメソッドはレスポンスで長時間実行オペレーションを返します。長時間実行オペレーションのポーリングで説明されているように、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 フィールドの値を使用します。この値は Cloud de Confiance コンソールには表示されませんが、 ListKeys メソッドを呼び出して、 すべての API キーの names を取得できます。Key.name フィールドは常に 次の形式です: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • displayName フィールドはコンソールの Name フィ 101Cloud de Confiance ールドにマッピングされるため、displayName を呼び出すときに CreateKey を指定することをおすすめします。
  • keyString フィールドには、API キーを必要とする API に送信する文字列が含まれます。keyString はAPI key フィールドに Cloud de Confiance コンソールにマッピングされます。 GetKeyString メソッドを呼び出して、API キーの keyString を取得できます。
  • etag フィールドには、キーの現在の値に基づいてサーバーによって計算されたチェックサムが含まれます。UpdateKey メソッドと DeleteKey メソッドを呼び出すときは、etag 値を渡してください。

ユーザー指定のキー ID

クエリ パラメータとして CreateKey メソッドの keyId を指定できます。指定すると、その値は Key.name の最後のコンポーネントになります。

たとえば、CreateKey の次の呼び出しについて考えてみましょう。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key with user-specified ID"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1'

この例では、Key.name フィールドの値は次のようになります。

"name": "projects/PROJECT_NUMBER/locations/global/keys/my-test-key1"

表示名を更新する

API キーの displayName を変更する場合、または displayName なしで作成された API キーに displayName を追加する場合は、UpdateKey メソッドを呼び出します。UpdateKey を呼び出すと、キーを更新する長時間実行オペレーションが開始されます。

次の例は、UpdateKey を呼び出す方法を示しています。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName": "New display name",
          "etag" : "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName'

operations.get からのレスポンスに "done": true が含まれている場合、response には更新された displayName を持つ Key オブジェクトが含まれます。

API キーを削除する

API キーを削除するには、DeleteKey メソッドを使用します。DeleteKey を呼び出すと、キーを DELETED としてマークする長時間実行オペレーションが開始されます。

次の例は、DeleteKey を呼び出す方法を示しています。

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H 'If-Match: "ETAG"' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID'

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 に設定します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true'

30 日後に、API キーは完全に削除されます。

API キーを復元する

API キーが完全に削除される前に復元するには、UndeleteKey メソッドを呼び出します。UndeleteKey を呼び出すと、キーを ACTIVE としてマークする長時間実行オペレーションが開始されます。

次の例は、UndeleteKey を呼び出す方法を示しています。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete'

次のステップ