Traffic mit der Admin API migrieren und aufteilen

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.

Trafficmenge, die von einer Version Ihrer Anwendung empfangen wird, durch Migrieren und Aufteilen des Traffics verwalten

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].[REGION_ID].r.appspot.com verteilt den Traffic auf Versionen des Dienstes default.
[MY_SERVICE]-dot-[MY_PROJECT_ID].[REGION_ID].r.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 Google Cloud Console finden Sie unter Traffic migrieren und Traffic aufteilen.

Vorbereitung

Die Migration von Traffic mit der Admin API verhält sich anders als bei der Google Cloud Console. 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 an 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
- Autoscaling
  
  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 Autorisierung des Zugriffs auf die Admin API kann je nach den Anforderungen Ihrer API-Anwendung mit unterschiedlichen OAuth-Abläufen erfolgen. 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.
Mit der Methode patch der Sammlung apps.services können Sie die Konfiguration der Version entweder so migrieren, dass der Traffic migriert oder die Trafficaufteilung konfiguriert wird. 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 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. Erforderlich für die schrittweise Trafficmigration (migrateTraffic=true). 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 Paar key:value angegeben. Der Trafficprozentsatz wird als Dezimalbruch angegeben und muss in der Summe 1 ergeben. Beispiel: "allocations": { "v1": 0.8, "v2": 0.2 }
In der apps.services-Sammlung finden Sie Details und eine vollständige Liste der Parameter und Felder.

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 } } }
```
- Migrieren Sie den gesamten Traffic zu v2:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": 1 } } }
```
- Teilen Sie 80% des Traffics auf Version v1 und 20% auf v2 auf:
```
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: Der Server gibt Fehler zurück. Daher haben Sie den Fehler behoben, die neue v2-Version bereitgestellt und möchten den gesamten Traffic weiterleiten.

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

Prüfen Sie mit der Methode GET der apps.services-Sammlung, ob 100% des Traffics derzeit an die Version v1 gesendet werden.

HTTP-Beispielanfrage GET:

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

Beispielantwort:

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

Aktualisieren Sie die Konfiguration der Trafficaufteilung so, dass der gesamte Traffic mithilfe der Methode PATCH der apps.services-Sammlung auf die neue Version übertragen wird.

In der HTTP-PATCH-Anfrage müssen Sie den Dienst innerhalb der Anwendung angeben, in dem beide Versionen ausgeführt werden, z. B. default. Sie müssen auch das Feld updateMask mit dem Wert split angeben, um anzugeben, dass Sie die Konfiguration der Trafficaufteilung aktualisieren.

HTTP-Beispielanfrage PATCH:

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

Beispiel eines cURL-Befehls:

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"
  }
}

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 Vorgangs anzeigen lassen möchten, verwenden Sie die Methode GET der apps.operations-Sammlung zusammen mit dem Vorgang name, der in der HTTP-Antwort des vorherigen Schritts zurückgegeben wurde:
  
  HTTP-Beispielanfrage GET:
```
GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
```
  Dabei 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 eines cURL-Befehls:
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
2. Wenn der Vorgang abgeschlossen ist, können Sie die Details des Dienstes aufrufen, in dem sich die Version befindet. Hierfür verwenden Sie eine weitere HTTP-GET-Anfrage:
  
  HTTP-Beispielanfrage GET:
```
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
```
Optional: Mit einer HTTP-DELETE-Anfrage können Sie jetzt die fehlerhafte Version v1 aus Ihrer App Engine-Anwendung entfernen.

HTTP-Beispielanfrage DELETE:
```
DELETE https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Beispiel eines cURL-Befehls:
```
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 prüfen, ob der Vorgang erfolgreich war, der Löschvorgang abgeschlossen ist 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 Features enthalten. Sie möchten diese Features aber langsam einführen, sodass jede nur 20% des Traffics erhält.

Nach der Bereitstellung der Versionen v2 und v3 für Ihre App Engine-Anwendung verwenden Sie die HTTP-PATCH-Anfrage, um die drei Versionen so zu konfigurieren, dass der Traffic zu 60% an v1 und zu jeweils 20% an v2 undv3 aufgeteilt wird:

HTTP-Beispielanfrage 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 eines cURL-Befehls:

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:

HTTP-Beispielanfrage PATCH:

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

Beispielantwort:

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