Erste Schritte mit Cloud Endpoints Frameworks für Python

Auf dieser Seite erfahren Sie, wie Sie Anfragen an eine Beispiel-API mithilfe von Cloud Endpoints Frameworks für Python konfigurieren, erstellen und senden. Endpoints Frameworks für Python ist in die App Engine-Standardlaufzeitumgebung für Python 2.7 eingebunden. Endpoints Frameworks besteht aus Tools, Bibliotheken und Funktionen, die es Ihnen erlauben, APIs und Clientbibliotheken aus einer App Engine-Anwendung zu generieren.

Lernziele

Orientieren Sie sich beim Durcharbeiten der Anleitung an der folgenden Aufgabenliste. Alle Aufgaben sind erforderlich, um Anfragen sicher an die API senden zu können.

Richten Sie ein Google Cloud-Projekt ein. Siehe Vorbereitung.
Erforderliche Software installieren und eine App Engine-Anwendung erstellen. Siehe Erforderliche Software installieren und konfigurieren.
Beispielcode herunterladen. Siehe Beispielcode abrufen.
Ein OpenAPI-Dokument erstellen. Siehe Endpoints konfigurieren.
Die Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
Das Beispiel auf Ihrem Computer ausführen. Siehe Beispiel lokal ausführen.
Ein Backend für die API erstellen und die API bereitstellen. Siehe API-Backend bereitstellen.
Senden Sie eine Anfrage an die API. Siehe Anfrage an die API senden.
API-Aktivitäten verfolgen. Siehe API-Aktivitäten verfolgen.
Vermeiden Sie Gebühren, die Ihrem Google Cloud-Konto in Rechnung gestellt werden. Siehe Bereinigen.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Nach Abschluss der in diesem Dokument beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen. Weitere Informationen finden Sie unter Bereinigen.

Hinweise

Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

Zur Projektauswahl

Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

Zur Projektauswahl

Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

Notieren Sie sich die Google Cloud-Projekt-ID, da sie später benötigt wird.

Erforderliche Software installieren und konfigurieren

Folgen Sie der Anleitung unter Google Cloud CLI für Python installieren, um Ihre standardmäßige App Engine-Entwicklungsumgebung einzurichten. Achten Sie darauf, dass die gcloud-Komponenten app-engine-python und app-engine-python-extras installiert sind.
Führen Sie die folgenden Befehle aus:
1. Aktualisieren Sie die gcloud CLI.
```
gcloud components update
```
2. Die Google Cloud CLI (gcloud) muss berechtigt sein, auf Ihre Daten und Dienste in Google Cloud zuzugreifen:
```
gcloud auth login
```
3. Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.
4. Legen Sie für das Standardprojekt Ihre Projekt-ID fest:
```
gcloud config set project [YOUR_PROJECT_ID]
```
  Ersetzen Sie [YOUR_PROJECT_ID] durch Ihre Google Cloud-Projekt-ID. Wenn Sie weitere Google Cloud-Projekte mit gcloud verwalten möchten, lesen Sie gcloud CLI-Konfigurationen verwalten.
Sie benötigen eine Anwendung, um Anfragen an die Beispiel-API zu senden.
- Nutzer von Linux und macOS: Diese Anleitung enthält ein Beispiel, bei dem curl verwendet wird. Das Tool ist normalerweise auf Ihrem Betriebssystem vorinstalliert. Wenn curl nicht installiert ist, können Sie es von der Seite Releases und Downloads für curl herunterladen.
- Nutzer von Windows: Diese Anleitung enthält ein Beispiel, bei dem Invoke-WebRequest verwendet wird. Der Befehl wird in PowerShell ab Version 3.0 unterstützt.
Achten Sie darauf, dass Ihre Python-Entwicklungsumgebung pip enthält.
Vergewissern Sie sich, dass Sie C-Erweiterungen für Python kompilieren können.
- Windows: Microsoft Visual C++ 9.0 oder höher ist erforderlich. Sie können den Microsoft Visual C++ Compiler für Python 2.7 im Microsoft Download Center herunterladen.
- Andere Betriebssysteme: Abhängig von Ihrem Betriebssystem müssen Sie möglicherweise Compilertools (manchmal in einem Paket namens build-essential) bzw. die Python-Entwicklungs-Header (manchmal in einem Paket namens python-dev) installieren.
Legen Sie unter Linux für die Umgebungsvariable ENDPOINTS_GAE_SDK den Pfad Ihres App Engine SDK-Ordners fest: [Path-to-Google-Cloud-SDK]/platform/google_appengine.

Ersetzen Sie [Path-to-Google-Cloud-SDK] durch die Ausgabe des folgenden Befehls:
```
gcloud info --format="value(installation.sdk_root)"
```
Erstellen Sie eine App Engine-Anwendung:
1. Wählen Sie die Region aus, in der Sie Ihre App Engine-Anwendung erstellen möchten. Führen Sie den folgenden Befehl aus, damit eine Liste der Regionen angezeigt wird:
```
gcloud app regions list
```
2. Erstellen Sie mit dem folgenden Befehl eine App Engine-Anwendung. Ersetzen Sie [YOUR_PROJECT_ID] durch Ihre Google Cloud-Projekt-ID und [YOUR_REGION] durch die Region, in der die App Engine-Anwendung erstellt werden soll:
```
gcloud app create \
--project=[YOUR_PROJECT_ID] \
--region=[YOUR_REGION]
```
  Beispiel:
```
gcloud app create --project=example-project-12345 --region=us-central
```

Beispielcode abrufen

So klonen Sie die Beispiel-API aus GitHub:

