Autorização
Todas as solicitações para as APIs do Google Fotos precisam ser autorizadas por um usuário autenticado.
Os detalhes do processo de autorização para o OAuth 2.0 variam um pouco, dependendo do tipo de aplicativo que você está criando. O processo geral a seguir se aplica a todos os tipos de aplicativo:
- Para se preparar para o processo de autorização, faça o seguinte:
- Registre seu aplicativo usando o Console de APIs do Google.
- Ative as APIs do Google Fotos e extraia detalhes do OAuth, como um ID do cliente e uma chave secreta do cliente. Para mais informações, consulte Começar.
- Para acessar os dados do usuário, o aplicativo faz uma solicitação ao Google para um determinado escopo de acesso.
- O Google exibe uma tela de consentimento para o usuário, pedindo que ele autorize o app a solicitar alguns dos dados dele.
- Se o usuário aprovar, o Google vai fornecer ao aplicativo um token de acesso que expira após um breve período.
- O aplicativo faz uma solicitação para os dados do usuário, anexando o token de acesso à solicitação.
- Se o Google determinar que a solicitação e o token são válidos, ele vai retornar os dados solicitados.
Para determinar quais escopos são adequados para seu aplicativo, consulte Escopos de autorização.
O processo de alguns tipos de aplicativos inclui etapas adicionais, como usar tokens de atualização para adquirir novos tokens de acesso. Para mais informações sobre fluxos de vários tipos de aplicativos, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.
Armazenamento em cache
Mantenha os dados atualizados.
Se você precisar armazenar mídia temporariamente (como miniaturas, fotos ou vídeos) por motivos de desempenho, não armazene em cache por mais de 60 minutos de acordo com nossas diretrizes de uso.
Também não armazene baseUrls, que expiram após aproximadamente 60
minutos.
Os IDs de itens de mídia e de álbuns que identificam de forma exclusiva o conteúdo na biblioteca de um usuário estão isentos da restrição de armazenamento em cache. Você pode armazenar esses IDs indefinidamente (sujeito à política de privacidade do seu app). Use IDs de itens de mídia e IDs de álbuns para recuperar URLs e dados acessíveis novamente usando os endpoints apropriados. Para mais informações, consulte Receber um item de mídia ou Listar álbuns.
Se você tiver muitos itens de mídia para atualizar, talvez seja mais eficiente armazenar os parâmetros de pesquisa que retornaram os itens de mídia e reenviar a consulta para recarregar os dados.
Acesso SSL
O HTTPS é obrigatório para todas as solicitações de serviço Web das APIs do Google Fotos usando o seguinte URL:
https://photoslibrary.googleapis.com/v1/service/output?parameters
As solicitações feitas por HTTP são rejeitadas.
Tratamento de erros
Para informações sobre como processar erros retornados pela API, consulte Como lidar com erros nas APIs do Cloud.
Como repetir solicitações com falha
Os clientes precisam tentar novamente em erros 5xx com espera exponencial, conforme descrito em
Espera exponencial. O atraso mínimo precisa ser 1 s,
a menos que esteja documentado de outra forma.
Para erros 429, o cliente pode tentar novamente com um atraso mínimo de 30s. Para todos os outros
erros, a nova tentativa pode não ser aplicável. Verifique se a solicitação é idempotente e confira
a mensagem de erro para orientação.
Espera exponencial
Em casos raros, algo pode dar errado ao atender sua solicitação.Você pode receber um
código de resposta HTTP 4XX ou 5XX, ou a conexão TCP pode falhar em algum lugar
entre o cliente e o servidor do Google. Muitas vezes, vale a pena tentar novamente a
solicitação. A solicitação de acompanhamento pode ser bem-sucedida quando a original falhar. No entanto,
é importante não ficar em um loop, fazendo solicitações repetidamente para os servidores do Google. Esse
comportamento de loop pode sobrecarregar a rede entre o cliente e o Google e
causar problemas para várias partes.
Uma melhor abordagem é tentar novamente com intervalos maiores entre as tentativas. Geralmente, o atraso é aumentado por um fator multiplicativo com cada tentativa, uma abordagem conhecida como espera exponencial.
Também é preciso tomar cuidado para que não haja um código de tentativa maior na cadeia de chamadas do aplicativo que leve a solicitações repetidas em rápida sucessão.
Uso adequado das APIs do Google
Clientes de API mal projetados podem processar mais carga do que o necessário tanto na Internet quanto nos servidores do Google. Esta seção contém algumas práticas recomendadas para clientes das APIs. Seguir estas práticas recomendadas pode ajudar você a evitar que o aplicativo seja bloqueado por abuso inadvertido das APIs.
Solicitações sincronizadas
Grandes números de solicitações sincronizadas às APIs do Google podem parecer um ataque distribuído de negação de serviço (DDoS) na infraestrutura do Google e ser tratado de acordo. Para evitar isso, verifique se as solicitações da API não estão sincronizadas entre os clientes.
Por exemplo, considere um aplicativo que exibe a hora do fuso horário atual. Este aplicativo provavelmente definirá um alarme no sistema operacional do cliente, despertando-o no início do minuto para que a hora exibida possa ser atualizada. O aplicativo não pode fazer chamadas de API como parte do processamento associado a esse alarme.
Fazer chamadas de API em resposta a um alarme fixo é ruim, porque resulta em chamadas de API sendo sincronizadas com o início do minuto, mesmo entre diferentes dispositivos, em vez de serem distribuídos igualmente com o decorrer do tempo. Um aplicativo mal projetado fazendo isso produz um pico de tráfego sessenta vezes maior do que o nível normal no início de cada minuto.
Em vez disso, um bom possível design é ter um segundo alarme definido a um horário escolhido aleatoriamente. Quando esse segundo alarme dispara, o aplicativo faz chamadas para todas as APIs necessárias e armazena os resultados. Para atualizar a tela no início do minuto, o aplicativo usa resultados armazenados anteriormente em vez de chamar a API novamente. Com esta abordagem, chamas de API são espalhadas igualmente com o decorrer do tempo. Além disso, as chamadas de API não atrasam a renderização quando a tela está sendo atualizada.
Além do início do minuto, outros momentos de sincronização comuns com os quais se deve tomar cuidado para não escolher são os inícios de horas e de cada dia à meia-noite.