Mit API-Schlüsseln authentifizieren

Auf dieser Seite wird beschrieben, wie Sie sich mit API-Schlüsseln bei Google Cloud APIs und Diensten authentifizieren, die API-Schlüssel unterstützen.

Die meisten Google Cloud APIs unterstützen keine API-Schlüssel. Prüfen Sie, ob API-Schlüssel von der gewünschten API unterstützt werden, bevor Sie diese Authentifizierungsmethode verwenden.

Informationen zur Verwendung von API-Schlüsseln zur Authentifizierung bei der Google Maps Platform finden Sie in der Google Maps Platform-Dokumentation. Weitere Informationen zur API Keys API finden Sie in der API Keys-Dokumentation.

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 und stellt keine Autorisierungsinformationen bereit. Daher wird in der Anfrage nicht die Identitäts- und Zugriffsverwaltung (IAM) verwendet, um zu prüfen, ob der Aufrufer die Berechtigung hat, den angeforderten Vorgang auszuführen.

Der API-Schlüssel verknüpft die Anfrage mit dem Google Cloud-Projekt zu Abrechnungs- und Kontingentzwecken. Da API-Schlüssel den Aufrufer nicht identifizieren, werden sie häufig für den Zugriff auf öffentliche Daten oder Ressourcen verwendet.

Viele Google Cloud APIs akzeptieren keine API-Schlüssel für die Authentifizierung. Lesen Sie die Authentifizierungsdokumentation für den Dienst oder die API, die Sie verwenden möchten, um festzustellen, ob sie API-Schlüssel unterstützt.

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.

Zum Verwalten von API-Schlüsseln benötigen Sie die Rolle "API-Schlüssel-Administrator" (roles/serviceusage.apiKeysAdmin) für das Projekt.

Hinweis

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

You can use the gcloud CLI samples on this page from either of the following development environments:

  • Cloud Shell: To use an online terminal with the gcloud CLI already set up, activate Cloud Shell.

    At the bottom of this page, a Cloud Shell session starts and displays a command-line prompt. It can take a few seconds for the session to initialize.

  • Local shell: To use the gcloud CLI in a local development environment, install and initialize the gcloud CLI.

Java

To use the Java samples on this page from a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Installieren Sie die Google Cloud CLI.

  2. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init

  3. Erstellen Sie lokale Anmeldedaten zur Authentifizierung für Ihr Google-Konto: 

    gcloud auth application-default login

For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.

Python

To use the Python samples on this page from a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Installieren Sie die Google Cloud CLI.

  2. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init

  3. Erstellen Sie lokale Anmeldedaten zur Authentifizierung für Ihr Google-Konto: 

    gcloud auth application-default login

For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.

REST

To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  1. Installieren Sie die Google Cloud CLI.

  2. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init

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 beta 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 beta services api-keys create --display-name=DISPLAY_NAME

Java

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

auth/src/main/java/CreateApiKey.java 

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üsselclientbibliothek installieren, um dieses Beispiel auszuführen.

auth/api-client/create_api_key.py 

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. Wenn Sie keinen Testschlüssel verwenden, den Sie später wieder löschen, fügen Sie Einschränkungen für API-Schlüssel hinzu.

API-Schlüssel verwenden

Wenn eine API die Verwendung von API-Schlüsseln unterstützt, können Sie die API mit API-Schlüsseln authentifizieren. Sie verwenden API-Schlüssel mit REST-Anfragen und Clientbibliotheken, die diese unterstützen.

API-Schlüssel mit REST verwenden

Sie können den API-Schlüssel als Abfrageparameter in einem REST API-Aufruf mit dem folgenden Format übergeben. Ersetzen Sie API_KEY durch den Schlüsselstring Ihres API-Schlüssels.

So übergeben Sie beispielsweise einen API-Schlüssel für eine Cloud Natural Language API-Anfrage für documents.analyzeEntities:

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

Alternativ können Sie den Header x-goog-api-key verwenden, um Ihren Schlüssel zu übergeben. Dieser Header muss mit gRPC-Anfragen verwendet werden.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "X-goog-api-key: API_KEY" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

API-Schlüssel mit Clientbibliotheken verwenden

Die Clientbibliotheksunterstützung für API-Schlüssel ist sprachspezifisch.

Python

In diesem Beispiel wird die Cloud Natural Language API verwendet, die API-Schlüssel für die Authentifizierung unterstützt, um zu zeigen, wie Sie einen API-Schlüssel für die Bibliothek bereitstellen.

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

auth/api-client/authenticate_with_api_key.py 

