API-Schlüssel erstellen und verwalten

Auf dieser Seite wird erläutert, wie Sie mit der API Keys API API-Schlüssel erstellen und verwalten.

Informationen zum Verwenden eines API-Schlüssels für Aufrufe Ihrer Google Cloud APIs finden Sie unter API-Schlüssel verwenden.

Hinweis

Die Seite verwendet curl mit dem Befehlszeilentool oauth2l, um Anfragen an die API-Schlüssel-API zu senden. Unter Erste Schritte mit den API-Schlüsseln finden Sie weitere Informationen zur Einrichtung der API.

API-Schlüssel erstellen

Sie können mit der Methode CreateKey einen API-Schlüssel erstellen. Die Methode erfordert den Parameter Key. Sie können nur die Felder displayName und restrictions des Key-Objekts angeben. CreateKey ist keine synchrone Methode. Stattdessen initiieren Sie einen lang andauernden Vorgang, wenn Sie CreateKey aufrufen. Im folgenden Beispiel wird ein CreateKey-Aufruf ausgeführt, um einen API-Schlüssel ohne Einschränkungen zu erstellen:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys -X POST -d '{"displayName" : "Example API key"}'

Bei Erfolg gibt die Methode einen lang andauernden Vorgang in der Antwort zurück. Wie unter Lange laufende Vorgänge abfragen beschrieben, senden Sie wiederholt operations.get-Aufrufe mit dem Wert aus den name. }. Wenn die Antwort von operations.get "done": true enthält, enthält das response-Objekt ein Key, das in etwa so aussieht:

{
  "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=="
  }
}

Im Objekt response:

  • Das Feld name enthält eine eindeutige Kennung für den API-Schlüssel. Sie verwenden den Wert im Feld name in den anderen Methoden, die einen Schlüsselnamen benötigen. Dieser Wert wird nicht in der Google Cloud Console angezeigt. Sie können aber die Methode ListKeys aufrufen, um die names für alle Ihre API-Schlüssel abzurufen. Das Feld Key.name hat immer das folgende Format: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • Das Feld displayName entspricht dem Feld Name in der Cloud Console. Sie sollten also beim Aufrufen von CreateKey eine displayName angeben.
  • Das Feld keyString enthält den String, den Sie an die APIs senden, die einen API-Schlüssel erfordern. keyString wird in der Cloud Console dem Feld API key zugeordnet. Sie können die Methode GetKeyString aufrufen, um die keyString für einen API-Schlüssel abzurufen.
  • Das Feld etag enthält eine vom Server berechnete Prüfsumme, die auf dem aktuellen Wert des Schlüssels basiert. Übergeben Sie beim Aufrufen der Methoden UpdateKey und DeleteKey den Wert etag.

Vom Nutzer angegebene Schlüssel-ID

Sie können einen keyId als Abfrageparameter für die Methode CreateKey angeben. Wenn dieser Wert angegeben ist, wird der Wert die letzte Komponente von Key.name.

Betrachten Sie zum Beispiel den folgenden Aufruf von CreateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1 -X POST -d '{"displayName" : "Example API key"}'

In diesem Beispiel hat das Feld Key.name den folgenden Wert: 

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

API-Schlüssel klonen

Mit der Methode CloneKey erstellen Sie eine Kopie eines API-Schlüssels im selben Cloud-Projekt. Wenn Sie anrufenCloneKey starten Sie einen lang andauernden Vorgang, der einen Schlüssel mit der gleichendisplayName undrestrictions als ursprünglichen Schlüssel, aber neuname undkeyString Werte fest.

Das folgende Beispiel zeigt, wie CloneKey aufgerufen wird:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:clone -X POST

Wenn die Antwort von operations.get "done": true enthält, enthält response das neue Key-Objekt.

Der neue Schlüssel hat denselben displayName und restrictions wie der ursprüngliche Schlüssel, aber eine neue name und keyString.

Anzeigenamen aktualisieren

Zum Ändern der displayName eines API-Schlüssels oder zum Hinzufügen eines displayName zu einem API-Schlüssel, der ohne einen erstellt wurde, rufen Sie die Methode UpdateKey auf. Wenn Sie UpdateKey aufrufen, initiieren Sie einen lang andauernden Vorgang, der den Schlüssel aktualisiert.

Das folgende Beispiel zeigt, wie UpdateKey aufgerufen wird:

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"}'

Wenn die Antwort von operations.get "done": true enthält, enthält response ein Key-Objekt mit dem aktualisierten displayName.

API-Schlüssel löschen

Verwenden Sie zum Löschen eines API-Schlüssels die Methode DeleteKey. Wenn Sie DeleteKey aufrufen, initiieren Sie einen lang andauernden Vorgang, der den Schlüssel als DELETED kennzeichnet.

Das folgende Beispiel zeigt, wie DeleteKey aufgerufen wird:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?etag="ETAG" -X DELETE

Wenn die Antwort von operations.get "done": true enthält, sieht response so aus:

{
  "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=="
  }
}

API-Schlüssel mit der Kennzeichnung DELETED können nicht verwendet werden, aber sie werden auch nicht vollständig aus unserem System entfernt. Nach 30 Tagen wird der API-Schlüssel endgültig gelöscht. Sie können der Methode ListKeys einen Filter hinzufügen, um API-Schlüssel zurückzugeben, die als DELETED gekennzeichnet sind:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?filter=state:DELETED

API-Schlüssel wiederherstellen

Mit der Methode UndeleteKey können Sie einen API-Schlüssel wiederherstellen, bevor er endgültig gelöscht wird. Wenn Sie UndeleteKey aufrufen, initiieren Sie einen lang andauernden Vorgang, der den Schlüssel als ACTIVE kennzeichnet.

Das folgende Beispiel zeigt, wie UndeleteKey aufgerufen wird:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete -X POST

Nächste Schritte