Questa pagina è stata tradotta dall'API Cloud Translation.

Migrazione e suddivisione del traffico con l'API Admin

ID regione

REGION_ID è un codice abbreviato assegnato da Google in base alla regione selezionata al momento della creazione dell'app. Il codice non corrispondono a un paese o a una provincia, anche se potrebbero essere visualizzati alcuni ID regione in modo simile ai codici paese e provincia di uso comune. Per le app create dopo il giorno Febbraio 2020, REGION_ID.r è incluso in 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 il volume di traffico ricevuto da una versione della tua applicazione per eseguire la migrazione o la suddivisione del traffico.

La migrazione del traffico cambia facilmente il routing delle richieste, spostandosi gradualmente traffico dalle versioni che attualmente ricevono traffico verso una o più versioni da te specificati.

La suddivisione del traffico distribuisce una percentuale di traffico alle versioni della tua applicazione. Puoi suddividere il traffico per indirizzare il 100% del traffico a una singola versione o per instradare percentuali di traffico a più versioni. Suddivisione del traffico a due o più versioni ti consente di eseguire test A/B tra le versioni e controlla il ritmo 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.

REGION_ID è un codice abbreviato assegnato da Google in base alla regione selezionata quando crei l'app. Il codice non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono sembrare simili ai codici di paesi e province 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.

Per ulteriori informazioni, consulta la sezione Come vengono effettuate le richieste Routed.

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

Prima di iniziare

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

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

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

Migrazione o suddivisione del traffico

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

Autorizzare le richieste HTTP, ad esempio ottenere un token di accesso.

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

Suggerimento: se vuoi utilizzare i token di accesso, puoi ottenerle immediatamente dal OAuth 2.0 Playground.
Utilizza il metodo patch della raccolta apps.services per aggiornare la configurazione della versione per eseguire la migrazione del traffico o configurare la suddivisione del traffico. La seguente richiesta HTTP PATCH di esempio ha aggregato intenzionalmente per una migliore 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 della richiesta HTTP:
- updateMask: specifica su quale campo della configurazione aggiornamento.
- migrateTraffic=true (facoltativo): specifica di eseguire la migrazione del traffico gradualmente.
  Importante: le versioni per cui vuoi per eseguire la migrazione del traffico deve soddisfare il traffico requisiti per la migrazione.
- split: definisce la configurazione del 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 ciascuna versione. La versione e la percentuale di traffico sono specificate come coppia key:value. La percentuale di traffico è specificata come frazione decimale e deve essere pari a 1. Esempio: "allocations": { "v1": 0.8, "v2": 0.2 }
Visualizza la raccolta apps.services per informazioni dettagliate e l'elenco completo dei parametri e dei campi.

Esempi di richieste HTTP:
- Sposta tutto il traffico a 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 è appena stato eseguito il deployment. Ad esempio, se il server restituisce errori, hai corretto i ha 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 sia attualmente inviato alla versione v1 con il metodo GET di apps.services di Google Cloud.

Richiesta HTTP GET di esempio:

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

Comando cURL di esempio:

 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 nella nuova versione utilizzando il metodo PATCH di apps.services personalizzata.

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

Richiesta HTTP PATCH di esempio:

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

Comando cURL di esempio:

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

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

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 collezione apps.operations insieme all'operazione name restituita nella risposta HTTP del passaggio precedente:
  
  Esempio di richiesta HTTP GET:
```
GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
```
  Dove [OPERATION_NAME] è il valore del campo name nella risposta della 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
```
  Comando cURL di esempio:
```
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:
  
  Richiesta HTTP GET di esempio:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
  Comando cURL di esempio:
```
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 difettosa dalla tua applicazione App Engine con una richiesta DELETE HTTP.

Richiesta HTTP DELETE di esempio:
```
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 andata a buon fine, una per verificare il completamento dell'operazione di eliminazione e un'altra per verificare che la versione sia stata eliminata.

Esempio: suddivisione del traffico tra versioni

Questo esempio mostra come configurare la suddivisione del traffico tra più le versioni precedenti della tua applicazione. Ad esempio, hai appena creato le versioni v2 e v3 che includono ciascuna 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 in 60% per v1 e 20% per v2 e v3:

Richiesta HTTP PATCH di esempio:

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

Comando cURL di esempio:

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 il prompt HTTP GET richiesta di verificare che il traffico sia stato suddiviso tra le tue versioni, Ad esempio:

Esempio di richiesta HTTP PATCH:

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

Comando cURL di esempio:

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

Risposta di esempio:

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