Einführung
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 dies tun, indem maschinenlesbare Metadaten über andere Google APIs über eine einfache API verfügbar gemacht werden. Dieser Leitfaden bietet einen Überblick über die einzelnen Abschnitte des Discovery-Dokuments sowie nützliche Tipps zur Verwendung des Dokuments.
Alle API-Aufrufe sind nicht authentifizierte, JSON-basierte REST-Anfragen mit SSL, d.h. URLs beginnen mit https.
Wenn Sie mit den Konzepten von Google APIs Discovery Service nicht vertraut sind, sollten Sie den Artikel Erste Schritte lesen, bevor Sie mit dem Programmieren beginnen.
Format des Discovery-Dokuments
In diesem Abschnitt erhalten Sie einen Überblick über das Discovery-Dokument.
In allen Beispielen unten wird das Discovery-Dokument der Google Cloud Service Management API verwendet. Sie können das Discovery-Dokument für die Google Cloud Service Management API laden, indem Sie die folgende GET-Anfrage ausführen:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1Das Format eines Discovery-Dokuments umfasst sechs Hauptkategorien:
- Allgemeine Beschreibung der API.
- Informationen zur Authentifizierung für die API
- Ressourcen- und Schemadetails, in denen die API-Daten beschrieben werden.
- Details zu den API-Methoden
- Informationen zu benutzerdefinierten Funktionen, die von der API unterstützt werden.
- Inline-Dokumentation, in der die wichtigsten Elemente der API beschrieben werden
Jeder dieser Abschnitte im Discovery-Dokument wird unten beschrieben. Weitere Informationen zu den einzelnen Properties finden Sie in der Referenzdokumentation.
Grundlegende API-Beschreibung
Das Discovery-Dokument enthält eine Reihe von API-spezifischen Eigenschaften:
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
Diese API-Level-Properties enthalten Details zu einer bestimmten API-Version, einschließlich der 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 bestimmte 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 unter Mit OAuth 2.0 auf Google APIs zugreifen.
Der Abschnitt auth enthält die verschachtelten Bereiche oauth2 und scopes. Der Abschnitt scopes ist eine Schlüssel/Wert-Paar-Zuordnung vom Bereichswert zu weiteren Details zum Bereich:
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"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 zur Verknüpfung dieser Bereiche mit einer API-Methode finden Sie unten im Abschnitt Methoden.
Ressourcen und Schemas
API-Vorgänge wirken auf Datenobjekte mit dem Namen resources. Das Discovery-Dokument baut auf dem Konzept der Ressourcen auf. Jedes Discovery-Dokument hat einen resources-Abschnitt auf oberster Ebene, in dem alle mit der API verknüpften Ressourcen gruppiert sind. Beispiel: Die Google Cloud Service Management API hat eine services-Ressource und eine operations-Ressource unter der obersten resources. Die services-Ressource hat drei Unterressourcen, configs, rollouts und consumers:
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
In jedem Ressourcenabschnitt befinden sich die mit dieser Ressource verknüpften Methoden. Die Google Cloud Service Management API hat beispielsweise drei Methoden, die mit der Ressource services.rollouts verknüpft sind: get, list und create.
Schemas zeigen Ihnen, wie die Ressourcen in einer API aussehen. Jedes Discovery-Dokument hat einen schemas-Abschnitt auf oberster Ebene, der ein Name/Wert-Paar der Schema-ID des Objekts enthält. Schema-IDs sind pro API eindeutig und werden verwendet, um das Schema im Abschnitt methods des Discovery-Dokuments eindeutig zu identifizieren:
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
APIs Discovery Service verwendet JSON-Schema-03 für seine Schemadarstellungen. Hier sehen Sie ein Snippet des JSON-Schemas für die URL-Ressource sowie eine tatsächliche Antwortressource:
| JSON-Schema für Roll-out-Ressource: | Tatsächliche Ressourcenantwort für Roll-out: |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
Die fett formatierten Felder zeigen die Zuordnung zwischen dem JSON-Schema und der tatsächlichen Antwort.
Schemas können auch Verweise auf andere Schemas enthalten. Wenn Sie eine Clientbibliothek erstellen, können Sie damit die Objekte einer API in Ihren Datenmodellklassen effektiv modellieren. Im Beispiel Rollout oben ist die Property trafficPercentStrategy tatsächlich ein Verweis auf ein Schema mit der ID TrafficPercentStrategy. Im Abschnitt schemas sehen Sie das Schema TrafficPercentStrategy. Der Wert dieses Schemas kann in der Ressource Rollout durch das Attribut trafficPercentStrategy ersetzt werden. Beachten Sie, dass die Syntax $ref aus der JSON-Schemaspezifikation stammt.
Methoden können auch auf Schemas verweisen, wenn ihre Anfrage- und Antworttexte angegeben werden. Weitere Informationen finden Sie im Abschnitt Methoden.
Methoden
Der Kern des Discovery-Dokuments basiert auf Methoden. Methoden sind die Vorgänge, die über eine API ausgeführt werden können. Sie finden den Abschnitt methods in verschiedenen Bereichen des Discovery-Dokuments, beispielsweise auf der obersten Ebene (API-Level-Methoden) oder auf der Ebene von 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 haben, eine Ressource muss jedoch den Abschnitt methods haben.
Jeder methods-Abschnitt ist eine Schlüssel/Wert-Zuordnung vom Methodennamen zu anderen Details dieser Methode. Im folgenden Beispiel werden die drei Methoden get, list und create dokumentiert:
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
Zuletzt werden im Abschnitt zu den verschiedenen Methoden verschiedene Eigenschaften dieser Methode beschrieben. Hier ein Beispiel für die Methode get:
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
Dieser Abschnitt enthält allgemeine Details zur Methode, z. B. eine eindeutige ID zur Identifizierung der Methode, die zu verwendende httpMethod und die path der Methode (Details zur Verwendung der path-Property zur Berechnung der vollständigen Methoden-URL finden Sie im Abschnitt Anfrage erstellen). Neben diesen allgemeinen Methodeneigenschaften gibt es einige Eigenschaften, die die Methode mit anderen Abschnitten im Discovery-Dokument verbinden:
Sucher
Der zuvor in dieser Dokumentation definierte Abschnitt auth enthält Informationen zu allen Bereichen, die von einer bestimmten API unterstützt werden. Wenn eine Methode einen dieser Bereiche unterstützt, hat sie ein Bereichsarray. Dieses Array enthält für jeden von der Methode unterstützten Bereich einen Eintrag. Der Abschnitt scopes der Google Cloud Service Management API-Methode get sieht beispielsweise so aus:
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
Die Auswahl eines Authentifizierungsbereichs für Ihre Anwendung hängt von verschiedenen Faktoren ab, z. B. davon, welche Methoden aufgerufen und welche Parameter zusammen mit der Methode gesendet werden. Die Entscheidung, welcher Umfang verwendet werden soll, bleibt dem Entwickler überlassen. Nur Discovery-Dokumente, die für eine Methode gültig sind.
Anfrage und Antwort
Wenn die Methode einen Anfrage- oder Antworttext hat, sind diese in den Abschnitten request bzw. response dokumentiert. Im Beispiel get oben hat die Methode den Text response:
"response": {
"$ref": "Rollout"
}
Die obige Syntax zeigt, dass der Antworttext durch ein JSON-Schema mit der ID Rollout definiert ist. Dieses Schema finden Sie im Abschnitt zu Schemas auf oberster Ebene. Sowohl Anfrage- als auch Antworttexte verwenden die $ref-Syntax zum Verweisen auf Schemas.
Parameter
Wenn eine Methode Parameter hat, die vom Nutzer angegeben werden sollten, sind 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:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
Im obigen Beispiel gibt es zwei Parameter für die Methode get:serviceName und rolloutId. Parameter können entweder in path oder in der URL query angegeben werden. Die Property location gibt an, wo der Parameter von der Clientbibliothek platziert werden soll.
Es gibt viele weitere Attribute, die den Parameter beschreiben, einschließlich der Parameterdaten type (nützlich für stark typisierte Sprachen), ob der Parameter required ist und ob es sich bei dem Parameter um eine Aufzählung handelt. Weitere Informationen zu den Eigenschaften finden Sie im Referenzhandbuch.
Parameterreihenfolge
Es gibt viele Möglichkeiten, die Schnittstellen von Clientbibliotheken zu strukturieren. Eine Möglichkeit besteht darin, mit jedem API-Parameter in der Methodensignatur eine Methode zu haben. Da es sich bei JSON jedoch um ein ungeordnetes Format handelt, ist es programmatisch schwer zu erkennen, wie die Parameter in der Methodensignatur angeordnet werden. Das Array parameterOrder bietet eine feste Parameterreihenfolge für Anfragen. Das Array listet den Namen jedes Parameters in der Reihenfolge seiner Bedeutung auf. Es kann entweder einen Pfad oder Abfrageparameter enthalten, aber jeder Parameter im Array ist erforderlich. Im Beispiel oben könnte eine Signatur für eine Java-Methode in etwa so aussehen:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);Der erste Wert im Array parameterOrder (serviceName) ist auch das erste Element in der Methodensignatur. Wenn es weitere Parameter im Array parameterOrder gibt, werden diese nach dem Parameter serviceName gestellt. Da das Array parameterOrder nur die erforderlichen Parameter enthält, empfiehlt es sich, Nutzern die Möglichkeit zu geben, optionale Parameter anzugeben. Im obigen Beispiel wird dies mit der Karte optionalParameters erreicht.
Medienupload
Wenn eine Methode das Hochladen von Medien wie Bilder, Audiodateien oder Videos unterstützt, werden der Speicherort und die Protokolle für das Hochladen dieser Medien im Abschnitt mediaUpload dokumentiert. Dieser Abschnitt enthält Details dazu, welche Uploadprotokolle unterstützt werden und welche Arten von Medien hochgeladen werden können:
"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 Beispiel oben ist die Property supportsMediaUpload ein boolescher Wert, der bestimmt, ob die Methode das Hochladen von Medien unterstützt. Wenn der Wert „true“ ist, wird im Abschnitt mediaUpload dokumentiert, welche Arten von Medien hochgeladen werden können.
Die Property accept ist eine Liste von Medienbereichen, mit denen festgelegt wird, welche MIME-Typen hochgeladen werden können. Der im Beispiel oben gezeigte Endpunkt akzeptiert jedes Bildformat.
Die Property maxSize hat die maximale Größe eines Uploads. Der Wert ist ein String in MB, GB oder TB. Im Beispiel oben sind Uploads auf eine maximale Größe von 10 MB beschränkt. Hinweis: Dieser Wert stellt nicht das verbleibende Speicherkontingent eines einzelnen Nutzers für diese API dar. Selbst wenn der Upload weniger als maxSize beträgt, sollte die Clientbibliothek trotzdem auf einen Upload vorbereitet sein, der aufgrund von zu wenig Speicherplatz fehlschlägt.
Im Abschnitt protocols werden die Uploadprotokolle aufgeführt, die von einer Methode unterstützt werden. Das simple-Protokoll sendet die Medien einfach über eine einzige HTTP-Anfrage an den angegebenen Endpunkt. Das Protokoll resumable impliziert, dass der im URI path angegebene Endpunkt das fortsetzbare Uploadprotokoll unterstützt. Wenn das Attribut multipart den Wert true hat, akzeptiert der Endpunkt mehrteilige Uploads. Das bedeutet, dass sowohl die JSON-Anfrage als auch die Medien in einem mehreren/zusammenhängenden Text zusammengefasst und zusammen gesendet werden können. Sowohl das simple- als auch das resumable-Protokoll unterstützen möglicherweise mehrteilige Uploads.
Die Property path ist eine URI-Vorlage und sollte wie die Property path für die Methode erweitert werden, wie im Abschnitt Anfrage erstellen beschrieben.
Mediendownload
Wenn eine Methode das Herunterladen von Medien wie Bilder, Audio oder Video unterstützt, ist das durch den Parameter supportsMediaDownload angegeben:
"supportsMediaDownload": true,
Wenn Sie Medien herunterladen, müssen Sie in der Anfrage-URL den alt-Abfrageparameter auf media festlegen.
Wenn das Attribut useMediaDownloadService der API-Methode true lautet, füge /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} sind. Es wird empfohlen, eine Medien-Download-URL mit /download zu erstellen, auch wenn useMediaDownloadService „false“ ist.
Allgemeine Parameter
Das Discovery-Dokument der obersten Ebene enthält die Property parameters. Dieser Abschnitt ähnelt dem Parameterabschnitt für jede Methode, aber Sie können ihn auf jede Methode in der API anwenden.
Beispielsweise kann die Methode „get“, „insert“ oder „list“ der Google Cloud Service Management API einen prettyPrint-Parameter in den Anfrageparametern haben, der die Antwort für alle diese Methoden in einem für Menschen lesbaren Format formatiert. Hier ist eine Liste allgemeiner Parameter:
| Parameter | Bedeutung | Hinweise | Geltungsbereich |
|---|---|---|---|
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 festgelegt wird, die in der Antwort enthalten sein soll. |
|
|
key |
API-Schlüssel. (erforderlich*) |
|
|
prettyPrint |
Gibt die Antwort mit Kennungen und Zeilenumbrüchen zurück. |
|
|
quotaUser |
Alternative zu userIp. |
|
|
userIp |
IP-Adresse des Endnutzers, für den der API-Aufruf durchgeführt wird. |
|
Features
In einigen Fällen unterstützen APIs benutzerdefinierte Funktionen, die nicht im Rest des Discovery-Dokuments verfügbar sind. Diese werden im features-Array erfasst. Das Array „features“ enthält ein Stringlabel für jedes Spezialfeature, das von der API unterstützt wird. Derzeit ist dataWrapper die einzige unterstützte Funktion. Es werden aber möglicherweise noch weitere Funktionen hinzukommen.
"features": dataWrapper
Die Funktion dataWrapper gibt an, dass alle Anfragen an die API und alle Antworten darauf von einem data-JSON-Objekt umschlossen sind. Dies ist eine Funktion älterer Google APIs, die jedoch in Zukunft eingestellt wird. Die folgenden APIs unterstützen die Funktion dataWrapper: Moderator v1 und Übersetzer v2.
Wenn eine API die Funktion „dataWrapper“ unterstützt, sollten Sie so vorgehen:
- Bei Anfragen: Verpacken Sie die Anfrageressource in ein
data-JSON-Objekt. - Bei Antworten: Suchen Sie die Ressource in einem
data-JSON-Objekt.
Die Schemas im Discovery-Dokument enthalten den Daten-Wrapper nicht. Sie müssen sie daher explizit hinzufügen und entfernen. Angenommen, es gibt eine API mit einer Ressource namens „Foo“:
{
"id": 1,
"foo": "bar"
}
Bevor Sie diese Ressource mit der API einfügen, müssen Sie sie in einem Datenelement zusammenfassen:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Wenn Sie jedoch eine Antwort von der API erhalten, enthält sie auch den Daten-Wrapper:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Entfernen Sie den Daten-Wrapper, um die durch das Schema definierte Ressource abzurufen:
{
"id": 1,
"foo": "bar"
}
Inline-Dokumentation
Jedes Discovery-Dokument ist mit einer Reihe von description-Feldern gekennzeichnet, die eine Inline-Dokumentation für die API enthalten. Die description-Felder finden Sie für die folgenden API-Elemente:
- API selbst
- OAuth-Bereiche
- Ressourcenschemas
- API-Methoden
- Methodenparameter
- 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 wie JavaDoc generieren möchten.