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

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

  1. 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. Weitere Informationen finden Sie unter Systemattribute.
    3. Geben Sie entweder einen URI an, der auf eine gültige API-Spezifikationsdatei verweist, auf die Sie Zugriff haben, oder rufen Sie eine API-Spezifikationsdatei auf Ihrem System auf.
    4. Optional: Wenn Sie die hochgeladene Spezifikation streng validieren möchten, klicken Sie das Kästchen Upload von Spezifikationsdateien mit Fehlern einschränken an. Wenn diese Option ausgewählt ist, werden Spezifikationen mit Validierungsfehlern nicht hochgeladen. Standardmäßig werden Spezifikationen mit Fehlern hochgeladen.
  2. 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:

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

    Zum API-Hub
  2. Klicken Sie auf APIs.
  3. 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.
  4. API auswählen.
  5. Klicken Sie auf Spezifikationsdatei hinzufügen.
  6. Geben Sie einen Anzeigenamen für die Spezifikationsdatei ein. Sie können einen beliebigen Namen verwenden.
  7. Wählen Sie den Spezifikationsdateityp aus. Der Spezifikationstyp ist ein konfigurierbares Systemattribut. Siehe auch Systemattribute.
  8. Geben Sie entweder einen URI an, der auf eine gültige API-Spezifikationsdatei verweist, auf die Sie Zugriff haben, oder rufen Sie eine API-Spezifikationsdatei auf Ihrem System auf.
  9. Optional: Wenn Sie die hochgeladene Spezifikation streng validieren möchten, klicken Sie das Kästchen Upload von Spezifikationsdateien mit Fehlern einschränken an. Wenn diese Option ausgewählt ist, werden Spezifikationen mit Validierungsfehlern nicht hochgeladen. Standardmäßig werden Spezifikationen mit Fehlern hochgeladen.
  10. Wählen Sie die Version aus, der Sie die Spezifikationsdatei hinzufügen möchten.
  11. Klicken Sie auf Erstellen.

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:

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

    Zum API-Hub
  2. Klicken Sie auf APIs.
  3. Verwenden Sie Filter, um Suchbegriffe anzugeben, um die Liste der APIs zu filtern. Verwenden Sie bei Bedarf Search, um eine API zu finden.
  4. Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
  5. Suchen Sie auf dem Tab Versionen die Version, die Sie prüfen möchten.
  6. Version auswählen
  7. 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:

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

    Zum API-Hub
  2. Klicken Sie auf APIs.
  3. 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.
  4. Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
  5. Suchen Sie auf dem Tab Versionen die Version, die Sie prüfen möchten.
  6. Version auswählen
  7. 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:

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

    Zum API-Hub
  2. Klicken Sie auf APIs.
  3. 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.
  4. Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
  5. Suchen Sie auf dem Tab Versionen die Version, die die zu löschende Spezifikation enthält.
  6. Wählen Sie die Version aus.
  7. 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.
  8. 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.

Spezifikationsmetadaten bearbeiten

Sie können einige der Metadaten bearbeiten, die mit einer im API-Hub gespeicherten Spezifikation verknüpft sind. Eine Liste der Metadaten, die Sie bearbeiten können, finden Sie unter Spezifikations-Patch API.

Console

Sie können über die Google Cloud Console Änderungen an einer vorhandenen Spezifikation vornehmen. Sie können beispielsweise den Anzeigenamen ändern, eine neue Spezifikationsdatei hochladen, den Dateityp ändern und Attribute bearbeiten:

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

    Zum API-Hub
  2. Klicken Sie auf APIs.
  3. Suchen Sie die API mit der Version, die die Spezifikation enthält, die Sie bearbeiten 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.
  4. Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
  5. Suchen Sie auf dem Tab Versionen nach der Version, die die Spezifikation enthält, die Sie bearbeiten möchten.
  6. Wählen Sie die Version aus.
  7. Suchen Sie auf der Seite „Versionen“ nach der Spezifikation, die Sie bearbeiten möchten.
  8. Wählen Sie in der Zeile der Spezifikation, die Sie bearbeiten möchten, im Menü Aktionen die Option Bearbeiten aus.
  9. Im Bereich zum Bearbeiten der Spezifikation können Sie die folgenden Spezifikationsmetadaten ändern:
    • Anzeigename
    • Spezifikationsdateityp
    • Spezifikationsdokument: Wählen Sie eine neue Spezifikationsdatei zum Hochladen aus.
    • Optional: Wenn Sie die hochgeladene Spezifikation streng validieren möchten, klicken Sie das Kästchen Upload von Spezifikationsdateien mit Fehlern einschränken an. Wenn diese Option ausgewählt ist, werden Spezifikationen mit Validierungsfehlern nicht hochgeladen. Standardmäßig werden Spezifikationen mit Fehlern hochgeladen.
    • Benutzerdefinierte Attribute (falls vorhanden)
  10. Klicken Sie auf Speichern.

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.

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

    Zum API-Hub
  2. Klicken Sie auf APIs.
  3. 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.
  4. Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
  5. Suchen Sie auf dem Tab Versionen die Version mit der Spezifikation, die Sie prüfen möchten.
  6. Klicken Sie in der Spalte „Lint-Ergebnisse“ auf Ergebnisse ansehen, 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:

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

    Zum API-Hub
  2. Klicken Sie auf APIs.
  3. 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.
  4. Klicken Sie auf eine API, um die zugehörigen Details aufzurufen.
  5. Suchen Sie auf dem Tab Versionen die Version mit der Spezifikation, die Sie prüfen möchten.
  6. 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"
}