Einige oder alle Informationen auf dieser Seite gelten möglicherweise nicht für Trusted Cloud von S3NS.

Clientbibliothek erstellen

Mit dem Google APIs Discovery Service können Sie eine Vielzahl verschiedener Tools für Google APIs erstellen. Der Hauptzweck des Discovery-Dokuments besteht jedoch darin, Google die Erstellung von Clientbibliotheken in verschiedenen Programmiersprachen zu ermöglichen. In diesem Dokument wird beschrieben, wie Sie eine benutzerdefinierte Clientbibliothek für Google APIs erstellen können.

Eine stabile und funktionsvollständige Clientbibliothek ist ein komplexes Tool, dessen Entwicklung Monate dauern kann. Die allgemeine Anleitung zum Erstellen einer einfachen Clientbibliothek für Google APIs gliedert sich jedoch in drei einfache Schritte:

Discovery-Dokument abrufen und API-Oberfläche erstellen
Anfrage erstellen
Aufruf durchführen und Antwort abrufen

Diese Ebenen werden in den folgenden Abschnitten ausführlicher beschrieben. Sie können auch das Beispiel Einfacher API-Client im Abschnitt "Beispiele" ansehen, um zu sehen, wie diese Anleitung dem Code zugeordnet wird.

Discovery-Dokument abrufen

Bevor Sie mit der Implementierung einer Clientbibliothek beginnen, gibt es einige grundlegende Anforderungen, die sich auf Ihren Entwicklungspfad auswirken. Beispielsweise kann die Programmiersprache Ihrer Wahl entweder typisiert oder nicht typisiert sein. Wenn sie typisiert ist, kann sie entweder statisch oder dynamisch typisiert sein. Sie kann kompiliert oder interpretiert werden. Diese Anforderungen leiten Sie durch die Verwendung des Discovery-Dokuments.

Die erste Entwicklungsaufgabe besteht darin, das Discovery-Dokument abzurufen. Der genaue Zeitpunkt, zu dem das Dokument abgerufen werden soll, hängt von den Anforderungen ab, die Sie identifiziert haben. In einer statisch orientierten Sprache können Sie beispielsweise das Discovery-Dokument zu Beginn des Prozesses abrufen und dann Code generieren, um die im Discovery-Dokument beschriebene spezifische API zu verarbeiten. Bei einer stark typisierten Sprache können Sie Code generieren und eine kompilierte Bibliothek erstellen. Bei einer dynamisch typisierten Sprache können Sie die Programmierstrukturen träge erstellen, um die API bei der Verwendung der Programmieroberfläche direkt zu verbinden.

Anfrage verfassen

Das Erstellen einer Anfrage umfasst zwei separate Schritte:

Anfragetext verfassen
Anfrage-URL erstellen

Sie müssen den Anfragetext gegebenenfalls aus einer sprachspezifischen Darstellung in das richtige Wire-Format konvertieren. In einer Java-Clientbibliothek kann es beispielsweise eine Klasse für jeden Anfragetyp geben, die eine typsichere Manipulation der Anfragedaten ermöglicht und in JSON serialisiert werden kann.

Die Erstellung der Anfrage-URL ist etwas komplizierter.

Das Attribut path jeder Methode in der API verwendet die Syntax der URI-Vorlage v04. Dieses Attribut kann Variablen enthalten, die in geschweifte Klammern gesetzt sind. Hier ein Beispiel für eine path-Property mit Variablen:

/example/path/var

Im obigen Pfad ist var eine Variable. Der Wert für diese Variable stammt aus dem Abschnitt parameters des Discovery-Dokuments für diese Methode. Jeder Variablenname hat einen entsprechenden Wert im parameters-Objekt. Im obigen Beispiel gibt es einen Parameter namens var im Abschnitt parameters (und das Attribut location lautet path, um anzugeben, dass es sich um eine Pfadvariable handelt).

Wenn Sie eine Anfrage stellen, sollten Sie den Wert für var in die URL einfügen. Wenn beispielsweise der Nutzer der Bibliothek eine Auswahl trifft, bei der var auf den Wert foo gesetzt wird, ist die neue URL /example/path/foo.

