Best practice per l'API Compute Engine

Questo documento descrive le best practice consigliate per l'utilizzo dell'API Compute Engine ed è rivolto agli utenti che la conoscono già. Se sei agli inizi, scopri i prerequisiti e come utilizzare l'API Compute Engine.

Seguire queste best practice può aiutarti a risparmiare tempo, a evitare errori e a mitigare gli effetti delle quote di frequenza.

Utilizzo delle librerie client

Le librerie client sono il modo consigliato per accedere attraverso la programmazione all'API Compute Engine. Le librerie client forniscono codice che ti consente di accedere all'API tramite linguaggi di programmazione comuni, il che può farti risparmiare tempo e migliorare il rendimento del codice.

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

Genera richieste REST utilizzando la console Cloud

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

Scopri come generare richieste REST.

Attendi il completamento delle operazioni

Non dare per scontato che un'operazione, ovvero qualsiasi richiesta API che modifica una risorsa, sia completata o abbia avuto esito positivo. Utilizza invece un metodo wait per la risorsa Operation per verificare che l'operazione sia stata eseguita. (Non è necessario verificare una richiesta che non modifica le risorse, ad esempio una richiesta di lettura che utilizza 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 volta che una richiesta API viene 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 o meno. Ad esempio, puoi ricevere un 200, ma l'operazione potrebbe non essere ancora stata completata o l'operazione 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. Un'operazione è completata quando il campo status della risorsa Operation è DONE. Per controllare lo stato, utilizza il metodo wait corrispondente all'ambito della risorsa Operation restituita:

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

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

Per controllare lo stato di un'operazione richiesta, consulta Controllo dello stato dell'operazione.

Mentre attendi il 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 di elenco (ad esempio un metodo *.list, un metodo *.aggregatedList o qualsiasi altro metodo che restituisce un elenco), impagina risultati, se possibile, per assicurarti di leggere l'intera risposta. Se non esegui l'impaginazione, puoi ricevere solo i primi 500 elementi come stabilito dal parametro di query maxResults.

Per ulteriori informazioni sull'impaginazione su Google Cloud, consulta Impaginazione degli elenchi. Per dettagli ed esempi specifici, consulta la documentazione di riferimento del metodo di elenco che vuoi utilizzare, ad esempio instances.list.

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

Utilizza i filtri degli elenchi lato client per evitare errori di quota

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

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

Fai affidamento sui codici di errore, non sui 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 generalmente destinati agli sviluppatori, non ai programmi.

Scopri di più sugli errori relativi alle API.

Riduci al minimo i nuovi tentativi lato client per rispettare 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 rispettare le quote di frequenza per i tuoi progetti:

  • Evita intervalli di polling brevi.
  • Utilizza il bursting con parsimonia e in modo selettivo.
  • Esegui sempre le chiamate in un ciclo di nuovi tentativi con backoff esponenziale.
  • Utilizza un limitatore di frequenza lato client.
  • Suddividi le applicazioni in più progetti.

Evita intervalli di polling brevi

Evita intervalli di polling brevi, in cui i client effettuano continuamente richieste al server senza attendere una risposta. Se utilizzi un intervallo di polling breve, è più difficile rilevare le richieste non valide che vengono conteggiate ai fini della quota, anche se non restituiscono dati utili.

Invece utilizzare intervalli di polling brevi, devi aspettare il completamento delle operazioni.

Utilizza il bursting con parsimonia e in modo selettivo

Utilizza il bursting con parsimonia e in modo selettivo. Il bursting è l'atto di consentire a un client specifico di effettuare molte richieste API in breve tempo. Di solito, il bursting viene eseguito in risposta a scenari eccezionali, ad esempio quando l'applicazione deve gestire più traffico del solito. Il bursting consuma rapidamente la quota di frequenza, quindi assicurati di utilizzarlo solo quando necessario.

Quando è necessario il bursting, utilizza API batch dedicate, se possibile, come l'API per le istanze in blocco o i gruppi di istanze gestite.

Scopri di più sulle richieste batch.

Esegui sempre le chiamate in un ciclo di nuovi tentativi con backoff esponenziale

Utilizza il backoff esponenziale per distanziare le richieste in modo progressivo quando raggiungono il timeout o quando raggiungi la quota di frequenza.

Qualsiasi ciclo di nuovi tentativi deve avere un backoff esponenziale che garantisca che i nuovi tentativi frequenti non sovraccarichino l'applicazione e non superino le quote di frequenza. In caso contrario, rischi di influire negativamente su tutti gli altri sistemi nello stesso progetto.

Se hai bisogno di un ciclo di nuovi tentativi per un'operazione non riuscita perché hai raggiunto la quota di frequenza, la strategia di backoff esponenziale deve consentire un tempo sufficiente tra i nuovi tentativi per ricaricare il bucket della quota (in genere ogni minuto).

In alternativa, se hai bisogno di un ciclo di nuovi tentativi per quando l'attesa di un'operazione raggiunge il timeout, 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 relativo all'operazione.

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

Utilizza 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 determinata quantità di quota, impedendo a un singolo client di consumare tutta la quota.

Suddividi le applicazioni in più progetti

Suddividere le applicazioni in più progetti può contribuire 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 ciascuna abbia il proprio bucket di quota dedicato.

Elenco di controllo di riepilogo

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

Passaggi successivi