Erste Schritte mit Cloud Endpoints Frameworks für Python

Beispielcode abrufen

So klonen Sie die Beispiel-API aus GitHub:

1. Klonen Sie das Beispiel-Repository auf Ihrem lokalen Computer:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

2. Ändern Sie das Verzeichnis, das den Beispielcode enthält:

   cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

Endpoints konfigurieren

Zum Konfigurieren von Endpoints müssen Sie zuerst die Python-Bibliothek von Endpoints Frameworks installieren. Verwenden Sie danach ein Tool aus der Endpoints Frameworks-Bibliothek, um ein OpenAPI-Dokument für die Beispiel-API zu erstellen. Sie benötigen die Endpoints Frameworks-Bibliothek und das OpenAPI-Dokument, damit Endpoints die API verwalten kann. Weitere Informationen finden Sie unter API-Verwaltung hinzufügen.

Endpoints Frameworks-Bibliothek installieren

In diesem Abschnitt wird beschrieben, wie Sie mit dem Python-Befehl pip die Endpoints Frameworks-Bibliothek in das Projektverzeichnis der Beispiel-API einfügen.

So fügen Sie die Endpoints Frameworks-Bibliothek in das Beispiel ein:

1. Prüfen Sie, ob Sie sich im Hauptverzeichnis python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo der Beispiel-API befinden.

2. Erstellen Sie im Projekt das Unterverzeichnis /lib:

   mkdir lib
   

3. Führen Sie im Hauptverzeichnis python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo folgenden Installationsbefehl aus:

   pip install --target lib --requirement requirements.txt --ignore-installed
   

   Wichtige Hinweise:

   • Dieser pip-Befehl kann Erweiterungsmodule mithilfe von GCC (GNU Compiler Collection) kompilieren. Wenn Sie macOS verwenden und GCC zum ersten Mal in Ihrem System ausgeführt haben, müssen Sie die XCode-Lizenz von Apple akzeptieren. Führen Sie dazu den Befehl sudo xcodebuild -license aus:

   • Wenn auf Ihrem Computer mehrere Python-Versionen installiert sind, sollten Sie eine Version von pip verwenden, die der in dieser Anleitung verwendeten Python-Version entspricht. Abweichende Versionen (zum Beispiel pip von Python 3.4, während python von Python 2.7 verwendet wird) können Fehler hervorrufen, die möglicherweise schwer nachzuvollziehen sind. Falls erforderlich, können Sie pip als Python-Modul ausführen. Ersetzen Sie dazu pip im genannten Befehl durch python -m pip.

   • Wenn pip beim Ausführen des Befehls kein geeignetes Paket finden kann, führen Sie mit pip install --upgrade pip eine Aktualisierung durch. Führen Sie den Installationsbefehl nach Abschluss der Aktualisierung noch einmal aus.

   • Bei einigen Debian- und Ubuntu-Releases schlägt pip möglicherweise mit "DistutilsOptionError" fehl. Wenn dieser Fehler angezeigt wird, fügen Sie das Flag --system hinzu.

Nach dem erfolgreichen Abschluss des Vorgangs wird das Verzeichnis lib mit den Dateien gefüllt, die zum Erstellen der Endpoints Frameworks-Anwendung erforderlich sind.

OpenAPI-Dokument erstellen

Sie verwenden ein Tool aus der Endpoints Frameworks-Bibliothek, um ein Dokument zu erstellen, in dem die REST API des Beispielcodes beschrieben wird.

So erstellen Sie das OpenAPI-Dokument:

1. Prüfen Sie, ob Sie sich im Beispielhauptverzeichnis befinden:

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. Generieren Sie das OpenAPI-Dokument:

   python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.com
   

   Ersetzen Sie [YOUR_PROJECT_ID] durch Ihre Google Cloud-Projekt-ID. Ignorieren Sie die angezeigten Warnungen. Das Endpoints-Tool generiert im aktuellen Verzeichnis ein OpenAPI-Dokument namens echov1openapi.json. Das Endpoints-Tool benennt die Datei basierend auf dem Namen und der Version des Dienstes, der im Decorator @endpoints.api angegeben ist. Weitere Informationen finden Sie unter API erstellen.

   Endpoints verwendet den im Argument hostname angegebenen Text als Dienstnamen. Das Namensformat YOUR_PROJECT_ID.appspot.com stimmt mit dem DNS-Eintrag überein, der automatisch erstellt wird, wenn Sie die API im App Engine-Back-End bereitstellen. In diesem Fall stimmt der Endpoints-Dienstname mit dem vollständig qualifizierten Domainnamen (FQDN) überein.

Nach dem erfolgreichen Abschluss des Vorgangs wird folgende Meldung angezeigt: OpenAPI spec written to ./echov1openapi.json

Endpoints-Konfiguration bereitstellen

Für die Bereitstellung der Endpoints-Konfiguration verwenden Sie die Service Infrastructure. Dies ist die grundlegende Dienstplattform von Google, die von Endpoints und anderen Diensten zum Erstellen und Verwalten von APIs und Diensten genutzt wird.

