Migrazione e suddivisione del traffico con l'API Admin

ID regione

REGION_ID è un codice abbreviato assegnato da Google in base all'area geografica selezionata al momento della creazione dell'app. Il codice non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono sembrare simili ai codici paese e provincia di uso comune. Per le app create dopo febbraio 2020, REGION_ID.r è incluso negli URL di App Engine. Per le app esistenti create prima di questa data, l'ID regione è facoltativo nell'URL.

Scopri di più sugli ID regione.

Gestisci la quantità di traffico ricevuta da una versione dell'applicazione eseguendo la migrazione o la suddivisione del traffico.

La migrazione del traffico modifica il routing delle richieste in modo fluido, spostando gradualmente il traffico dalle versioni che attualmente ricevono traffico a una o più versioni specificate da te.

La suddivisione del traffico distribuisce una percentuale del traffico alle versioni della tua applicazione. Puoi suddividere il traffico per trasferire il 100% del traffico a una singola versione o instradare percentuali di traffico a più versioni. La suddivisione del traffico in due o più versioni ti consente di eseguire test A/B tra le tue versioni e di controllare la velocità durante l'implementazione delle funzionalità.

Ricorda: la suddivisione del traffico viene applicata agli URL che non hanno come target esplicito una versione. Ad esempio, i seguenti URL suddividono il traffico perché hanno come target tutte le versioni disponibili all'interno del servizio specificato:

[MY_PROJECT_ID].[REGION_ID].r.appspot.com: distribuisce il traffico alle versioni del servizio default.
[MY_SERVICE]-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com: distribuisce il traffico alle versioni del servizio MY_SERVICE.

Per ulteriori informazioni, vedi Modalità di routing delle richieste.

Per eseguire manualmente la migrazione e la suddivisione del traffico dalla console Google Cloud, consulta Migrazione del traffico e Suddivisione del traffico.

Prima di iniziare

La migrazione del traffico con l'API Admin si comporta in modo diverso dalla console Google Cloud. Per eseguire la migrazione del traffico con l'API Admin, devi essere in grado di autorizzare le richieste HTTP e le versioni devono soddisfare i requisiti di migrazione del traffico:

Requisiti per la migrazione del traffico (migrateTraffic=true):

Il tuo account utente deve includere i privilegi necessari prima di poter configurare il traffico.
La migrazione graduale del traffico non è supportata nell'ambiente flessibile di App Engine.
Per eseguire una migrazione graduale del traffico, le versioni di destinazione devono essere posizionate all'interno di istanze configurate per:
- Richieste di riscaldamento
- Scalabilità automatica
  
  Per informazioni sulla configurazione, consulta il riferimento app.yaml.

Migrazione o suddivisione del traffico

Per eseguire la migrazione o suddividere il traffico tra le versioni della tua app:

Autorizza le tue richieste HTTP, ad esempio ottieni un token di accesso.

L'autorizzazione dell'accesso all'API Admin può essere eseguita con flussi OAuth diversi, a seconda delle esigenze dell'app API. Per ulteriori informazioni, consulta la sezione Accesso all'API.

Suggerimento: se vuoi utilizzare token di accesso, puoi ottenerli immediatamente da OAuth 2.0 Playground.
Utilizza il metodo patch della raccolta apps.services per aggiornare la configurazione della versione in modo da eseguire la migrazione del traffico o configurare la suddivisione del traffico. La seguente richiesta HTTP PATCH di esempio è stata sottoposta a wrapping intenzionalmente per la leggibilità:
```
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] }
    }
  }
```
Parametri e campi delle richieste HTTP:
- updateMask: specifica quali campi della configurazione aggiornare.
- (Facoltativo) migrateTraffic=true: specifica di eseguire la migrazione graduale del traffico.
  Importante: le versioni per le quali vuoi eseguire la migrazione del traffico devono soddisfare i requisiti di migrazione del traffico.
- split: definisce la configurazione per il traffico verso le tue versioni.
  - shardBy (facoltativo): definisce il metodo utilizzato per suddividere il traffico. Obbligatorio per la migrazione graduale del traffico (migrateTraffic=true). I valori validi sono COOKIE o IP.
  - allocations: definisce una o più versioni e la percentuale di traffico distribuita a ogni versione. La versione e la percentuale del traffico sono specificate come coppia key:value. La percentuale di traffico è specificata come frazione decimale e deve avere come somma 1. Esempio: "allocations": { "v1": 0.8, "v2": 0.2 }
Consulta la raccolta apps.services per i dettagli e l'elenco completo di parametri e campi.

