API-Konfiguration erstellen

Auf dieser Seite wird beschrieben, wie Sie eine API-Konfiguration erstellen, die in API Gateway bereitgestellt werden soll.

Hinweis

Bevor Sie eine API-Konfiguration erstellen, müssen Sie Folgendes tun:

• Bereiten Sie die Entwicklungsumgebung wie unter Entwicklungsumgebung konfigurieren beschrieben vor.

• Erstellen Sie eine API-Definition als OpenAPI-Spezifikation.

• Wenn Sie die Google Cloud CLI verwenden, können Sie optional eine API erstellen. Wenn die API nicht vorhanden ist, wird sie beim Erstellen der API-Konfiguration erstellt.

  Hinweis: Wenn Sie die Google Cloud -Konsole verwenden, werden die API und die API-Konfiguration beim Bereitstellen der API in einem Gateway erstellt.

Anforderungen an die API-Konfigurations-ID

Bei vielen der unten aufgeführten gcloud CLI-Befehle müssen Sie die ID der API-Konfiguration im folgenden Format angeben: CONFIG_ID. In API Gateway gelten folgende Anforderungen für die API-Konfigurations-ID:

• Muss eine maximale Länge von 63 Zeichen haben.
• Darf nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten.
• Er darf nicht mit einem Bindestrich beginnen.
• Er darf keinen Unterstrich enthalten.

API-Konfiguration erstellen

Erstellen Sie eine API-Konfiguration, indem Sie Ihre API-Definition hochladen.

Hinweis :API Gateway unterstützt die Erstellung von API-Definitionen als OpenAPI-Spezifikationen für alle verfügbaren Backend-Dienste. API Gateway unterstützt auch die Verwendung von gRPC-Dienstdefinitionen und -Konfigurationen für gRPC-Dienste in Cloud Run.

Wenn managedService in Ihrer API-Definition auf einen ESPv2 Beta-Dienst festgelegt ist, muss das Feld host (OpenAPI 2.0) oder server.url (OpenAPI 3.x) in Ihrer API-Konfiguration auf eine x-google-endpoint-Erweiterung festgelegt sein.

So erstellen Sie eine API-Konfiguration:

Google Cloud Console

Sie erstellen eine API-Konfiguration, wenn Sie eine API für ein Gateway bereitstellen.

Google Cloud CLI

Laden Sie die API-Definition hoch, um eine API-Konfiguration zu erstellen. Wenn Sie die API-Definition hochladen, müssen Sie den Namen der API angeben. Wenn die API noch nicht in API Gateway vorhanden ist, wird sie mit diesem Befehl ebenfalls erstellt.

Hinweis: Wenn Sie OpenAPI 3.x verwenden möchten, müssen Sie die gcloud CLI-Komponenten aktualisieren, bevor Sie eine API-Konfiguration erstellen, um Fehler beim Hochladen Ihrer API-Definition zu vermeiden.

1. Wechseln Sie in das Verzeichnis, das Ihre API-Definition enthält.

   Weitere Informationen zum Erstellen der OpenAPI-Spezifikation für Ihre API-Definition finden Sie unter OpenAPI-Übersicht und Kurzanleitung: Traffic zu einem Dienst mit der gcloud CLI sichern.

   Weitere Informationen zum Erstellen einer gRPC-Dienstdefinition und -Konfiguration für Ihre API-Definition finden Sie unter gRPC-Dienst konfigurieren und Erste Schritte mit API Gateway und Cloud Run für gRPC.

2. Überprüfen Sie anhand der Projekt-ID, die vom folgenden Befehl zurückgegeben wurde, ob der Dienst im richtigen Projekt erstellt wird.

   gcloud config list project

   Wenn Sie das Standardprojekt ändern müssen, führen Sie den folgenden Befehl aus und ersetzen Sie PROJECT_ID durch die Google Cloud Projekt-ID, in der Sie den Dienst erstellen möchten:

   gcloud config set project PROJECT_ID

