API-Schlüssel verwalten

Auf dieser Seite wird beschrieben, wie Sie API-Schlüssel erstellen, bearbeiten und einschränken.

Einführung in API-Schlüssel

Wenn Sie einen API-Schlüssel für die Authentifizierung bei einer API verwenden, identifiziert der API-Schlüssel kein Hauptkonto. Der API-Schlüssel verknüpft die Anfrage mit dem Google Cloud-Projekt zu Abrechnungs- und Kontingentzwecken. Ohne ein Hauptkonto kann in der Anfrage nicht mithilfe der Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM) geprüft werden, ob der Aufrufer berechtigt ist, den angeforderten Vorgang auszuführen.

Ein API-Schlüssel besteht aus den folgenden Komponenten, die Sie zur Verwaltung und Verwendung des Schlüssels verwenden:

String

Der API-Schlüsselstring ist ein verschlüsselter String, z. B. AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Wenn Sie einen API-Schlüssel zur Authentifizierung verwenden, verwenden Sie immer den String des Schlüssels. API-Schlüsseln ist keine JSON-Datei zugeordnet.

ID

Die API-Schlüssel-ID wird von Google Cloud-Verwaltungstools verwendet, um den Schlüssel eindeutig zu identifizieren. Die Schlüssel-ID kann nicht zur Authentifizierung verwendet werden. Die Schlüssel-ID finden Sie in der URL der Bearbeitungsseite des Schlüssels in der Google Cloud Console. Sie können die Schlüssel-ID auch abrufen, indem Sie die Google Cloud CLI verwenden, um die Schlüssel in Ihrem Projekt aufzulisten.

Anzeigename

Der Anzeigename ist ein optionaler, beschreibender Name für den Schlüssel, den Sie beim Erstellen oder Aktualisieren des Schlüssels festlegen können.

Hinweise

Führen Sie die folgenden Aufgaben aus, um die Beispiele auf dieser Seite zu verwenden.

Authentifizierung einrichten

Select the tab for how you plan to use the samples on this page:

Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

C++

Wenn Sie die C++ Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten in der Dokumentation zur Google Cloud-Authentifizierung.

Java

Wenn Sie die Java Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten in der Dokumentation zur Google Cloud-Authentifizierung.

Python

Wenn Sie die Python Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten in der Dokumentation zur Google Cloud-Authentifizierung.

REST

Verwenden Sie die von der gcloud CLI bereitgestellten Anmeldedaten, um die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung zu verwenden.

Install the Google Cloud CLI, then initialize it by running the following command:

gcloud init

Weitere Informationen finden Sie unter Für die Verwendung von REST authentifizieren in der Dokumentation zur Google Cloud-Authentifizierung.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwalten von API-Schlüsseln benötigen:

• API Keys Admin (roles/serviceusage.apiKeysAdmin)
• Sie können einen API-Schlüssel über die Google Cloud Console auf bestimmte APIs beschränken: Dienstnutzungsanzeige (roles/serviceusage.serviceUsageViewer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

API-Schlüssel erstellen

Verwenden Sie eine der folgenden Optionen, um einen API-Schlüssel zu erstellen:

Console

1. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten:

   Zu den Anmeldedaten

2. Klicken Sie auf Anmeldedaten erstellen und wählen Sie im Menü API-Schlüssel aus.

   Das Dialogfeld API-Schlüssel erstellt enthält den String für den neu erstellten Schlüssel.

gcloud

Verwenden Sie den gcloud services api-keys create-Befehl, um einen API-Schlüssel zu erstellen.

Ersetzen Sie DISPLAY_NAME durch einen aussagekräftigen Namen für Ihren Schlüssel.

 gcloud services api-keys create --display-name=DISPLAY_NAME
 

C++

Sie müssen die API-Schlüssel-Clientbibliothek installieren, um dieses Beispiel auszuführen.

#include "google/cloud/apikeys/v2/api_keys_client.h"
#include "google/cloud/location.h"

google::api::apikeys::v2::Key CreateApiKey(
    google::cloud::apikeys_v2::ApiKeysClient client,
    google::cloud::Location location, std::string display_name) {
  google::api::apikeys::v2::CreateKeyRequest request;
  request.set_parent(location.FullName());
  request.mutable_key()->set_display_name(std::move(display_name));
  // As an example, restrict the API key's scope to the Natural Language API.
  request.mutable_key()->mutable_restrictions()->add_api_targets()->set_service(
      "language.googleapis.com");

  // Create the key, blocking on the result.
  auto key = client.CreateKey(request).get();
  if (!key) throw std::move(key.status());
  std::cout << "Successfully created an API key: " << key->name() << "\n";

  // For authenticating with the API key, use the value in `key->key_string()`.

  // The API key's resource name is the value in `key->name()`. Use this to
  // refer to the specific key in a `GetKey()` or `DeleteKey()` RPC.
  return *key;
}

Java

Sie müssen die google-cloud-apikeys-Clientbibliothek installieren, um dieses Beispiel auszuführen.

import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.ApiTarget;
import com.google.api.apikeys.v2.CreateKeyRequest;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.LocationName;
import com.google.api.apikeys.v2.Restrictions;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateApiKey {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    //  2. Set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    //  3. Make sure you have the necessary permission to create API keys.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    createApiKey(projectId);
  }

  // Creates an API key.
  public static void createApiKey(String projectId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      Key key = Key.newBuilder()
          .setDisplayName("My first API key")
          // Set the API key restriction.
          // You can also set browser/ server/ android/ ios based restrictions.
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys#api_key_restrictions
          .setRestrictions(Restrictions.newBuilder()
              // Restrict the API key usage by specifying the target service and methods.
              // The API key can only be used to authenticate the specified methods in the service.
              .addApiTargets(ApiTarget.newBuilder()
                  .setService("translate.googleapis.com")
                  .addMethods("translate.googleapis.com.TranslateText")
                  .build())
              .build())
          .build();

      // Initialize request and set arguments.
      CreateKeyRequest createKeyRequest = CreateKeyRequest.newBuilder()
          // API keys can only be global.
          .setParent(LocationName.of(projectId, "global").toString())
          .setKey(key)
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.createKeyAsync(createKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      // To restrict the usage of this API key, use the value in "result.getName()".
      System.out.printf("Successfully created an API key: %s", result.getName());
    }
  }
}

