APIs veröffentlichen

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Veröffentlichen Sie APIs in Ihrem Portal, um sie App-Entwicklern zur Verfügung zu stellen, wie in den folgenden Abschnitten beschrieben.

API-Veröffentlichung

Die Veröffentlichung von APIs in Ihrem Portal erfolgt in zwei Schritten:

  1. Wählen Sie das API-Produkt aus, das Sie in Ihrem Portal veröffentlichen möchten.
  2. Rendern Sie die API-Referenzdokumentation aus Ihrem OpenAPI-Dokument oder GraphQL-Schema, damit App-Entwickler Informationen zu Ihren APIs erhalten können. Weitere Informationen finden Sie in der API-Dokumentation.

Was wird im Portal veröffentlicht?

Wenn Sie eine API veröffentlichen, werden die folgenden Aktualisierungen automatisch an Ihrem Portal vorgenommen:

  • API-Referenzdokumentation. Welche Schnittstelle bereitgestellt wird, hängt davon ab, ob Sie Ihre API mit einem OpenAPI-Dokument oder einem GraphQL-Schema veröffentlichen. Siehe:
  • Der Seite „APIs“ wird ein Link zur API-Referenzseite hinzugefügt.

    Die Seite „APIs“ (im Beispielportal enthalten) umfasst eine Liste aller in Ihrem Portal veröffentlichten APIs in alphabetischer Reihenfolge. Auch Links zur entsprechenden API-Referenzdokumentation mit weitere Informationen sind dort zu finden. Sie können Folgendes nach Bedarf anpassen:

    • Das für jede API-Karte angezeigte Bild
    • Kategorien zum Taggen von APIs, damit Entwickler auf der Seite „APIs“ ähnliche APIs finden können
    Grafik: Seite „APIs“ im Live-Portal mit zwei Kategorien und verwendeten Bildern Grafik: Seite „APIs“ im Live-Portal mit zwei Kategorien und verwendeten Bildern

SmartDocs (OpenAPI)

Wenn Sie eine API mit einem OpenAPI-Dokument veröffentlichen, wird die SmartDocs API-Referenzdokumentation Ihrem Portal hinzugefügt.

Entwickler können die Referenzdokumentation der SmartDocs API aufrufen und im Bereich API testen eine API-Anfrage stellen und die Ausgabe ansehen. API testen funktioniert mit ungesicherten Endpunkten oder gesicherten Endpunkten mit Basisauthentifizierung, API-Schlüssel oder OAuth-Authentifizierung – entsprechend der in Ihrem OpenAPI-Dokument festgelegten Sicherheitsmethode. Bei OAuth werden folgende Abläufe unterstützt: Autorisierungscode, Passwort und Clientanmeldedaten.

Grafik: Seite der API-Referenzdokumentation mit Zusatzinformationen, die Aufschluss darüber geben, wie Sie den API-Aufruf autorisieren, das Feld „API testen“ abkoppeln, die relevante Spezifikation herunterladen und die API ausführen

Grafik: Seite der API-Referenzdokumentation mit Zusatzinformationen, die Aufschluss darüber geben, wie Sie den API-Aufruf autorisieren, das Feld „API testen“ abkoppeln, die relevante Spezifikation herunterladen und die API ausführen

Klicken Sie auf um das Feld API testen zu maximieren. Im maximierten Steuerfeld können Sie die curl-Aufruf- und Codebeispiele in verschiedenen Formaten ansehen, z. B. HTTP, Python, Node.js usw. (siehe unten).

Grafik: Maximiert das Feld „API testen“

Grafik: Maximiert das Feld „API testen“

GraphQL Explorer

Wenn Sie eine API mithilfe eines GraphQL-Schemas veröffentlichen, wird der GraphQL-Explorer Ihrem Portal hinzugefügt. Der GraphQL Explorer ist ein interaktiver Playground zum Ausführen von Abfragen für Ihre API. Der Explorer basiert auf GraphiQL, einer von der GraphQL Foundation entwickelten Referenzimplementierung der GraphQL-IDE.

Entwickler können mit GraphQL Explorer die schemabasierte interaktive Dokumentation entdecken, Abfragen erstellen und ausführen, Abfrageergebnisse ansehen und das Schema herunterladen. Um den Zugriff auf Ihre API zu sichern, können Entwickler Autorisierungsheader im Bereich Anfrageheader übergeben. Weitere Informationen zu GraphQL finden Sie unter graphql.org.

GraphQL Explorer im Portal

GraphQL Explorer im Portal

Informationen zur API-Dokumentation

Jedes OpenAPI- oder GraphQL-Dokument dient im gesamten Lebenszyklus einer API als „Source of Truth“. Die gleiche Dokument wird in jeder Phase des API-Lebenszyklus verwendet, von der Entwicklung über die Veröffentlichung bis hin zum Monitoring. Wenn Sie ein Dokument ändern, müssen Sie wissen, welche Auswirkungen die Änderungen auf Ihre API durch andere Lebenszyklusphasen haben, wie unter Was passiert, wenn ich ein Dokument ändere? beschrieben.

Wenn Sie Ihre API in einem Portal veröffentlichen, speichern Sie eine Version des OpenAPI- oder GraphQL-Dokuments, um die API-Referenzdokumentation zu rendern. Wenn Sie das Dokument ändern, können Sie die im Portal veröffentlichte API-Referenzdokumentation aktualisieren, um die neuesten Änderungen widerzuspiegeln.

Über Callback-URLs

