API-Spezifikationen verwalten

Diese Seite gilt für Apigee und Apigee Hybrid.

In diesem Dokument wird beschrieben, wie API-Spezifikationen im API-Hub verwaltet werden. Weitere Informationen finden Sie unter Einführung in API-Spezifikationen.

API-Spezifikation zu einer Version hinzufügen

Sie können einer API-Version eine oder mehrere API-Spezifikationen hinzufügen. Wählen Sie eine der folgenden Optionen aus:

Spezifikation beim Erstellen einer Version hinzufügen
Spezifikation zu einer vorhandenen Version hinzufügen

Spezifikation beim Erstellen einer Version hinzufügen

Über die Benutzeroberfläche können Sie gleichzeitig mit der Versionserstellung eine API-Spezifikation hinzufügen. Sie können entweder die URL zu einer Spezifikation angeben, auf die Sie zugreifen, oder eine Spezifikationsdatei direkt aus Ihrem System hochladen.

Console

So fügen Sie eine Spezifikation zu einer neuen Version hinzu:

Führen Sie die Schritte unter API-Version erstellen aus. Auf der Seite Neue Version hinzufügen können Sie der Version optional eine Spezifikationsdatei hinzufügen:
1. Geben Sie einen Anzeigenamen für die Spezifikationsdatei ein. Sie können einen beliebigen Namen verwenden.
2. Wählen Sie den Spezifikationsdateityp aus. Der Spezifikationstyp ist ein konfigurierbares Systemattribut. Siehe auch Systemattribute.
3. Geben Sie entweder einen URI an, der auf eine gültige API-Spezifikationsdatei verweist, auf die Sie Zugriff haben, oder wechseln Sie zu einer API-Spezifikationsdatei in Ihrem System.
  Hinweis: Im öffentlichen Vorschaurelease wird das Parsing von API-Spezifikationen nur für OpenAPI-Spezifikationen unterstützt (v.2.0, v3.0 und v3.1) im JSON- und YAML-Format.
Füllen Sie die Seite Neue Version hinzufügen aus und klicken Sie auf Erstellen, wenn Sie fertig sind.

Spezifikation zu einer vorhandenen Version hinzufügen

Sie können die UI oder die REST API verwenden, um einer vorhandenen Version eine API-Spezifikation hinzuzufügen.

Console

So fügen Sie eine Spezifikation direkt zu einer Version hinzu:

Rufen Sie in der Google Cloud Console die Seite API-Hub auf.
Zum API-Hub
Klicken Sie auf APIs.
Suchen Sie die API mit der Version, die Sie ändern möchten. Verwenden Sie Filter, um Suchbegriffe anzugeben, um die Liste der APIs zu filtern. Verwenden Sie bei Bedarf Search, um eine API zu finden.
API auswählen.
Klicken Sie auf Spezifikationsdatei hinzufügen.
Geben Sie einen Anzeigenamen für die Spezifikationsdatei ein. Sie können einen beliebigen Namen verwenden.
Wählen Sie den Spezifikationsdateityp aus. Der Spezifikationstyp ist ein konfigurierbares Systemattribut. Siehe auch Systemattribute.
Geben Sie entweder einen URI an, der auf eine gültige API-Spezifikationsdatei verweist, auf die Sie Zugriff haben, oder wechseln Sie zu einer API-Spezifikationsdatei in Ihrem System.
Wählen Sie die Version aus, der die Spezifikationsdatei hinzugefügt werden soll.
Klicken Sie auf Erstellen.
Hinweis: Im öffentlichen Vorschaurelease wird das Parsing von API-Spezifikationen nur für OpenAPI-Spezifikationen unterstützt (v.2.0, v3.0 und v3.1) im JSON- und YAML-Format.

REST

Verwenden Sie die API API-Spezifikation hinzufügen, um eine API-Spezifikation zu einer Version hinzuzufügen:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

Ersetzen Sie Folgendes:

API_PROJECT ist der Name des API-Hub-Hostprojekts. Das Hostprojekt wurde bei der Bereitstellung des API-Hubs ausgewählt.
API_LOCATION: der Standort des Hostprojekts. Der Standort wurde bei der Bereitstellung des API-Hubs ausgewählt.
API_ID: Die eindeutige ID einer API-Ressource.
VERSION_ID: Die ID einer Version, die an die API-Ressource angehängt ist.
SPEC_ID: (Optional) Die ID der Spezifikation. Wenn nicht angegeben, wird eine vom System generierte ID verwendet. Der Name muss ein String mit 4 bis 63 Zeichen sein, wobei gültige Zeichen /[a-z][0-9]-/. sind.
DATA_FILE or URI: entweder eine Base64-codierte Datei mit einer gültigen API-Spezifikation oder einen Link zu einer Spezifikation. Siehe das REST-Beispiel.