Python

Sie müssen die API-Schlüssel-Clientbibliothek installieren, um dieses Beispiel auszuführen.

from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def create_api_key(project_id: str, suffix: str) -> Key:
    """
    Creates and restrict an API key. Add the suffix for uniqueness.

    TODO(Developer):
    1. Before running this sample,
      set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    2. Make sure you have the necessary permission to create API keys.

    Args:
        project_id: Google Cloud project id.

    Returns:
        response: Returns the created API Key.
    """
    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    key = api_keys_v2.Key()
    key.display_name = f"My first API key - {suffix}"

    # Initialize request and set arguments.
    request = api_keys_v2.CreateKeyRequest()
    request.parent = f"projects/{project_id}/locations/global"
    request.key = key

    # Make the request and wait for the operation to complete.
    response = client.create_key(request=request).result()

    print(f"Successfully created an API key: {response.name}")
    # For authenticating with the API key, use the value in "response.key_string".
    # To restrict the usage of this API key, use the value in "response.name".
    return response

REST

Verwenden Sie die keys.create-Methode, um einen API-Schlüssel zu erstellen. Diese Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Sie müssen den Vorgang abfragen, um die Informationen für den neuen Schlüssel abzurufen.

Ersetzen Sie die folgenden Werte:

• DISPLAY_NAME: Optional. Ein beschreibender Name für Ihren Schlüssel.
• PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

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

Weitere Informationen zum Erstellen von API-Schlüsseln mithilfe der REST API finden Sie in der API-API-Dokumentation unter API-Schlüssel erstellen.

Kopieren Sie den Schlüsselstring und bewahren Sie ihn sicher auf. Mit API-Schlüsseleinschränkungen können Sie die Verwendung des Schlüssels einschränken.

Einschränkungen für API-Schlüssel anwenden

API-Schlüssel sind standardmäßig uneingeschränkt. Uneingeschränkte Schlüssel sind unsicher, da sie von jedem beliebigen Nutzer verwendet werden können. Für Produktionsanwendungen sollten Sie sowohl Anwendungseinschränkungen als auch API-Einschränkungen festlegen.

Einschränkungen für Anwendungen hinzufügen

Anwendungseinschränkungen geben an, welche Websites, IP-Adressen oder Anwendungen einen API-Schlüssel verwenden dürfen.

Sie können jeweils nur einen Einschränkungstyp einer Anwendung anwenden. Wählen Sie den für Ihren Anwendungstyp geeigneten Einschränkungstyp aus.

Wahltaste	Anwendungstyp	Hinweise
HTTP-Verweis-URLs	Webanwendungen	Gibt die Websites an, die den Schlüssel verwenden können.
IP-Adressen	Von bestimmten Servern aufgerufene Anwendungen	Gibt die Server oder Cronjobs an, die den Schlüssel verwenden können.
Android-Apps	Android-Anwendungen	Gibt die Android-Anwendung an, die den Schlüssel verwenden kann.
iOS-Apps	iOS-Anwendungen	Gibt die iOS-Bundles an, die den Schlüssel verwenden können.

HTTP-Verweis-URLs

Um die Websites einzuschränken, die Ihren API-Schlüssel verwenden können, fügen Sie eine oder mehrere HTTP-Verweis-URLs hinzu.

Sie können das Platzhalterzeichen (*) durch das Platzhalterzeichen oder den Pfad ersetzen, aber nicht in der Mitte der URL ein Platzhalterzeichen einfügen. *.example.com ist beispielsweise gültig und akzeptiert alle Websites, die auf .example.com enden. mysubdomain*.example.com ist jedoch keine gültige Einschränkung.

In den HTTP-Verweiseinschränkungen können Portnummern enthalten sein. Wenn Sie eine Portnummer angeben, werden nur Anfragen zugeordnet, die diesen Port verwenden. Wenn Sie keine Portnummer angeben, werden Anfragen von einer beliebigen Portnummer abgeglichen.

Sie können einem API-Schlüssel bis zu 1.200 HTTP-Verweis-URLs hinzufügen

Die folgende Tabelle enthält einige Beispielszenarien und Browsereinschränkungen:

