API-Zugriff mit API-Schlüsseln einschränken

Mit API-Schlüsseln können Sie den Zugriff auf bestimmte API-Methoden oder auf alle Methoden in einer API beschränken. Auf dieser Seite wird beschrieben, wie Sie den API-Zugriff auf die Clients beschränken, die einen API-Schlüssel haben, und wie Sie einen API-Schlüssel erstellen.

Wenn Sie in Ihrer API eine API-Schlüsselanforderung festlegen, werden Anfragen an die geschützte Methode, Klasse oder API abgelehnt, es sei denn, sie haben einen Schlüssel, der in Ihrem Projekt oder in anderen Projekten von Entwicklern generiert wurde, denen Zugriff zum Aktivieren Ihrer API erteilt wurde. Das Projekt, in dem der API-Schlüssel erstellt wurde, wird nicht protokolliert und nicht in den Anfrageheader eingefügt. Sie können jedoch das Google Cloud-Projekt, mit dem ein Client verknüpft ist, auf der Seite Endpoints > Dienste aufrufen. Weitere Informationen hierzu finden Sie unter Nach einem bestimmten Nutzerprojekt filtern.

Informationen darüber, in welchem Google Cloud-Projekt ein API-Schlüssel erstellt werden sollte, finden Sie unter Durch einen API-Schlüssel geschützte APIs freigeben.

Zugriff auf alle API-Methoden einschränken

Wenn Sie einen API-Schlüssel zur Voraussetzung für alle Aufrufe der API machen möchten, fügen Sie apiKeyRequired = AnnotationBoolean.TRUE in die @Api-Annotation ein. Beispiel:

@Api(
  name = "echo",
  version = "v1",
  apiKeyRequired = AnnotationBoolean.TRUE
  )
public class Echo {
//API class and methods...
}

Zugriff auf bestimmte API-Methoden einschränken

Wenn Sie einen API-Schlüssel für alle Aufrufe einer bestimmten API-Methode voraussetzen möchten, fügen Sie apiKeyRequired = AnnotationBoolean.TRUE in die @ApiMethod-Annotation ein. Beispiel:

@ApiMethod(name = "echo_api_key", path = "echo_api_key", apiKeyRequired = AnnotationBoolean.TRUE)
public Message echoApiKey(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}

Wenn Sie einen API-Schlüssel für alle Aufrufe einer bestimmten API-Klasse zur Voraussetzung machen möchten, fügen Sie apiKeyRequired = AnnotationBoolean.TRUE in die @ApiClass-Annotation ein.

API-Schlüsseleinschränkung für eine Methode entfernen

Wenn Sie die API-Schlüsselvalidierung für eine API oder API-Methode deaktivieren möchten, entfernen Sie api_key_required=True (Python) oder apiKeyRequired = AnnotationBoolean.TRUE (Java) aus der API, dem Methoden-Decorator oder der Annotation. Kompilieren Sie die API anschließend neu und stellen Sie sie erneut bereit.

API mithilfe eines API-Schlüssels aufrufen

Wenn eine API oder eine API-Methode einen API-Schlüssel voraussetzt, geben Sie den Schlüssel mithilfe des Abfrageparameters key wie in diesem cURL-Beispiel an:

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"message": "echo"}' \
    "${HOST}/_ah/api/echo/v1/echo_api_key?key=${API_KEY}"

Dabei sind HOST und API_KEY Variablen mit dem Namen des API-Hosts bzw. dem API-Schlüssel. Ersetzen Sie echo durch den Namen Ihrer API und v1 durch die Version der API.

Durch einen API-Schlüssel geschützte APIs freigeben

API-Schlüssel sind dem Google Cloud-Projekt zugeordnet, in dem sie erstellt wurden. Wenn Sie für Ihre API das Anfordern eines API-Schlüssels festgelegt haben, hängt das Google Cloud-Projekt, in dem der API-Schlüssel erstellt wird, von den Antworten auf die folgenden Fragen ab:

  • Müssen Sie zwischen den Aufrufern Ihrer API unterscheiden, damit Sie Endpoints-Features wie Kontingente verwenden können?
  • Haben alle Aufrufer Ihrer API eigene Google Cloud-Projekte?
  • Müssen Sie verschiedene API-Schlüsseleinschränkungen einrichten?

Sie können sich am folgenden Entscheidungsbaum orientieren, um festzulegen, in welchem Google Cloud-Projekt der API-Schlüssel erstellt werden soll.

API-Schlüssel-Entscheidungsbaum