Wenn Ihre Anwendungen eine Callback-URL erfordern, z. B. bei Verwendung des Berechtigungstyps "OAuth 2.0-Autorisierungscode" (auch als Dreibeiniges OAuth bezeichnet), können Sie festlegen, dass Entwickler bei der Registrierung ihrer Anwendung eine Callback-URL angeben müssen. Die Callback-URL gibt normalerweise die URL einer Anwendung an, die einen Autorisierungscode im Namen der Clientanwendung erhalten soll. Weitere Informationen finden Sie unter Berechtigungstyp "Autorisierungscode" implementieren.

Sie können konfigurieren, ob beim Hinzufügen einer API zu Ihrem Portal eine Callback-URL bei der Anwendungsregistrierung erforderlich ist. Sie können diese Einstellung jederzeit ändern, wie unter Callback-URL für eine API verwalten beschrieben.

Entwickler müssen bei der Registrierung einer Anwendung eine Callback-URL für alle APIs eingeben, die sie benötigen, wie unter Anwendungen registrieren beschrieben.

API-Proxy für die Unterstützung des Feldes „API testen” konfigurieren

Bevor Sie Ihre APIs mit einem OpenAPI-Dokument veröffentlichen, müssen Sie Ihren API-Proxy für die Unterstützung von Anfragen im Bereich "API testen" in der Referenzdokumentation der SmartDocs API folgendermaßen konfigurieren:

  • Fügen Sie Ihren API-Proxys CORS-Unterstützung hinzu, um clientseitige Cross-Origin-Anfragen zu erzwingen.
    CORS ist ein Standardmechanismus, mit dem JavaScript XMLHttpRequest-Aufrufe (XHR), die auf einer Webseite ausgeführt werden, mit Ressourcen von Nicht-Origin-Domains interagieren können. CORS ist eine häufig implementierte Lösung für die Same-Origin-Richtlinie, die von allen Browsern durchgesetzt wird.
  • Aktualisieren Sie die API-Proxykonfiguration, wenn Sie eine Basisauthentifizierung oder OAuth 2.0 verwenden

In der folgenden Tabelle sind die Anforderungen für die API-Proxy-Konfiguration zusammengefasst, um das Feld „API testen“ in der Referenzdokumentation der SmartDocs API basierend auf dem Authentifizierungszugriff zu unterstützen.

Auth-Zugriff Anforderungen an die Richtlinienkonfiguration
Keine oder API-Schlüssel Fügen Sie Ihrem API-Proxy CORS-Unterstützung hinzu. Folgen Sie dazu der Anleitung unter CORS-Unterstützung zu einem API-Proxy hinzufügen.
Basisauthentifizierung Führen Sie folgende Schritte aus:
  1. Fügen Sie Ihrem API-Proxy CORS-Unterstützung hinzu. Folgen Sie dazu der Anleitung unter CORS-Unterstützung zu einem API-Proxy hinzufügen.
  2. Prüfen Sie in der Richtlinie "CORS hinzufügen", ob der Header Access-Control-Allow-Headers das Attribut authorization enthält. Beispiel: 
    
<Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
oauth 2.0
  1. Fügen Sie Ihrem API-Proxy CORS-Unterstützung hinzu. Folgen Sie dazu der Anleitung unter CORS-Unterstützung zu einem API-Proxy hinzufügen.
  2. Prüfen Sie in der Richtlinie "CORS hinzufügen", ob der Header Access-Control-Allow-Headers das Attribut authorization enthält. Beispiel: 
    
<Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
  3. Korrigieren Sie das nicht RFC-konforme Verhalten in der OAuth 2.0-Richtlinie. Verwenden Sie die OAuth 2.0-Beispiellösung aus GitHub oder gehen Sie folgendermaßen vor:
    • Das Element <GrantType> in der OAuth 2.0-Richtlinie muss auf request.formparam.grant_type (Formparameter) gesetzt sein. Weitere Informationen finden Sie unter <GrantType>.
    • token_type in der OAuth 2.0-Richtlinie muss auf Bearer und nicht auf die Standardeinstellung BearerToken gesetzt sein.

APIs verwalten

Verwalten Sie Ihre APIs wie in den folgenden Abschnitten beschrieben.

Alle APIs anzeigen

Verwenden Sie die Console oder den Befehl curl, um die im Portal enthaltenen APIs aufzurufen.

Console

So rufen Sie den API-Katalog auf:

  1. Wählen Sie Veröffentlichen > Portale und anschließend dein Portal aus.

  2. Klicken Sie auf der Startseite des Portals auf API-Katalog.
    Alternativ können Sie im Drop-down-Menü des Portals im oberen Navigationsmenü die Option API-Katalog auswählen.
    Auf dem Tab „APIs“ im API-Katalog wird eine Liste der APIs angezeigt, die Ihrem Portal hinzugefügt wurden.

    Grafik: Tab „APIs“ mit Informationen zu den APIs, einschließlich Name, Beschreibung, Sichtbarkeit, Kategorien, zugehöriger Spezifikation und geändert

    Grafik: Tab „APIs“ mit Informationen zu den APIs, einschließlich Name, Beschreibung, Sichtbarkeit, Kategorien, zugehöriger Spezifikation und geändert

    Wie bereits erwähnt, können Sie auf dem Tab „APIs“ Folgendes tun:

curl

So listen Sie APIs mit organizations.sites.apidocs/list auf:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.

Unter Paginierungshinweise finden Sie eine Anleitung zur Verwendung der Paginierung in der Antwortnutzlast.

Antwortnutzlast:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

Dabei gilt:

  • modified: Zeit, zu der das Katalogelement zuletzt in Millisekunden seit der Epoche geändert wurde. Beispiel: 1698165480000.
  • id:: Die ID des Katalogartikels. Beispiel: 399668.