Szenario	Einschränkungen
Bestimmte URL zulassen	Fügen Sie eine URL mit einem genauen Pfad hinzu. Beispiel: www.example.com/path www.example.com/path/path Einige Browser implementieren eine Verweisrichtlinie, die für ursprungsübergreifende Anfragen nur die Ursprungs-URL sendet. Nutzer dieser Browser können keine Schlüssel mit seitenspezifischen URL-Einschränkungen verwenden.
Eine beliebige URL auf Ihrer Website zulassen	Sie müssen zwei URLs in der Liste allowedReferers festlegen. URL für die Domain ohne Subdomain und mit einem Platzhalter für den Pfad. Beispiel: example.com/* Eine zweite URL, die einen Platzhalter für die Subdomain und einen Platzhalter für den Pfad enthält. Beispiel: *.example.com/*
Eine beliebige URL in einer einzelnen Subdomain oder einer Grunddomain zulassen	Sie müssen zwei URLs in der Liste allowedReferers festlegen, um eine gesamte Domain zuzulassen: URL für die Domain ohne abschließenden Schrägstrich. Beispiel: www.example.com sub.example.com example.com Eine zweite URL für die Domain, die einen Platzhalter für den Pfad enthält. Beispiel: www.example.com/* sub.example.com/* example.com/*

Verwenden Sie eine der folgenden Optionen, um Ihren API-Schlüssel auf bestimmte Websites zu beschränken:

Console

1. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten:

   Zu den Anmeldedaten

2. Klicken Sie auf den Namen des API-Schlüssels, den Sie einschränken möchten.

3. Wählen Sie im Abschnitt Anwendungseinschränkungen die Option HTTP-Verweis-URLs aus.

4. Klicken Sie für jede gewünschte Einschränkung auf Element hinzufügen, geben Sie die Einschränkung ein und klicken Sie auf Fertig.

5. Klicken Sie auf Speichern, um die Änderungen zu speichern und zur API-Schlüsselliste zurückzukehren.

gcloud

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Um die ID abzurufen, listen Sie mit dem Befehl gcloud services api-keys list die Schlüssel in Ihrem Projekt auf.

2. Verwenden Sie den Befehl gcloud services api-keys update, um einem API-Schlüssel Einschränkungen für HTTP-Verweis-URLs hinzuzufügen.

   Ersetzen Sie die folgenden Werte:

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   • ALLOWED_REFERRER_1: Ihre HTTP-Referrer-URL.

     Sie können beliebig viele Einschränkungen hinzufügen. Verwenden Sie Kommas, um die Einschränkungen zu trennen. Sie müssen alle Verweiseinschränkungen mit dem Befehl "update" angeben. Die Verweiseinschränkungen, die aufgehoben wurden, ersetzen alle vorhandenen Verweiseinschränkungen für den Schlüssel.

   gcloud services api-keys update KEY_ID \
    --allowed-referrers="ALLOWED_REFERRER_1"

Java

Sie müssen die google-cloud-apikeys-Clientbibliothek installieren, um dieses Beispiel auszuführen.

import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.BrowserKeyRestrictions;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyHttp {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyHttp(projectId, keyId);
  }

  // Restricts an API key. To restrict the websites that can use your API key,
  // you add one or more HTTP referrer restrictions.
  public static void restrictApiKeyHttp(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage to specific websites by adding them
      // to the list of allowed_referrers.
      Restrictions restrictions = Restrictions.newBuilder()
          .setBrowserKeyRestrictions(BrowserKeyRestrictions.newBuilder()
              .addAllowedReferrers("www.example.com/*")
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Sie müssen die API-Schlüssel-Clientbibliothek installieren, um dieses Beispiel auszuführen.

from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_http(project_id: str, key_id: str) -> Key:
    """
    Restricts an API key. To restrict the websites that can use your API key,
    you add one or more HTTP referrer restrictions.

    TODO(Developer): Replace the variables before running this sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Restrict the API key usage to specific websites by adding them to the list of allowed_referrers.
    browser_key_restrictions = api_keys_v2.BrowserKeyRestrictions()
    browser_key_restrictions.allowed_referrers = ["www.example.com/*"]

    # Set the API restriction.
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.browser_key_restrictions = browser_key_restrictions

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Sie erhalten die ID, indem Sie die Methode keys.list verwenden. Die ID wird im Feld uid der Antwort aufgeführt.

   Ersetzen Sie PROJECT_ID durch die Google Cloud-Projekt-ID oder den Projektnamen.

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

2. Verwenden Sie die Methode keys.patch, um dem API-Schlüssel Einschränkungen für HTTP-Verweis-URLs hinzuzufügen.

   Diese Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Sie müssen den Vorgang abfragen, um festzustellen, wann der Vorgang abgeschlossen ist, und den Vorgangsstatus abzurufen.

   Ersetzen Sie die folgenden Werte:

   • ALLOWED_REFERRER_1: Ihre HTTP-Referrer-URL.

     Sie können beliebig viele Einschränkungen hinzufügen. Verwenden Sie Kommas, um die Einschränkungen zu trennen. Sie müssen alle Verweiseinschränkungen in der Anfrage angeben Die angegebenen Verweiseinschränkungen ersetzen alle vorhandenen Verweiseinschränkungen für den Schlüssel.

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{
   "restrictions" : {
   "browserKeyRestrictions": {
     "allowedReferrers": ["ALLOWED_REFERRER_1"]
   }
   }
   }' \
   "https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Weitere Informationen zum Hinzufügen von HTTP-Verweiseinschränkungen zu einem Schlüssel mithilfe der REST API finden Sie in der API-Dokumentation zu API Keys unter Browsereinschränkungen hinzufügen.

IP-Adressen

Sie können eine oder mehrere IP-Adressen der Aufrufer angeben, z. B. Webserver oder Cronjobs, die Ihren API-Schlüssel verwenden dürfen. Sie können die IP-Adressen in einem der folgenden Formate angeben:

• IPv4 (198.51.100.1)
• IPv6 (2001:db8::1)
• Ein Subnetz mit CIDR-Notation (198.51.100.0/24, 2001:db8::/64)

Die Verwendung von localhost wird für Servereinschränkungen nicht unterstützt.

Verwenden Sie eine der folgenden Optionen, um den API-Schlüssel auf bestimmte IP-Adressen zu beschränken:

Console

1. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten:

   Zu den Anmeldedaten

2. Klicken Sie auf den Namen des API-Schlüssels, den Sie einschränken möchten.

3. Wählen Sie im Abschnitt Anwendungseinschränkungen die IP-Adressen.

4. Klicken Sie für jede IP-Adresse, die Sie hinzufügen möchten, auf Element hinzufügen, geben Sie die Adresse ein und klicken Sie auf Fertig.

5. Klicken Sie auf Speichern, um die Änderungen zu speichern und zur API-Schlüsselliste zurückzukehren.

gcloud

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Um die ID abzurufen, listen Sie mit dem Befehl gcloud services api-keys list die Schlüssel in Ihrem Projekt auf.

2. Verwenden Sie den Befehl gcloud services api-keys update, um einem API-Schlüssel Server-IP-Einschränkungen hinzuzufügen.

   Ersetzen Sie die folgenden Werte:

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   • ALLOWED_IP_ADDR_1: ist Ihre zulässige IP-Adresse.

     Sie können beliebig viele IP-Adressen hinzufügen. Verwenden Sie Kommas, um die Adressen zu trennen.

   gcloud services api-keys update KEY_ID \
   --allowed-ips="ALLOWED_IP_ADDR_1"

Java

Sie müssen die google-cloud-apikeys-Clientbibliothek installieren, um dieses Beispiel auszuführen.

import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.ServerKeyRestrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.Arrays;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyServer {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyServer(projectId, keyId);
  }

  // Restricts the API key based on IP addresses. You can specify one or more IP addresses
  // of the callers, for example web servers or cron jobs, that are allowed to use your API key.
  public static void restrictApiKeyServer(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage by specifying the IP addresses.
      // You can specify the IP addresses in IPv4 or IPv6 or a subnet using CIDR notation.
      Restrictions restrictions = Restrictions.newBuilder()
          .setServerKeyRestrictions(ServerKeyRestrictions.newBuilder()
              .addAllAllowedIps(Arrays.asList("198.51.100.0/24", "2000:db8::/64"))
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Sie müssen die API-Schlüssel-Clientbibliothek installieren, um dieses Beispiel auszuführen.

from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_server(project_id: str, key_id: str) -> Key:
    """
    Restricts the API key based on IP addresses. You can specify one or more IP addresses of the callers,
    for example web servers or cron jobs, that are allowed to use your API key.

    TODO(Developer): Replace the variables before running this sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Restrict the API key usage by specifying the IP addresses.
    # You can specify the IP addresses in IPv4 or IPv6 or a subnet using CIDR notation.
    server_key_restrictions = api_keys_v2.ServerKeyRestrictions()
    server_key_restrictions.allowed_ips = ["198.51.100.0/24", "2000:db8::/64"]

    # Set the API restriction.
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.server_key_restrictions = server_key_restrictions

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Sie erhalten die ID, indem Sie die Methode keys.list verwenden. Die ID wird im Feld uid der Antwort aufgeführt.

   Ersetzen Sie PROJECT_ID durch die Google Cloud-Projekt-ID oder den Projektnamen.

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

2. Verwenden Sie die Methode keys.patch, um einem API-Schlüssel Servereinschränkungen (IP-Adresse) hinzuzufügen.

   Diese Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Sie müssen den Vorgang abfragen, um festzustellen, wann der Vorgang abgeschlossen ist, und den Vorgangsstatus abzurufen.

   Ersetzen Sie die folgenden Werte:

   • ALLOWED_IP_ADDR_1: ist Ihre zulässige IP-Adresse.

     Sie können beliebig viele IP-Adressen hinzufügen. Verwenden Sie Kommas, um die Einschränkungen zu trennen. Sie müssen alle IP-Adressen mit der Anfrage angeben. Die angegebenen Einschränkungen für Verweis-URLs ersetzen vorhandene IP-Adressbeschränkungen für den Schlüssel.

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{
   "restrictions" : {
     "serverKeyRestrictions": {
       "allowedIps": ["ALLOWED_IP_ADDR_1"]
     }
   }
   }' \
   "https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Weitere Informationen zum Hinzufügen von IP-Adressbeschränkungen für einen Schlüssel mithilfe der REST API finden Sie in der API-Dokumentation zu API Keys unter Servereinschränkungen hinzufügen.

Android-Apps

Sie können die Verwendung eines API-Schlüssels auf bestimmte Android-Apps beschränken. Sie müssen den Paketnamen und den 20-Byte-SHA1-Zertifikatfingerabdruck für jede Anwendung angeben.

Wenn Sie den API-Schlüssel in einer Anfrage verwenden, müssen Sie den Paketnamen und den Zertifikatfingerabdruck mit den folgenden HTTP-Headern angeben:

• X-Android-Package
• X-Android-Cert

Hinweis: Es ist ganz einfach, diese Einschränkung zu umgehen. Wenn Sie diese Einschränkung verwenden, sollten Sie auch API-Einschränkungen hinzufügen und die Nutzung sorgfältig überwachen.

Verwenden Sie eine der folgenden Optionen, um Ihren API-Schlüssel auf eine oder mehrere Android-Apps zu beschränken:

Console

1. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten:

   Zu den Anmeldedaten

2. Klicken Sie auf den Namen des API-Schlüssels, den Sie einschränken möchten.

3. Wählen Sie im Abschnitt Anwendungseinschränkungen Android-Apps aus.

4. Klicken Sie für jede Android-App, die Sie hinzufügen möchten, auf Element hinzufügen, geben Sie den Paketnamen und den SHA1-Zertifikat-Fingerabdruck ein und klicken Sie auf Fertig.

5. Klicken Sie auf Speichern, um die Änderungen zu speichern und zur API-Schlüsselliste zurückzukehren.

gcloud

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Um die ID abzurufen, listen Sie mit dem Befehl gcloud services api-keys list die Schlüssel in Ihrem Projekt auf.

2. Geben Sie mit dem Befehl gcloud services api-keys update die Android-Apps an, die einen API-Schlüssel verwenden können.

   Ersetzen Sie die folgenden Werte:

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   • SHA1_FINGERPRINT und PACKAGE_NAME: Die App-Informationen für eine Android-App, die den Schlüssel verwenden kann.

     Sie können beliebig viele Anwendungen hinzufügen. Verwenden Sie zusätzliche --allowed-application-Flags.

   gcloud services api-keys update KEY_ID \
   --allowed-application=sha1_fingerprint=SHA1_FINGERPRINT_1,package_name=PACKAGE_NAME_1 \
   --allowed-application=sha1_fingerprint=SHA1_FINGERPRINT_2,package_name=PACKAGE_NAME_2

Java

Sie müssen die google-cloud-apikeys-Clientbibliothek installieren, um dieses Beispiel auszuführen.

import com.google.api.apikeys.v2.AndroidApplication;
import com.google.api.apikeys.v2.AndroidKeyRestrictions;
import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyAndroid {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyAndroid(projectId, keyId);
  }

  // Restricts an API key based on android applications.
  // Specifies the Android application that can use the key.
  public static void restrictApiKeyAndroid(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage by specifying the allowed android applications.
      Restrictions restrictions = Restrictions.newBuilder()
          .setAndroidKeyRestrictions(AndroidKeyRestrictions.newBuilder()
              .addAllowedApplications(AndroidApplication.newBuilder()
                  // Specify the android application's package name and SHA1 fingerprint.
                  .setPackageName("com.google.appname")
                  .setSha1Fingerprint("0873D391E987982FBBD30873D391E987982FBBD3")
                  .build())
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Sie müssen die API-Schlüssel-Clientbibliothek installieren, um dieses Beispiel auszuführen.

from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_android(project_id: str, key_id: str) -> Key:
    """
    Restricts an API key based on android applications.

    Specifies the Android application that can use the key.

    TODO(Developer): Replace the variables before running this sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Specify the android application's package name and SHA1 fingerprint.
    allowed_application = api_keys_v2.AndroidApplication()
    allowed_application.package_name = "com.google.appname"
    allowed_application.sha1_fingerprint = "0873D391E987982FBBD30873D391E987982FBBD3"

    # Restrict the API key usage by specifying the allowed applications.
    android_key_restriction = api_keys_v2.AndroidKeyRestrictions()
    android_key_restriction.allowed_applications = [allowed_application]

    # Set the restriction(s).
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.android_key_restrictions = android_key_restriction

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Sie erhalten die ID, indem Sie die Methode keys.list verwenden. Die ID wird im Feld uid der Antwort aufgeführt.

   Ersetzen Sie PROJECT_ID durch die Google Cloud-Projekt-ID oder den Projektnamen.

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

2. Verwenden Sie die Methode keys.patch, um die Android-Apps anzugeben, die einen API-Schlüssel verwenden können.

   Diese Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Sie müssen den Vorgang abfragen, um festzustellen, wann der Vorgang abgeschlossen ist, und den Vorgangsstatus abzurufen.

   Ersetzen Sie die folgenden Werte:

   • SHA1_FINGERPRINT_1 und PACKAGE_NAME_1: Die App-Informationen für eine Android-App, die den Schlüssel verwenden kann.

     Sie können die Informationen für so viele Anwendungen wie nötig hinzufügen. Verwenden Sie Kommas, um die AndroidApplication-Objekte zu trennen. Sie müssen alle Anwendungen mit der Anfrage bereitstellen. Die bereitgestellten Anwendungen ersetzen alle vorhandenen zulässigen Anwendungen für den Schlüssel.

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{
   "restrictions" : {
   "androidKeyRestrictions": {
     "allowedApplications": [
       {
         "sha1Fingerprint": "SHA1_FINGERPRINT_1",
         "packageName": "PACKAGE_NAME_1"
       },
    ]
   }
   }
   }' \
   "https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Weitere Informationen zum Hinzufügen von Einschränkungen für Android-Apps zu einem Schlüssel mithilfe der REST API finden Sie in der API-Dokumentation zu API Keys unter Android-Einschränkungen hinzufügen.

iOS-Apps

Sie können die Nutzung eines API-Schlüssels auf bestimmte iOS-Apps beschränken, indem Sie die Bundle-ID der einzelnen Apps angeben.

Wenn Sie den API-Schlüssel in einer Anfrage verwenden, müssen Sie die Bundle-ID mit dem HTTP-Header X-Ios-Bundle-Identifier angeben.

Hinweis: Es ist ganz einfach, diese Einschränkung zu umgehen. Wenn Sie diese Einschränkung verwenden, sollten Sie auch API-Einschränkungen hinzufügen und die Nutzung sorgfältig überwachen.

Verwenden Sie eine der folgenden Optionen, um Ihren API-Schlüssel auf eine oder mehrere iOS-Apps zu beschränken:

Console

1. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten:

   Zu den Anmeldedaten

2. Klicken Sie auf den Namen des API-Schlüssels, den Sie einschränken möchten.

3. Wählen Sie im Abschnitt Anwendungseinschränkungen iOS-App aus.

4. Klicken Sie für jede iOS-App, die Sie hinzufügen möchten, auf Element hinzufügen, geben Sie die Bundle-ID ein und klicken Sie dann auf Fertig.

5. Klicken Sie auf Speichern, um die Änderungen zu speichern und zur API-Schlüsselliste zurückzukehren.

gcloud

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Um die ID abzurufen, listen Sie mit dem Befehl gcloud services api-keys list die Schlüssel in Ihrem Projekt auf.

2. Mit der Methode gcloud services api-keys update können Sie die iOS-Apps festlegen, die den Schlüssel verwenden können.

   Ersetzen Sie die folgenden Werte:

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   • ALLOWED_BUNDLE_ID: Die Bundle-ID einer iOS-App, die diesen API-Schlüssel verwenden soll.

     Sie können beliebig viele Bundle-IDs hinzufügen. Verwenden Sie Kommas, um die IDs zu trennen.

   gcloud services api-keys update KEY_ID \
   --allowed-bundle-ids=ALLOWED_BUNDLE_ID_1,ALLOWED_BUNDLE_ID_2

Java

Sie müssen die google-cloud-apikeys-Clientbibliothek installieren, um dieses Beispiel auszuführen.

import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.IosKeyRestrictions;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.Arrays;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyIos {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyIos(projectId, keyId);
  }

  // Restricts an API key. You can restrict usage of an API key to specific iOS apps
  // by providing the bundle ID of each app.
  public static void restrictApiKeyIos(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage by specifying the bundle ID(s)
      // of iOS app(s) that can use the key.
      Restrictions restrictions = Restrictions.newBuilder()
          .setIosKeyRestrictions(IosKeyRestrictions.newBuilder()
              .addAllAllowedBundleIds(Arrays.asList("com.google.gmail", "com.google.drive"))
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Sie müssen die API-Schlüssel-Clientbibliothek installieren, um dieses Beispiel auszuführen.

from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_ios(project_id: str, key_id: str) -> Key:
    """
    Restricts an API key. You can restrict usage of an API key to specific iOS apps
    by providing the bundle ID of each app.

    TODO(Developer): Replace the variables before running this sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Restrict the API key usage by specifying the bundle ID(s) of iOS app(s) that can use the key.
    ios_key_restrictions = api_keys_v2.IosKeyRestrictions()
    ios_key_restrictions.allowed_bundle_ids = ["com.google.gmail", "com.google.drive"]

    # Set the API restriction.
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.ios_key_restrictions = ios_key_restrictions

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Sie erhalten die ID, indem Sie die Methode keys.list verwenden. Die ID wird im Feld uid der Antwort aufgeführt.

   Ersetzen Sie PROJECT_ID durch die Google Cloud-Projekt-ID oder den Projektnamen.

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

2. Verwenden Sie die Methode keys.patch, um die Android-Apps anzugeben, die einen API-Schlüssel verwenden können.

   Diese Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Sie müssen den Vorgang abfragen, um festzustellen, wann der Vorgang abgeschlossen ist, und den Vorgangsstatus abzurufen.

   Ersetzen Sie die folgenden Werte:

   • ALLOWED_BUNDLE_ID: Die Bundle-ID einer iOS-App, die den Schlüssel verwenden kann.

     Sie können die Informationen für so viele Anwendungen wie nötig hinzufügen. Verwenden Sie Kommas, um die Bundle-IDs zu trennen. Sie müssen alle Bundle-IDs mit der Anfrage angeben. Die angegebenen Bundle-IDs ersetzen alle vorhandenen zulässigen Anwendungen für den Schlüssel.

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{
   "restrictions" : {
   "iosKeyRestrictions": {
     "allowedBundleIds": ["ALLOWED_BUNDLE_ID_1","ALLOWED_BUNDLE_ID_2"]
   }
   }
   }' \
   "https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Weitere Informationen zum Hinzufügen von iOS-App-Einschränkungen zu einem Schlüssel mithilfe der REST API finden Sie unter iOS-Einschränkungen hinzufügen in der API-Dokumentation zu API Keys.

API-Einschränkungen hinzufügen

API-Einschränkungen geben an, welche APIs mit dem API-Schlüssel aufgerufen werden können.

Hinweis: Bevor Sie eine API für eine API-Einschränkung angeben können, muss die API für Ihr Projekt aktiviert sein. Öffnen Sie das API-Dashboard, um eine API zu aktivieren.

Verwenden Sie eine der folgenden Optionen, um API-Einschränkungen hinzuzufügen:

Console

1. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten:

   Zu den Anmeldedaten

2. Klicken Sie auf den Namen des API-Schlüssels, den Sie einschränken möchten.

3. Klicken Sie im Abschnitt API-Einschränkungen auf Schlüssel einschränken.

4. Wählen Sie alle APIs aus, für die Ihr API-Schlüssel verwendet wird.

5. Klicken Sie auf Speichern, um die Änderungen zu speichern und zur API-Schlüsselliste zurückzukehren.

gcloud

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Um die ID abzurufen, listen Sie mit dem Befehl gcloud services api-keys list die Schlüssel in Ihrem Projekt auf.

2. Geben Sie mit dem Befehl gcloud services api-keys update an, für welche Dienste ein API-Schlüssel zur Authentifizierung verwendet werden kann.

   Ersetzen Sie die folgenden Werte:

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   • SERVICE_1, SERVICE_2...: Die Dienstnamen der APIs, auf die der Schlüssel zugreifen kann.

     Sie müssen alle Dienstnamen mit dem Befehl "update" angeben. Ersetzen Sie durch die bereitgestellten Dienstnamen alle vorhandenen Dienste für den Schlüssel.

   Sie finden den Dienstnamen, indem Sie im API-Dashboard nach der API suchen. Dienstnamen sind Strings wie bigquery.googleapis.com.

   gcloud services api-keys update KEY_ID \
   --api-target=service=SERVICE_1 --api-target=service=SERVICE_2

Java

Sie müssen die google-cloud-apikeys-Clientbibliothek installieren, um dieses Beispiel auszuführen.

import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.ApiTarget;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyApi {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyApi(projectId, keyId);
  }

  // Restricts an API key. Restrictions specify which APIs can be called using the API key.
  public static void restrictApiKeyApi(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage by specifying the target service and methods.
      // The API key can only be used to authenticate the specified methods in the service.
      Restrictions restrictions = Restrictions.newBuilder()
          .addApiTargets(ApiTarget.newBuilder()
              .setService("translate.googleapis.com")
              .addMethods("translate.googleapis.com.TranslateText")
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Sie müssen die API-Schlüssel-Clientbibliothek installieren, um dieses Beispiel auszuführen.

from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_api(project_id: str, key_id: str) -> Key:
    """
    Restricts an API key. Restrictions specify which APIs can be called using the API key.

    TODO(Developer): Replace the variables before running the sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Restrict the API key usage by specifying the target service and methods.
    # The API key can only be used to authenticate the specified methods in the service.
    api_target = api_keys_v2.ApiTarget()
    api_target.service = "translate.googleapis.com"
    api_target.methods = ["transate.googleapis.com.TranslateText"]

    # Set the API restriction(s).
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.api_targets = [api_target]

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

1. Rufen Sie die ID des Schlüssels ab, den Sie einschränken möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Sie erhalten die ID, indem Sie die Methode keys.list verwenden. Die ID wird im Feld uid der Antwort aufgeführt.

   Ersetzen Sie PROJECT_ID durch die Google Cloud-Projekt-ID oder den Projektnamen.

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

2. Verwenden Sie die Methode keys.patch, um anzugeben, für welche Dienste ein API-Schlüssel zur Authentifizierung verwendet werden kann.

   Diese Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Sie müssen den Vorgang abfragen, um festzustellen, wann der Vorgang abgeschlossen ist, und den Vorgangsstatus abzurufen.

   Ersetzen Sie die folgenden Werte:

   • SERVICE_1, SERVICE_2...: Die Dienstnamen der APIs, auf die der Schlüssel zugreifen kann.

     Sie müssen alle Dienstnamen mit der Anfrage angeben. Ersetzen Sie durch die bereitgestellten Dienstnamen alle vorhandenen Dienste für den Schlüssel.

     Sie finden den Dienstnamen, indem Sie im API-Dashboard nach der API suchen. Dienstnamen sind Strings wie bigquery.googleapis.com.

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.

   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{
   "restrictions" : {
   "apiTargets": [
     {
       "service": "SERVICE_1"
     },
     {
       "service" : "SERVICE_2"
     },
   ]
   }
   }' \
   "https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Weitere Informationen zum Hinzufügen von API-Einschränkungen zu einem Schlüssel mithilfe der REST API finden Sie unter API-Einschränkungen hinzufügen in der API-Dokumentation zu API Keys.

Projektinformationen aus einem Schlüsselstring abrufen

Sie können anhand des Strings feststellen, welchem Google Cloud-Projekt ein API-Schlüssel zugeordnet ist.

Ersetzen Sie KEY_STRING durch den Schlüsselstring, für den Sie Projektinformationen benötigen.

gcloud

Verwenden Sie den gcloud services api-keys lookup-Befehl, um die Projekt-ID aus einem Schlüsselstring abzurufen.

 gcloud services api-keys lookup KEY_STRING
 

Java

Sie müssen die google-cloud-apikeys-Clientbibliothek installieren, um dieses Beispiel auszuführen.

import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.LookupKeyRequest;
import com.google.api.apikeys.v2.LookupKeyResponse;
import java.io.IOException;

public class LookupApiKey {

  public static void main(String[] args) throws IOException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    //  2. Set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    //  3. Make sure you have the necessary permission to view API keys.
    // API key string to retrieve the API key name.
    String apiKeyString = "API_KEY_STRING";

    lookupApiKey(apiKeyString);
  }

  // Retrieves name (full path) of an API key using the API key string.
  public static void lookupApiKey(String apiKeyString) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Initialize the lookup request and set the API key string.
      LookupKeyRequest lookupKeyRequest = LookupKeyRequest.newBuilder()
          .setKeyString(apiKeyString)
          .build();

      // Make the request and obtain the response.
      LookupKeyResponse response = apiKeysClient.lookupKey(lookupKeyRequest);

      System.out.printf("Successfully retrieved the API key name: %s", response.getName());
    }
  }
}

Python

Sie müssen die API-Schlüssel-Clientbibliothek installieren, um dieses Beispiel auszuführen.

from google.cloud import api_keys_v2


def lookup_api_key(api_key_string: str) -> None:
    """
    Retrieves name (full path) of an API key using the API key string.

    TODO(Developer):
    1. Before running this sample,
      set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    2. Make sure you have the necessary permission to view API keys.

    Args:
        api_key_string: API key string to retrieve the API key name.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Initialize the lookup request and set the API key string.
    lookup_key_request = api_keys_v2.LookupKeyRequest(
        key_string=api_key_string,
        # Optionally, you can also set the etag (version).
        # etag=etag,
    )

    # Make the request and obtain the response.
    lookup_key_response = client.lookup_key(lookup_key_request)

    print(f"Successfully retrieved the API key name: {lookup_key_response.name}")

REST

Verwenden Sie die lookupKey-Methode, um die Projekt-ID aus einem Schlüsselstring abzurufen.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://apikeys.googleapis.com/v2/keys:lookupKey?keyString=KEY_STRING"

API-Schlüssel wiederherstellen

Wenn Sie einen API-Schlüssel versehentlich löschen, können Sie ihn innerhalb von 30 Tagen nach dem Löschen wiederherstellen. Nach 30 Tagen können Sie den API-Schlüssel nicht wiederherstellen.

Console

1. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten:

   Zu den Anmeldedaten

2. Klicken Sie auf Gelöschte Anmeldedaten wiederherstellen.

3. Suchen Sie den gelöschten API-Schlüssel, den Sie wiederherstellen möchten, und klicken Sie auf Wiederherstellen.

   Es kann einige Minuten dauern, bis das Wiederherstellen eines API-Schlüssels wirksam wird. Nach der Weitergabe wird der wiederhergestellte API-Schlüssel in der Liste der API-Schlüssel angezeigt.

gcloud

1. Rufen Sie die ID des Schlüssels ab, den Sie wiederherstellen möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Um die ID abzurufen, listen Sie mit dem Befehl gcloud services api-keys list --show-deleted die gelöschten Schlüssel in Ihrem Projekt auf.

2. Verwenden Sie den gcloud services api-keys undelete-Befehl, um einen API-Schlüssel wiederherzustellen.

   gcloud services api-keys undelete KEY_ID

   Ersetzen Sie die folgenden Werte:

   • KEY_ID: Die ID des Schlüssels, den Sie wiederherstellen möchten.

REST

1. Rufen Sie die ID des Schlüssels ab, den Sie wiederherstellen möchten.

   Die ID ist nicht mit dem Anzeigenamen oder dem Schlüsselstring identisch. Sie erhalten die ID, indem Sie die Methode keys.list verwenden, wobei der Abfrageparameter showDeleted auf true gesetzt ist. Die Schlüssel-ID wird im Feld uid der Antwort aufgeführt.

   Ersetzen Sie PROJECT_ID durch die Google Cloud-Projekt-ID oder den Projektnamen.

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

2. Verwenden Sie die Methode wiederherstellen, um den API-Schlüssel wiederherzustellen.

   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_ID/locations/global/keys/KEY_ID:undelete"

   Diese Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Sie müssen den Vorgang abfragen, um festzustellen, wann der Vorgang abgeschlossen ist, und den Vorgangsstatus abzurufen.

   Ersetzen Sie die folgenden Werte:

   • PROJECT_ID: Ihre Google Cloud-Projekt-ID oder Ihr Name.
   • KEY_ID: Die ID des Schlüssels, den Sie einschränken möchten.

Vorgänge mit langer Ausführungszeit abfragen

API-Methoden für API Keys verwenden Vorgänge mit langer Ausführungszeit. Wenn Sie die REST API zum Erstellen und Verwalten von API-Schlüsseln verwenden, wird von der ersten Methodenanfrage ein Vorgangsobjekt zurückgegeben. Sie verwenden den Vorgangsnamen, um den Vorgang mit langer Ausführungszeit abzufragen. Wenn die Anfrage mit langer Ausführungszeit abgeschlossen ist, werden durch die Abfrage die Daten der Anfrage mit langer Ausführungszeit zurückgegeben.

Zum Abfragen eines lange laufenden API Keys-API-Vorgangs verwenden Sie die Methode operations.get.

Ersetzen Sie OPERATION_NAME durch den Vorgangsnamen, der vom lang andauernden Vorgang zurückgegeben wird. Beispiel: operations/akmf.p7-358517206116-cd10a88a-7740-4403-a8fd-979f3bd7fe1c

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    "https://apikeys.googleapis.com/v2/OPERATION_NAME"

Limits für API-Schlüssel

Sie können bis zu 300 API-Schlüssel pro Projekt erstellen. Dies ist ein Systemlimit; es kann nicht mithilfe einer Anfrage zur Kontingenterhöhung geändert werden.

Wenn mehr API-Schlüssel erforderlich sind, müssen Sie mehrere Projekte verwenden.

Nächste Schritte

• Best Practices für die Sicherheit Ihrer API-Schlüssel
• Weitere Informationen zur API Keys API

Feedback geben