Autorizzazione
Tutte le richieste all'API della Libreria Google Foto devono essere autorizzate da un utente autenticato.
I dettagli della procedura di autorizzazione per OAuth 2.0 variano leggermente a seconda del tipo di applicazione che stai scrivendo. La seguente procedura generale si applica a tutti i tipi di applicazione:
- Preparati al processo di autorizzazione seguendo questi passaggi:
- Registra la tua applicazione utilizzando la console API di Google.
- Attivare l'API Library e recuperare i dettagli OAuth come un ID client e un client secret. Per ulteriori informazioni, consulta la guida introduttiva.
- Per accedere ai dati utente, l'applicazione invia una richiesta a Google per un determinato ambito di accesso.
- Google mostra all'utente una schermata di consenso in cui viene chiesto di autorizzare l'applicazione a richiedere alcuni dati.
- Se l'utente approva la richiesta, Google fornisce all'applicazione un token di accesso che scade dopo un breve periodo di tempo.
- L'applicazione effettua una richiesta di dati utente, allegando il token di accesso alla richiesta.
- Se Google determina che la richiesta e il token sono validi, restituisce i dati richiesti.
Per determinare quali ambiti sono adatti alla tua applicazione, consulta Ambiti di autorizzazione.
Il processo per alcuni tipi di applicazione include passaggi aggiuntivi, come l'utilizzo di token di aggiornamento per acquisire nuovi token di accesso. Per informazioni dettagliate sui flussi per vari tipi di applicazioni, consulta Utilizzo di OAuth 2.0 per accedere alle API di Google.
Memorizzazione nella cache
Mantieni i dati aggiornati.
Per motivi legati alle prestazioni, se devi archiviare temporaneamente contenuti multimediali (ad esempio miniature, foto o video) non memorizzarli nella cache per più di 60 minuti, in base alle nostre linee guida sull'utilizzo.
Inoltre, non devi archiviare baseUrls, che scadono dopo circa 60 minuti.
Gli ID elemento multimediale e gli ID album che identificano in modo univoco i contenuti nella raccolta di un utente sono esenti dalle restrizioni sulla memorizzazione nella cache. Puoi archiviare questi ID a tempo indeterminato (in base alle norme sulla privacy della tua applicazione). Utilizza gli ID elementi multimediali e gli ID album per recuperare nuovamente gli URL e i dati accessibili utilizzando gli endpoint appropriati. Per ulteriori informazioni, vedi Ottenere una voce multimediale o Elencare album.
Se hai molti elementi multimediali da aggiornare, potrebbe essere più efficiente archiviare i parametri di ricerca che hanno restituito gli elementi multimediali e inviare nuovamente la query per ricaricare i dati.
Accesso SSL
HTTPS è obbligatorio per tutte le richieste al servizio web dell'API Library che utilizzano il seguente URL:
https://photoslibrary.googleapis.com/v1/service/output?parameters
Le richieste effettuate tramite HTTP vengono rifiutate.
Gestione degli errori
Per informazioni su come gestire gli errori restituiti dall'API, consulta la sezione Gestione degli errori delle API Cloud.
Nuovo tentativo per richieste non riuscite
I client devono riprovare in caso di errori 5xx con backoff esponenziale, come descritto in
Backoff esponenziale. Il ritardo minimo deve essere 1 s, se non diversamente documentato.
Per 429 errori, il client può riprovare con un ritardo minimo di 30s. Per tutti gli altri errori, il nuovo tentativo potrebbe non essere applicabile. Assicurati che la richiesta sia idempotente e visualizza
il messaggio di errore per indicazioni.
Backoff esponenziale
In rari casi, potrebbe verificarsi un problema nell'elaborazione della tua richiesta.Potresti ricevere un codice di risposta HTTP 4XX o 5XX oppure la connessione TCP potrebbe non riuscire a metà tra il tuo client e il server di Google. Spesso, vale la pena ritentare la richiesta. La richiesta di follow-up potrebbe avere esito positivo se la richiesta originale non è andata a buon fine. Tuttavia, è importante non eseguire il loop, inviando ripetutamente richieste ai server di Google. Questo comportamento di loop può sovraccaricare la rete tra il client e Google, causando problemi a molte parti.
Un approccio migliore consiste nel riprovare con un ritardo crescente tra un tentativo e l'altro. Di solito, il ritardo viene aumentato di un fattore moltiplicativo per ogni tentativo, un approccio noto come backoff esponenziale.
Devi inoltre assicurarti che non ci sia un nuovo tentativo di codice più in alto nella catena di chiamate dell'applicazione che porta a richieste ripetute in rapida successione.
Uso educato delle API di Google
I client API progettati in modo errato possono caricare più carico del necessario sia su internet sia sui server di Google. Questa sezione contiene alcune best practice per i client delle API. Seguendo queste best practice puoi evitare che la tua applicazione venga bloccata per abuso involontario delle API.
Richieste sincronizzate
Un numero elevato di richieste sincronizzate alle API di Google possono sembrare un attacco Distributed Denial of Service (DDoS) sull'infrastruttura di Google ed essere trattate di conseguenza. Per evitare che ciò accada, devi assicurarti che le richieste API non siano sincronizzate tra i client.
Ad esempio, prendiamo in considerazione un'applicazione che mostra l'ora nel fuso orario corrente. Questa applicazione probabilmente imposterà un allarme nel sistema operativo client attivando la sveglia all'inizio del minuto, in modo che l'ora visualizzata possa essere aggiornata. L'applicazione non deve effettuare chiamate API nell'ambito dell'elaborazione associata all'allarme.
Effettuare chiamate API in risposta a un allarme fisso non è corretta perché permette alle chiamate API di essere sincronizzate all'inizio del minuto, anche tra dispositivi diversi, anziché essere distribuite in modo uniforme nel tempo. Un'applicazione progettata male in questo modo produce un picco di traffico a livelli sessanta volte normali all'inizio di ogni minuto.
Una soluzione alternativa potrebbe essere quella di impostare una seconda sveglia su un orario scelto casualmente. Quando si attiva questo secondo allarme, l'applicazione effettua chiamate alle API di cui ha bisogno e archivia i risultati. Per aggiornare la visualizzazione all'inizio del minuto, l'applicazione utilizza i risultati archiviati in precedenza anziché chiamare di nuovo l'API. Con questo approccio, le chiamate API vengono distribuite in modo uniforme nel tempo. Inoltre, le chiamate API non ritardano il rendering durante l'aggiornamento del display.
A parte l'inizio del minuto, altri orari di sincronizzazione comuni che devi fare attenzione a non scegliere come target sono l'inizio di un'ora e l'inizio di ogni giorno a mezzanotte.