Traffic mit der Admin API migrieren und aufteilen

Verwalten Sie die von einer Version Ihrer Anwendung empfangene Trafficmenge, indem Sie den Traffic migrieren oder aufteilen.

Bei der Trafficmigration wechselt das Anfragerouting nahtlos, sodass der Traffic von den derzeit empfangenen Versionen nach und nach an die von Ihnen angegebenen Versionen gesendet wird.

Bei der Trafficaufteilung wird ein Teil des Traffics auf Versionen Ihrer Anwendung verteilt. Sie können den Traffic wahlweise vollständig an eine einzelne Version senden oder einen Teil des Traffics an mehrere Versionen weiterleiten. Durch die Aufteilung des Traffics auf zwei oder mehr Versionen können Sie A/B-Tests zwischen den Versionen durchführen. Außerdem können Sie steuern, wie schnell Funktionen eingeführt werden.

Hinweis: Die Trafficaufteilung wird auf URLs angewendet, die nicht explizit auf eine Version ausgerichtet sind. Mit den folgenden URLs wird der Traffic beispielsweise aufgeteilt, weil sie auf alle verfügbaren Versionen innerhalb des angegebenen Dienstes ausgerichtet sind:

[MY_PROJECT_ID].appspot.com: Verteilt den Traffic auf Versionen des Standarddienstes default.
[MY_SERVICE].[MY_PROJECT_ID].appspot.com: Verteilt den Traffic auf Versionen des Dienstes MY_SERVICE.

Weitere Informationen finden Sie im Artikel über das Anfragenrouting.

Informationen zum manuellen Migrieren und Aufteilen von Traffic über die GCP Console finden Sie unter Traffic migrieren und Traffic aufteilen.

Vorbereitung

Traffic wird über die Admin API anders als über die GCP Console migriert. Für die Trafficmigration über die Admin API müssen Sie HTTP-Anfragen autorisieren können. Außerdem müssen die Versionen die Anforderungen für die Trafficmigration erfüllen:

Anforderungen für die Trafficmigration (migrateTraffic=true):

Ihr Nutzerkonto muss die erforderlichen Berechtigungen zum Konfigurieren des Traffics haben.
Die schrittweise Trafficmigration wird in der flexiblen App Engine-Umgebung nicht unterstützt.
Für eine schrittweise Trafficmigration müssen sich die Zielversionen in Instanzen befinden, die für Folgendes konfiguriert sind:
- Aufwärmanfragen
- Automatische Skalierung
  
  Weitere Informationen finden Sie in der Referenz zu app.yaml.

Traffic migrieren oder aufteilen

So können Sie Traffic zwischen Versionen Ihrer Anwendung aufteilen oder migrieren:

Autorisieren Sie Ihre HTTP-Anfragen, indem Sie zum Beispiel ein Zugriffstoken anfordern.

Die Zugriffsberechtigung zur Admin-API lässt sich über verschiedene OAuth-Abläufe erhalten. Dies hängt von den Anforderungen Ihrer API-App ab. Weitere Informationen finden Sie unter Zugriff auf die API.

Tipp: Wenn Sie Zugriffstokens verwenden möchten, können Sie diese direkt in OAuth 2.0 Playground abrufen.
Aktualisieren Sie die Konfiguration der Version mit der Methode patch der Sammlung apps.services, um den Traffic wahlweise zu migrieren oder aufzuteilen. Das folgende Beispiel der HTTP-Anfrage PATCH wurde zur besseren Lesbarkeit umgebrochen:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/
  ?updateMask=split {
    "split": {
      "shardBy": "[MY_SHARDBY_METHOD]",
      "allocations": { "[MY_APP_VERSION]": [MY_TRAFFIC_PERCENT] }
    }
  }
```
Parameter und Felder der HTTP-Anfrage:
- updateMask: Gibt an, welche der Felder in der Konfiguration aktualisiert werden sollen.
- migrateTraffic=true (optional): Gibt an, dass der Traffic schrittweise migriert werden soll.
  Wichtig: Die Versionen, für die Sie Traffic migrieren möchten, müssen die Anforderungen für die Trafficmigration erfüllen.
- split: Definiert die Konfiguration für Traffic zu Ihren Versionen.
  - shardBy (optional): Definiert die Methode zum Aufteilen des Traffics. Dies ist für die schrittweise Trafficmigration (migrateTraffic=true) erforderlich. Gültige Werte sind COOKIE und IP.
  - allocations: Definiert eine oder mehrere Versionen und den Anteil des Traffics, der an jede Version gesendet wird. Die Version und der Prozentsatz des Traffics werden als key:value-Paar angegeben. Der Trafficprozentsatz wird als Dezimalbruch angegeben und muss in der Summe 1 ergeben. Beispiel: "allocations": { "v1": 0.8, "v2": 0.2 }
Details und die vollständige Liste der Parameter und Felder finden Sie in der Sammlung apps.services.

Beispiel einer HTTP-Anfrage:
- Gesamten Traffic zu einer Version umleiten:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v1": 1 } } }
```
- Gesamten Traffic zu v2 migrieren:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": 1 } } }
```
- 80 % des Traffics an Version v1 und 20 % an v2 senden:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": 0.8, "v2": 0.2 } } }
```

Beispiel: Traffic zu einer anderen Version umleiten

In diesem Beispiel wird veranschaulicht, wie Sie den gesamten Traffic zu einer neu bereitgestellten Version umleiten. Beispiel: Nachdem Sie vom Server zurückgegebene Fehler behoben und die neue Version v2 bereitgestellt haben, soll der gesamten Traffic umgeleitet werden.

So leiten Sie den gesamten Traffic von v1 zu v2 um:

Prüfen Sie mit der Methode GET der Sammlung apps.services, ob aktuell der gesamte Traffic an Version v1 gesendet wird.

Beispiel der HTTP-Anfrage GET:

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Beispiel des Befehls "cURL":

 curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Beispielantwort:

{
  "name": "apps/[MY_PROJECT_ID]/services/default",
  "id": "default",
  "split": {
    "allocations": {
      "v1": 1
    }
  }
}

Aktualisieren Sie mit der Methode PATCH der Sammlung apps.services die Konfiguration der Trafficaufteilung, sodass der gesamte Traffic zur neuen Version geleitet wird.

Geben Sie den Dienst in der HTTP-Anfrage PATCH innerhalb der Anwendung an, in der beide Versionen ausgeführt werden, z. B. default. Schließen Sie außerdem das Feld updateMask mit dem Wert split ein. Sie geben dadurch an, dass Sie die Konfiguration der Trafficaufteilung aktualisieren.

Beispiel der HTTP-Anfrage PATCH:

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

Beispiel des Befehls "cURL":

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

Beispielantwort:

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

Tipp: Mit der vorangegangenen HTTP-Anfrage PATCH wird der Traffic sofort zu Version v2 umgeleitet. Wenn Sie den Traffic während der Migration schrittweise umleiten möchten, geben Sie den Parameter migrateTraffic=true an und beziehen Sie das Feld shardBy ein. Beispiel:

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": "1" } } }

Prüfen Sie, ob die Konfigurationsaktualisierung abgeschlossen ist:
1. Senden Sie die HTTP-Anfrage GET, um den Status des Aktualisierungsvorgangs anzuzeigen:
  
  Wenn Sie den Status des Aktualisierungsvorgangs prüfen möchten, verwenden Sie die Methode GET der Sammlung apps.operations zusammen mit dem Vorgangsnamen, der im vorherigen Schritt in der HTTP-Antwort im Feld name zurückgegeben wurde:
  
  Beispiel der HTTP-Anfrage GET:
```
GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
```
  Hierbei ist [OPERATION_NAME] der Wert des Feldes name in der Antwort der HTTP-Anfrage PATCH, die Sie im vorherigen Schritt gesendet haben.
  
  Wenn die HTTP-Antwort aus dem vorherigen Schritt Folgendes enthält:
```
"name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420"
```
  Dann rufen Sie den Vorgangsstatus mit der folgenden HTTP-Anfrage ab:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
  Beispiel des Befehls "cURL":
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
2. Nach Abschluss des Vorgangs können Sie die Details des Dienstes aufrufen, in dem sich die Version befindet. Hierfür verwenden Sie eine weitere HTTP-Anfrage vom Typ GET:
  
  Beispiel der HTTP-Anfrage GET:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
  Beispiel des Befehls "cURL":
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
Optional: Sie können die fehlerhafte Version v1 jetzt mit der HTTP-Anfrage DELETE aus Ihrer App Engine-Anwendung entfernen.

Beispiel der HTTP-Anfrage DELETE:
```
DELETE https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Beispiel des Befehls "cURL":
```
curl -X DELETE -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Tipp: Sie können mit HTTP-Anfragen vom Typ GET überprüfen, ob der Vorgang erfolgreich war, der Löschvorgang abgeschlossen und die Version gelöscht wurde.

Beispiel: Traffic zwischen Versionen aufteilen

Dieses Beispiel zeigt, wie Sie den Traffic auf mehrere Versionen Ihrer Anwendung aufteilen. Sie haben beispielsweise die Versionen v2 und v3 erstellt, die jeweils neue Funktionen enthalten. Sie möchten diese Funktionen nach und nach bereitstellen. Daher soll jede nur 20 % des Traffics erhalten.

Nach der Bereitstellung von Version v2 und v3 für die App Engine-Anwendung konfigurieren Sie mit der HTTP-Anfrage PATCH die drei Versionen so, dass der Traffic zu 60 % auf v1 und zu jeweils 20 % auf v2 und v3 aufgeteilt wird:

Beispiel der HTTP-Anfrage PATCH:

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": "0.6", "v2": "0.2", "v3": "0.2" } } }

Beispiel des Befehls "cURL":

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

Nachdem Sie überprüft haben, ob der Vorgang abgeschlossen wurde, können Sie mit der HTTP-Anfrage GET überprüfen, ob der Traffic zwischen den Versionen aufgeteilt wurde. Beispiel:

Beispiel der HTTP-Anfrage PATCH:

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Beispiel des Befehls "cURL":

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Beispielantwort:

{
  "name": "apps/[MY_PROJECT_ID]/services/default",
  "id": "default",
  "split": {
    "allocations": {
      "v1": 0.6,
      "v2": 0.2,
      "v3": 0.2
    }
  }
}

Vorbereitung

Traffic migrieren oder aufteilen

Beispiel: Traffic zu einer anderen Version umleiten

Beispiel: Traffic zwischen Versionen aufteilen

Feedback geben zu...