Paginierungshinweise:

  • Seitengröße: Verwenden Sie pageSize, um die Anzahl der Listenelemente anzugeben, die auf einer Seite zurückgegeben werden sollen. Der Standardwert ist 25 und der Höchstwert 100. Wenn weitere Seiten vorhanden sind, wird nextPageToken mit einem Token gefüllt:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
   -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Ersetzen Sie:

    • PAGE_SIZE durch die Anzahl der Listenelemente, die auf einer Seite zurückgegeben werden sollen. Beispiel: 10.

    Antwortnutzlast:

    {
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "918815495",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "apigee",
      "modified": "1699146887000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    }
  ],
  "nextPageToken": "7zcqrin9l6xhi4nbrb9"
}

  • Seitentoken:

    Verwenden Sie pageToken, um nachfolgende Seiten abzurufen, wenn mehrere vorhanden sind:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Ersetzen Sie:

    • PAGE_SIZE durch die Anzahl der Listenelemente, die auf einer Seite zurückgegeben werden sollen. Beispiel: 10.
    • PAGE_TOKEN durch den Wert nextPageToken. Beispiel: 7zcqrin9l6xhi4nbrb9

API hinzufügen

So fügen Sie Ihrem Portal eine API hinzu:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.

  3. Klicken Sie auf Hinzufügen.

    Das Dialogfeld API-Produkt zum Katalog hinzufügen wird angezeigt.

  4. Wählen Sie das API-Produkt aus, das Sie dem Portal hinzufügen möchten.

  5. Klicken Sie auf Next (Weiter). Die Seite API-Details wird angezeigt.

  6. Konfigurieren Sie den Inhalt der API-Referenzdokumentation und seine Sichtbarkeit im Portal:

    Feld Beschreibung
    Veröffentlicht Wählen Sie Veröffentlicht aus, um die API in Ihrem Portal zu veröffentlichen. Entfernen Sie das Häkchen aus dem Kästchen, wenn Sie die API nicht veröffentlichen möchten. Sie können die Einstellung später ändern, wie unter API veröffentlichen oder Veröffentlichung aufheben beschrieben.
    Anzeigename Aktualisieren Sie den Titel Ihrer API, der im Katalog angezeigt wird. Standardmäßig wird der API-Produktname verwendet. Sie können den Titel später ändern. Weitere Informationen dazu finden Sie unter Angezeigten Titel und Beschreibung bearbeiten.
    Angezeigte Beschreibung Aktualisieren Sie die im Katalog angezeigte Beschreibung der API. Standardmäßig wird die API-Produktbeschreibung verwendet. Sie können die Anzeigebeschreibung später ändern, wie unter Angezeigten Titel und Beschreibung bearbeiten beschrieben.
    Entwickler müssen eine Callback-URL angeben Aktivieren Sie diese Option, wenn App-Entwickler eine Callback-URL angeben sollen. Sie können die Callback-URL später hinzufügen oder aktualisieren, wie in Callback-URL für eine API verwalten beschrieben.
    API-Dokumentation

    So verwenden Sie ein OpenAPI-Dokument:

    1. Wählen Sie OpenAPI-Dokument aus.
    2. Klicken Sie auf Dokument auswählen.
    3. Führen Sie einen der folgenden Schritte aus:
      • Klicken Sie auf den Tab Datei hochladen und laden Sie eine Datei hoch.
      • Klicken Sie auf den Tab Von einer URL importieren und importieren Sie eine Spezifikation, indem Sie einen Namen und eine URL angeben, aus der importiert werden soll.
    4. Klicken Sie auf Auswählen.

    So verwenden Sie ein GraphQL-Schema:

    1. Wählen Sie GraphQL-Schema.
    2. Klicken Sie auf Dokument auswählen.
    3. Rufen Sie das GraphQL-Schema auf und wählen Sie es aus.
    4. Klicken Sie auf Auswählen.

    Alternativ können Sie Keine Dokumentation auswählen und später eine anfügen, nachdem die API hinzugefügt wurde, wie unter API-Dokumentation verwalten beschrieben.

    Visuelle Hilfsmittel

    Wenn Sie sich noch nicht für die Betaversion des Features zur Zielgruppenverwaltung angemeldet haben, wählen Sie eine der folgenden Optionen aus:

    • Anonyme Nutzer, damit alle Nutzer die API sehen können.
    • Registrierte Nutzer, um nur registrierten Nutzern Zugriff auf die API zu gewähren.

    Wenn Sie sich für die Betaversion der Funktion „Zielgruppenverwaltung“ angemeldet haben, wählen Sie eine der folgenden Optionen aus:

    • Öffentlich (für alle sichtbar), damit alle Nutzer die API aufrufen können.
    • Authentifizierte Nutzer, um nur registrierten Nutzern Zugriff auf die API zu gewähren.
    • Ausgewählte Zielgruppen, um die spezifischen Zielgruppen auszuwählen, die in der Lage sein sollen, die API aufzurufen.

    Sie können die Sichtbarkeit der Zielgruppe später verwalten, wie unter Sichtbarkeit einer API verwalten beschrieben.

    Bild anzeigen Wenn auf der Seite „APIs“ ein Bild auf der API-Karte angezeigt werden soll, klicken Sie auf Bild auswählen. Wählen Sie im Dialogfeld Bild auswählen ein vorhandenes Bild aus, laden Sie ein neues Bild hoch oder geben Sie die URL eines externen Bilds an und klicken Sie auf Auswählen. Sehen Sie sich eine Vorschau der API-Miniaturansicht an und klicken Sie auf Auswählen. Sie können später ein Bild hinzufügen, wie unter Bild für eine API-Karte verwalten beschrieben. Wenn Sie die URL eines externen Bilds angeben, wird das Bild nicht in Ihre Assets hochgeladen. Außerdem hängt das Laden des Bildes im integrierten Portal von dessen Verfügbarkeit ab. Diese kann durch Inhaltssicherheitsrichtlinien blockiert oder eingeschränkt werden.
    Kategorien

    Fügen Sie die Kategorien hinzu, mit denen die API getaggt wird, damit App-Entwickler auf der Seite „APIs“ ähnliche APIs finden können. So bestimmen Sie eine Kategorie:

    • Wählen Sie eine Kategorie aus der Drop-down-Liste aus.
    • Fügen Sie eine neue Kategorie hinzu, indem Sie ihre Bezeichnung eingeben und die Eingabetaste drücken. Die neue Kategorie wird der Seite „Kategorien“ hinzugefügt und bereitgestellt, sobald Sie weitere APIs hinzufügen oder bearbeiten.

  7. Klicken Sie auf Speichern.