Esempi di richieste HTTP:
- Sposta tutto il traffico in una versione:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v1": 1 } } }
```
- Esegui la migrazione di tutto il traffico a v2:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": 1 } } }
```
- Suddividi l'80% del traffico alla versione v1 e il 20% alla versione v2:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": 0.8, "v2": 0.2 } } }
```

Esempio: spostare il traffico a un'altra versione

Questo esempio mostra come spostare tutto il traffico in una nuova versione di cui hai appena eseguito il deployment. Ad esempio, il server restituisce errori, quindi hai corretto il bug, hai eseguito il deployment della nuova versione di v2 e ora vuoi reindirizzare tutto il traffico.

Per spostare tutto il traffico da v1 a v2:

Verifica che il 100% del traffico venga attualmente inviato alla versione v1 con il metodo GET della raccolta apps.services.

Esempio di richiesta GET HTTP:

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

Esempio di comando cURL:

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

Esempio di risposta:

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

Aggiorna la configurazione di suddivisione del traffico in modo che tutto il traffico venga spostato alla nuova versione utilizzando il metodo PATCH della raccolta apps.services.

Nella richiesta HTTP PATCH, devi specificare il servizio all'interno della tua applicazione in cui sono in esecuzione entrambe le versioni, ad esempio default. Devi anche includere il campo updateMask con il valore split per indicare che stai aggiornando la configurazione di suddivisione del traffico.

Esempio di richiesta PATCH HTTP:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v2": "1" } } }
```
Esempio di comando 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
```
Esempio di risposta:
```
{
  "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"
  }
}
```
Suggerimento: la richiesta HTTP PATCH riportata sopra trasferisce immediatamente il traffico alla versione v2. Se vuoi eseguire la migrazione del traffico in modo che venga reindirizzato gradualmente, devi specificare il parametro migrateTraffic=true e includere il campo shardBy, ad esempio:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": "1" } } }
```
Nota: le versioni per cui vuoi eseguire la migrazione del traffico devono soddisfare i requisiti di migrazione del traffico.
Assicurati che l'aggiornamento della configurazione sia stato completato:
1. Visualizza lo stato dell'operazione di aggiornamento con una richiesta HTTP GET:
  
  Per visualizzare lo stato dell'operazione che esegue l'aggiornamento, utilizza il metodo GET della raccolta apps.operations insieme all'operazione name restituita nella risposta HTTP del passaggio precedente:
  
  Esempio di richiesta GET HTTP:
```
GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
```
  Dove [OPERATION_NAME] è il valore del campo name nella risposta alla richiesta HTTP PATCH inviata nel passaggio precedente.
  
  Se la risposta HTTP del passaggio precedente include:
```
"name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420"
```
  Quindi, invia la seguente richiesta HTTP per visualizzare lo stato dell'operazione:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
  Esempio di comando cURL:
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
2. Al termine dell'operazione, puoi visualizzare i dettagli del servizio in cui si trova la versione con un'altra richiesta GET HTTP:
  
  Esempio di richiesta GET HTTP:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
  Esempio di comando cURL:
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
(Facoltativo) Ora puoi rimuovere la versione v1 errata dall'applicazione App Engine con una richiesta DELETE HTTP.

Esempio di richiesta DELETE HTTP:
```
DELETE https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Esempio di comando cURL:
```
curl -X DELETE -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Suggerimento: puoi eseguire richieste HTTP GET per verificare che l'operazione sia riuscita, una per verificare che l'operazione di eliminazione sia stata completata e un'altra per verificare che la versione sia stata eliminata.

Esempio: suddividere il traffico tra le versioni

Questo esempio mostra come configurare la suddivisione del traffico tra più versioni dell'applicazione. Ad esempio, hai appena creato le versioni v2 e v3, ognuna delle quali include nuove funzionalità, ma vuoi implementarle lentamente, in modo che ciascuna riceva solo il 20% del traffico.

Dopo aver eseguito il deployment delle versioni v2 e v3 nell'applicazione App Engine, utilizza la richiesta HTTP PATCH per configurare le tre versioni in modo che il traffico venga suddiviso per il 60% in v1 e per il 20% ciascuna in v2 e v3:

Esempio di richiesta PATCH HTTP:

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

Esempio di comando 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

Dopo aver verificato il completamento dell'operazione, puoi inviare la richiesta HTTP GET per verificare che il traffico sia stato suddiviso tra le tue versioni, ad esempio:

Esempio di richiesta PATCH HTTP:

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

Esempio di comando cURL:

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

Esempio di risposta:

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