Escopos da autorização

As APIs do Google Fotos contêm vários escopos usados para acessar itens de mídia e álbuns. As respostas retornadas de várias chamadas são diferentes com base nos escopos que foram solicitados pelo desenvolvedor.

Toda solicitação que seu aplicativo envia para as APIs do Google Fotos precisa incluir um token de autorização. O token também identifica o aplicativo para o Google.

Sobre os protocolos de autorização

O aplicativo deve obrigatoriamente usar o OAuth 2.0 para autorizar solicitações. Não há outros protocolos de autorização compatíveis. Se o aplicativo usa o Fazer login com o Google, alguns aspectos da autorização são administrados para você.

Autorizar solicitações com OAuth 2.0

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 ou “fluxo” 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:

Ao criar seu aplicativo, registre-o usando o Console de APIs do Google. Em seguida, o Google fornece informações que serão usadas mais tarde, como um ID e uma chave secreta do cliente.
Ative as APIs Google Photos no Console de APIs do Google. Se ela não estiver no Console de APIs, pule essa etapa.
Quando seu aplicativo precisar de acesso aos dados do usuário, ele solicitará ao Google um determinado escopo do acesso.
O Google exibe uma tela de consentimento ao usuário, pedindo para que o aplicativo seja autorizado a solicitar alguns dos dados dele.
Se o usuário aprovar, o Google fornecerá ao aplicativo um token de acesso de curta duração.
O aplicativo solicita dados de 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.

Alguns fluxos incluem etapas adicionais, como atualizar tokens para adquirir novos tokens de acesso. Para mais informações sobre fluxos de vários tipos de aplicativos, acesse a documentação OAuth 2.0 do Google.

Confira as informações de escopo do OAuth 2.0 para as APIs Google Photos:

Escopos da API Picker

Escopo	Significado
`https://www.googleapis.com/auth/photospicker.mediaitems.readonly`	Acesso para criar, receber e excluir sessões e listar itens de mídia para sessões.

Escopos da API da biblioteca

Escopo	Significado
`https://www.googleapis.com/auth/photoslibrary.readonly` `https://www.googleapis.com/auth/photoslibrary.sharing` `https://www.googleapis.com/auth/photoslibrary`	Aviso:esses escopos estão sendo removidos como parte das atualizações das APIs do Google Fotos. Depois de 31 de março de 2025, só será possível acessar o conteúdo criado pelo seu app. Analise os outros escopos disponíveis e ajuste as solicitações de autorização do seu aplicativo. Se o app precisar selecionar fotos da biblioteca de um usuário, use a nova API Picker. Para novos desenvolvimentos, use a documentação atualizada da API Library. Se você estiver migrando um aplicativo existente, consulte a documentação da API de biblioteca legada para receber mais suporte.
`https://www.googleapis.com/auth/photoslibrary.appendonly`	Somente acesso de gravação. Acesso para fazer upload de bytes, criar itens de mídia, criar álbuns e adicionar enriquecimentos. Permite apenas que novas mídias sejam criadas na biblioteca do usuário e em álbuns criados pelo app.
`https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata`	Acesso de leitura a itens de mídia e álbuns criados pelo desenvolvedor. Para mais informações, consulte Acessar itens de mídia e Listar conteúdos da biblioteca, álbuns e itens de mídia. Destinado a ser solicitado com o escopo `photoslibrary.appendonly`.
`https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata`	Apenas acesso para editar. Acesso para mudar estes detalhes em álbuns e itens de mídia criados pelo desenvolvedor: Organizar as fotos e os vídeos nos álbuns (Adicionar aos álbuns, remover dos álbuns e atualizar posição). Títulos dos álbuns e fotos da capa Descrições de itens de mídia

Para solicitar acesso usando o OAuth 2.0, seu aplicativo precisa de informações do escopo, bem como informações fornecidas pelo Google durante o registro do aplicativo, como o ID e a chave secreta do cliente.

Dica: as bibliotecas cliente de APIs do Google cuidam de parte do processo de autorização para você. Elas estão disponíveis para uma série de linguagens de programação. Acesse a página de bibliotecas e exemplos para mais detalhes.

Como selecionar escopos

Como regra geral, escolha o escopo mais restritivo possível e evite solicitar escopos de que o app não precisa. Os usuários concedem acesso a escopos limitados e claramente descritos com mais facilidade. Os usuários podem hesitar em conceder acesso amplo às mídias, a menos que confiem no app e entendam por que ele precisa das informações.

Solicitar escopos de forma incremental

Seguindo as práticas recomendadas de autorização, seu app só deve solicitar os escopos conforme necessário. Evite solicitar todos os escopos para seu app imediatamente no login. Em vez disso, forneça uma justificativa e faça a solicitação no contexto. Explique claramente o que você vai fazer com os dados dos usuários e como eles vão se beneficiar ao conceder acesso, de acordo com as diretrizes e práticas recomendadas de UX para enviar avisos e pedir consentimento.

Contas de serviço

As APIs do Google Fotos não oferecem suporte a contas de serviço. Seu aplicativo precisa usar os outros fluxos OAuth 2.0 disponíveis, como o OAuth 2.0 para aplicativos de servidor da Web ou o OAuth 2.0 para apps para dispositivos móveis e computadores.