curl

So fügen Sie Ihrem Portal mit organizations.sites.apidocs.create eine API hinzu:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
  • TITLE durch den Anzeigetitel. Beispiel: Hello World 2.
  • DESCRIPTION durch die angezeigte Beschreibung. Beispiel: Simple hello world example.
  • ANON_TRUE_OR_FALSE durch true oder false (Standard), wobei true den anonymen Nutzerzugriff aktiviert. Diese Einstellung wird ignoriert, wenn Sie sich für die Betaversion des Features zur Zielgruppenverwaltung angemeldet haben.
  • IMAGE_URL durch die URL eines externen Images, das für das Katalogelement verwendet wird, oder einen Dateipfad für im Portal gespeicherte Bilddateien, z. B. /files/book-tree.jpg Wenn Sie die URL eines externen Bilds angeben, wird das Bild nicht in Ihre Assets hochgeladen. Darüber hinaus hängt das Laden des Bildes im integrierten Portal von dessen Verfügbarkeit ab. Diese kann durch Inhaltssicherheitsrichtlinien blockiert oder eingeschränkt werden.
  • CALLBACK_TRUE_OR_FALSE durch true oder false (Standard), wobei true erfordert, dass ein Portalnutzer beim Verwalten der Anwendung eine URL eingibt.

  • CATEGORY_ID durch die ID der Kategorie. Beispiel: bf6505eb-2a0f-47af-a00a-ded40ac72960. Trennen Sie mehrere Kategorie-IDs durch ein Komma. Die Kategorie-ID erhalten Sie mit dem Befehl API-Listen auflisten.

  • PUBLISHED_TRUE_OR_FALSE durch true oder false (Standard), wobei true angibt, dass die API öffentlich verfügbar ist.

  • API_PRODUCT durch den Namen des API-Produkts. Beispiel: Hello World 2.

Antwortnutzlast:

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Dabei gilt:

  • modified: Zeit, zu der das Katalogelement zuletzt in Millisekunden seit der Epoche geändert wurde. Beispiel: 1698165480000.
  • id:: Die ID des Katalogartikels. Beispiel: 399668.

API bearbeiten

Nachdem Sie eine API hinzugefügt haben, verwenden Sie die Console oder einen API-Aufruf, um Änderungen vorzunehmen.

In diesem Abschnitt finden Sie ein detailliertes Beispiel für die Schritte zum Ändern einer vorhandenen API in Ihrem Portal.

In den folgenden Abschnitten finden Sie spezifische Änderungseinstellungen.

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.
  5. Nehmen Sie unter API-Details die gewünschten Änderungen vor. Eine Beschreibung der Optionen finden Sie unter API hinzufügen.
  6. Klicken Sie auf Speichern.

curl

Nachdem Sie eine API hinzugefügt haben, können Sie mit dem Aufruf organizations.sites.apidocs.update Änderungen vornehmen.

