Introduzione all'API Admin

ID regione

REGION_ID è un codice abbreviato assegnato da Google in base alla regione selezionata al momento della creazione dell'app. Non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono apparire simili ai codici di 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.

Questa guida è pensata per aiutarti a imparare a utilizzare l'API App Engine Admin per eseguire il deployment di un'applicazione Python di esempio in App Engine. Puoi utilizzare l'intero processo per ottenere insight su come creare codice che gestisce ed esegue il deployment delle tue app in modo programmatico.

In questa guida, l'esempio utilizzato è una semplice app Hello World che visualizza il testo "Hello, World!" ed è disponibile in GitHub. Per l'autorizzazione con la console Google Cloud, vengono utilizzati un ID client OAuth e un browser web. Per dimostrare i singoli passaggi della procedura, vengono forniti i comandi cURL che ti consentono di inviare richieste HTTP dal tuo terminale.

Obiettivi

Abilita le API nel progetto della console Google Cloud e crea le credenziali dell'ID client OAuth.
Ottenere token di accesso per l'autenticazione con App Engine.
Utilizza l'API Admin per eseguire il deployment dell'app di esempio in App Engine.
(Facoltativo) Configura il traffico verso la versione in cui hai eseguito il deployment dell'app di esempio.

Prima di iniziare

Devi avere o creare un Account Google.
Scarica e installa Google Cloud CLI, quindi inizializza gcloud CLI:
Scarica l'SDK

Configurazione del tuo progetto Google Cloud

Abilita l'API App Engine Admin e le API Cloud Storage nel tuo progetto Google Cloud, quindi configura le credenziali:

Abilita le API nella console Google Cloud:

Abilita le API
Nella procedura guidata, seleziona un progetto esistente dall'elenco o fai clic su Continua per creare un nuovo progetto.
Fai clic su Continua per creare una credenziale ID client OAuth:
1. Nella schermata di consenso OAuth, specifica almeno il tuo Indirizzo email e il Nome del prodotto mostrato agli utenti.
2. Salva le impostazioni della schermata per il consenso e poi passa alla scheda Credenziali facendo clic su Salva.
3. Fai clic su Crea credenziali, quindi su ID client OAuth per creare un ID client.
4. Fai clic su Applicazione web, specifica un nome, quindi utilizza https://www.google.com come URI di reindirizzamento.
  
  Nota: l'URI di reindirizzamento definisce dove viene inviata la risposta HTTP. L'URI https://www.google.com viene utilizzato in questa guida come esempio, ma per la produzione devi specificare l'endpoint di autenticazione dell'applicazione, che gestisce le risposte dal server OAuth 2.0.
5. Fai clic su Crea per salvare la credenziale.
6. Prendi nota dell'ID client visualizzato perché verrà utilizzato in un passaggio successivo per richiedere il token di accesso.

Per ulteriori informazioni sulla creazione delle credenziali per l'API Admin, consulta la sezione Accesso all'API.

Creazione di un file di configurazione

Crea un file di configurazione che definisca il deployment dell'app Hello World. In un file denominato app.json, definisci il bucket Cloud Storage dell'app Hello World nel campo sourceUrl e le informazioni di configurazione per la versione, incluso l'ID versione nel campo 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"
  ]
}

Ad esempio, root/python-docs-samples/appengine/standard/hello_world/app.json

Autorizzazione delle richieste HTTP

Esegui l'autenticazione con App Engine in modo da poter inviare richieste HTTP con l'API Admin.

Utilizza una delle seguenti opzioni per iniziare rapidamente. Entrambe le opzioni HTTPS e gcloud forniscono una procedura manuale, ma semplice, per ottenere i token di accesso allo scopo di provare l'API Admin.

HTTPS

Per simulare un flusso OAuth 2.0 lato client, aggiungi la credenziale dell'ID client OAuth a un URI, quindi invia la richiesta HTTPS tramite il tuo browser web:

Nel browser web, richiedi un token di accesso utilizzando l'ID client delle credenziali dell'API. L'esempio seguente utilizza client_id=[MY_CLIENT_ID] e redirect_uri=https://www.google.com, dove [MY_CLIENT_ID] è l'ID client della credenziale che hai creato in precedenza:
```
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
```
Recupera il token di accesso dalla risposta alla richiesta.

Il campo dell'indirizzo del browser web deve contenere l'URI di reindirizzamento specificato nelle credenziali insieme al token di accesso aggiunto all'URI, ad esempio:
```
https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
```
Ora puoi utilizzare il token di accesso [MY_ACCESS_TOKEN] fornito nel campo access_token per inviare richieste HTTP al tuo progetto Google Cloud.

gcloud

Per recuperare semplicemente un token di accesso, esegui questi comandi gcloud:

Imposta la credenziale predefinita di applicazione (ADC) che vuoi utilizzare per richiedere un token di accesso:
```
gcloud auth application-default login
```

Richiedi il token di accesso:

gcloud auth application-default print-access-token

Per maggiori dettagli su questi comandi, vedi gcloud auth application-default.

Ricorda: il token di accesso scade circa 60 minuti dopo l'emissione.

Le opzioni precedenti non sono destinate all'utilizzo nell'implementazione programmatica, ma le informazioni su come implementare un flusso di autorizzazione OAuth 2.0 sono disponibili in Accesso all'API Admin.

Deployment dell'app Hello World