Klonen Sie das Beispiel-Repository auf Ihrem lokalen Computer:

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

Ä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:

Prüfen Sie, ob Sie sich im Hauptverzeichnis python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo der Beispiel-API befinden.
Erstellen Sie im Projekt das Unterverzeichnis /lib:
```
mkdir lib
```
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:

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

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

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:

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

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

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

Für die API-Verwaltung erfordert Endpoints Frameworks folgende Dienste:

Name	Titel
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API
`endpoints.googleapis.com`	Google Cloud Endpoints

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
gcloud services enable endpoints.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 Endpunkte 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.

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

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

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 gedruckten Google Cloud Console-Logs angegeben:
```
INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
```
Senden Sie eine Anfrage an den lokalen Entwicklungsserver:

Linux oder macOS

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

Im vorherigen curl gilt Folgendes:

Durch die Option --data werden die an die API zu übertragenden Daten festgelegt.
Durch die Option --header wird angegeben, dass die Daten im JSON-Format vorliegen.

PowerShell

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

In diesem Beispiel enden die ersten beiden Zeilen mit einem Graviszeichen. Achten Sie beim Einfügen des Beispiels in PowerShell darauf, dass nach dem Graviszeichen kein Leerzeichen folgt. Informationen zu den in der Beispielanfrage verwendeten Optionen finden Sie in der Microsoft-Dokumentation unter Invoke-WebRequest.

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:

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

Öffnen Sie die Datei app.yaml im Verzeichnis python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

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

Nehmen Sie im Abschnitt env_variables die folgenden Änderungen vor:
- Ersetzen Sie YOUR-PROJECT-ID im Feld ENDPOINTS_SERVICE_NAME durch Ihre Google Cloud-Projekt-ID.
- Ersetzen Sie den Text im Feld ENDPOINTS_SERVICE_VERSION durch die Dienstkonfigurations-ID. Beispiel:
```
  ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com
  ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
```
Führen Sie dazu diesen Befehl aus:
```
gcloud app deploy
```
Befolgen Sie die angezeigten Anweisungen. Warten Sie kurz, bis die Bereitstellung abgeschlossen ist. Ignorieren Sie die Warnmeldungen. Nach Abschluss der Bereitstellung erhalten Sie in etwa folgende Meldung:
```
File upload done.
Updating service [default]...done.
```
Wenn Sie eine Fehlermeldung erhalten, lesen Sie die Informationen unter Fehlerbehebung in der App Engine-Dokumentation.

Warten Sie einige Minuten, bevor Sie Requests an Ihre API senden, damit App Engine die Initialisierung abschließen kann.

Anfrage an die Beispiel-API senden

Linux oder macOS

Senden Sie eine HTTP-Anfrage mithilfe von curl. Ersetzen Sie [YOUR_PROJECT_ID] durch Ihre Google Cloud-Projekt-ID.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

Im vorherigen curl gilt Folgendes:

Durch die Option --data werden die an die API zu übertragenden Daten festgelegt.
Durch die Option --header wird angegeben, dass die Daten im JSON-Format vorliegen.

PowerShell

Senden Sie eine HTTP-Anfrage mithilfe von Invoke-WebRequest. Ersetzen Sie [YOUR_PROJECT_ID] durch Ihre Google Cloud-Projekt-ID:

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content

Drittanbieteranwendung

Sie können eine Drittanbieteranwendung wie die Chrome-Browsererweiterung Postman zum Senden der Anfrage verwenden:

Wählen Sie POST als HTTP-Verb aus.
Wählen Sie für den Header den Schlüssel content-type und den Wert application/json aus.
Geben Sie als Text Folgendes ein:
{"message":"hello world"}
Geben Sie die URL zur Beispielanwendung ein. Beispiel:
https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

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

{
 "message": "hello world"
}

Wenn Sie als Antwort einen Fehler erhalten haben, lesen Sie die Informationen unter Fehlerbehebung bei Antwortfehlern.

API-Aktivität verfolgen

Sehen Sie sich in der Google Cloud Console auf der Seite Endpunkte > Dienste die Aktivitätsgrafiken für Ihre API an.

Endpoints-Dienste aufrufen

Es kann einige Momente dauern, bis die Anfrage in den Grafiken angezeigt wird.
Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.

Zur Seite „Log-Explorer“

Entwicklerportal für die API erstellen

Sie können mit dem Cloud Endpoints-Portal ein Entwicklerportal erstellen. Das ist eine Website zur Interaktion mit der Beispiel-API. Weitere Informationen finden Sie unter Übersicht über das Cloud Endpoints-Portal.

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie entweder das Projekt, das die Ressourcen enthält, oder Sie behalten das Projekt und löschen die einzelnen Ressourcen.

Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.
Zur Seite „Ressourcen verwalten“
Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen.
Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Shut down (Beenden), um das Projekt zu löschen.

Erste Schritte mit Cloud Endpoints Frameworks für Python

Lernziele

Kosten

Hinweise

Erforderliche Software installieren und konfigurieren

Beispielcode abrufen

Endpoints konfigurieren

Endpoints Frameworks-Bibliothek installieren

OpenAPI-Dokument erstellen

Endpoints-Konfiguration bereitstellen

Erforderliche Dienste prüfen

Beispiel lokal ausführen

Linux oder macOS

PowerShell

API-Back-End bereitstellen

Anfrage an die Beispiel-API senden

Linux oder macOS

PowerShell

Drittanbieteranwendung

API-Aktivität verfolgen

Entwicklerportal für die API erstellen

Bereinigen

Nächste Schritte