Cloud Endpoints Frameworks-Befehlszeilentool für App Engine

Auf dieser Seite wird beschrieben, wie Sie das Endpoints Frameworks-Befehlszeilentool verwenden, um von Ihrer Python-Back-End API aus (dem Code, der auf dem Server ausgeführt wird) eine Clientbibliothek zu generieren. Diese Bibliothek kann von allen Java- oder Android-Apps zum Aufrufen der API verwendet werden.

Sie können über das Endpoints Frameworks-Befehlszeilentool Clientbibliothek-Bundles generieren, mit denen Anwendungen auf Ihre API zugreifen können. Wenn Sie eine Clientbibliothek generieren, generiert das Endpoints Frameworks-Befehlszeilentool automatisch ein Discovery-Dokument, in dem die Oberfläche Ihrer API beschrieben wird.

Das Endpoints Frameworks-Befehlszeilentool endpointscfg.py ist in der Endpoints Frameworks-Bibliothek verfügbar. Informationen zur Installation der Endpoints Frameworks-Bibliothek mit pip finden Sie unter Endpoints Frameworks-Bibliothek installieren. Beachten Sie, dass die folgenden Befehle davon ausgehen, dass Sie die Endpoints Frameworks-Bibliothek in einem Verzeichnis namens lib installiert haben. Außerdem wird in dieser Anleitung vorausgesetzt, dass Sie Ihre Back-End API erstellt haben. Wie das Endpoints Frameworks-Befehlszeilentools bei einem Beispielcode verwendet wird, wird in der Anleitung zu Endpoints Frameworks in Python beschrieben.

Clientbibliothek-Bundle von einer API generieren

Mit dem Endpoints Frameworks-Befehlszeilentool können Sie die folgenden Arten von Client-Bundles generieren:

  • Maven: Dieses Bundle enthält die Datei pom.xml mit den Abhängigkeiten von Endpoints Frameworks und von der Google API-Clientbibliothek. Die Datei readme.html enthält detaillierte Informationen darüber, was Sie je nach Art der Clientanwendung jeweils der Datei pom.xml hinzufügen müssen und wie Sie mit Maven eine Clientbibliothek für Ihre API erstellen.

  • Gradle: Dieses Bundle enthält die Datei build.gradle mit den Abhängigkeiten von Endpoints Frameworks und von der Google API-Clientbibliothek. Die Datei readme.html enthält detaillierte Informationen darüber, was Sie je nach Art der Clientanwendung jeweils der Datei build.gradle hinzufügen müssen und wie Sie mit Gradle eine Clientbibliothek für Ihre API erstellen.

  • Standard-Client-Bundle: Dieses Bundle enthält alle Abhängigkeitsbibliotheken und die generierte Datei source.jar. Dies ist die Java-Bibliothek, die Sie in Ihrem Client zum Aufrufen der API verwenden. Das Bundle bietet Ihrem Client alle Funktionen der Google API-Clientbibliothek, einschließlich OAuth. In der Datei readme.html sind die .jar-Dateien aufgelistet, die für verschiedene Arten von Clientanwendungen jeweils erforderlich sind, sowie andere Details zur Verwendung der Clientbibliothek.

Wenn Sie die Clientbibliothek mit einer Android-App verwenden, empfiehlt sich ein Gradle-Client-Bundle.

Clientbibliothek generieren

So generieren Sie die Clientbibliothek:

  1. Geben Sie das Verzeichnis an, in dem Ihre API-Datei app.yaml sowie Ihre API-Dienstklassen gespeichert sind. Sie können mit der Option --application auch einen anderen Speicherort für Ihr Anwendungsverzeichnis festlegen.

  2. Das Endpoints Frameworks-Befehlszeilentool sollte in etwa so aufgerufen werden:

    lib/endpoints/endpointscfg.py get_client_lib java -bs gradle main.EchoApi
    

    Dabei ist main die Klasse mit Ihrer API und EchoApi der API-Name.

  3. Warten Sie, bis die Clientbibliothek generiert wurde. Zur Bestätigung wird im Anschluss in etwa folgende Meldung eingeblendet:

    API client library written to ./echo-v1.zip
    
  4. Fügen Sie der Android-App die JAR-Datei der Clientbibliothek hinzu.

  5. Wiederholen Sie die vorangegangenen Schritte bei jeder Änderung des API-Codes.

