Diese Seite wurde von der Cloud Translation API übersetzt.

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

OpenAPI | gRPC

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 mit einem API-Schlüssel beschränken und wie Sie einen API-Schlüssel erstellen.

Der Extensible Service Proxy (ESP) verwendet Service Control API, um einen API-Schlüssel und seine Verknüpfung mit der aktivierten API eines Projekts zu prüfen. Wenn Sie eine API-Schlüsselanforderung in Ihrer API 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 gewährt wurde. Das Projekt, in dem der API-Schlüssel erstellt wurde, wird nicht protokolliert und nicht in den Anfrage-Header eingefügt. Sie können jedoch das Google Cloud-Projekt, mit dem ein Client verknüpft ist, auf der Seite Endpoints > Dienste aufrufen. Eine Beschreibung 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

So fordern Sie einen API-Schlüssel für den Zugriff auf alle Methoden einer API an:

Öffnen Sie die openapi.yaml-Datei Ihres Projekts in einem Texteditor.
Fügen Sie unter securityDefinitions: die api_key:-Werte apiKey, key, query hinzu, wie im Beispielcode-Snippet zu sehen:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Dadurch wird ein "Sicherheitsschema" namens api_key festgelegt, das Sie zum Schutz der API verwenden können. Weitere api_key-Definitionsoptionen finden Sie unter Einschränkungen der API-Schlüsseldefinition.
Fügen Sie auf oberster Ebene der Datei (nicht eingerückt oder verschachtelt) api_key: [] in die Anweisung security ein. Sie müssen die Anweisung security einfügen, falls sie nicht bereits vorhanden ist:
```
  security:
    - api_key: []
```
Mit dieser Anweisung wird das Sicherheitsschema api_key auf alle Methoden in der Datei angewendet. Fügen Sie nichts in die Klammern ein. Die OpenAPI-Spezifikation erfordert eine leere Liste für Sicherheitsschemas, die OAuth nicht verwenden.

Zugriff auf bestimmte API-Methoden einschränken

So fordern Sie einen API-Schlüssel für eine bestimmte Methode an:

Öffnen Sie die openapi.yaml-Datei Ihres Projekts in einem Texteditor.
Fügen Sie eine leere security-Anweisung auf oberster Ebene der Datei ein (nicht eingerückt oder verschachtelt), um sie auf die gesamte API anzuwenden:
```
security: []
```
Fügen Sie unter securityDefinitions: die api_key:-Werte apiKey, key, query hinzu, wie im Beispielcode-Snippet zu sehen:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Dadurch wird ein "Sicherheitsschema" namens api_key festgelegt, das Sie zum Schutz der API verwenden können. Weitere api_key-Definitionsoptionen finden Sie unter Einschränkungen der API-Schlüsseldefinition.
Fügen Sie api_key: [] in die Anweisung security in der Methodendefinition ein:
```
...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security:
  - api_key: []
  produces:
  ...
```
Durch diese Anweisung wird das Sicherheitsschema api_key auf die Methode angewendet. Fügen Sie nichts in die Klammern ein. Die OpenAPI-Spezifikation erfordert eine leere Liste für Sicherheitsschemas, die OAuth nicht verwenden.

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

So deaktivieren Sie die API-Schlüsselvalidierung für eine bestimmte Methode trotz eingeschränktem Zugriff auf die API:

Öffnen Sie die openapi.yaml-Datei Ihres Projekts in einem Texteditor.

Fügen Sie eine leere security-Anweisung in die Methodendefinition ein:

...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security: []
  produces:
  ...

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 im nachfolgenden cURL-Beispiel an:

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

Dabei sind ENDPOINTS_HOST und ENDPOINTS_KEY Umgebungsvariablen, die Ihren API-Hostnamen bzw. API-Schlüssel enthalten.

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.

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:

Erteilen Sie jedem Nutzer im Google Cloud-Projekt, in dem die API konfiguriert ist, die Berechtigung zum Aktivieren Ihrer API.
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:

Erstellen Sie ein separates Projekt für jeden Aufrufer.
Aktivieren Sie die API in jedem Projekt und erstellen Sie einen API-Schlüssel.
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:

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

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.
Geben Sie jedem Aufrufer denselben API-Schlüssel.

Best Practices

Wenn Sie API-Schlüssel verwenden, um den Zugriff auf Ihre API- und Nutzerdaten zu schützen, setzen Sie das Flag --service_control_network_fail_open beim Konfigurieren des Starts von Extensible Service Proxy V2 (ESPv2) auf close. Der Standardwert für das Flag ist open..

ESPv2 ruft Service Control auf, um API-Schlüssel zu verifizieren. Wenn beim Herstellen einer Verbindung zu Service Control und ESPv2 Netzwerkfehler auftreten, kann der API-Schlüssel nicht verifiziert werden. Dadurch wird sichergestellt, dass alle potenziellen Anfragen an Ihre API mit betrügerischen Schlüsseln abgelehnt werden.