Clientbibliothek erstellen

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:

  1. Discovery-Dokument abrufen und API-Oberfläche erstellen
  2. Anfrage erstellen
  3. 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:

  1. Verfassen des Anfragetexts.
  2. 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:

  1. Übernehmen Sie die Property rootUrl von der obersten Ebene des Discovery-Dokuments.
    Beispiel für das Attribut rootUrl im Discovery-Dokument für die Google Cloud Service Management API:

    https://servicemanagement.googleapis.com/

  2. Übernehmen Sie die servicePath aus der obersten Ebene des Discovery-Dokuments.
    Beispiel: Das Attribut servicePath im Discovery-Dokument für die Google Cloud Service Management API ist leer.

  3. Verketten Sie sie, um Folgendes zu erhalten:

    https://servicemanagement.googleapis.com/

  4. 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 Dienstmethode get der Google Cloud Service Management API ist der Wert der Eigenschaft path beispielsweise v1/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 Speicherort query 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 Abschnitt methods wird eine neue Methode an das Objekt Collection angehängt. Da Sammlungen verschachtelt sein können, suchen wir nach resources und erstellen rekursiv ein Collection-Objekt für alle Mitglieder, falls eines gefunden wird. Jede verschachtelte Sammlung wird auch als Attribut an das Collection-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.