In diesem Beispiel werden die Schritte beschrieben, mit denen Sie den veröffentlichten Status Ihrer API in Ihrem Portal von true zu false ändern können. Bei Bedarf können Sie mehrere Einstellungen in einem API-Aufruf ändern.

  1. Rufen Sie mit organizations.sites.apidocs/list eine Liste der APIs in Ihrem Portal ab, um die generierte id zu finden, die jede API eindeutig identifiziert:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Ersetzen Sie Folgendes:

    • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
    • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.

    Antwortnutzlast:

    {
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ]
}

    Dabei gilt:

    • modified: Zeit, zu der das Katalogelement zuletzt in Millisekunden seit der Epoche geändert wurde. Beispiel: 1698165480000.
    • id:: Die ID des Katalogartikels. Beispiel: 399668.

  2. Verwenden Sie den Aufruf organizations.sites.apidocs.get, um die aktuellen Werte für eine bestimmte API zurückzugeben:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Ersetzen Sie Folgendes:

    • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
    • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
    • API_DOC durch die generierte id des Dokuments. Beispiel: 399668. Verwenden Sie den Befehl list API docs, um diesen Wert zu finden.

    Antwortnutzlast:

    {
  "status": "success",
  "message": "apidoc returned",
  "requestId": "2072952505",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "specId": "hello-new-world",
    "modified": "1698950207000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg?v=1698165437881",
    "id": "399668",
    "categoryIds": [
      "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "61c1014c-89c9-40e6-be3c-69cca3505620"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

  3. Fügen Sie die änderbaren Werte, die Sie in den organizations.sites.apidocs.update-Aufruf aufnehmen möchten, ein und ändern Sie die gewünschten Werte. Wenn Sie eine Zeile weglassen, wird die Standardeinstellung verwendet. Ändern Sie in diesem Beispiel die Einstellung published von true in false:

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": "IMAGE_URL",
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": false,
        "apiProductName": "API_PRODUCT",
     }'

    Ersetzen Sie Folgendes:

    • TITLE durch den Anzeigetitel. Beispiel: Hello World 2.
    • DESCRIPTION durch die angezeigte Beschreibung. Beispiel: Simple hello world example.
    • ANON_TRUE_OR_FALSE durch true oder false (Standard), wobei true den anonymen Nutzerzugriff aktiviert. Diese Einstellung wird ignoriert, wenn Sie sich für die Betaversion des Features zur Zielgruppenverwaltung angemeldet haben.
    • IMAGE_URL durch die URL eines externen Images, das für das Katalogelement verwendet wird, oder einen Dateipfad für im Portal gespeicherte Bilddateien, z. B. /files/book-tree.jpg Wenn Sie die URL eines externen Bilds angeben, wird das Bild nicht in Ihre Assets hochgeladen. Darüber hinaus hängt das Laden des Bildes im integrierten Portal von dessen Verfügbarkeit ab. Diese kann durch Inhaltssicherheitsrichtlinien blockiert oder eingeschränkt werden.
    • CALLBACK_TRUE_OR_FALSE durch true oder false (Standard), wobei true erfordert, dass ein Portalnutzer beim Verwalten der Anwendung eine URL eingibt.
    • CATEGORY_ID durch die ID der Kategorie. Beispiel: bf6505eb-2a0f-47af-a00a-ded40ac72960. Trennen Sie mehrere Kategorie-IDs durch ein Komma. Die Kategorie-ID erhalten Sie mit dem Befehl API-Listen auflisten.
    • API_PRODUCT durch den Namen des API-Produkts. Beispiel: Hello World 2.

    Antwortnutzlast:

    {
  "status": "success",
  "message": "ApiDoc updated",
  "requestId": "197181831",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example.",
    "modified": "1698884328000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "408567",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": PUBLISHED_TRUE_OR_FALSE,
    "apiProductName": "Hello World 2"
  }
}

API veröffentlichen oder Veröffentlichung aufheben

Beim Veröffentlichen werden Ihre APIs App-Entwicklern zur Nutzung zur Verfügung gestellt.

So veröffentlichen Sie eine API auf Ihrem Portal oder heben die Veröffentlichung auf:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.
  5. Wählen Sie in den API-Details die Option Veröffentlicht (im Katalog aufgeführt) aus oder heben Sie die Auswahl auf, um die API auf Ihrem Portal zu veröffentlichen bzw. ihre Veröffentlichung rückgängig zu machen.
  6. Klicken Sie auf Speichern.

curl

Fügen Sie einen der folgenden Werte in den Aufruf von update ein:

  "published": true,    # API is published to your portal
  "published": false,   # API is not published in your portal

So bearbeiten Sie die API:

  1. Verwenden Sie den Aufruf organizations.sites.apidocs.get, um die aktuellen Werte zurückzugeben:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Verwenden Sie den Aufruf organizations.sites.apidocs.update, um die API zu bearbeiten. Fügen Sie die änderbaren Werte ein, die Sie beibehalten und die Sie ändern möchten. Wenn Sie eine änderbare Einstellung weglassen, wird der Standardwert verwendet.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlasten finden Sie unter API bearbeiten.

Sichtbarkeit einer API verwalten

Verwalten Sie die Sichtbarkeit einer API in Ihrem Portal durch Gewähren des Zugriffs für:

So verwalten Sie die Sichtbarkeit einer API in Ihrem Portal:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.

  5. Wählen Sie die Sichtbarkeitseinstellung aus. Wenn Sie sich für die Betaversion der Zielgruppenfunktion angemeldet haben, wählen Sie unter API-Sichtbarkeit eine der folgenden Optionen aus:

    • Öffentlich (für alle sichtbar), damit alle Nutzer die Seite aufrufen können.
    • Authentifizierte Nutzer, um nur registrierten Nutzern die Anzeige der Seite zu ermöglichen.
    • Ausgewählte Zielgruppen, damit nur von Ihnen festgelegte Zielgruppen die Seite aufrufen können. Weitere Informationen finden Sie unter Zielgruppen für Ihr Portal verwalten.

    Wählen Sie andernfalls unter Zielgruppe eine der folgenden Optionen aus:

    • Anonyme Nutzer, um allen Nutzern die Anzeige der Seite zu ermöglichen.
    • Registrierte Nutzer, um nur registrierten Nutzern die Anzeige der Seite zu ermöglichen.

  6. Klicken Sie auf Senden.

curl

Wenn Sie sich für die Betaversion des Features zur Zielgruppenverwaltung angemeldet haben, können Sie die Zielgruppen mit der Console verwalten.

Wenn Sie sich nicht für das Feature zur Zielgruppenverwaltung registriert haben, wird die Sichtbarkeit mit anonAllowed verwaltet.

Fügen Sie einen der folgenden Werte in den Aufruf von update ein:

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

So bearbeiten Sie die API:

  1. Verwenden Sie den Aufruf organizations.sites.apidocs.get, um die aktuellen Werte zurückzugeben:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Verwenden Sie den Aufruf organizations.sites.apidocs.update, um die API zu bearbeiten. Fügen Sie die änderbaren Werte ein, die Sie beibehalten und die Sie ändern möchten. Wenn Sie eine änderbare Einstellung weglassen, wird der Standardwert verwendet.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlasten finden Sie unter API bearbeiten.

Callback-URL für eine API verwalten

