Die Discovery API stellt eine Liste von Google APIs bereit, über die für jede API maschinenlesbare Metadaten für „Discovery-Dokumente“ abgerufen werden können.
Dieses Dokument richtet sich an Entwickler, die Clientbibliotheken, IDE-Plug-ins und andere Tools zur Interaktion mit Google APIs schreiben möchten.
Hintergrund für Discovery Service
Konzepte
Der Google APIs Discovery Service basiert auf zwei grundlegenden Konzepten:
- API-Verzeichnis: Eine Liste aller APIs, die vom APIs Discovery Service unterstützt werden. Jeder Verzeichniseintrag enthält Details zu einer unterstützten API, einschließlich Name, einer kurzen Beschreibung der API und eines Dokumentationslinks. Eine API kann mehrere Verzeichniseinträge enthalten, einen für jede unterstützte Version.
- Discovery-Dokument: Eine maschinenlesbare Beschreibung einer bestimmten API. Das Discovery-Dokument beschreibt die Oberfläche für eine bestimmte API-Version. Das Dokument enthält Details dazu, wie Sie über RESTful-HTTP-Aufrufe auf die verschiedenen Methoden der einzelnen APIs zugreifen. Ein Discovery-Dokument enthält Beschreibungen der mit der API verknüpften Daten und Methoden sowie Informationen zu verfügbaren OAuth-Bereichen und Beschreibungen von Schemas, Methoden, Parametern und verfügbaren Parameterwerten.
Datenmodell
Eine Ressource ist ein individuelles Datenobjekt mit einer eindeutigen ID. Der Google APIs Discovery Service arbeitet basierend auf den oben genannten Konzepten mit zwei Arten von Ressourcen.
APIs Directory List: Eine Liste von APIs
Jeder Verzeichniseintrag enthält ein API-Paar name/version mit den folgenden Informationen:
- Identifikations- und Beschreibungsinformationen: Name, Version, Titel und Beschreibung.
- Dokumentationsinformationen: Symbole und ein Link zur Dokumentation.
- Statusinformationen: einschließlich Statuslabels, und eine Angabe dazu, ob dies die bevorzugte Version der API ist.
-
Link zum Discovery-Dokument: Der URI des Discovery-Dokuments für diese API (als vollständige URL angegeben, z. B.
https://serviceusage.googleapis.com/$discovery/rest?version=v1).
Discovery-Dokumentressource: Eine maschinenlesbare Beschreibung einer bestimmten API
Neben den Informationen im APIs-Verzeichnis enthält ein Discovery-Dokument Folgendes:
- Schemas: Eine Liste von API-Ressourcenschemata, die die Daten beschreiben, auf die Sie in jeder API zugreifen können. Die Schemas des Google APIs Discovery Service basieren auf dem JSON Schema.
- Methoden, einschließlich einer Liste der API-Methoden und der verfügbaren Parameter für jede Methode.
- OAuth-Bereiche: Die Liste der für diese API verfügbaren OAuth-Bereiche.
- Inline-Dokumentation mit kurzen Beschreibungen von Schemas, Methoden, Parametern und verfügbaren Parameterwerten.
Die einzelne Verzeichnissammlung ist der konzeptionelle Container der einzelnen API-Verzeichnisressource und der Discovery-Dokumentressourcen für jede unterstützte API.
Abläufe
Sie können zwei verschiedene Methoden für Sammlungen und Ressourcen im Google APIs Discovery Service aufrufen, wie in der folgenden Tabelle beschrieben.
| Vorgang | Beschreibung | REST-HTTP-Zuordnungen |
|---|---|---|
| list | Liste aller unterstützten APIs. | GET für den URI der Verzeichnisressource. |
Aufrufstil
REST
Die unterstützten Vorgänge des Google APIs Discovery Service sind dem REST-HTTP-GET-Verb direkt zugeordnet, wie unter Vorgänge beschrieben.
Für URIs des Google APIs Discovery Service gelten folgende spezielle Formate:
https://API/$discovery/rest?version=VERSION
Dabei ist API die Kennung für eine Discovery-Dokumentressource und VERSION die Kennung der jeweiligen API-Version.
Hier einige Beispiele dafür, wie das im Google APIs Discovery Service funktioniert.
Listen Sie alle von Google APIs Discovery Service unterstützten APIs auf:
GET https://discovery.googleapis.com/discovery/v1/apis
Jetzt im APIs Explorer ausprobieren!
Rufen Sie das Discovery-Dokument für die Service Usage API, Version 1 ab:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1