Best practice per l'API Compute Engine

Questo documento descrive le best practice consigliate per l'utilizzo dell'API Compute Engine ed è destinato agli utenti che l'hanno già dimestichezza. Se sei alle prime armi, scopri di più sui prerequisiti e sull'utilizzo dell'API Compute Engine.

Attenendoti a queste best practice, puoi risparmiare tempo, evitare errori e mitigare gli effetti delle quote di frequenza.

Utilizzo delle librerie client

Le librerie client sono il metodo consigliato per accedere in modo programmatico all'API Compute Engine. Le librerie client forniscono codice che consente di accedere all'API mediante linguaggi di programmazione comuni, che possono farti risparmiare tempo e migliorare le prestazioni del codice.

Scopri di più sulle librerie client di Compute Engine e sulle best practice per le librerie client.

Genera richieste REST mediante la console Cloud

Quando crei una risorsa, genera la richiesta REST utilizzando le pagine di creazione delle risorse o le pagine dei dettagli nella console Google Cloud. L'utilizzo di una richiesta REST generata fa risparmiare tempo e aiuta a prevenire errori di sintassi.

Scopri come generare richieste REST.

Attendi il completamento delle operazioni

Non dare per scontato che un'operazione (qualsiasi richiesta API che modifichi una risorsa) sia completata o riuscita. Utilizza invece un metodo wait per la risorsa Operation al fine di verificare che l'operazione sia completata. Non è necessario verificare una richiesta che non modifica le risorse, ad esempio una richiesta di lettura utilizzando un verbo HTTP GET, perché la risposta dell'API indica già se la richiesta è andata a buon fine. Di conseguenza, l'API Compute Engine non restituisce risorse Operation per queste richieste.

Ogni richiesta API avviata correttamente restituisce un codice di stato HTTP 200. Sebbene la ricezione di un 200 indichi che il server ha ricevuto correttamente la richiesta API, questo codice di stato non indica se l'operazione richiesta è stata completata correttamente. Ad esempio, puoi ricevere un messaggio 200, ma l'operazione potrebbe non essere ancora stata completata o potrebbe non essere riuscita.

Qualsiasi richiesta di creazione, aggiornamento o eliminazione per un'operazione a lunga esecuzione restituisce una risorsa Operation, che acquisisce lo stato della richiesta. Viene eseguita un'operazione quando il campo status della risorsa Operation è DONE. Per controllare lo stato, utilizza il metodo wait che corrisponde all'ambito della risorsa Operation restituita:

Il metodo wait viene restituito al termine dell'operazione o quando la richiesta si sta avvicinando alla scadenza dei due minuti. Quando utilizzi il metodo wait, evita il polling breve, ovvero quando i client inviano continuamente richieste al server senza attendere una risposta. L'utilizzo del metodo wait in un loop di nuovo con backoff esponenziale per verificare lo stato della richiesta, anziché il metodo get con il polling breve per la risorsa Operation, consente di preservare le quote di frequenza e ridurre la latenza.

Per ulteriori informazioni ed esempi di utilizzo del metodo wait, consulta Gestione delle risposte dell'API.

Per controllare lo stato di un'operazione richiesta, consulta la sezione Verificare lo stato dell'operazione.

In attesa del completamento di un'operazione, tieni conto del periodo di conservazione minimo dell'operazione, poiché le operazioni completate potrebbero essere rimosse dal database dopo questo periodo.

Impagina i risultati dell'elenco

Quando utilizzi un metodo elenco (ad esempio un metodo *.list, un metodo *.aggregatedList o qualsiasi altro metodo che restituisce un elenco), quando possibile impagina i risultati per assicurarti di leggere l'intera risposta. Se non esegui l'impaginazione, puoi ricevere solo fino ai primi 500 elementi come stabilito dal parametro di query maxResults.

Per ulteriori informazioni sull'impaginazione in Google Cloud, consulta la pagina relativa all'impaginazione degli elenchi. Per dettagli ed esempi specifici, consulta la documentazione di riferimento per il metodo dell'elenco che vuoi utilizzare, ad esempio instances.list.

Puoi anche utilizzare le librerie client di Cloud per gestire l'impaginazione.

Utilizza i filtri dell'elenco lato client per evitare errori di quota

Quando utilizzi i filtri con i metodi *.list o *.aggregatedList, ti vengono addebitati costi aggiuntivi per la quota se le richieste contengono più di 10.000 risorse filtrate. Per maggiori informazioni, vedi filtered_list_cost_overhead in Quote di frequenza.