So stellen Sie die Konfigurationsdatei bereit:

1. Prüfen Sie, ob Sie sich im Beispielhauptverzeichnis befinden:

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. Stellen Sie das im vorherigen Abschnitt generierte OpenAPI-Dokument bereit, indem Sie den folgenden Befehl ausführen:

   gcloud endpoints services deploy echov1openapi.json

   Dadurch wird ein neuer Endpoints-Dienst mit dem Namen erstellt, den Sie beim Erstellen des OpenAPI-Dokuments mithilfe des Endpoints-Tools im Argument hostname angegeben haben. Unabhängig vom Namen des Endpoints-Dienstes wird beim Bereitstellen der API in App Engine ein DNS-Eintrag mit dem Namensformat YOUR_PROJECT_ID.appspot.com erstellt. Dies ist der FQDN, den Sie verwenden, wenn Sie Anfragen an die API senden.

   Beim Erstellen und Konfigurieren des Dienstes gibt Service Management große Mengen von Daten an das Terminal aus. Warnhinweise, die besagen, dass für die Pfade in echov1openapi.json kein API-Schlüssel erforderlich ist, können Sie bedenkenlos ignorieren. Nach Abschluss der Bereitstellung erhalten Sie in etwa folgende Meldung:

   Service Configuration [2017-02-13r2] uploaded for service [example-project-12345.appspot.com]
   

   Im obigen Beispiel ist 2017-02-13-r2 die Dienstkonfigurations-ID und example-project-12345.appspot.com der Dienstname.

   Weitere Informationen finden Sie in der gcloud-Referenzdokumentation unter gcloud endpoints services deploy.

Erforderliche Dienste prüfen

In der Regel werden die erforderlichen Dienste mit dem Befehl gcloud endpoints services deploy aktiviert. Unter folgenden Umständen kann es vorkommen, dass der Befehl gcloud erfolgreich ausgeführt wird, die erforderlichen Dienste jedoch nicht aktiviert werden:

• Wenn Sie eine Drittanbieteranwendung wie Terraform verwendet haben und Sie diese Dienste nicht hinzufügen.

• Wenn Sie die Endpoints-Konfiguration für ein vorhandenes Google Cloud-Projekt bereitgestellt haben, in dem diese Dienste explizit deaktiviert wurden.

Prüfen Sie mit dem folgenden Befehl, ob die erforderlichen Dienste aktiviert sind:

gcloud services list

Wenn die erforderlichen Dienste nicht aufgeführt sind, müssen Sie sie aktivieren:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Aktivieren Sie auch Ihren Endpoints-Dienst:

gcloud services enable ENDPOINTS_SERVICE_NAME

Zum Ermitteln des ENDPOINTS_SERVICE_NAME haben Sie folgende Möglichkeiten:

• Rufen Sie nach der Bereitstellung der Endpoints-Konfiguration die Seite Endpoints in der Cloud Console auf. Die Liste der möglichen ENDPOINTS_SERVICE_NAME wird in der Spalte Dienstname angezeigt.

• Bei OpenAPI ist ENDPOINTS_SERVICE_NAME der Wert, den Sie im Feld host Ihrer OpenAPI-Spezifikation angegeben haben. Bei gRPC ist der ENDPOINTS_SERVICE_NAME das, was Sie im Feld name Ihrer gRPC-Endpoints-Konfiguration angegeben haben.

Weitere Informationen zu den gcloud-Befehlen finden Sie unter gcloud-Dienste.

Beispiel lokal ausführen

Nach dem Bereitstellen der Endpoints-Konfiguration können Sie das Beispiel lokal mit dem lokalen Entwicklungsserver ausführen.

1. Prüfen Sie, ob Sie sich im Beispielhauptverzeichnis befinden:

   python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
   

2. Starten Sie den lokalen Entwicklungsserver:

   dev_appserver.py ./app.yaml
   

   Standardmäßig überwacht der Entwicklungsserver http://localhost:8080, wie in den von dev_appserver.py ausgegebenen Google Cloud Console-Logs angegeben:

   INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
   

3. Senden Sie eine Anfrage an den lokalen Entwicklungsserver:

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

Die API gibt die von Ihnen gesendete Meldung zurück und reagiert mit folgender Zeile:

{
 "message": "hello world"
}

API-Back-End bereitstellen

Bisher haben Sie zwar das OpenAPI-Dokument für Service Management bereitgestellt, den Code für das API-Back-End haben Sie jedoch noch nicht implementiert. In diesem Abschnitt wird die Bereitstellung der Beispiel-API für App Engine beschrieben.

So stellen Sie das API-Back-End bereit:

1. Rufen Sie die Dienstkonfigurations-ID auf, indem Sie den folgenden Befehl ausführen:

   gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com

   Ersetzen Sie [YOUR_PROJECT_ID] durch Ihre Projekt-ID. Beispiel:

   gcloud endpoints configs list --service=example-project-12345.appspot.com
   
   

2. Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.

   env_variables:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy swagger.json' command.
     ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
     ENDPOINTS_SERVICE_VERSION: 2016-08-01r0