3. Hier erhalten Sie Hilfe zum Befehl api-configs create:

   gcloud api-gateway api-configs create --help

4. Führen Sie den folgenden Befehl aus, um die API-Konfiguration zu erstellen:

   gcloud api-gateway api-configs create CONFIG_ID \
         --api=API_ID --openapi-spec=API_DEFINITION \
         --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   wobei

   • CONFIG_ID die ID der neuen API-Konfiguration angibt.
   • API_ID die ID der API Gateway API angibt, die mit dieser API-Konfiguration verknüpft ist. Wenn die API nicht bereits vorhanden ist, wird sie von diesem Befehl erstellt.
   • API_DEFINITION den Namen der OpenAPI-Spezifikation angibt, die die API-Definition enthält.
   • SERVICE_ACCOUNT_EMAIL gibt das Dienstkonto an, das zum Signieren von Tokens für Back-Ends mit konfigurierter Authentifizierung verwendet wird. Weitere Informationen finden Sie unter Dienstkonto konfigurieren, das zum Erstellen von API-Konfigurationen verwendet wird.

   Beim Erstellen der API und der API-Konfiguration gibt API Gateway Informationen an das Terminal aus. Dieser Vorgang kann einige Minuten dauern, da die API-Konfiguration an nachgelagerte Systeme weitergegeben wird. Das Erstellen einer komplexen API-Konfiguration kann bis zu zehn Minuten dauern. Versuchen Sie während der Erstellung einer Konfiguration nicht, eine weitere Konfiguration für dieselbe API zu erstellen. Pro API kann jeweils nur eine Konfiguration erstellt werden.

5. Nach erfolgreichem Abschluss können Sie den folgenden Befehl verwenden, um Details zur neuen API-Konfiguration anzuzeigen:

   gcloud api-gateway api-configs describe CONFIG_ID \
         --api=API_ID

   Dieser Befehl gibt Folgendes zurück:

   createTime: '2020-02-04T18:33:11.882707149Z'
   displayName: CONFIG_ID
   gatewayConfig:
         backendConfig:
           googleServiceAccount: [e-mail]
   labels: ''
   name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
   serviceRollout:
         rolloutId: 2020-02-04r2
   state: ACTIVE
   updateTime: '2020-02-04T18:33:12.219323647Z'

6. Aktivieren Sie die API mit dem Namen des verwalteten Dienstes der API. Sie finden diesen Wert in der Spalte "Verwalteter Dienst" für Ihre API auf der Landingpage der APIs:

   gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

   Sie müssen diesen Befehl nur einmal ausführen, wenn Sie die API erstellen. Wenn Sie die API später ändern, müssen Sie den Befehl nicht noch einmal ausführen.

Die gcloud CLI hat viele Optionen, einschließlich der in der Referenz zur Google Cloud CLI beschriebenen. Darüber hinaus können Sie für API Gateway beim Erstellen einer API-Konfiguration die folgenden Optionen festlegen:

• --async: Gibt die Steuerung sofort an das Terminal zurück, ohne auf den Abschluss des Vorgangs zu warten.
• --display-name=NAME: Gibt den Anzeigenamen der API-Konfiguration an, d. h. den in der Benutzeroberfläche Anzeigenamen. Verwenden Sie keine Leerzeichen im Namen. Verwenden Sie stattdessen Bindestriche und Unterstriche. Der Standardwert ist CONFIG_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,...: Gibt Labels an, die der API-Konfiguration zugeordnet sind.

Beispiel:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

Sie können die Labels in der Ausgabe des gezeigten Befehls describe sehen oder im Befehl list, wenn Sie die Option --format angeben:

gcloud api-gateway api-configs list \
  --api=API_ID --format="table(name, labels)"

API-Konfigurationen auflisten

Alle API-Gateways auflisten, die in Ihrem Google Cloud -Projekt bereitgestellt wurden.

