Questo documento descrive come creare richieste API e gestire le risposte API dall'API Compute Engine. Spiega come:
- Crea il corpo di una richiesta.
- Determinare gli URI delle risorse necessari per una richiesta.
- Gestire le risposte dell'API.
- Determina se una richiesta API è riuscita.
Questo documento non spiega come eseguire l'autenticazione nell'API. Per scoprire come eseguire l'autenticazione nell'API, leggi Autenticazione in Compute Engine.
Prima di iniziare
- Acquisisci familiarità con le API REST.
- Scoprire come autenticarsi per l'API Compute Engine.
Creazione di una richiesta API
L'API Compute Engine prevede che le richieste API siano in formato JSON.
Per effettuare una richiesta API, puoi effettuare una richiesta HTTP diretta utilizzando
strumenti come curl
o httplib2
oppure puoi utilizzare una delle
librerie client disponibili.
Quando effettui una richiesta API che richiede un corpo della richiesta, ad esempio una richiesta POST
, UPDATE
o PATCH
, il corpo della richiesta contiene le proprietà della risorsa che vuoi impostare in questa richiesta. Ad esempio, il seguente comando curl
effettua una richiesta POST
all'URI della risorsa Istanze. La richiesta crea un'istanza con le proprietà definite nel corpo della richiesta. Il corpo della richiesta è
indicato dal flag -d
:
curl -X POST -H "Authorization: Bearer [OAUTH_TOKEN]" -H "Content-Type: application/json" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances -d '{ "disks":[ { "boot":"true", "initializeParams":{ "sourceImage":"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-10-buster-v20210122" } } ], "machineType":"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2", "name":"VM_NAME", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default" } ] }'
L'URI dell'immagine ha un ID progetto diverso (debian-cloud
) da quello del tuo ID progetto
perché le immagini appartengono a progetti diversi, a seconda del tipo di immagine.
Ad esempio, tutte le immagini Debian disponibili pubblicamente offerte da
Compute Engine sono ospitate nel progetto debian-cloud
.
Quando fai riferimento a un'altra risorsa, utilizza l'URI completo della risorsa.
Ad esempio, la proprietà network
utilizza un URI completo per la rete default
.
Richieste API di esempio
Python
Java
Creazione di URI delle risorse
Nell'API Compute Engine, un riferimento a un'altra risorsa Google Cloud viene fornito come URI completo:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/RESOURCE_TYPE/SPECIFIC_RESOURCE
Ogni volta che specifichi un'immagine, un tipo di macchina, una rete o qualsiasi altra risorsa, devi fornire l'URI alla risorsa quando utilizzi l'API. Strumenti client come Google Cloud CLI e la console Google Cloud nascondono questa complessità e gestiscono la creazione di questi URI delle risorse per te, ma quando interagisci direttamente con l'API, devi creare personalmente questi URI delle risorse.
Esistono URI leggermente diversi per tipi di risorse diversi. Ad
esempio, una risorsa di zona ha la specifica zone
nell'URI:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2
Le risorse di regione sostituiscono la specifica zone
con una specifica
region
:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME
Analogamente, le risorse globali hanno la specifica global
:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/VM_NAME
L'API Compute Engine accetta anche URI parziali perché il servizio può dedurre informazioni come l'ID progetto. Pertanto, sono accettabili anche le seguenti versioni parziali degli URI precedenti:
zones/ZONE/machineTypes/e2-standard-2
regions/REGION/addresses/ADDRESS_NAME
project/PROJECT_ID/global/images/VM_NAME
Negli URI parziali, sia gli URI di zona che quelli a livello di regione hanno omesso l'ID progetto, al contrario dell'URI dell'immagine. Questo perché le immagini disponibili pubblicamente offerte da Compute Engine sono ospitate in altri progetti, ad esempio debian-cloud
per tutte le immagini Debian e ubuntu-os-cloud
per tutte le immagini Ubuntu. Prima di poter utilizzare queste immagini, devi fornire l'ID progetto appropriato. Se ometti l'ID progetto per le immagini, Compute Engine tenta di trovare l'immagine nel tuo progetto e la richiesta non riesce perché l'immagine non esiste.
Tuttavia, se usi un'immagine personalizzata che appartiene al tuo progetto (lo stesso progetto in cui stai creando questa risorsa), puoi omettere la specifica del progetto quando fornisci un URI dell'immagine.
Determinazione delle proprietà obbligatorie
La documentazione di riferimento dell'API Compute Engine, disponibile sia per le API v1 che per le API beta, descrive tutte le possibili proprietà che puoi impostare per una risorsa specifica. La documentazione di riferimento fa una distinzione tra proprietà mutabili e immutabili (contrassegnate da un [Output Only]
nella descrizione della proprietà), ma per determinare le proprietà richieste per una risorsa, devi rivedere la documentazione specifica per l'attività.
Ad esempio, se stai creando un'istanza, leggi la documentazione sulla creazione di un'istanza da un'immagine per conoscere le proprietà API richieste per la richiesta. Se vuoi creare un indirizzo IP esterno statico nell'API, leggi la documentazione sugli indirizzi IP esterni statici.
Convalida delle richieste API
Per convalidare le richieste API:
- In Riferimento API Compute Engine,
trova il metodo chiamato dal tuo codice. Ad esempio,
v1/compute.instances.insert
. Nel menu dei contenuti, fai clic su Prova! Viene visualizzata la finestra Prova questa API.
In Parametri di richiesta, non è necessario fornire un progetto o una zona perché la convalida non richiede l'invio della richiesta.
In Request body (Corpo della richiesta), incolla la richiesta.
Gli elementi della richiesta non corretti vengono sottolineati in blu. Fai clic su ogni sezione sottolineata per ulteriori informazioni sul problema da risolvere.
Gestione delle risposte dell'API
Se effettui una richiesta che muta (altera) i dati, Compute Engine
restituisce un oggetto Operation
che puoi sottoporre a polling per ottenere lo stato
delle operazioni per la tua richiesta. La risorsa Operation
ha il seguente aspetto:
{ "kind": "compute#operation", "id": "7127550864823803662", "name": "operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b", "zone": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE", "operationType": "insert", "targetLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM", "targetId": "4132355614508179214", "status": "PENDING", "user": "user@example.com", "progress": 0, "insertTime": "2016-03-24T14:53:37.788-07:00", "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b" }
Se la richiesta originale deve mutare (alterare) una risorsa di zona, ad esempio per eseguire lo snapshot di un disco o arrestare un'istanza, Compute Engine restituisce un oggetto zoneOperations
. Allo stesso modo, le risorse a livello di regione e globali restituiscono rispettivamente un oggetto regionOperations
o globalOperations
. Puoi ottenere lo stato di un'operazione eseguendo una richiesta che utilizza il metodo get
o wait
per la risorsa Operation
specifica e fornendo il name
dell'operazione.
La tua richiesta non è completa finché lo stato della risorsa Operation
non torna come
DONE
. Questa operazione può richiedere del tempo, a seconda della natura della richiesta. Quindi,
una volta che lo stato della risorsa Operation
è tornato come DONE
, puoi controllare
se l'operazione è riuscita e se si sono verificati errori.
Ad esempio, la seguente risposta indica che l'operazione precedente
è ora completata, specificata dallo stato DONE
:
endTime: '2016-03-24T14:54:07.119-07:00' id: '7127550864823803662' insertTime: '2016-03-24T14:53:37.788-07:00' kind: compute#operation name: operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b operationType: insert progress: 100 selfLink: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b startTime: '2016-03-24T14:53:38.397-07:00' status: DONE targetId: '4132355614508179214' targetLink: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM user: user@example.com zone: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE
Per conferma, effettua una richiesta get
alla risorsa per verificare che esista e sia in esecuzione. Ad esempio:
GET /compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM { "cpuPlatform": "Intel Haswell", "creationTimestamp": "2016-03-24T14:53:37.170-07:00", "disks": [ ..[snip].. "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM", "status": "RUNNING", "tags": { "fingerprint": "42WmSpB8rSM=" }, "zone": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE" }
Operazioni di polling
Puoi scrivere del codice per eseguire periodicamente il polling dell'operazione con una richiesta get
o wait
che viene restituita quando lo stato dell'operazione è DONE
.
Con una richiesta get
, l'operazione viene restituita immediatamente, indipendentemente dal suo stato. Per sapere quando l'operazione è terminata,
devi eseguire un polling periodico.
Se effettui una richiesta wait
, la richiesta verrà restituita quando l'operazione è DONE
o se la richiesta si avvicina alla scadenza di 2 minuti. Puoi scegliere di utilizzare wait
o get
per eseguire un polling delle tue operazioni, ma il metodo wait
offre alcuni vantaggi rispetto al metodo get
:
- Puoi configurare i tuoi client in modo che eseguano il polling per lo stato dell'operazione meno frequentemente, riducendo l'utilizzo di QPS dell'API Compute Engine.
- La latenza media tra il momento in cui viene completata l'operazione e il momento in cui il client viene informato che l'operazione viene eseguita è notevolmente ridotta poiché il server risponde non appena viene completata l'operazione.
- Il metodo fornisce tempi di attesa limitati. Il metodo non supera il timeout HTTP predefinito (2 minuti), quindi restituisce lo stato attuale dell'operazione, che potrebbe essere
DONE
o ancora in corso.
Il metodo wait
è un'API best effort. Se il server è sovraccarico, la richiesta potrebbe essere restituita prima di raggiungere la scadenza predefinita o dopo aver atteso solo zero secondi. Inoltre, non è garantito che il metodo venga restituito solo quando
l'operazione è DONE
. Ad esempio, se la richiesta si avvicina alla scadenza di 2 minuti, il metodo restituisce anche se l'operazione non viene completata. Per verificare
le tue operazioni, ti consigliamo di utilizzare il metodo wait
o
get
, in un ciclo di nuovi tentativi con una sospensione intermedia, per eseguire periodicamente
il polling dello stato dell'operazione. L'intervallo massimo di nuovi tentativi non deve superare il periodo minimo di conservazione delle operazioni.
Esempio di sondaggio
Nei seguenti esempi viene utilizzato il metodo get
. Puoi sostituire il metodo get
con il metodo wait
: