Erste Schritte mit der Admin API

Regions-ID

REGION_ID ist ein abgekürzter Code, den Google anhand der Region zuweist, die Sie beim Erstellen Ihrer Anwendung ausgewählt haben. Der Code bezieht sich nicht auf ein Land oder eine Provinz, auch wenn einige Regions-IDs häufig verwendeten Länder- und Provinzcodes ähneln können. Bei Anwendungen, die nach Februar 2020 erstellt wurden, ist REGION_ID.r in den App Engine-URLs enthalten. Bei Anwendungen, die vor diesem Datum erstellt wurden, ist die Regions-ID in der URL optional.

Hier finden Sie weitere Informationen zu Regions-IDs.

Hier wird erläutert, wie Sie mit der App Engine Admin API eine Python-Beispielanwendung in App Engine bereitstellen. Sie erhalten einen Überblick über das Erstellen von Code, mit dem Sie Ihre Anwendungen programmatisch verwalten und bereitstellen können.

Hier wird als Beispiel die einfache, in GitHub verfügbare Anwendung "Hello World" verwendet, die den Text "Hello, World!" anzeigt. Für die Autorisierung mit der Google Cloud Console werden eine OAuth-Client-ID und ein Webbrowser verwendet. Zur Demonstration der einzelnen Schritte werden cURL-Befehle bereitgestellt, mit denen Sie von Ihrem Terminal aus HTTP-Anfragen senden können.

Ziele

APIs in Ihrem Google Cloud Console-Projekt aktivieren und OAuth-Client-ID-Anmeldedaten erstellen
Zugriffstoken für die Authentifizierung bei App Engine anfordern
Über die Admin API die Beispielanwendung in App Engine bereitstellen
Optional: Traffic für die Version konfigurieren, in der Sie die Beispielanwendung bereitgestellt haben

Vorbereitung

Sie müssen ein Google-Konto haben oder erstellen.
Laden Sie die Google Cloud-CLI herunter und installieren Sie sie. Anschließend initialisieren Sie die gcloud CLI:
SDK herunterladen

Google Cloud-Projekt konfigurieren

Aktivieren Sie die App Engine Admin API und die Cloud Storage APIs in Ihrem Google Cloud-Projekt und konfigurieren Sie dann Anmeldedaten:

Aktivieren Sie die APIs in der Google Cloud Console:

APIs aktivieren
Wählen Sie im Assistenten ein vorhandenes Projekt in der Liste aus oder klicken Sie auf Weiter, um ein neues Projekt zu erstellen.
Klicken Sie auf Weiter, um Anmeldedaten mit OAuth-Client-ID zu erstellen:
1. Geben Sie im OAuth-Zustimmungsbildschirm zumindest Ihre E-Mail-Adresse an und füllen Sie das Feld Produktname, den Nutzer sehen aus.
2. Klicken Sie auf Speichern, um die Einstellungen des Zustimmungsbildschirms zu speichern und zum Tab Anmeldedaten zu wechseln.
3. Klicken Sie auf Anmeldedaten erstellen und dann auf OAuth-Client-ID, um eine Client-ID zu erstellen.
4. Klicken Sie auf Webanwendung, geben Sie einen Namen an und verwenden Sie dann https://www.google.com als Weiterleitungs-URI.
  
  Hinweis: Durch den Weiterleitungs-URI wird festgelegt, wohin die HTTP-Antwort gesendet wird. Der URI https://www.google.com wird in diesem Leitfaden als Beispiel verwendet. Für die Produktion müssen Sie jedoch den Authentifizierungsendpunkt Ihrer Anwendung angeben, der Antworten vom OAuth 2.0-Server verarbeitet.
5. Klicken Sie auf Erstellen, um die Anmeldedaten zu speichern.
6. Notieren Sie sich die angezeigte Client-ID. Sie benötigen sie in einem späteren Schritt zum Anfordern des Zugriffstokens.

Weitere Informationen zum Erstellen von Anmeldedaten für die Admin API finden Sie unter Admin API aufrufen.

Konfigurationsdatei erstellen

Erstellen Sie eine Konfigurationsdatei, in der Sie die Bereitstellung der Anwendung "Hello World" definieren. Geben Sie in einer Datei mit dem Namen app.json den Cloud Storage-Bucket der Hello World-Anwendung im Feld sourceUrl und die Konfigurationsinformationen für die Version an, einschließlich der Versions-ID im Feld id.

{
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

Beispiel: root/python-docs-samples/appengine/standard/hello_world/app.json

HTTP-Anfragen autorisieren

Wenn Sie sich mit App Engine authentifizieren, können Sie über die Admin API HTTP-Anfragen senden.

Verwenden Sie für einen schnellen Einstieg eine der folgenden Optionen. Sowohl mit der Option HTTPS als auch mit gcloud können Sie manuelle, aber einfache Schritte zum Abrufen von Zugriffstokens für das Testen der Admin API ausführen.

HTTPS

Wenn Sie einen clientseitigen OAuth 2.0-Flow simulieren möchten, fügen Sie einem URI Ihre OAuth-Client-ID hinzu. Senden Sie dann die HTTPS-Anfrage über Ihren Webbrowser:

Fordern Sie in Ihrem Webbrowser mit der Client-ID Ihrer API-Anmeldedaten ein Zugriffstoken an. Im folgenden Beispiel werden client_id=[MY_CLIENT_ID] und redirect_uri=https://www.google.com verwendet, wobei [MY_CLIENT_ID] die Client-ID der zuvor erstellten Anmeldedaten ist:
```
https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=[MY_CLIENT_ID]&scope=https://www.googleapis.com/auth/cloud-platform&redirect_uri=https://www.google.com
```
Rufen Sie das Zugriffstoken aus der Anfrageantwort ab.

Das Adressfeld in Ihrem Webbrowser sollte den Weiterleitungs-URI, den Sie in Ihren Anmeldedaten angegeben haben, und das dem URI angehängte Zugriffstoken enthalten. Beispiel:
```
https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
```
Jetzt können Sie mit dem Zugriffstoken [MY_ACCESS_TOKEN] im Feld access_token HTTP-Anfragen an Ihr Google Cloud-Projekt senden.

gcloud

Führen Sie die folgenden gcloud-Befehle aus, um ein Zugriffstoken einfach abzurufen:

Legen Sie die Standardanmeldedaten für die Anwendung fest, mit denen Sie ein Zugriffstoken anfordern möchten:
```
gcloud auth application-default login
```

Fordern Sie das Zugriffstoken an:

gcloud auth application-default print-access-token

Weitere Informationen zu diesen Befehlen finden Sie unter gcloud auth application-default.

Hinweis: Das Zugriffstoken läuft ungefähr 60 Minuten nach der Ausgabe ab.

Die oben aufgeführten Optionen sind nicht für die Verwendung in Ihrer programmatischen Implementierung vorgesehen. Wie Sie eine OAuth 2.0-Autorisierung implementieren, erfahren Sie unter Admin API aufrufen.

Anwendung "Hello World" bereitstellen

Sie stellen die Anwendung "Hello World" mit einer HTTP-Anfrage über die Admin API bereit:

Senden Sie mithilfe der Admin API eine HTTP-POST-Anfrage, um eine Version der Anwendung "Hello World" bereitzustellen. Beispiel:

POST https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions app.json

Beispiel eines cURL-Befehls:

Führen Sie den Befehl in dem Verzeichnis aus, in dem Sie die Konfigurationsdatei app.json erstellt haben. Beispiel:

cd root/python-docs-samples/appengine/standard/hello_world/

curl -X POST -T "app.json" -H "Content-Type: application/json" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions

Dabei gilt:

[MY_ACCESS_TOKEN] ist das Zugriffstoken, das Sie erhalten haben, um Ihre HTTP-Anfragen zu autorisieren.
[MY_PROJECT_ID] ist die ID des Projekts, in dem Sie die Version bereitstellen möchten.

Beispielantwort:

{
  "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2016-07-29T17:12:44.679Z",
    "method": "google.appengine.v1.Versions.CreateVersion",
    "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "user": "me@example.com"
  }
}

Dabei ist [MY_PROJECT_ID] Ihre Google Cloud-Projekt-ID.

Prüfen Sie, ob die Version der Anwendung "Hello World" in Ihrer App Engine-Anwendung erfolgreich bereitgestellt wurde:

Sehen Sie sich den Status des tatsächlichen Bereitstellungsvorgangs an. Verwenden Sie dazu den Namen des Vorgangs, der im vorherigen Schritt als Feld name in einer HTTP-GET-Methode zurückgegeben wurde. Beispiel:

GET https://appengine.googleapis.com/v1/[OPERATION_NAME]

Beispiel eines cURL-Befehls:

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/[OPERATION_NAME]

Dabei gilt:

[OPERATION_NAME] ist der Wert des Feldes name, der im vorherigen Schritt beim Bereitstellen der Anwendung zurückgegeben wurde, z. B. apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85.
[MY_ACCESS_TOKEN] ist das Zugriffstoken, das Sie erhalten haben, um Ihre HTTP-Anfragen zu autorisieren.
[MY_PROJECT_ID] ist die ID des Projekts, in dem Sie die Version bereitstellen möchten.

Beispielantwort:

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "endTime": "2016-07-29T17:13:20.424Z",
    "insertTime": "2016-07-29T17:12:44.679Z",
    "method": "google.appengine.v1.Versions.CreateVersion",
    "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "user": "me@example.com"
  },
  "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
  "response": {
    "@type": "type.googleapis.com/google.appengine.v1.Version",
    "creationTime": "2016-07-29T17:12:46.000Z",
    "deployer": "me@example.com",
    "id": "appengine-helloworld",
    "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "runtime": "python27",
    "servingStatus": "SERVING",
    "threadsafe": true,
  }
}

Dabei ist [MY_PROJECT_ID] Ihre Google Cloud-Projekt-ID.

Prüfen Sie, ob die Version der Anwendung "Hello World" in der App Engine-Anwendung erstellt wurde. Rufen Sie dazu mit einer HTTP-GET-Anfrage die Versionsdetails auf. Beispiel:

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL

Beispiel eines cURL-Befehls:

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL

Dabei gilt:

[MY_ACCESS_TOKEN] ist das Zugriffstoken, das Sie erhalten haben, um Ihre HTTP-Anfragen zu autorisieren.
[MY_PROJECT_ID] ist die ID des Projekts, in dem Sie die Version bereitstellen möchten.

Beispielantwort:

{
  "creationTime": "2016-07-29T17:12:46.000Z",
  "deployer": "me@example.com",
  "deployment": {
    "files": {
      "main.py": {
        "sha1Sum": "13f7ea1e24f7cd2de5c66660525f2b509da37c14",
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      }
    }
  },
  "handlers": [
    {
      "authFailAction": "AUTH_FAIL_ACTION_REDIRECT",
      "login": "LOGIN_OPTIONAL",
      "script": {
        "scriptPath": "main.app",
      },
      "securityLevel": "SECURE_OPTIONAL",
      "urlRegex": "/.*"
    }
  ]
  "id": "appengine-helloworld",
  "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
  "runtime": "python27",
  "servingStatus": "SERVING",
  "threadsafe": true,
  "versionUrl": "https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot"
}

Dabei ist [MY_PROJECT_ID] Ihre Google Cloud-Projekt-ID.

Rufen Sie die Anwendung "Hello World" in Ihrem Webbrowser auf. Verwenden Sie hierfür die URL im Feld versionUrl der HTTP-Antwort des vorherigen Schritts. Beispiel:
```
https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com
```
Dabei ist [MY_PROJECT_ID] Ihre Google Cloud-Projekt-ID.
REGION_ID ist ein abgekürzter Code, den Google anhand der Region zuweist, die Sie beim Erstellen Ihrer Anwendung ausgewählt haben. Der Code bezieht sich nicht auf ein Land oder eine Provinz, auch wenn einige Regions-IDs häufig verwendeten Länder- und Provinzcodes ähneln können. Bei Anwendungen, die nach Februar 2020 erstellt wurden, ist REGION_ID.r in den App Engine-URLs enthalten. Bei Anwendungen, die vor diesem Datum erstellt wurden, ist die Regions-ID in der URL optional.

Konfigurieren Sie den Traffic für die Anwendung "Hello World".

Standardmäßig wird der gesamte Traffic an die anfänglich in einer neuen App Engine-Anwendung bereitgestellte Version gesendet. Nachfolgende Versionen erhalten keinen Traffic.

Prüfen Sie mit der HTTP-Anfrage GET, ob Ihre Version für den Empfang von Traffic konfiguriert ist. Beispiel:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
Beispiel eines cURL-Befehls:
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
Dabei gilt:
- [MY_ACCESS_TOKEN] ist das Zugriffstoken, das Sie erhalten haben, um Ihre HTTP-Anfragen zu autorisieren.
- [MY_PROJECT_ID] ist die ID des Projekts, in dem Sie die Version bereitstellen möchten.
Beispielantwort:
```
{
  "name": "apps/[MY_PROJECT_ID]/services/default/",
  "id": "default",
  "split": {
    "allocations": {
      "appengine-helloworld": 1
    }
  }
}
```
Dabei ist [MY_PROJECT_ID] Ihre Google Cloud-Projekt-ID.

Senden Sie eine HTTP-PATCH-Anfrage, um den gesamten Traffic zu einer Version zu verschieben. Beispiel:

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "appengine-helloworld": 1 } } }

Beispiel eines cURL-Befehls:

curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'allocations': { 'appengine-helloworld': '1' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

Dabei gilt:

[MY_ACCESS_TOKEN] ist das Zugriffstoken, das Sie erhalten haben, um Ihre HTTP-Anfragen zu autorisieren.
[MY_PROJECT_ID] ist die ID des Projekts, in dem Sie die Version bereitstellen möchten.

Beispielantwort:

{
  "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2016-07-29T17:25:30.413Z",
    "method": "com.google.appengine.v1.Services.UpdateService",
    "target": "apps/[MY_PROJECT_ID]/services/default",
    "user": "me@example.com"
  }
}

Dabei ist [MY_PROJECT_ID] Ihre Google Cloud-Projekt-ID.

Erweitertes Lernen

Wenn Sie mehrere Versionen einer Anwendung haben, können Sie den Traffic mit den folgenden Schritten aufteilen:

Stellen Sie in derselben App Engine-Anwendung eine zweite Version der Anwendung "Hello World" bereit:
1. Aktualisieren Sie in der vorhandenen Konfigurationsdatei app.json der Anwendung "Hello World", die Sie zuvor erstellt haben, das Feld id, um eine andere Version anzugeben. Hängen Sie beispielsweise -2 an:
```
"id": "appengine-helloworld-2"
```
2. Führen Sie dieselben Schritte noch einmal aus, um eine appengine-helloworld-2-Version bereitzustellen. Beispiel:
  1. Authentifizieren Sie sich bei Ihrem Projekt.
  2. Stellen Sie die neue Version appengine-helloworld-2 bereit.
  3. Prüfen Sie, ob die Version appengine-helloworld-2 erfolgreich bereitgestellt wurde.
  4. Sehen Sie sich die ausgeführte Anwendung in Ihrem Webbrowser an.

Folgen Sie der Anleitung zum Migrieren und Aufteilen des Traffics. Senden Sie beispielsweise die HTTP-Anfrage PATCH:

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }

Beispiel eines cURL-Befehls:

curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

Dabei gilt:

[MY_ACCESS_TOKEN] ist das Zugriffstoken, das Sie erhalten haben, um Ihre HTTP-Anfragen zu autorisieren.
[MY_PROJECT_ID] ist die ID des Projekts, in dem Sie die Version bereitstellen möchten.

Nächste Schritte

Anmeldedaten für Ihre Anwendungen erstellen, konfigurieren und einrichten: Admin API aufrufen