Autorização
Todas as solicitações para a API Google Photos Library precisam ser autorizadas por um usuário autenticado.
Os detalhes do processo de autorização do OAuth 2.0 variam um pouco dependendo do tipo de aplicativo sendo criado. O processo geral a seguir se aplica a todos os tipos de aplicativos:
- Para se preparar para o processo de autorização, faça o seguinte:
- Registre seu aplicativo usando o Console de APIs do Google.
- Ative a API Library e recupere detalhes do OAuth, como um ID e uma chave secreta do cliente. Para mais informações, consulte Como começar.
- Para acessar os dados do usuário, o aplicativo solicita ao Google um escopo de acesso específico.
- O Google exibe uma tela de consentimento para o usuário pedindo autorização para que o aplicativo solicite alguns dados.
- Se o usuário aprovar, o Google fornecerá ao aplicativo um token de acesso que expira após um breve período.
- O aplicativo faz uma solicitação de 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 retornará os dados solicitados.
Para determinar quais escopos são adequados para seu aplicativo, consulte Escopos de autorização.
O processo para alguns tipos de aplicativos inclui outras etapas, como o uso de tokens de atualização para adquirir novos tokens de acesso. Para informações detalhadas 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 a armazene em cache por mais de 60 minutos, de acordo com nossas diretrizes de uso.
Também não é recomendável armazenar baseUrls, que expiram após aproximadamente 60
minutos.
Os IDs de itens de mídia e de álbuns que identificam exclusivamente 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 aplicativo). Use os IDs de itens de mídia e de álbuns para recuperar URLs e dados acessíveis novamente usando os endpoints adequados. Para mais informações, consulte Acessar um item de mídia ou Como listar álbuns.
Se você tiver muitos itens de mídia para atualizar, pode ser 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 da Web da API Library 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 lidar com erros retornados da API, consulte Como lidar com erros das APIs do Cloud.
Como repetir solicitações com falha
Os clientes precisam tentar novamente em caso de erros 5xx com espera exponencial, conforme descrito em
Espera exponencial. O atraso mínimo precisa ser de 1 s,
a menos que seja 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 veja a mensagem de erro para orientação.
Espera exponencial
Em casos raros, algo pode dar errado ao atender sua solicitação.Talvez você receba um código de resposta HTTP 4XX ou 5XX, ou a conexão TCP pode falhar em algum lugar entre seu cliente e o servidor do Google. Muitas vezes, vale a pena repetir a solicitação. A solicitação de acompanhamento pode ser bem-sucedida quando a original falha. No entanto, é importante não repetir, fazendo solicitações repetidamente aos servidores do Google. Esse
comportamento de loop pode sobrecarregar a rede entre seu cliente e o Google e
causar problemas para muitas partes.
Uma melhor abordagem é tentar novamente com intervalos maiores entre as tentativas. Normalmente, o atraso é aumentado por um fator multiplicativo a cada tentativa, uma abordagem conhecida como espera exponencial.
Também tome cuidado para que não haja um código de repetição mais alto na cadeia de chamadas do aplicativo que leve a solicitações repetidas em rápida sucessão.
Uso educado das APIs do Google
Clientes de API mal projetados podem gerar mais carga do que o necessário na Internet e nos servidores do Google. Esta seção contém algumas práticas recomendadas para clientes das APIs. Seguir essas práticas recomendadas pode ajudar a evitar que o aplicativo seja bloqueado por abuso acidental das APIs.
Solicitações sincronizadas
Um grande número de solicitações sincronizadas para as APIs do Google pode parecer um ataque distribuído de negação de serviço (DDoS, na sigla em inglês) na infraestrutura do Google e ser tratado de acordo. Para evitar isso, verifique se as solicitações de API não estão sincronizadas entre os clientes.
Por exemplo, considere um aplicativo que exibe a hora no fuso horário atual. Este aplicativo provavelmente definirá um alarme no sistema operacional do cliente, despertando-o no início do minuto para que o horário exibido possa ser atualizado. 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 na sincronização das chamadas de API com o início do minuto, mesmo entre dispositivos diferentes, em vez de serem distribuídas uniformemente ao longo do tempo. Um aplicativo mal projetado que faz isso produz um pico de tráfego 60 vezes mais níveis do normal no início de cada minuto.
Em vez disso, um bom design possível é definir um segundo alarme para um horário escolhido aleatoriamente. Quando esse segundo alarme é acionado, o aplicativo faz chamadas para qualquer API necessária e armazena os resultados. Para atualizar a tela no início do minuto, o app usa os resultados armazenados anteriormente em vez de chamar a API de novo. 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 horários de sincronização comuns que você precisa ter cuidado para não segmentar são no início de uma hora e no início de cada dia à meia-noite.