REST-Beispiel

Erstellen Sie in diesem Beispiel eine neue Spezifikation im API-Hub mit einer Base64-codierten OpenAPI-Spezifikation. Beim Hochladen parst der API-Hub die Spezifikation und erstellt eine neue Spezifikationsentität, die beschreibende Metadaten sowie Gruppen von Vorgangs- und Definitionsentitäten enthält.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

Beispielausgabe:

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

So geben Sie die Spezifikationsdetails zurück:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

Ausgabe:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Spezifikationen auflisten

In diesem Abschnitt wird erläutert, wie Sie die mit einer API-Version verknüpften Spezifikationen auflisten.

Console

So listen Sie Spezifikationen über die Benutzeroberfläche auf:

Rufen Sie in der Google Cloud Console die Seite API-Hub auf.
Zum API-Hub
Klicken Sie auf APIs.
Verwenden Sie Filter, um Suchbegriffe anzugeben, um die Liste der APIs zu filtern. Verwenden Sie bei Bedarf Search, um eine API zu finden.
Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
Suchen Sie auf dem Tab Versionen die Version, die Sie prüfen möchten.
Version auswählen
Alle mit der Version verknüpften Spezifikationen sind im Abschnitt Spezifikationsdatei aufgeführt.

REST

Verwenden Sie die Listenspezifikationen-API, um die mit einer API-Version verknüpften Spezifikationen aufzulisten:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ersetzen Sie Folgendes:

HUB_PROJECT ist der Name des API-Hub-Hostprojekts. Das Hostprojekt wurde bei der Bereitstellung des API-Hubs ausgewählt.
HUB_LOCATION: der Standort des Hostprojekts. Der Standort wurde bei der Bereitstellung des API-Hubs ausgewählt.
API_ID: Die eindeutige ID der API-Ressource.
VERSION_ID: Die eindeutige ID der Version.

Spezifikationsdetails abrufen

In diesem Abschnitt wird erläutert, wie Sie Details zu einer API-Spezifikation abrufen, die einer Version zugeordnet ist.

Console

So rufen Sie Details zu einer Spezifikation über die UI auf:

Rufen Sie in der Google Cloud Console die Seite API-Hub auf.
Zum API-Hub
Klicken Sie auf APIs.
Suchen Sie die API mit der Version, die die Spezifikation enthält, die Sie prüfen möchten. Verwenden Sie Filter, um Suchbegriffe anzugeben, um die Liste der APIs zu filtern. Verwenden Sie bei Bedarf Search, um eine API zu finden.
Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
Suchen Sie auf dem Tab Versionen die Version, die Sie prüfen möchten.
Version auswählen
Wählen Sie im Abschnitt Spezifikationsdatei eine Spezifikation aus, um die zugehörigen Details aufzurufen.

REST

Verwenden Sie die Get feature details API, um Details zu einer Spezifikation aufzurufen:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ersetzen Sie Folgendes:

HUB_PROJECT ist der Name des API-Hub-Hostprojekts. Das Hostprojekt wurde bei der Bereitstellung des API-Hubs ausgewählt.
HUB_LOCATION: der Standort des Hostprojekts. Der Standort wurde bei der Bereitstellung des API-Hubs ausgewählt.
API_ID: Die eindeutige ID der API-Ressource.
VERSION_ID: Die eindeutige ID der Version.
SPEC_ID: Die eindeutige ID der Spezifikation.

Beispielausgabe:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

API-Spezifikation löschen

In diesem Abschnitt wird erläutert, wie Sie eine API-Spezifikation aus einer Version löschen. Beim Löschen einer Spezifikation werden auch die zugehörigen Vorgänge aus der Version gelöscht.

Console

So löschen Sie API-Ressourcen über die UI:

Rufen Sie in der Google Cloud Console die Seite API-Hub auf.
Zum API-Hub
Klicken Sie auf APIs.
Suchen Sie die API mit der Version, die die zu löschende Spezifikation enthält. Verwenden Sie Filter, um Suchbegriffe anzugeben, um die Liste der APIs zu filtern. Verwenden Sie bei Bedarf Search, um eine API zu finden.
Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
Suchen Sie auf dem Tab Versionen die Version, die die zu löschende Spezifikation enthält.
Wählen Sie die Version aus.
Wählen Sie im Abschnitt Spezifikationsdatei im Menü Aktionen in der Zeile der Spezifikation, die Sie löschen möchten, die Option Löschen aus.
Klicken Sie auf Löschen.