Utilizzi una richiesta HTTP per eseguire il deployment dell'app Hello World con l'API Admin:

Invia una richiesta POST HTTP utilizzando l'API Admin per eseguire il deployment di una versione dell'app Hello World nella tua applicazione App Engine, ad esempio:

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

Comando cURL di esempio:

Esegui il comando dalla directory in cui hai creato il file di configurazione app.json, ad esempio:

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

Dove:

[MY_ACCESS_TOKEN] è il token di accesso che hai ottenuto per autorizzare le richieste HTTP.
[MY_PROJECT_ID] è l'ID del progetto in cui vuoi eseguire il deployment della versione.

Esempio di risposta:

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

Dove [MY_PROJECT_ID] è il tuo ID progetto Google Cloud.

Verifica che il deployment della versione dell'app Hello World sia stato eseguito correttamente nell'applicazione App Engine:

Visualizza lo stato dell'operazione di deployment effettiva utilizzando il nome dell'operazione restituita nel passaggio precedente come campo name in un metodo GET HTTP, ad esempio:

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

Comando cURL di esempio:

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

Dove:

[OPERATION_NAME] è il valore del campo name restituito nel passaggio precedente quando hai eseguito il deployment dell'app, ad esempio apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85.
[MY_ACCESS_TOKEN] è il token di accesso che hai ottenuto per autorizzare le richieste HTTP.
[MY_PROJECT_ID] è l'ID del progetto in cui vuoi eseguire il deployment della versione.

Esempio di risposta:

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

Dove [MY_PROJECT_ID] è il tuo ID progetto Google Cloud.

Verifica che la versione dell'app Hello World sia stata creata nell'applicazione App Engine utilizzando una richiesta HTTP GET per visualizzare i dettagli della versione, ad esempio:

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

Comando cURL di esempio:

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

Dove:

[MY_ACCESS_TOKEN] è il token di accesso che hai ottenuto per autorizzare le richieste HTTP.
[MY_PROJECT_ID] è l'ID del progetto in cui vuoi eseguire il deployment della versione.

Esempio di risposta:

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

Dove [MY_PROJECT_ID] è il tuo ID progetto Google Cloud.

Visualizza l'app Hello World nel browser web visitando l'URL specificato nel campo versionUrl della risposta HTTP del passaggio precedente, ad esempio:
```
https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com
```
Dove [MY_PROJECT_ID] è il tuo ID progetto Google Cloud.
REGION_ID è un codice abbreviato assegnato da Google in base alla regione selezionata al momento della creazione dell'app. Non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono apparire simili ai codici di 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.

Configura il traffico verso l'app Hello World.

Per impostazione predefinita, la versione iniziale di cui esegui il deployment in una nuova applicazione App Engine riceve automaticamente il 100% del traffico e le versioni successive non ricevono traffico.

Per vedere se la tua versione è configurata per ricevere traffico, invia una richiesta GET HTTP, ad 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
```
Dove:
- [MY_ACCESS_TOKEN] è il token di accesso che hai ottenuto per autorizzare le richieste HTTP.
- [MY_PROJECT_ID] è l'ID del progetto in cui vuoi eseguire il deployment della versione.
Esempio di risposta:
```
{
  "name": "apps/[MY_PROJECT_ID]/services/default/",
  "id": "default",
  "split": {
    "allocations": {
      "appengine-helloworld": 1
    }
  }
}
```
Dove [MY_PROJECT_ID] è il tuo ID progetto Google Cloud.

Per spostare tutto il traffico a una versione, invia una richiesta PATCH HTTP, ad esempio:

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

Comando cURL di esempio:

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

Dove:

[MY_ACCESS_TOKEN] è il token di accesso che hai ottenuto per autorizzare le richieste HTTP.
[MY_PROJECT_ID] è l'ID del progetto in cui vuoi eseguire il deployment della versione.

Esempio di risposta:

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

Dove [MY_PROJECT_ID] è il tuo ID progetto Google Cloud.

Apprendimento esteso

Se disponi di più versioni di un'app, puoi procedere nel seguente modo per suddividere il traffico tra queste versioni:

Per eseguire il deployment di una seconda versione dell'app Hello World nella stessa applicazione App Engine:
1. Nel file di configurazione app.json esistente dell'app Hello World che hai creato in precedenza, aggiorna il campo id per specificare una versione diversa. Ad esempio, aggiungi un -2:
```
"id": "appengine-helloworld-2"
```
2. Esegui di nuovo gli stessi passaggi per eseguire il deployment di una versione appengine-helloworld-2, ad esempio:
  1. Esegui l'autenticazione nel progetto.
  2. Esegui il deployment della nuova versione di appengine-helloworld-2.
  3. Verifica che il deployment della versione appengine-helloworld-2 sia stato eseguito correttamente.
  4. Visualizza l'app in esecuzione nel browser web.

Segui le istruzioni per la suddivisione del traffico riportate in Migrazione e suddivisione del traffico, ad esempio invii una richiesta PATCH HTTP:

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

Comando cURL di esempio:

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

Dove:

[MY_ACCESS_TOKEN] è il token di accesso che hai ottenuto per autorizzare le richieste HTTP.
[MY_PROJECT_ID] è l'ID del progetto in cui vuoi eseguire il deployment della versione.

Passaggi successivi

Creare, configurare e impostare le credenziali per le applicazioni: Accesso all'API