API-Konfiguration erstellen

Vorbereitung

Bevor Sie eine API-Konfiguration erstellen, müssen folgende Voraussetzungen erfüllt sein:

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

• API-Definition als OpenAPI-Spezifikation erstellt

• Optional können Sie eine API erstellen, wie unter API erstellen beschrieben. Wenn die API noch nicht vorhanden ist, wird sie beim Erstellen der API-Konfiguration erstellt.

Anforderungen an die API-Konfigurations-ID

Bei vielen der unten aufgeführten gcloud-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

Verwenden Sie die Google Cloud CLI, um Ihre API-Definition hochzuladen und 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.

Note: API Gateway supports creation of API definitions as OpenAPI specs for all available backend services. API Gateway unterstützt auch die Verwendung von gRPC-Dienstdefinitionen und -Konfigurationen für gRPC-Dienste in Cloud Run.

So erstellen Sie eine API-Konfiguration:

1. Geben Sie das Verzeichnis an, 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: API auf API Gateway bereitstellen.

   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 ID des Google Cloud-Projekts, in dem 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

   Dabei gilt:

   • 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.
   • PROJECT_ID die Google Cloud-Projekt-ID angibt.
   • 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.

   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 --project=PROJECT_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 Google Cloud CLI bietet viele Optionen, einschließlich der in der gcloud-Referenz beschriebenen Optionen. 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 \
  --project=PROJECT_ID --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 oben gezeigten Befehls describe sehen oder im Befehl list, wenn Sie die Option --format angeben:

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

API-Konfigurationen auflisten

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

gcloud api-gateway api-configs list --project=PROJECT_ID

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 --project=PROJECT_ID

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

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_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 oben unter API-Konfiguration erstellen gezeigt.

Verwenden Sie die folgende gcloud, 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  --project=PROJECT_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.

Verwenden Sie den folgenden gcloud-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