Callback-URL für eine API verwalten Weitere Informationen finden Sie unter Callback-URLs.

So verwalten Sie die Callback-URL für eine API:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.
  5. Aktivieren oder deaktivieren Sie unter API-Details die Option Entwickler müssen eine Callback-URL angeben, um anzugeben, dass eine Callback-URL erforderlich bzw. nicht erforderlich ist.
  6. Klicken Sie auf Speichern.

curl

Fügen Sie einen der folgenden Werte in den Aufruf von update ein:

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

So bearbeiten Sie die API:

  1. Verwenden Sie den Aufruf organizations.sites.apidocs.get, um die aktuellen Werte zurückzugeben:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Verwenden Sie den Aufruf organizations.sites.apidocs.update, um die API zu bearbeiten. Fügen Sie die änderbaren Werte ein, die Sie beibehalten und die Sie ändern möchten. Wenn Sie eine änderbare Einstellung weglassen, wird der Standardwert verwendet.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlasten finden Sie unter API bearbeiten.

Bild für eine API-Karte verwalten

Verwalten Sie das Bild, das mit einer API-Karte auf der Seite „APIs“ angezeigt wird, indem Sie das aktuelle Bild hinzufügen oder ändern.

So verwalten Sie das Bild für eine API-Karte:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.

  5. Gehen Sie unter API-Details folgendermaßen vor:

    • Klicken Sie auf Image auswählen, um ein Image anzugeben, falls derzeit keins ausgewählt ist.
    • Klicken Sie auf Image ändern, um ein anderes Image anzugeben.
    • Klicken Sie im Bild auf x, um es zu entfernen.

    Geben Sie beim Angeben eines Bildes entweder ein Bild mit einer externen URL an, die für das Katalogelement verwendet wird, oder einen Dateipfad für im Portal gespeicherte Bilddateien. Beispiel: /files/book-tree.jpg Wenn Sie die URL eines externen Bilds angeben, wird das Bild nicht in Ihre Assets hochgeladen. Darüber hinaus hängt das Laden des Bildes im integrierten Portal von dessen Verfügbarkeit ab. Diese kann durch Inhaltssicherheitsrichtlinien blockiert oder eingeschränkt werden.

  6. Klicken Sie auf Speichern.

curl

Fügen Sie Folgendes in den Aufruf von update ein:

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

So bearbeiten Sie die API:

  1. Verwenden Sie den Aufruf organizations.sites.apidocs.get, um die aktuellen Werte zurückzugeben:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Verwenden Sie den Aufruf organizations.sites.apidocs.update, um die API zu bearbeiten. Fügen Sie die änderbaren Werte ein, die Sie beibehalten und die Sie ändern möchten. Wenn Sie eine änderbare Einstellung weglassen, wird der Standardwert verwendet.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlasten finden Sie unter API bearbeiten.

API mithilfe von Kategorien taggen

Mithilfe von Kategorien können App-Entwickler ähnliche APIs finden. Siehe auch Kategorien verwalten.

So taggen Sie eine API mit Kategorien:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.

  5. Klicken Sie auf das Feld Kategorien und führen Sie einen der folgenden Schritte aus:

    • Wählen Sie eine Kategorie aus der Drop-down-Liste aus.
    • Fügen Sie eine neue Kategorie hinzu, indem Sie ihre Bezeichnung eingeben und die Eingabetaste drücken. Die neue Kategorie wird der Seite Kategorien hinzugefügt und bereitgestellt, sobald Sie weitere APIs hinzufügen oder bearbeiten.

  6. Wiederholen Sie diese Schritte, um die API mehreren Kategorien zuzuordnen.

  7. Klicken Sie auf Speichern.

curl

Fügen Sie Folgendes in den Aufruf von update ein:

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

Verwenden Sie den Befehl list categories, um die Kategorien-ID-Nummern abzurufen.

So bearbeiten Sie die API:

  1. Verwenden Sie den Aufruf organizations.sites.apidocs.get, um die aktuellen Werte zurückzugeben:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Verwenden Sie den Aufruf organizations.sites.apidocs.update, um die API zu bearbeiten. Fügen Sie die änderbaren Werte ein, die Sie beibehalten und die Sie ändern möchten. Wenn Sie eine änderbare Einstellung weglassen, wird der Standardwert verwendet.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlasten finden Sie unter API bearbeiten.

Angezeigten Titel und Beschreibung bearbeiten

So bearbeiten Sie den angezeigten Titel und die Beschreibung:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.
  5. Bearbeiten Sie nach Bedarf die Felder Titel anzeigen und Beschreibung anzeigen.
  6. Klicken Sie auf Speichern.

curl

Fügen Sie Folgendes in den Aufruf von update ein:

  "title": "TITLE",              # Display title
  "description": "DESCRIPTION",  # Display description

So bearbeiten Sie die API:

  1. Verwenden Sie den Aufruf organizations.sites.apidocs.get, um die aktuellen Werte zurückzugeben:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Verwenden Sie den Aufruf organizations.sites.apidocs.update, um die API zu bearbeiten. Fügen Sie die änderbaren Werte ein, die Sie beibehalten und die Sie ändern möchten. Wenn Sie eine änderbare Einstellung weglassen, wird der Standardwert verwendet.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlasten finden Sie unter API bearbeiten.

API entfernen

So entfernen Sie eine API aus dem Portal:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Wählen Sie den Tab APIs aus, falls noch nicht geschehen.
  3. Bewegen Sie den Mauszeiger in der Liste auf die API, um das Aktionsmenü einzublenden.
  4. Klicken Sie auf Löschen.

curl

