Dieses Dokument richtet sich an Entwickler, die Clientbibliotheken, IDE-Plug-ins und andere Tools für die Interaktion mit Google APIs schreiben möchten. Mit dem Google APIs Discovery Service können Sie all das tun, indem Sie maschinenlesbare Metadaten zu anderen Google APIs über eine einfache API bereitstellen. Dieser Leitfaden bietet einen Überblick über die einzelnen Abschnitte des Discovery-Dokuments sowie nützliche Tipps zur Verwendung des Dokuments.
Alle Aufrufe der API sind nicht authentifizierte, JSON-basierte REST-Anfragen, die SSL verwenden, d. h. URLs beginnen mit https.
Format des Discovery-Dokuments
In diesem Abschnitt erhalten Sie einen Überblick über das Discovery-Dokument.
In allen folgenden Beispielen wird das Discovery-Dokument der Service Usage API verwendet.
Sie können das Discovery-Dokument für die Service Usage API laden, indem Sie die folgende GET-Anfrage ausführen:
GET https://serviceusage.s3nsapis.fr/$discovery/rest?version=v1
Das Format eines Discovery-Dokuments enthält Informationen, die in sechs Hauptkategorien unterteilt sind:
- Grundlegende Beschreibung der API
- Authentifizierungsinformationen für die API.
- Ressourcen- und Schemadetails, die die Daten der API beschreiben.
- Details zu den Methoden der API
- Informationen zu allen benutzerdefinierten Features, die von der API unterstützt werden.
- Inline-Dokumentation, die die wichtigsten Elemente der API beschreibt.
Jeder dieser Abschnitte des Discovery-Dokuments wird unten beschrieben.
API-Beschreibung
Das Discovery-Dokument enthält eine Reihe von API-spezifischen Eigenschaften. Diese Eigenschaften werden nicht unbedingt in dieser Reihenfolge oder im selben Abschnitt des Discovery-Dokuments aufgeführt:
"id": "serviceusage:v1", "canonicalName": "Service Usage", "revision": "20240331", "servicePath": "", "baseUrl": "https://serviceusage.s3nsapis.fr/", "kind": "discovery#restDescription", "description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.", "ownerDomain": "google.com", "version_module": true, "version": "v1", "fullyEncodeReservedExpansion": true, "name": "serviceusage", "title": "Service Usage API", "discoveryVersion": "v1", "rootUrl": "https://serviceusage.s3nsapis.fr/", "protocol": "rest"
Diese Eigenschaften auf API-Ebene enthalten Details zu einer bestimmten Version einer API, einschließlich name, version, title und description. protocol hat immer einen festen Wert von rest, da der APIs Discovery Service nur RESTful-Methoden für den Zugriff auf die APIs unterstützt.
Das Feld servicePath gibt das Pfadpräfix für diese API-Version an.
Authentifizierung
Der Abschnitt auth enthält Details zu den OAuth 2.0-Authentifizierungsbereichen für die API. Weitere Informationen zur Verwendung von Bereichen mit OAuth 2.0 finden Sie im Hilfeartikel Mit OAuth 2.0 auf Google APIs zugreifen.
Der Abschnitt auth enthält einen verschachtelten Abschnitt oauth2 und scopes. Der Abschnitt scopes ist eine Schlüssel/Wert-Zuordnung vom Bereichswert zu weiteren Details zum Bereich:
"auth": { "oauth2": { "scopes": { "https://www.googleapis.com/auth/cloud-platform": { "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account." }, "https://www.googleapis.com/auth/cloud-platform.read-only": { "description": "View your data across Google Cloud services and see the email address of your Google Account" }, "https://www.googleapis.com/auth/service.management": { "description": "Manage your Google API service configuration" } } } }
Im Abschnitt auth werden nur die Bereiche für eine bestimmte API definiert. Informationen zum Verknüpfen dieser Bereiche mit einer API-Methode finden Sie unten im Abschnitt „Methoden“.
Ressourcen und Schemas
Die Vorgänge einer API wirken sich auf Datenobjekte aus, die resources genannt werden. Das Discovery-Dokument basiert auf dem Konzept der Ressourcen. Jedes Discovery-Dokument enthält einen Abschnitt resources auf oberster Ebene, in dem alle mit der API verknüpften Ressourcen gruppiert sind. Beispiel: Die Service Usage API hat eine services-Ressource und eine operations-Ressource unter resources der obersten Ebene:
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods associated with the operations resource } }
In jedem Ressourcenabschnitt befinden sich die mit dieser Ressource verknüpften Methoden. Die Service Usage API hat beispielsweise sechs Methoden mit der Ressource services verknüpft: get, enable, disable, batchGet, batchEnable und list.
Schemas geben Aufschluss darüber, wie die Ressourcen in einer API aussehen. Jedes Discovery-Dokument enthält den Abschnitt schemas auf oberster Ebene, der ein Name/Wert-Paar aus Schema-ID und Objekt enthält. Schema-IDs sind für jede API eindeutig und werden verwendet, um das Schema im Abschnitt methods des Discovery-Dokuments eindeutig zu identifizieren. Hier sind einige der Schemas im Discovery-Dokument der Service Usage API:
"schemas": { "Method": { // JSON schema of the Method resource }, "Authentication": { // JSON schema of the Authentication resource }, "RubySettings": { // JSON schema of the RubySettings resource }, "EnableServiceResponse": { // JSON schema of the EnableServiceResponse resource } }
Der APIs Discovery Service verwendet JSON Schema draft-03 für seine Schemadarstellungen. Im Folgenden ist ein Snippet des JSON-Schemas für die EnableServiceResponse-Ressource zusammen mit der GoogleApiServiceusagev1Service, auf die es verweist. Neben diesen Schemas ist ein Teil einer tatsächlichen Antwort auf eine Anfrage zur Aktivierung der Pub/Sub API (pubsub.googleapis.com) zu sehen.
EnableServiceResponse JSON-Schema für Ressourcen: |
Tatsächliche Antwort zum Aktivieren eines Dienstes: |
"EnableServiceResponse": { "id": "EnableServiceResponse", "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.", "properties": { "service": { "description": "The new state of the service after enabling.", "$ref": "GoogleApiServiceusageV1Service" } }, "type": "object" }, "GoogleApiServiceusageV1Service": { "description": "A service that is available for use by the consumer.", "properties": { "config": { "$ref": "GoogleApiServiceusageV1ServiceConfig", "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method." }, "name": { "type": "string", "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com" }, " |
"response": { "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse", "service": { "name": "projects/232342569935/services/pubsub.googleapis.com", "config": { "name": "pubsub.googleapis.com", "title": "Cloud Pub/Sub API", "documentation": { "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n" }, "quota": {}, "authentication": {}, "usage": { "requirements": [ "serviceusage.googleapis.com/tos/cloud" ] }, "monitoring": {} }, " |
Die fett formatierten Felder zeigen die Zuordnung zwischen dem JSON-Schema und der tatsächlichen Antwort.
Wie in diesem Beispiel gezeigt, können Schemas Verweise auf andere Schemas enthalten. Wenn Sie eine Clientbibliothek erstellen, können Sie so die Objekte einer API in Ihren Datenmodellklassen effektiv modellieren. Im obigen Beispiel EnableServiceResponse ist das Attribut service ein Verweis auf ein Schema mit der ID GoogleApiServiceusageV1Service, einem anderen Schema im Service Usage API Discovery-Dokument. Sie können das Attribut GoogleApiServiceusageV1Service in der Ressource EnableServiceResponse durch den Wert des Schemas GoogleApiServiceusageV1Service ersetzen. Beachten Sie dabei, dass die $ref-Syntax stammt von der JSON-Schemaspezifikation kommt.
Methoden können auch auf Schemas verweisen, wenn sie ihre Anfrage- und Antworttexte angeben. Weitere Informationen finden Sie im Abschnitt Methoden.
Methoden
Der Kern des Discovery-Dokuments basiert auf Methoden. Methoden sind die Vorgänge, die in einer API ausgeführt werden können. Sie finden den Abschnitt methods in verschiedenen Bereichen des Discovery-Dokuments, etwa auf der obersten Ebene (die Methoden der API-Ebene genannt) oder auf der Ebene resources.
"methods": { // API-level methods } "resources": { "resource1": { "methods": { // resource-level methods } "resources": { "nestedResource": { "methods": { // methods can even be found in nested-resources } } } } }
Eine API kann Methoden auf API-Ebene enthalten, eine Ressource muss jedoch den Abschnitt methods haben.
Jeder methods-Abschnitt ist eine Schlüssel/Wert-Zuordnung vom Methodennamen zu anderen Details zu dieser Methode. Im folgenden Beispiel werden drei Methoden dokumentiert: get, enable und disable:
"methods": { "get": { //details about the "get" method }, "enable": { //details about the "enable" method }, "disable": { //details about the "disable" method } }
Schließlich werden im Abschnitt der einzelnen Methoden verschiedene Attribute zu dieser Methode beschrieben. Hier ein Beispiel für die enable-Methode:
"enable": { "path": "v1/{+name}:enable", "request": { "$ref": "EnableServiceRequest" }, "parameterOrder": [ "name" ], "id": "serviceusage.services.enable", "response": { "$ref": "Operation" }, "description": "Enable a service so that it can be used with a project.", "httpMethod": "POST", "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable", "scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/service.management" ], "parameters": { "name": { "location": "path", "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.", "required": true, "type": "string", "pattern": "^[^/]+/[^/]+/services/[^/]+$" } } },
Dieser Abschnitt enthält allgemeine Methodendetails wie einen eindeutigen ID zur Identifizierung der Methode, den zu verwendenden httpMethod und den path der Methode. Weitere Informationen zur Verwendung des Attributs path, um die vollständige Methoden-URL zu berechnen, finden Sie im Abschnitt Anfrage erstellen. Zusätzlich zu diesen allgemeinen Methodeneigenschaften gibt es einige Eigenschaften, die die Methode mit anderen Abschnitten im Discovery-Dokument verknüpfen:
Bereiche
Der Abschnitt auth, der bereits in dieser Dokumentation definiert wurde, enthält Informationen zu allen Bereichen, die von einer bestimmten API unterstützt werden. Wenn eine Methode einen dieser Bereiche unterstützt, enthält sie ein scopes-Array. Dieses Array enthält einen Eintrag für jeden Gültigkeitsbereich, der von der Methode unterstützt wird.
Die Auswahl eines Authentifizierungsbereichs für Ihre Anwendung hängt von verschiedenen Faktoren ab, z. B. von den aufgerufenen Methoden und den mit der Methode gesendeten Parametern. Daher bleibt die Entscheidung, welcher Bereich verwendet werden soll, dem Entwickler überlassen. Es werden nur Dokumente mit Gültigkeitsbereichen für eine Methode ermittelt.
Anfrage und Antwort
Wenn die Methode einen Anfrage- oder Antworttext hat, werden diese jeweils in den Abschnitten request oder response dokumentiert. Beispielsweise gibt der Inhalt des Abschnitts request für die Methode enable an, dass die Anfrage der Methode durch ein JSON-Schema mit der ID EnableServiceRequest definiert wird. Dieses Schema finden Sie im Abschnitt „Schemas der obersten Ebene“.
Parameter
Wenn eine Methode Parameter enthält, die vom Nutzer angegeben werden sollen, werden diese Parameter im Abschnitt parameters auf Methodenebene dokumentiert. Dieser Abschnitt enthält eine Schlüssel/Wert-Zuordnung des Parameternamens zu weiteren Details zu diesem Parameter.
Für die Methode enable gibt es beispielsweise einen Parameter: name.
Die Parameter können entweder in path oder die URL-query eingefügt werden. Das Attribut location gibt an, wo die Clientbibliothek den Parameter einfügen soll.
Es gibt viele weitere Attribute, die den Parameter beschreiben, darunter die Parameterdaten type (nützlich für Sprachen mit starker Typisierung), ob der Parameter required ist und ob es sich um einen Enum-Parameter handelt. Weitere Informationen zu diesen Attributen finden Sie in der Referenzdokumentation zu dieser API.
Parameterreihenfolge
Clientbibliotheken können ihre Schnittstellen auf viele Arten strukturieren. Eine Möglichkeit besteht darin, eine Methode mit jedem API-Parameter in der Methodensignatur zu haben. Da JSON jedoch ein ungeordnetes Format ist, ist es schwierig, programmatisch zu wissen, wie die Parameter in der Methodensignatur angeordnet werden. Das parameterOrder-Array bietet eine feste Parameterreihenfolge für Anfragen. Das Array listet die Namen jedes Parameters in der Reihenfolge ihrer Bedeutung auf. Es kann entweder Pfad- oder Abfrageparameter enthalten, aber jeder Parameter im Array ist erforderlich.
Medienupload
Wenn eine Methode das Hochladen von Medien wie Bildern, Audio oder Video unterstützt, werden der Speicherort und die Protokolle, die für das Hochladen dieser Medien unterstützt werden, im Abschnitt mediaUpload dokumentiert. Dieser Abschnitt enthält Details zu den unterstützten Uploadprotokollen und Informationen dazu, welche Arten von Medien hochgeladen werden können.
Die Methode enable enthält keinen Abschnitt mediaUpload. Ein typischer mediaUpload-Abschnitt könnte jedoch so aussehen:
"supportsMediaUpload": true, "mediaUpload": { "accept": [ "image/*" ], "maxSize": "10MB", "protocols": { "simple": { "multipart": true, "path": "/upload/storage/v1beta1/b/{bucket}/o" }, "resumable": { "multipart": true, "path": "/resumable/upload/storage/v1beta1/b/{bucket}/o" } } }
Im obigen Beispiel ist das Attribut supportsMediaUpload ein boolescher Wert, der bestimmt, ob die Methode das Hochladen von Medien unterstützt. Wenn der Wert „true“ ist, werden im Abschnitt mediaUpload die Medienarten dokumentiert, die hochgeladen werden können.
Das Attribut accept ist eine Liste von Medienbereichen, die bestimmen, welche MIME-Typen hochgeladen werden können. Der im obigen Beispiel gezeigte Endpunkt akzeptiert jedes Bildformat.
Die Property maxSize hat die maximale Größe eines Uploads. Der Wert ist ein String in den Einheiten MB, GB oder TB. Im Beispiel oben sind Uploads auf eine maximale Größe von 10 MB beschränkt.
Beachten Sie, dass dieser Wert nicht das verbleibende Speicherkontingent eines einzelnen Nutzers für diese API widerspiegelt. Selbst wenn der Upload kleiner als maxSize ist, sollte die Clientbibliothek trotzdem auf einen Upload vorbereitet sein, der wegen unzureichenden Speicherplatzes fehlschlägt.
Im Abschnitt protocols werden die von einer Methode unterstützten Uploadprotokolle aufgelistet. Beim simple-Protokoll werden die Medien einfach in einer einzigen HTTP-Anfrage per POST an den angegebenen Endpunkt gesendet. Das Protokoll resumable impliziert, dass der im URI path angegebene Endpunkt das Protokoll für fortsetzbare Uploads unterstützt. Wenn das Attribut multipart den Wert true hat, akzeptiert der Endpunkt mehrteilige Uploads. Dies bedeutet, dass sowohl die JSON-Anfrage als auch die Medien in einem mehrteiligen/verwandten Text zusammengefasst und zusammen gesendet werden können. Sowohl das simple- als auch das resumable-Protokoll können mehrere Uploads unterstützen.
Die path-Eigenschaft ist eine URI-Vorlage und sollte genau wie die path-Eigenschaft für die Methode erweitert werden, wie im Abschnitt Anfrage erstellen beschrieben.
Mediendownload
Wenn eine Methode das Herunterladen von Medien wie Bildern, Audio oder Video unterstützt, wird dies durch den Parameter supportsMediaDownload angegeben:
"supportsMediaDownload": true,
Beim Herunterladen von Medien müssen Sie den Abfrageparameter alt in der Anfrage-URL auf media setzen.
Wenn das Attribut useMediaDownloadService der API-Methode true lautet, fügen Sie /download vor servicePath ein, um eine Weiterleitung zu vermeiden. Der Downloadpfad ist beispielsweise /download/youtube/v3/captions/{id}, wenn die Verkettung von servicePath und path /youtube/v3/captions/{id} ist. Es wird empfohlen, Mediendownload-URL mit /download zu erstellen, auch wenn useMediaDownloadService auf „false“ gesetzt ist.
Häufige Parameter
Das Discovery-Dokument der obersten Ebene enthält ein parameters-Attribut. Dieser Abschnitt ähnelt dem Abschnitt „Parameter“ für jede Methode. Diese Parameter können jedoch auf jede Methode in der API angewendet werden.
Beispielsweise können die Methoden get und list der Service Usage API einen prettyPrint-Parameter in den Anfrageparametern enthalten, der die Antwort für alle diese Methoden in einem von einem Menschen lesbaren Format formatiert. Im Folgenden finden Sie eine Liste der häufigsten Parameter:
| Parameter | Bedeutung | Hinweise | Gültigkeit |
|---|---|---|---|
access_token |
OAuth 2.0-Token für den aktuellen Nutzer |
|
|
alt |
Datenformat für die Antwort. |
|
|
callback |
Callback-Funktion |
|
|
fields |
Auswahl, mit der eine Teilmenge von Feldern angegeben wird, die in der Antwort enthalten sein soll. |
|
|
key |
API-Schlüssel (ERFORDERLICH) |
|
|
prettyPrint |
Gibt die Antwort mit Einzügen und Zeilenumbrüchen zurück. |
|
|
quotaUser |
Alternative zu userIp. |
|
|
userIp |
IP-Adresse des Endnutzers, für den der API-Aufruf durchgeführt wird. |
|
Inline-Dokumentation
Jedes Discovery-Dokument ist mit einer Reihe von description-Feldern annotiert, die eine Inline-Dokumentation für die API bereitstellen. Die description-Felder finden Sie für die folgenden API-Elemente:
- API selbst
- OAuth-Bereiche
- Ressourcenschemas
- API-Methoden
- Parameter der Methode:
- Zulässige Werte für bestimmte Parameter
Diese Felder sind besonders nützlich, wenn Sie mit dem Google APIs Discovery Service eine für Menschen lesbare Dokumentation für eine Clientbibliothek generieren möchten, z. B. JavaDoc.