REST

Verwenden Sie die API Delete API resource, um eine API-Ressource aus dem API-Hub zu löschen:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

Ersetzen Sie Folgendes:

HUB_PROJECT ist der Name des API-Hub-Hostprojekts. Das Hostprojekt wurde bei der Bereitstellung des API-Hubs ausgewählt.
HUB_LOCATION: der Standort des Hostprojekts. Der Standort wurde bei der Bereitstellung des API-Hubs ausgewählt.
API_ID: Die eindeutige ID der API-Ressource.
VERSION_ID: Die eindeutige ID der Version.
SPEC_ID: Die eindeutige ID der zu löschenden Spezifikation.

Spezifikation bearbeiten

Sie können einige Attribute einer Spezifikation bearbeiten. Eine Liste der Attribute, die Sie aktualisieren können, finden Sie unter Versionsspezifikations-Patch API.

REST

So bearbeiten Sie eine Spezifikation mit der REST API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

Ersetzen Sie Folgendes:

HUB_PROJECT ist der Name des API-Hub-Hostprojekts. Das Hostprojekt wurde bei der Bereitstellung des API-Hubs ausgewählt.
HUB_LOCATION: der Standort des Hostprojekts. Der Standort wurde bei der Bereitstellung des API-Hubs ausgewählt.
API_ID: Die eindeutige ID der API-Ressource.
VERSION_ID: Die eindeutige ID der Version.
SPEC_ID: Die eindeutige ID der Spezifikation.
Anfragetext: Verwenden Sie den Anfragetext, um die zu ändernden Attribute anzugeben. Siehe Definition der Spezifikationsressource.

Lint-Ergebnisse von Spezifikationen ansehen

Der API-Hub bietet einen integrierten (Spectral) Linter (Validator), der die Open API-Spezifikation Ihrer API validiert. Siehe API-Spezifikationen validieren.

Rufen Sie in der Google Cloud Console die Seite API-Hub auf.
Zum API-Hub
Klicken Sie auf APIs.
Suchen Sie die API mit der Version, die die Spezifikation enthält, die Sie prüfen möchten. Verwenden Sie Filter, um Suchbegriffe anzugeben, um die Liste der APIs zu filtern. Verwenden Sie bei Bedarf Search, um eine API zu finden.
Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
Suchen Sie auf dem Tab Versionen die Version mit der Spezifikation, die Sie prüfen möchten.
Klicken Sie in der Lint-Spalte auf Ergebnisse, um die Lint-Ergebnisse aufzurufen.

Spezifikationsinhalte abrufen

Mit diesem Feature können Sie den Inhalt einer Spezifikation prüfen, die in den API-Hub hochgeladen wurde.

Console

So rufen Sie Details zu einer Spezifikation über die UI auf:

Rufen Sie in der Google Cloud Console die Seite API-Hub auf.
Zum API-Hub
Klicken Sie auf APIs.
Suchen Sie die API mit der Version, die die zu löschende Spezifikation enthält. Verwenden Sie Filter, um Suchbegriffe anzugeben, um die Liste der APIs zu filtern. Verwenden Sie bei Bedarf Search, um eine API zu finden.
Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
Suchen Sie auf dem Tab Versionen die Version mit der Spezifikation, die Sie prüfen möchten.
Klicken Sie auf den Namen der Spezifikation, um den Inhalt aufzurufen.

REST

Die API ruft den Base64-codierten Rohinhalt einer API-Spezifikation ab, die in den API-Hub hochgeladen wurde. Verwenden Sie die API Spezifikationsinhalte abrufen:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ersetzen Sie Folgendes:

HUB_PROJECT ist der Name des API-Hub-Hostprojekts. Das Hostprojekt wurde bei der Bereitstellung des API-Hubs ausgewählt.
HUB_LOCATION: der Standort des Hostprojekts. Der Standort wurde bei der Bereitstellung des API-Hubs ausgewählt.
API_ID: Die eindeutige ID der API-Ressource.
VERSION_ID: Die eindeutige ID der Version.
SPEC_ID: Die eindeutige ID der Spezifikation.

Beispielausgabe:

{
  "contents": "Base64-encoded file contents"
}