Se il progetto supera questa quota, viene visualizzato un errore 403 con motivo rateLimitExceeded. Per evitare questo errore, utilizza i filtri lato client per le richieste di elenco.

Affidati ai codici di errore, non ai messaggi di errore

Le API di Google devono utilizzare i codici di errore canonici definiti da google.rpc.Code, ma i messaggi di errore possono essere soggetti a modifiche senza preavviso. I messaggi di errore sono pensati per la lettura degli sviluppatori, non dei programmi.

Scopri di più sugli errori delle API.

Riduci al minimo i tentativi lato client per preservare le quote di frequenza

Riduci al minimo il numero di nuovi tentativi lato client per un progetto per evitare errori rateLimitExceeded e massimizzare l'utilizzo delle quote di frequenza. Le seguenti pratiche possono aiutarti a preservare le quote di frequenza per i tuoi progetti:

  • Evita sondaggi brevi.
  • Usa le serie di foto a raffica con parsimonia e in modo selettivo.
  • Effettua sempre le chiamate in un loop di nuovi tentativi con backoff esponenziale.
  • Utilizza un limitatore di frequenza lato client.
  • Suddividi le applicazioni in più progetti.

Evita sondaggi brevi

Evita di eseguire brevi polling, in cui i client inviano continuamente richieste al server senza attendere una risposta. Se si esegue un sondaggio breve, sarà più difficile individuare le richieste errate che incidono sulla quota di spazio di archiviazione, anche se non restituiscono dati utili.

Anziché eseguire un polling breve, devi attendere il completamento delle operazioni.

Usa la serie di foto a raffica con parsimonia e selettivamente

Usa le serie di foto a raffica con parsimonia e in modo selettivo. Il bursting è l'atto di consentire a un client specifico di effettuare molte richieste API in breve tempo. In genere, il bursting viene eseguito in risposta a scenari eccezionali, ad esempio nei casi in cui l'applicazione deve gestire più traffico del solito. Il bursting consuma rapidamente la tua quota di frequenza, quindi assicurati di utilizzarla solo quando necessario.

Quando è necessario il bursting, utilizza, se possibile, API batch dedicate, ad esempio l'API delle istanze collettive o i gruppi di istanze gestite.

Scopri di più sull'esecuzione di richieste in batch.

Effettua sempre le chiamate in un loop di nuovi tentativi con backoff esponenziale

Utilizza il backoff esponenziale per distanziare progressivamente le richieste quando scadono o quando raggiungi la quota di frequenza.

Qualsiasi loop di nuovi tentativi dovrebbe avere un backoff esponenziale che garantisce che i nuovi tentativi frequenti non sovraccarichino l'applicazione o non superino le quote di frequenza. In caso contrario, rischi di avere un impatto negativo su tutti gli altri sistemi nello stesso progetto.

Se hai bisogno di un loop di nuovi tentativi per un'operazione non riuscita perché hai raggiunto la quota di frequenza, la strategia di backoff esponenziale dovrebbe concedere tempo sufficiente tra un nuovo tentativo e l'altro affinché il bucket di quota venga ricaricato (di solito ogni minuto).

In alternativa, se hai bisogno di un loop di nuovi tentativi per il raggiungimento del timeout di attesa per un'operazione, l'intervallo massimo della strategia di backoff esponenziale non deve superare il periodo di conservazione minimo dell'operazione. In caso contrario, potresti ricevere un errore Not Found dell'operazione.

Per un esempio di implementazione del backoff esponenziale, consulta l'algoritmo di backoff esponenziale per l'API Identity and Access Management.

Utilizzare un limitatore di frequenza lato client

Utilizza un limitatore di frequenza lato client. Un limitatore di frequenza lato client imposta un limite artificiale in modo che il client in questione possa utilizzare solo una certa quantità di quota, impedendo a un solo client di consumare tutta la quota.

Suddividi le applicazioni in più progetti

Suddividere le applicazioni in più progetti può aiutare a ridurre al minimo il numero di richieste per i bucket di quota. Poiché le quote vengono applicate a livello di progetto, puoi suddividere le applicazioni in modo che ogni applicazione abbia il proprio bucket di quota dedicato.

Riepilogo elenco di controllo

Il seguente elenco di controllo riassume le best practice per l'utilizzo dell'API Compute Engine.

Passaggi successivi