Das Clientbibliotheks-Bundle wird in das aktuelle Verzeichnis geschrieben, sofern Sie mit der Option output kein anderes Ausgabeverzeichnis angeben.

Befehlszeilensyntax

Die grundlegende Syntax lautet:

/path-to/your-app/lib/endpointscfg.py get_client_lib TARGET_LANG OPTIONS CLASS_NAME

wobei

  • TARGET_LANG gibt den Typ des Client-Bundles an, das Sie erstellen möchten. Derzeit ist für Java-Clients wie Android der Wert java erforderlich.
  • OPTIONS, falls verfügbar, sind ein oder mehrere in der Tabelle "Optionen" angezeigte Elemente.
  • CLASS_NAME ist der vollständig qualifizierte Klassenname Ihrer API.

Optionen

Sie haben die folgenden Möglichkeiten:

Option Beschreibung Beispiel
application Standardmäßig erfolgt die Generierung aus der Back-End API im aktuellen Verzeichnis.
Wenn Sie ein anderes Verzeichnis für die Generierung verwenden möchten, geben Sie den Pfad zum Verzeichnis mit der Datei app.yaml und den Dienstklassen an, die Ihre API implementieren.
--application /my_path/my_api_dir
build-system Hiermit können Sie angeben, welcher Client-Bundle-Typ erstellt werden soll. Geben Sie für ein Gradle-Client-Bundle für Android gradle an, für ein Maven-Client-Bundle maven und für ein Bundle, das nur die Abhängigkeitsbibliotheken und die JAR-Quelldatei enthält, default (oder lassen Sie diese Option aus). --build-system=gradle
-bs gradle
hostname Legt das Discovery-Dokument rootURL fest.
Diese Option überschreibt den Standardwert, der aus dem application-Eintrag im Back-End API-Projekt app.yaml ([YOUR_APP_ID].appspot.com) abgeleitet wird, und den im Decorator für Ihre API definierten hostname.
Mit dieser Option geben Sie unter anderem den Hostnamen localhost als rootURL für lokale Tests an.
--hostname localhost
format Geben Sie hierfür nichts an, da nur der Standardwert rest für REST unterstützt wird. Nicht erforderlich, Standardwert verwenden.
output Legt das Verzeichnis fest, in das die Ausgabe geschrieben wird.
Standardmäßig wird das Verzeichnis verwendet, in dem das Tool aufgerufen wurde.
--output /mydir
-o /mydir

Unterstützte Clientplattformen

Die folgenden Plattformen werden in dem vom Endpoints Frameworks-Befehlszeilentool erstellten Client-Bundle unterstützt:

OpenAPI-Dokument aus einer API generieren

Das endpointscfg.py-Tool bietet einen Befehl zum Erzeugen eines OpenAPI-Dokuments aus einem API-Back-End. Die Befehlssyntax lautet:

lib/endpoints/endpointscfg.py get_openapi_spec
    [-h]
    [-a APPLICATION]
    [--hostname HOSTNAME]
    [-o OUTPUT]
    service [service ...]

positional arguments:
  service               Fully qualified service class name.

optional arguments:
  -h, --help            Show this help message and exit.
  -a APPLICATION, --application APPLICATION
                        The path to the Python App Engine application.
  --hostname HOSTNAME   Default application hostname, if none is specified for the API service.
  -o OUTPUT, --output OUTPUT
                        The directory to store output files.
  --x-google-api-name   Add the 'x-google-api-name' field to the generated OpenAPI document.

Verwenden Sie beispielsweise das echo-Beispiel:

$ lib/endpoints/endpointscfg.py get_openapi_spec --hostname=echo-example.appspot.com main.EchoApi
OpenAPI spec written to ./echov1openapi.json