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 un principiante, scopri i prerequisiti e l'utilizzo dell'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 in modo programmatico 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.

Generare 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 riuscita. 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, viene restituito un codice di stato HTTP200. Sebbene la ricezione di un codice 200 indichi che il server ha ricevuto correttamente la richiesta dell'API, questo codice di stato non indica se l'operazione richiesta è stata completata 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 lungo termine restituisce una Operation risorsa, che acquisisce lo stato della richiesta. Un'operazione viene eseguita 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 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 ripetizione con backoff esponenziale per controllare lo stato della richiesta, anziché utilizzare il metodo get con polling breve 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.

Eseguire la paginazione dei 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), suddividi i risultati in pagine, se possibile, per assicurarti di leggere l'intera risposta. Se non esegui la paginazione, puoi ricevere solo i primi 500 elementi come stabilito dal parametro di query maxResults.

Per ulteriori informazioni sulla paginazione su Google Cloud, consulta Paginazione degli elenchi. Per dettagli ed esempi specifici, consulta la documentazione di riferimento per il metodo di elenco che vuoi utilizzare, ad esempio instances.list.

Puoi anche utilizzare le librerie client di Cloud per gestire la paginazione.

Utilizzare 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 le quote se le richieste contengono più di 10.000 risorse filtrate. Per ulteriori informazioni, consulta filtered_list_cost_overhead in Quote tariffarie.

Se il tuo progetto supera questa quota di tariffa, 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 in genere destinati agli sviluppatori, non ai programmi.

Scopri di più sugli errori relativi all'API.

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

Riduci al minimo il numero di 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 tariffa per i tuoi progetti:

  • Evita di eseguire polling brevi.
  • Utilizza la pubblicazione frazionata con parsimonia e in modo selettivo.
  • Effettua 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.

Evitare il polling breve

Evita il polling breve, in cui i client inviano continuamente richieste al server senza attendere una risposta. Se esegui un sondaggio breve, è più difficile rilevare le richieste non valide che vengono conteggiate ai fini della quota, anche se non restituiscono dati utili.

Anziché utilizzare il polling breve, devi aspettare il completamento delle operazioni.

Utilizza la funzionalità di scatto continuo con parsimonia e in modo selettivo

Utilizza la pubblicazione frazionata con parsimonia e in modo selettivo. L'esplosione è 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 superamento del limite consuma rapidamente la quota tariffaria, quindi assicurati di utilizzarlo solo quando necessario.

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

Scopri di più sulle richieste raggruppate.

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

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

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

Se hai bisogno di un ciclo di ripetizione per un'operazione non riuscita perché hai raggiunto la quota di frequenza, la strategia di backoff esponenziale deve consentire un tempo sufficiente tra le ripetizioni per il reintegro del bucket della quota (di solito ogni minuto).

In alternativa, se hai bisogno di un ciclo di ripetizione 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 di 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.

Suddividere le applicazioni in più progetti

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

Riepilogo elenco di controllo

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

Passaggi successivi