API-Konfiguration erstellen

Vorbereitung

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

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

Laden Sie die API-Definition mit der Google Cloud CLI 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.

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

    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.
    • PROJECT_ID die Google Cloud-Projekt-ID angibt.
    • SERVICE_ACCOUNT_EMAIL gibt das Dienstkonto an, mit dem Tokens für Backends mit konfigurierter Authentifizierung signiert werden. 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: 1111111@developer.gserviceaccount.com
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 hat viele Optionen, einschließlich der in der gcloud-Referenz 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 \
  --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.

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

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