Google Cloud Console

So listen Sie API-Konfigurationen für eine bestimmte API in einem Projekt auf:

1. Rufen Sie in der Google Cloud Console die Seite API Gateway auf.

   Zu API Gateway

2. Klicken Sie auf die erforderliche API.
3. Klicken Sie auf den Tab Konfigurationen.

Auf der Seite wird die Liste der verfügbaren API-Konfigurationen angezeigt.

Google Cloud CLI

So listen Sie API-Konfigurationen für ein bestimmtes Projekt auf:

gcloud api-gateway api-configs list 

Dieser Befehl gibt Folgendes zurück:

NAME                                                                                                 DISPLAY_NAME             ROLLOUT_ID    STATE     CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

So listen Sie API-Konfigurationen für eine bestimmte API in einem Projekt auf:

gcloud api-gateway api-configs list --api=API_ID 

Verwenden Sie die API- und Konfigurations-IDs, um detaillierte Informationen zur API-Konfiguration zu erhalten:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID 

API-Konfiguration aktualisieren

Sie können eine vorhandene API-Konfiguration nur ändern, um ihre Labels und ihren Anzeigenamen zu aktualisieren.

Hinweis: Jedes Mal, wenn Sie eine API-Definition hochladen, erstellt API Gateway eine neue API-Konfiguration.

So aktualisieren Sie eine API-Definition:

1. Aktualisieren Sie die OpenAPI-Spezifikation, die die API-Definition enthält.
2. Laden Sie die API-Definition hoch, um eine neue API-Konfiguration zu erstellen.

Verwenden Sie zum Erstellen der neuen API-Konfiguration denselben Befehl, den Sie zum Erstellen der ursprünglichen API-Konfiguration verwendet haben, wie unter API-Konfiguration erstellen gezeigt.

Google Cloud Console

1. Rufen Sie in der Google Cloud Console die Seite API Gateway auf.

   Zu API Gateway

2. Klicken Sie auf die erforderliche API.
3. Klicken Sie auf den Tab Konfigurationen.
4. Klicken Sie auf die gewünschte API-Konfiguration.
5. Klicken Sie auf Bearbeiten Bearbeiten.
6. Bearbeiten Sie den Anzeigenamen oder die Labels.
7. Klicken Sie auf Speichern.

Google Cloud CLI

Verwenden Sie den folgenden `gcloud`-Befehl, um eine vorhandene API-Konfiguration zu aktualisieren:

• --display-name
• --update-labels
• --clear-labels
• --remove-labels

Beispiel:

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID \
  --update-labels=a=1,b=2

Verwenden Sie den folgenden Befehl, um alle Aktualisierungsoptionen aufzurufen:

gcloud api-gateway api-configs update --help

API-Konfiguration löschen

Warnung: Wenn Sie die API-Konfiguration in einem Gateway bereitgestellt haben, wird die API-Konfiguration möglicherweise erst gelöscht, wenn das Gateway diese API-Konfiguration nicht mehr verwendet.

Bevor Sie eine verwendete API-Konfiguration löschen, müssen Sie entweder:

• Eine andere API-Konfiguration für das Gateway bereitstellen.
• Das Gateway löschen.

Weitere Informationen finden Sie unter API auf einem Gateway bereitstellen.

Google Cloud Console

1. Rufen Sie in der Google Cloud Console die Seite API Gateway auf.

   Zu API Gateway

2. Klicken Sie auf die erforderliche API.
3. Klicken Sie auf den Tab Konfigurationen.
4. Klicken Sie auf das Dreipunkt-Menü und dann auf Löschen, um die ausgewählte API-Konfiguration zu löschen.

Google Cloud CLI

Verwenden Sie den folgenden gcloud CLI-Befehl, um eine vorhandene API-Konfiguration zu löschen:

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

Nächste Schritte

• API auf einem Gateway bereitstellen