So entfernen Sie eine API aus dem Portal mit organizations.sites.apidocs.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
  • API_DOC durch die generierte id des Dokuments. Beispiel: 399668. Verwenden Sie den Befehl list API docs, um diesen Wert zu finden.

Antwortnutzlast:

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

API-Dokumentation verwalten

In den folgenden Abschnitten wird beschrieben, wie Sie API-Dokumentation aktualisieren, herunterladen oder entfernen.

API-Dokumentation aktualisieren

Nach dem Veröffentlichen Ihrer API können Sie jederzeit eine neue Version des OpenAPI- oder GraphQL-Dokuments hochladen.

So laden Sie eine andere Version der API-Dokumentation hoch:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.
  5. Wählen Sie im Bereich API-Dokumentation eine der folgenden Optionen aus:
    • OpenAPI-Dokument
    • GraphQL-Schema
  6. Klicken Sie auf Dokument auswählen und wählen Sie die neueste Version des Dokuments aus.
  7. Geben Sie für GraphQL die Endpunkt-URL an.
  8. Klicken Sie auf Speichern.

curl

So aktualisieren Sie den Inhalt von OpenAPI oder GraphQL-Dokumentation mit organizations.sites.apidocs.updateDocumentation:

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
  • API_DOC durch die generierte id des Dokuments. Beispiel: 399668. Verwenden Sie den Befehl list API docs, um diesen Wert zu finden.
  • DISPLAY_NAME durch den Anzeigenamen der API-Dokumentation. Beispiel: Hello World 2
  • CONTENTS durch den base64-codierten String der Inhalte der API-Dokumentation. Die meisten Entwicklungsumgebungen enthalten ein Dienstprogramm zur base64-Konvertierung, aber es gibt auch viele Tools zur Online-Konvertierung.

Antwortnutzlast:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
  • API_DOC durch die generierte id des Dokuments. Beispiel: 399668. Verwenden Sie den Befehl list API docs, um diesen Wert zu finden.
  • DISPLAY_NAME durch den Anzeigenamen der API-Dokumentation. Beispiel: Hello World 2
  • ENDPOINT_URI durch den Domainnamen Ihres Endpunkt-URI. Beispiel: https://demo.google.com/graphql
  • CONTENTS durch den base64-codierten String der Inhalte der API-Dokumentation. Die meisten Entwicklungsumgebungen enthalten ein Dienstprogramm zur base64-Konvertierung, aber es gibt auch viele Tools zur Online-Konvertierung.

Antwortnutzlast:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

Die API-Referenzdokumentation wird aus dem Dokument gerendert und der API-Seite des Live-Portals hinzugefügt.

API-Dokumentation herunterladen

Nach dem Veröffentlichen Ihrer API können Sie jederzeit die auf Ihrem Portal veröffentlichte OpenAPI- oder GraphQL-Referenzdokumentation herunterladen.

So laden Sie die API-Dokumentation mit organizations.sites.apidocs.getDocumentation herunter:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.

  • API_DOC durch die generierte id des Dokuments. Beispiel: 399668. Verwenden Sie den Befehl list API docs, um diesen Wert zu finden.

    Antwortnutzlast:

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

Dabei gilt:

contents: Der base64-codierte Inhalt der API-Dokumentation.

API-Dokumentation entfernen

So entfernen Sie die API-Dokumentation:

Console

  1. Rufen Sie den API-Katalog auf.
  2. Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
  3. Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
  4. Klicken Sie auf  Bearbeiten.
  5. Wählen Sie im Bereich API-Dokumentation die Option Keine Dokumentation aus.
  6. Klicken Sie auf Speichern.

curl

Wenn Sie API-Dokumentinhalte mithilfe einer API entfernen möchten, löschen Sie die vorhandenen Einstellungen durch Senden eines leeren Anfragetexts.

So senden Sie einen leeren Anfragetext und löschen vorhandene Inhalte mit organizations.sites.apidocs.updateDocumentation:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
  • API_DOC durch die generierte id des Dokuments. Beispiel: 399668. Verwenden Sie den Befehl list API docs, um diesen Wert zu finden.

Antwortnutzlast:

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

Kategorien verwalten

Taggen Sie die API mithilfe von Kategorien, damit App-Entwickler ähnliche APIs auf der API-Seite des Live-Portals finden können. Fügen Sie Kategorien hinzu und verwalten Sie sie, wie in den folgenden Abschnitten beschrieben.

Kategorien entdecken

Verwenden Sie die Console oder den Befehl curl, um Kategorien aufzurufen.

Console

So rufen Sie die Seite „Kategorien“ auf:

  1. Wählen Sie Veröffentlichen > Portale und anschließend dein Portal aus.
  2. Klicken Sie auf der Startseite des Portals auf API-Katalog.
    Alternativ können Sie im Drop-down-Menü des Portals im oberen Navigationsmenü die Option API-Katalog auswählen.

  3. Klicken Sie auf den Tab Kategorien. Auf dem Tab Kategorien im API-Katalog wird die Liste der Kategorien angezeigt, die für Ihr Portal festgelegt wurden.

    Grafik: Tab „Kategorien“ mit dem Namen der Kategorie sowie den Namen und der Gesamtzahl der zugewiesenen APIs

    Grafik: Tab „Kategorien“ mit dem Namen der Kategorie sowie den Namen und der Gesamtzahl der zugewiesenen APIs

    Wie bereits erwähnt, können Sie auf der Seite „APIs“ Folgendes tun:

curl

So listen Sie Kategorien mit organizations.sites.apicategories.list auf:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.

Antwortnutzlast:

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

Dabei gilt:

  • id:: die ID des Kategorieelements. Beispiel: 61c1014c-89c9-40e6-be3c-69cca3505620.