from google.cloud import language_v1

def authenticate_with_api_key(quota_project_id: str, api_key_string: str) -> None:
    """
    Authenticates with an API key for Google Language service.

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

    Args:
        quota_project_id: Google Cloud project id that should be used for quota and billing purposes.
        api_key_string: The API key to authenticate to the service.
    """

    # Initialize the Language Service client and set the API key and the quota project id.
    client = language_v1.LanguageServiceClient(
        client_options={"api_key": api_key_string, "quota_project_id": quota_project_id}
    )

    text = "Hello, world!"
    document = language_v1.Document(
        content=text, type_=language_v1.Document.Type.PLAIN_TEXT
    )

    # Make a request to analyze the sentiment of the text.
    sentiment = client.analyze_sentiment(
        request={"document": document}
    ).document_sentiment

    print(f"Text: {text}")
    print(f"Sentiment: {sentiment.score}, {sentiment.magnitude}")
    print("Successfully authenticated using the API key")

API-Schlüssel sichern

Wenn Sie API-Schlüssel in Ihren Anwendungen verwenden, achten Sie darauf, dass sie sowohl beim Speichern als auch bei der Übertragung sicher sind. Wenn Sie Ihre API-Schlüssel öffentlich freigeben, kann dies zu unerwarteten Kosten in Ihrem Konto führen. Sie sollten diese Best Practices befolgen, um die Sicherheit Ihrer API-Schlüssel zu wahren:

  • Fügen Sie Ihrem Schlüssel API-Schlüsseleinschränkungen hinzu.

    Durch Hinzufügen von Einschränkungen können Sie die Verwendung eines API-Schlüssels einschränken und so die Auswirkungen eines manipulierten API-Schlüssels reduzieren.

  • Löschen Sie nicht benötigte API-Schlüssel, um das Angriffsrisiko zu minimieren.

  • Erstellen Sie Ihre API-Schlüssel regelmäßig neu.

    Sie sollten regelmäßig neue API-Schlüssel erstellen, die alten Schlüssel löschen und Ihre Anwendungen zur Verwendung der neuen API-Schlüssel aktualisieren.

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. *.google.com ist beispielsweise gültig und akzeptiert alle Websites, die auf .google.com enden. mysubdomain*.google.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 Verweis-URL, die nur die Ursprungs-URL für Cross-Origin-Anfragen 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.
  1. URL für die Domain ohne Subdomain und mit einem Platzhalter für den Pfad. Beispiel:
    example.com/*
  2. 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:

  1. URL für die Domain ohne abschließenden Schrägstrich. Beispiel:
    www.example.com
    sub.example.com
    example.com
  2. 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 beta 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 beta 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.

auth/src/main/java/RestrictApiKeyHttp.java 

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üsselclientbibliothek installieren, um dieses Beispiel auszuführen.

auth/api-client/restrict_api_key_http.py 

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 IP-Adressen aus.

  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 beta 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 beta 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.

auth/src/main/java/RestrictApiKeyServer.java 

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üsselclientbibliothek installieren, um dieses Beispiel auszuführen.

auth/api-client/restrict_api_key_server.py 

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_name
  • x-android_cert_fingerprint

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 beta 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 beta 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.

auth/src/main/java/RestrictApiKeyAndroid.java 

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üsselclientbibliothek installieren, um dieses Beispiel auszuführen.

auth/api-client/restrict_api_key_android.py 

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.

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-Apps 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 beta 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 beta 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.

auth/src/main/java/RestrictApiKeyIos.java 

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üsselclientbibliothek installieren, um dieses Beispiel auszuführen.

auth/api-client/restrict_api_key_ios.py 

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.

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 beta 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 beta 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.

auth/src/main/java/RestrictApiKeyApi.java 

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üsselclientbibliothek installieren, um dieses Beispiel auszuführen.

auth/api-client/restrict_api_key_api.py 

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 Befehl gcloud beta services api-keys lookup, um die Projekt-ID aus einem Schlüsselstring abzurufen.

 gcloud beta services api-keys lookup KEY_STRING

Java

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

auth/src/main/java/LookupApiKey.java 

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üsselclientbibliothek installieren, um dieses Beispiel auszuführen.

auth/api-client/lookup_api_key.py 

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.

    Das Wiederherstellen eines API-Schlüssels kann einige Minuten dauern. 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 Befehl gcloud beta services api-keys undelete, um einen API-Schlüssel wiederherzustellen.

    gcloud beta 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 und den Abfrageparameter showDeleted auf true setzen. 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