Berechtigung zum Aktivieren der API gewähren

Wenn Sie zwischen den Aufrufern Ihrer API unterscheiden müssen und jeder Aufrufer über ein eigenes Google Cloud-Projekt verfügt, können Sie Hauptkonten die Berechtigung erteilen, die API in ihren eigenen Google Cloud-Projekten zu aktivieren. Dadurch können Nutzer einen eigenen API-Schlüssel für die Verwendung mit Ihrer API erstellen.

Nehmen Sie als Beispiel ein Team, das eine API zur internen Verwendung durch verschiedene Clientprogramme in einem Unternehmen erstellt hat. Dabei gibt es für jedes Clientprogramm ein eigenes Google Cloud-Projekt. Zur Unterscheidung zwischen den Aufrufern der API muss der API-Schlüssel dann für jeden Aufrufer in einem anderen Google Cloud-Projekt erstellt werden. Den Mitarbeitern kann die Berechtigung zum Aktivieren der API in dem Google Cloud-Projekt, mit dem das Clientprogramm verknüpft ist, erteilt werden.

So ermöglichen Sie Nutzern, einen eigenen API-Schlüssel zu erstellen:

  1. Erteilen Sie jedem Nutzer im Google Cloud-Projekt, in dem die API konfiguriert ist, die Berechtigung zum Aktivieren Ihrer API.
  2. Teilen Sie den Nutzern mit, dass sie Ihre API im eigenen Google Cloud-Projekt aktivieren und einen API-Schlüssel erstellen können.

Separates Google Cloud-Projekt für jeden Aufrufer erstellen

Wenn Sie zwischen Aufrufern Ihrer API unterscheiden müssen und nicht alle Aufrufer über ein Google Cloud-Projekt verfügen, können Sie für jeden Aufrufer ein separates Google Cloud-Projekt und einen separaten API-Schlüssel erstellen. Überlegen Sie sich sinnvolle Projektnamen, bevor Sie die Projekte erstellen, damit Sie den Aufrufer, der mit dem jeweiligen Projekt verknüpft ist, einfach identifizieren können.

Beispiel: Ihre API wird von externen Kunden aufgerufen und Sie wissen nicht, wie die Clientprogramme, die Ihre API aufrufen, erstellt wurden. Einige Clients verwenden vielleicht Google Cloud-Dienste und haben ein Google Cloud-Projekt, andere aber nicht. Um zwischen den Aufrufern zu unterscheiden, müssen Sie für jeden Aufrufer ein separates Google Cloud-Projekt und einen separaten API-Schlüssel erstellen.

So erstellen Sie ein separates Google Cloud-Projekt und einen API-Schlüssel für jeden Aufrufer:

  1. Erstellen Sie ein separates Projekt für jeden Aufrufer.
  2. Aktivieren Sie die API in jedem Projekt und erstellen Sie einen API-Schlüssel.
  3. Geben Sie jedem Aufrufer den jeweiligen API-Schlüssel.

API-Schlüssel für jeden Aufrufer erstellen

Wenn Sie nicht zwischen Aufrufern Ihrer API unterscheiden müssen, aber Einschränkungen für API-Schlüssel einführen möchten, können Sie für jeden Aufrufer in demselben Projekt einen separaten API-Schlüssel erstellen.

So erstellen Sie einen API-Schlüssel für jeden Aufrufer im selben Projekt:

  1. Erstellen Sie in dem Projekt, in dem die API konfiguriert ist, oder in einem Projekt, in dem die API aktiviert ist, für jeden Kunden einen API-Schlüssel mit den gewünschten API-Schlüsseleinschränkungen.
  2. Geben Sie jedem Aufrufer den jeweiligen API-Schlüssel.

Einen einzigen API-Schlüssel für alle Aufrufer erstellen

Wenn Sie nicht zwischen den Aufrufern Ihrer API unterscheiden und keine API-Einschränkungen hinzufügen müssen, aber trotzdem einen API-Schlüssel voraussetzen möchten (um beispielsweise den anonymen Zugriff zu verhindern), können Sie einen API-Schlüssel erstellen, der von allen Aufrufern verwendet wird.

So erstellen Sie einen einzigen API-Schlüssel für alle Aufrufer:
  1. Erstellen Sie entweder in dem Projekt, in dem die API konfiguriert ist, oder in einem Projekt, in dem die API aktiviert ist, einen API-Schlüssel für alle Aufrufer.
  2. Geben Sie jedem Aufrufer denselben API-Schlüssel.

Weitere Informationen