Kategorie hinzufügen

So fügen Sie eine Kategorie hinzu:

Console

  1. Rufen Sie die Seite „Kategorien“ auf.
  2. Klicken Sie auf Hinzufügen.
  3. Geben Sie den Namen Ihrer neuen Kategorie ein.
  4. Optional können Sie eine oder mehrere APIs auswählen, die mit der Kategorie versehen werden sollen.
  5. Klicken Sie auf Erstellen.

curl

So fügen Sie eine Kategorie mit organizations.sites.apicategories.create hinzu:

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
  • CATEGORY_NAME durch den Namen der Kategorie. Beispiel: demo-backend.

Antwortnutzlast:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

Kategorie bearbeiten

So bearbeiten Sie eine Kategorie:

Console

  1. Rufen Sie die Seite „Kategorien“ auf.
  2. Bewegen Sie den Mauszeiger auf die Kategorie, die Sie bearbeiten möchten, damit das Aktionsmenü eingeblendet wird.
  3. Klicken Sie auf  Bearbeiten.
  4. Bearbeiten Sie den Namen der Kategorie.
  5. Fügen Sie API-Tags hinzu oder entfernen Sie sie.
  6. Klicken Sie auf Speichern.

curl

So bearbeiten Sie eine Kategorie mit organizations.sites.apicategories.patch:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
  • CATEGORY_ID durch die ID der Kategorie. Beispiel: bf6505eb-2a0f-47af-a00a-ded40ac72960. Die Kategorie-ID erhalten Sie mit dem Befehl API-Listen auflisten.
  • CATEGORY_NAME durch den Namen der Kategorie. Beispiel: demo-backend.

Antwortnutzlast:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

Kategorie löschen

Wenn Sie eine Kategorie löschen, werden auch alle API-Tags für diese Kategorie gelöscht.

So löschen Sie eine Kategorie:

Console

  1. Rufen Sie die Seite „Kategorien“ auf.
  2. Bewegen Sie den Mauszeiger auf die Kategorie, die Sie bearbeiten möchten, damit das Aktionsmenü eingeblendet wird.
  3. Klicken Sie auf Löschen.
  4. Klicken Sie zur Bestätigung auf Löschen.

curl

So löschen Sie eine Kategorie mit organizations.sites.apicategories.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

Ersetzen Sie Folgendes:

  • ORG_NAME durch den Namen der Organisation. Beispiel: my-org.
  • SITE_ID durch den Namen des Portals im Format ORG_NAME-PORTAL_NAME, wobei ORG_NAME der Name der Organisation und PORTAL_NAME der Portalname ist, konvertiert in nur Kleinbuchstaben und ohne Leerzeichen und Bindestriche. Beispiel: my-org-myportal.
  • CATEGORY_ID durch die ID der Kategorie. Beispiel: bf6505eb-2a0f-47af-a00a-ded40ac72960. Die Kategorie-ID erhalten Sie mit dem Befehl API-Listen auflisten.

Antwortnutzlast:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

Probleme mit veröffentlichten APIs beheben

In den folgenden Abschnitte erfahren Sie, wie Sie bestimmter Fehler bei unseren veröffentlichten APIs beheben.

Fehler: Abrufen des Fehlers bei Verwendung dieser API fehlgeschlagen

Wenn bei API testen der Fehler TypeError: Failed to fetch zurückgegeben wird, kann das folgende Ursachen haben:

  • Fehler aufgrund gemischter Inhalte werden möglicherweise durch ein bekanntes Problem mit der Swagger UI verursacht. Sie können das Problem möglicherweise umgehen, wenn Sie in der schemes-Definition Ihres OpenAPI-Dokuments HTTPS vor HTTP angeben. Beispiel:

    schemes:
   - https
   - http

  • Prüfen Sie bei Fehlern aufgrund von CORS-Einschränkungen (Cross-Origin Resource Sharing), ob Ihre API-Proxys CORS unterstützen. CORS ist ein Standardmechanismus, der clientseitige Cross-Origin-Anfragen ermöglicht. Siehe API-Proxy zur Unterstützung des Bereichs „API testen“ konfigurieren.

Fehler: Anfrageheaderfeld nicht zulässig

Wenn Sie bei Verwendung von API testen einen Request header field not allowed-Fehler wie im folgenden Beispiel erhalten, müssen Sie möglicherweise die in der CORS-Richtlinie unterstützten Header aktualisieren. Beispiel:

field content-type is not allowed by Access-Control-Allow-Headers in preflight
response

In diesem Beispiel müssen Sie den Abschnitt content-type in den Abschnitt Access-Control-Allow-Headers der CORS-AssignMessage-Richtlinie einfügen, wie unter CORS-Richtlinie an einen neuen API-Proxy anhängen beschrieben.

Fehler: Zugriff verweigert, wenn ein API-Proxy mit OAuth 2.0 aufgerufen wird

Die OAuthV2-Richtlinie der Google Cloud Console gibt eine Tokenantwort zurück, die bestimmte nicht RFC-konforme Attribute enthält. Die Richtlinie gibt beispielsweise ein Token mit dem Wert BearerToken anstelle des erwarteten RFC-konformen Werts Bearer zurück. Diese ungültige token_type-Antwort kann bei Verwendung von „API testen“ zu einem Access denied-Fehler führen.

Zur Behebung dieses Problems können Sie eine JavaScript- oder AssignMessage-Richtlinie erstellen, um die Richtlinienausgabe in ein konformes Format umzuwandeln. Weitere Informationen finden Sie unter Nicht RFC-konformes Verhalten.