Beachten Sie außerdem, dass das Attribut path ein relativer URI ist. So berechnen Sie den absoluten URI:

Wenn Sie Ihren Standort (Region) kennen und das Discovery-Dokument das Attribut endpoints enthält, prüfen Sie, ob Ihr Standort in der Liste endpoints enthalten ist. Wenn ja, suchen Sie in der Liste der endpoints nach der endpointUrl, deren location mit Ihrer übereinstimmt.
Wenn im Discovery-Dokument kein endpoints-Attribut enthalten ist oder Ihr Standort nicht in der endpoints-Liste enthalten ist oder Sie auf den globalen Endpunkt abzielen möchten, erfassen Sie das Attribut rootUrl aus der obersten Ebene des Discovery-Dokuments.

Die Eigenschaft rootUrl im Discovery-Dokument für die Service Usage API lautet beispielsweise:
```
https://serviceusage.s3nsapis.fr/
```
Rufen Sie das servicePath aus der obersten Ebene des Discovery-Dokuments ab. Beispielsweise ist die Eigenschaft servicePath im Discovery-Dokument für die Service Usage API leer.
Sie können diese verketten, um Folgendes zu erhalten:
```
https://serviceusage.s3nsapis.fr/
```
Rufen Sie das Attribut path ab, erweitern Sie sie als URI-Vorlage und kombinieren Sie die Ergebnisse dieser Erweiterung mit dem URI aus dem vorherigen Schritt. In der Methode serviceusage.services.enable der v1 Service Usage API lautet der Wert des Attributs path beispielsweise v1/{+name}:enable. Der vollständige URI für die Methode lautet also:
```
https://serviceusage.s3nsapis.fr/v1/{+name}:enable
```

Sie benötigen keinen API-Schlüssel, um die Service Usage API aufzurufen. Falls die aufgerufene API jedoch einen API-Schlüssel benötigt, können Sie den API-Schlüssel dem Abfragestring des URI hinzufügen:

REQUEST_URI?key=API_KEY

Aufruf durchführen und Antwort verarbeiten

Nachdem Sie die Anfrage gesendet haben, müssen Sie die Antwort in die entsprechende Sprachdarstellung deserialisieren. Dabei müssen Sie mögliche Fehlerbedingungen berücksichtigen, die sowohl im zugrunde liegenden HTTP-Transport als auch in Fehlermeldungen auftreten können, die vom API-Dienst generiert werden. Das Format der Fehler wird im JSON-Stilhandbuch von Google beschrieben.

Beispiele

Im folgenden Abschnitt finden Sie ein einfaches Beispiel für eine Clientbibliothek für APIs.

Einfacher API-Client

Unten sehen Sie ein Beispiel für eine sehr einfache Clientbibliothek, die in Python3 geschrieben wurde. Der Client erstellt eine Schnittstelle für die Interaktion mit der Service Usage API und verwendet diese Schnittstelle dann, um die Compute Engine API (compute.googleapis.com) im Projekt my-project zu aktivieren.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.s3nsapis.fr/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += 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 (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

Die kritischen Komponenten des Clients sind:

Schritt 1: Discovery-Dokument abrufen Das Discovery-Dokument für die Service Usage API wird abgerufen und in eine 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 in die Abfrageparameter der URL eingefügt. Schließlich wird eine Anfrage mit der im Discovery-Dokument angegebenen HTTP-Methode an die URL gesendet.
Schritt 3.a: Clientoberfläche erstellen Die Clientoberfläche wird durch rekursives Absteigen über das geparste Discovery-Dokument erstellt. Für jede Methode im Bereich methods wird dem Collection-Objekt eine neue Methode hinzugefügt. Da Sammlungen verschachtelt werden können, suchen wir nach resources und erstellen rekursiv ein Collection-Objekt für alle seine Mitglieder, sofern eines gefunden wird. Jede verschachtelte Sammlung wird dem Collection-Objekt auch als Attribut zugeordnet.
Schritt 3.b: Client verwenden Diese veranschaulicht die Nutzung der erstellten API-Oberfläche. Zuerst wird ein Dienstobjekt aus dem Discovery-Dokument erstellt. Anschließend wird die Compute Engine API mit der Service Usage API im Projekt my-project aktiviert.