Einführung
Mit dem Google APIs Discovery Service können Sie verschiedene Tools zur Verwendung mit Google APIs erstellen. Der Hauptzweck des Discovery-Dokuments besteht jedoch darin, Google zu ermöglichen, Clientbibliotheken in verschiedenen Programmiersprachen zu erstellen. In diesem Abschnitt wird beschrieben, wie Sie eine benutzerdefinierte Clientbibliothek für Google APIs erstellen können.
Eine stabile und funktionsreiche Clientbibliothek ist ein kompliziertes Tool, dessen Entwicklung Monate dauern kann. Die allgemeine Anleitung zum Erstellen einer einfachen Clientbibliothek für Google APIs kann jedoch in drei einfache Schritte unterteilt werden:
- Discovery-Dokument abrufen und API-Oberfläche erstellen
- Anfrage erstellen
- Einen Anruf starten und die Antwort abrufen
Diese Ebenen werden in den folgenden Abschnitten ausführlicher beschrieben. Sie können sich auch das Beispiel Client für einfache APIs im Abschnitt „Beispiele“ ansehen, um zu erfahren, wie diese Anleitung dem Code zugeordnet wird.
Schritt 1: Discovery-Dokument abrufen
Bevor Sie mit der Implementierung einer Clientbibliothek beginnen, müssen einige grundlegende Anforderungen erfüllt werden, die sich auf die Weiterentwicklung Ihres Entwicklungspfads auswirken. Beispielsweise kann deine bevorzugte Programmiersprache entweder typisiert oder nicht typisiert sein. Wird sie eingegeben, kann sie entweder statisch oder dynamisch eingegeben sein. Er kann kompiliert oder interpretiert werden. Diese Anforderungen sollen Ihnen dabei helfen, das Discovery-Dokument zu verwenden und zu verwenden.
Die erste Entwicklungsaufgabe besteht darin, das Discovery-Dokument abzurufen. Ihre Strategie für den genauen Zeitpunkt des Abrufs des Dokuments wird von den Anforderungen bestimmt, die Sie festgelegt haben. In einer statischen Sprache können Sie beispielsweise das Discovery-Dokument früh im Prozess abrufen und dann Code für die Verarbeitung der im Discovery-Dokument beschriebenen API generieren. Für eine typisierte Sprache können Sie Code generieren und eine kompilierte Bibliothek erstellen. Für eine dynamisch typisierte Sprache können Sie die Programmierstrukturen so konstruieren, dass sie während der Verwendung der Programmieroberfläche spontan mit der API verbunden werden können.
Schritt 2: Anfrage erstellen
Das Erstellen von Anfragen erfolgt in zwei separaten Schritten:
- Verfassen des Anfragetexts.
- Die Anfrage-URL wird erstellt.
Der Text der Anfrage muss gegebenenfalls von einer sprachspezifischen Darstellung in das richtige Drahtformat konvertiert werden. In einer Java-Clientbibliothek gibt es beispielsweise für jeden Anfragetyp eine Klasse, die eine typsichere Bearbeitung der Anfragedaten ermöglicht und in JSON serialisiert werden kann.
Die Erstellung der Anfrage-URL ist etwas komplizierter.
Für die path
-Property jeder Methode in der API wird die Syntax URI-Vorlage v04 verwendet. Dieses Attribut kann Variablen enthalten, die in geschweifte Klammern gesetzt sind. Hier ein Beispiel für ein path
-Attribut mit Variablen:
/example/path/var
Im Pfad oben ist var
eine Variable. Der Wert dieser Variable stammt aus dem Abschnitt parameters
des Discovery-Dokuments für diese Methode. Jeder Variablenname hat einen entsprechenden Wert im Objekt parameters
. Im Beispiel oben befindet sich der Parameter var
im Abschnitt parameters
. Das Attribut location
ist path
, um anzugeben, dass es sich um eine Pfadvariable handelt.
Wenn Sie eine Anfrage stellen, müssen Sie den Wert var
durch die URL ersetzen. Wenn der Nutzer der Bibliothek beispielsweise var
auswählt und den Wert foo
festlegt, lautet die neue URL /example/path/foo
.
Beachten Sie auch, dass die Property path
ein relativer URI ist. So berechnen Sie den absoluten URI:
Übernehmen Sie die Property
rootUrl
von der obersten Ebene des Discovery-Dokuments.
Beispiel für das AttributrootUrl
im Discovery-Dokument für die Google Cloud Service Management API:https://servicemanagement.googleapis.com/
Übernehmen Sie die
servicePath
aus der obersten Ebene des Discovery-Dokuments.
Beispiel: Das AttributservicePath
im Discovery-Dokument für die Google Cloud Service Management API ist leer.Verketten Sie sie, um Folgendes zu erhalten:
https://servicemanagement.googleapis.com/
Verwenden Sie die Property
path
, maximieren Sie sie als URI-Vorlage und kombinieren Sie die Ergebnisse dieser Erweiterung mit der im vorherigen Schritt.
In der Dienstmethodeget
der Google Cloud Service Management API ist der Wert der Eigenschaftpath
beispielsweisev1/services/{serviceName}
. Der vollständige URI für die Methode lautet also:https://servicemanagement.googleapis.com/v1/services/{serviceName}
Zum Aufrufen der Google Cloud Service Management API ist ein API-Schlüssel erforderlich. Nach dem Anwenden eines API-Schlüssels lautet der vollständige URI zum Abrufen der Dienstdefinition des API Discovery Service so:
https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY
Schritt 3: Anruf starten und Antwort verarbeiten
Nachdem Sie die Anfrage gesendet haben, müssen Sie die Antwort in die entsprechende Sprachdarstellung deserialisieren. Achten Sie dabei auf auftretende Fehlerbedingungen – sowohl im zugrunde liegenden HTTP-Transport als auch auf Fehlermeldungen, die vom API-Dienst generiert werden. Das Format der Fehler ist im Google JSON-Styleguide dokumentiert.
Beispiele
Einige konkrete Beispiele für Clientbibliotheken und Tools, die mit dem Google APIs Discovery Service implementiert wurden, finden Sie im Dokument Bibliotheken und Beispiele. Im folgenden Abschnitt finden Sie außerdem ein einfaches Beispiel für eine API-Clientbibliothek.
Einfacher API-Client
Das folgende Beispiel zeigt eine sehr einfache Clientbibliothek, die in Python3 geschrieben ist . Der Client erstellt eine Schnittstelle für die Interaktion mit der Google Cloud Service Management API und ruft dann die Dienstdefinition des API Discovery Service über diese Schnittstelle ab.
Warnung: Der folgende Code ist eine deutlich vereinfachte Version einer typischen Clientbibliothek. Sie ist eine unvollständige Implementierung, die einige Aspekte des Erstellens einer Clientbibliothek veranschaulicht. Es ist kein produktionsfertiger Code.
import httplib2 import json import uritemplate import urllib # Step 1: Fetch Discovery document DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1" h = httplib2.Http() resp, content = h.request(DISCOVERY_URI) discovery = json.loads(content) # Step 2.a: Construct base URI BASE_URL = discovery['rootUrl'] + discovery['servicePath'] class Collection(object): pass def createNewMethod(name, method): # Step 2.b Compose request def newMethod(**kwargs): body = kwargs.pop('body', None) url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs)) for pname, pconfig in method.get('parameters', {}).items(): if pconfig['location'] == 'path' and pname in kwargs: del kwargs[pname] if kwargs: url = url + '?' + urllib.parse.urlencode(kwargs) return h.request(url, method=method['httpMethod'], body=body, headers={'content-type': 'application/json'}) return newMethod # Step 3.a: Build client surface def build(discovery, collection): for name, resource in discovery.get('resources', {}).items(): setattr(collection, name, build(resource, Collection())) for name, method in discovery.get('methods', {}).items(): setattr(collection, name, createNewMethod(name, method)) return collection # Step 3.b: Use the client service = build(discovery, Collection()) print (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))
Die wichtigsten Komponenten des Clients sind:
- Schritt 1: Discovery-Dokument abrufen
Das Discovery-Dokument für die Google Cloud Service Management API wird abgerufen und in einer Datenstruktur geparst. Da Python eine dynamisch typisierte Sprache ist, kann das Discovery-Dokument zur Laufzeit abgerufen werden. - Schritt 2.a: Basis-URI erstellen
Der Basis-URI wird berechnet. - Schritt 2.b: Anfrage erstellen
Wenn eine Methode für eine Sammlung aufgerufen wird, wird die URI-Vorlage mit den an die Methode übergebenen Parametern erweitert. Parameter mit dem Speicherortquery
werden den Abfrageparametern der URL hinzugefügt. Schließlich wird mit der im Discovery-Dokument angegebenen HTTP-Methode eine Anfrage an die zusammengestellte URL gesendet. - Schritt 3.a: Clientoberfläche erstellen
Die Clientoberfläche wird rekursiv absteigend über das geparste Discovery-Dokument erstellt. Für jede Methode im Abschnittmethods
wird eine neue Methode an das ObjektCollection
angehängt. Da Sammlungen verschachtelt sein können, suchen wir nachresources
und erstellen rekursiv einCollection
-Objekt für alle Mitglieder, falls eines gefunden wird. Jede verschachtelte Sammlung wird auch als Attribut an dasCollection
-Objekt angehängt. - Schritt 3.b: Client verwenden
Hier sehen Sie, wie die erstellte API-Oberfläche verwendet wird. Zuerst wird ein Dienstobjekt aus dem Discovery-Dokument erstellt. Anschließend wird die Dienstdefinition des API Discovery Service über die Google Cloud Service Management API abgerufen.