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:
- Wählen Sie das API-Produkt aus, das Sie in Ihrem Portal veröffentlichen möchten.
- 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
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.
Klicken Sie auf curl
-Aufruf- und Codebeispiele in verschiedenen Formaten ansehen, z. B. HTTP, Python, Node.js usw. (siehe unten).
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.
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:
|
oauth 2.0 |
|
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:
- Wählen Sie Veröffentlichen > Portale und anschließend dein Portal aus.
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.Wie bereits erwähnt, können Sie auf dem Tab „APIs“ Folgendes tun:
- Details der auf Ihrem Portal verfügbaren APIs ansehen
- API zum Portal hinzufügen
- Eine API auf Ihrem Portal bearbeiten, indem Sie eine oder mehrere der folgenden Aufgaben ausführen:
- API aus dem Portal entfernen
- Kategorien verwalten
- Verwaiste APIs finden, deren zugehöriges API-Produkt aus der Google Cloud Console entfernt wurde, und Neuerstellung des API-Produkts bzw. Löschen der API aus dem Portal
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, wirdnextPageToken
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" }
-
PAGE_SIZE durch die Anzahl der Listenelemente, die auf einer Seite zurückgegeben werden sollen.
Beispiel:
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
-
PAGE_SIZE durch die Anzahl der Listenelemente, die auf einer Seite zurückgegeben werden sollen.
Beispiel:
API hinzufügen
So fügen Sie Ihrem Portal eine API hinzu:
Console
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
Klicken Sie auf
Hinzufügen.Das Dialogfeld API-Produkt zum Katalog hinzufügen wird angezeigt.
Wählen Sie das API-Produkt aus, das Sie dem Portal hinzufügen möchten.
Klicken Sie auf Weiter. Die Seite API-Details wird angezeigt.
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:
- Wählen Sie OpenAPI-Dokument aus.
- Klicken Sie auf Dokument auswählen.
- 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.
- Klicken Sie auf Auswählen.
So verwenden Sie ein GraphQL-Schema:
- Wählen Sie GraphQL-Schema.
- Klicken Sie auf Dokument auswählen.
- Rufen Sie das GraphQL-Schema auf und wählen Sie es aus.
- 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.
Sichtbarkeit 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.
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
oderfalse
(Standard), wobeitrue
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
oderfalse
(Standard), wobeitrue
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
oderfalse
(Standard), wobeitrue
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
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
- Nehmen Sie unter API-Details die gewünschten Änderungen vor. Eine Beschreibung der Optionen finden Sie unter API hinzufügen.
- 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.
Rufen Sie mit
organizations.sites.apidocs/list
eine Liste der APIs in Ihrem Portal ab, um die generierteid
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
.
-
ORG_NAME durch den Namen der Organisation. Beispiel:
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" } }
-
ORG_NAME durch den Namen der Organisation. Beispiel:
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 für dieses Beispiel die Einstellungpublished
vontrue
infalse
: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
oderfalse
(Standard), wobeitrue
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
oderfalse
(Standard), wobeitrue
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" } }
-
TITLE durch den Anzeigetitel. Beispiel:
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
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
- 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.
- Klicken Sie auf Speichern.
curl
Nehmen Sie in den Aufruf update
eine der folgenden Optionen auf:
"published": true, # API is published to your portal "published": false, # API is not published in your portal
So bearbeiten Sie die API:
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)"
Verwenden Sie zum Bearbeiten der API den Aufruf
organizations.sites.apidocs.update
. Fügen Sie die änderbaren Werte hinzu, die Sie beibehalten möchten, und ändern Sie die Werte, 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", }'
Unter API bearbeiten finden Sie ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlast.
Sichtbarkeit einer API verwalten
Verwalten Sie die Sichtbarkeit einer API in Ihrem Portal durch Gewähren des Zugriffs für:
- Öffentlich (für jeden sichtbar)
- Authentifizierte Nutzer
Ausgewählte Zielgruppen, wenn Sie sich für die Betaversion der Funktion zur Zielgruppenverwaltung angemeldet haben
So verwalten Sie die Sichtbarkeit einer API in Ihrem Portal:
Console
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
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.
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 noch nicht für die Zielgruppenverwaltung angemeldet haben, wird die Sichtbarkeit mit anonAllowed
verwaltet.
Nehmen Sie in den Aufruf update
eine der folgenden Optionen auf:
# 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:
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)"
Verwenden Sie zum Bearbeiten der API den Aufruf
organizations.sites.apidocs.update
. Fügen Sie die änderbaren Werte hinzu, die Sie beibehalten möchten, und ändern Sie die Werte, 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", }'
Unter API bearbeiten finden Sie ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlast.
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
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
- 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.
- Klicken Sie auf Speichern.
curl
Nehmen Sie in den Aufruf update
eine der folgenden Optionen auf:
"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:
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)"
Verwenden Sie zum Bearbeiten der API den Aufruf
organizations.sites.apidocs.update
. Fügen Sie die änderbaren Werte hinzu, die Sie beibehalten möchten, und ändern Sie die Werte, 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", }'
Unter API bearbeiten finden Sie ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlast.
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
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
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.Klicken Sie auf Speichern.
curl
Nehmen Sie Folgendes in den Aufruf update
auf:
# 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:
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)"
Verwenden Sie zum Bearbeiten der API den Aufruf
organizations.sites.apidocs.update
. Fügen Sie die änderbaren Werte hinzu, die Sie beibehalten möchten, und ändern Sie die Werte, 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", }'
Unter API bearbeiten finden Sie ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlast.
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
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
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.
Wiederholen Sie diese Schritte, um die API mehreren Kategorien zuzuordnen.
Klicken Sie auf Speichern.
curl
Nehmen Sie Folgendes in den Aufruf update
auf:
# 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:
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)"
Verwenden Sie zum Bearbeiten der API den Aufruf
organizations.sites.apidocs.update
. Fügen Sie die änderbaren Werte hinzu, die Sie beibehalten möchten, und ändern Sie die Werte, 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", }'
Unter API bearbeiten finden Sie ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlast.
Angezeigten Titel und Beschreibung bearbeiten
So bearbeiten Sie den angezeigten Titel und die Beschreibung:
Console
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
- Bearbeiten Sie nach Bedarf die Felder Titel anzeigen und Beschreibung anzeigen.
- Klicken Sie auf Speichern.
curl
Nehmen Sie Folgendes in den Aufruf update
auf:
"title": "TITLE", # Display title "description": "DESCRIPTION", # Display description
So bearbeiten Sie die API:
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)"
Verwenden Sie zum Bearbeiten der API den Aufruf
organizations.sites.apidocs.update
. Fügen Sie die änderbaren Werte hinzu, die Sie beibehalten möchten, und ändern Sie die Werte, 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", }'
Unter API bearbeiten finden Sie ein detailliertes Beispiel für die zurückgegebenen Schritte, Variablen und Nutzlast.
API entfernen
So entfernen Sie eine API aus dem Portal:
Console
- Rufen Sie den API-Katalog auf.
- Wählen Sie den Tab APIs aus, falls noch nicht geschehen.
- Bewegen Sie den Mauszeiger in der Liste auf die API, um das Aktionsmenü einzublenden.
- 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 die 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
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
- Wählen Sie im Bereich API-Dokumentation eine der folgenden Optionen aus:
- OpenAPI-Dokument
- GraphQL-Schema
- Klicken Sie auf Dokument auswählen und wählen Sie die neueste Version des Dokuments aus.
- Geben Sie für GraphQL die Endpunkt-URL an.
- Klicken Sie auf Speichern.
curl
So aktualisieren Sie den Inhalt der 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, 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, 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 OpenAPI- oder GraphQL-Referenzdokumentation herunterladen, die auf dem Portal veröffentlicht wurde.
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:
durch den base64-codierten String der Inhalte der API-Dokumentation.
API-Dokumentation entfernen
So entfernen Sie die API-Dokumentation:
Console
- Rufen Sie den API-Katalog auf.
- Klicken Sie auf den Tab APIs, falls er nicht bereits ausgewählt ist.
- Klicken Sie auf die Zeile der API, die Sie bearbeiten möchten.
- Klicken Sie auf Bearbeiten.
- Wählen Sie im Bereich API-Dokumentation die Option Keine Dokumentation aus.
- Klicken Sie auf Speichern.
curl
Wenn Sie den Inhalt eines API-Dokuments mithilfe einer API entfernen möchten, löschen Sie die vorhandenen Einstellungen, indem Sie einen leeren Anfragetext senden.
So senden Sie einen leeren Anfragetext und löschen vorhandenen Inhalt 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:
- Wählen Sie Veröffentlichen > Portale und anschließend dein Portal aus.
- 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. 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.
Wie bereits erwähnt, können Sie auf der Seite „APIs“ Folgendes tun:
- Kategorien und APIs ansehen, denen sie zugeordnet wurden
- Kategorie hinzufügen
- Kategorie bearbeiten
- Kategorie löschen
- In Ihrem Portal veröffentlichte APIs verwalten. Siehe APIs entdecken.
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
- Rufen Sie die Seite „Kategorien“ auf.
- Klicken Sie auf Hinzufügen.
- Geben Sie den Namen Ihrer neuen Kategorie ein.
- Optional können Sie eine oder mehrere APIs auswählen, die mit der Kategorie versehen werden sollen.
- 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
- Rufen Sie die Seite „Kategorien“ auf.
- Bewegen Sie den Mauszeiger auf die Kategorie, die Sie bearbeiten möchten, damit das Aktionsmenü eingeblendet wird.
- Klicken Sie auf Bearbeiten.
- Bearbeiten Sie den Namen der Kategorie.
- Fügen Sie API-Tags hinzu oder entfernen Sie sie.
- 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
- Rufen Sie die Seite „Kategorien“ auf.
- Bewegen Sie den Mauszeiger auf die Kategorie, die Sie bearbeiten möchten, damit das Aktionsmenü eingeblendet wird.
- Klicken Sie auf Löschen.
- 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.