Escolher escopos da API Google Drive

Este documento contém informações de autorização e autenticação específicas da API Google Drive. Antes de ler este documento, confira as informações gerais de autenticação e autorização do Google Workspace em Saiba mais sobre autenticação e autorização.

Configurar o OAuth 2.0 para autorização

Para autorizar seu app, a API Google Drive exige que você defina escopos do OAuth em dois lugares: o console do Google Cloud e seu app.

No console do Google Cloud, declare os escopos necessários para seu app na configuração da tela de permissão OAuth. Essas são as permissões de nível mais alto que seu app pode solicitar. Isso serve como uma solicitação formal ao Google, e os escopos declarados são o que o Google mostra aos usuários na tela de consentimento. Ele permite que o usuário entenda exatamente quais dados e ações seu app está pedindo acesso.

Configure a tela de permissão do OAuth e escolha escopos para definir quais informações são mostradas aos usuários e revisores de apps e registre o app para poder publicá-lo mais tarde.

No seu app, ao iniciar a API, você precisa solicitar explicitamente os escopos específicos necessários para essa sessão. Embora o console do Google Cloud defina o nível mais alto de permissões que seu app pode solicitar, o código determina as permissões reais de um determinado usuário. Isso ajuda a garantir que o app peça apenas as permissões necessárias para uma tarefa específica.

É possível declarar um ou mais escopos do OAuth por vez no código do app como uma matriz.

O exemplo de código a seguir mostra como declarar vários escopos do OAuth:

Java

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

Para saber como os escopos são declarados e usados em um exemplo de código completo, consulte Guias de início rápido.

Escopos da API Drive

Para definir o nível de acesso concedido ao seu app, é necessário identificar e declarar escopos de autorização. Um escopo de autorização é uma string URI do OAuth 2.0 que contém o nome do app do Google Workspace, o tipo de dados acessados e o nível de acesso. Os escopos são solicitações do app para trabalhar com dados do Google Workspace, incluindo dados da Conta do Google dos usuários.

Quando o app é instalado, o usuário precisa validar os escopos usados por ele. Em geral, escolha o escopo mais restrito possível e evite solicitar escopos que o app não exige. Os usuários concedem acesso mais facilmente a escopos limitados e claramente descritos.

Sempre que possível, use escopos não sensíveis, já que eles concedem acesso por arquivo e restringem o acesso a recursos específicos necessários para um app.

Escopos não confidenciais

Os seguintes escopos da API Drive são recomendados para a maioria dos casos de uso:

Código do escopo Descrição
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 Ver e gerenciar os dados de configuração do app no Google Drive.
https://www.googleapis.com/auth/drive.install Permitir que os apps apareçam como opção no menu "Abrir com" ou "Novo".
https://www.googleapis.com/auth/drive.file Criar ou modificar arquivos do Drive abertos com um app ou compartilhados com ele pelo usuário ao usar a API Google Picker ou o seletor de arquivos do app.

Escopos confidenciais

Código do escopo Descrição
https://www.googleapis.com/auth/drive.apps.readonly Ver os apps autorizados a acessar seu Drive.

Escopos restritos

Código do escopo Descrição
https://www.googleapis.com/auth/drive Ver e gerenciar todos os seus arquivos do Drive.
https://www.googleapis.com/auth/drive.readonly Ver e baixar todos os seus arquivos do Drive.
https://www.googleapis.com/auth/drive.activity Veja e adicione ao registro de atividades de arquivos no seu Drive.
https://www.googleapis.com/auth/drive.activity.readonly Veja o registro de atividades de arquivos no seu Drive.
https://www.googleapis.com/auth/drive.meet.readonly Confira os arquivos do Drive criados ou editados pelo Google Meet.
https://www.googleapis.com/auth/drive.metadata Ver e gerenciar metadados dos arquivos no seu Drive.
https://www.googleapis.com/auth/drive.metadata.readonly Ver metadados de arquivos no Drive.
https://www.googleapis.com/auth/drive.scripts Mude o comportamento dos scripts do Google Apps Script.

Os escopos nas tabelas anteriores indicam a sensibilidade deles, de acordo com as seguintes definições:

Se o app precisar de acesso a outras APIs do Google, adicione esses escopos também. Para mais informações sobre os escopos das APIs do Google, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Para mais informações sobre escopos específicos do OAuth 2.0, consulte Escopos do OAuth 2.0 para APIs do Google.

Qualificações para escopos restritos

Apenas tipos específicos de aplicativos podem usar escopos restritos para o Google Drive. Para se qualificar, seu app precisa se enquadrar em uma das seguintes categorias:

  1. Backup e sincronização: apps da Web e específicos da plataforma que oferecem sincronização local ou backup automático dos arquivos do Drive dos usuários.

  2. Produtividade e educação: apps com uma interface principal que pode envolver interação com arquivos, metadados ou permissões do Drive. Esses apps incluem gerenciamento de tarefas, anotações, comunicações de grupo de trabalho e colaboração em sala de aula.

  3. Relatórios e segurança: apps que oferecem insights aos usuários ou clientes sobre como os arquivos são compartilhados ou acessados.

Para continuar usando escopos restritos, prepare seu app para a verificação de escopo restrito.

Migrar um app atual de escopos restritos

Se o app do Drive usar escopos restritos, recomendamos migrar para um escopo não sensível da API Drive. Usar escopos não sensíveis, como drive.file, concede acesso por arquivo e restrito a recursos específicos necessários por um app.

Muitos apps podem fazer a transição para o acesso por arquivo sem nenhuma mudança.

Se você estiver usando seu próprio seletor de arquivos, recomendamos mudar para a API Google Picker, que oferece suporte total a diferentes escopos.

Benefícios do escopo de arquivo do Drive

Usar o escopo drive.file do OAuth em combinação com a API Google Picker otimiza a experiência e a segurança do usuário no seu app.

O escopo do OAuth drive.file permite que os usuários escolham quais arquivos querem compartilhar com seu app. Isso dá a eles mais controle e confiança de que o acesso do app aos arquivos é limitado e mais seguro. Por outro lado, exigir acesso amplo a todos os arquivos do Drive pode desencorajar os usuários a interagir com seu app.

Confira alguns motivos para usar o escopo drive.file:

  • Usabilidade: o escopo drive.file funciona com todos os recursos REST da API Drive, o que significa que você pode usá-lo da mesma forma que usa escopos OAuth mais amplos.

  • Recursos: a API Google Picker oferece uma interface semelhante à interface do Drive. Isso inclui várias visualizações mostrando prévias e miniaturas de arquivos do Drive, além de uma janela modal inline para que os usuários nunca saiam do app principal.

  • Praticidade: os apps podem aplicar filtros para determinados tipos de arquivos do Drive (como Documentos, Planilhas e fotos) ao usar um filtro em arquivos do Google Picker.

  • Verificação simples: como drive.file não é sensível, o processo de verificação é mais simples.

Armazenar tokens de atualização com segurança

Para acessar dados particulares usando a API Drive, seu app precisa receber um token de acesso que conceda acesso a essa API. Um único token de acesso pode conceder vários graus de acesso a várias APIs, regidos pelos escopos solicitados.

Como os tokens de acesso são de curta duração, use tokens de atualização para acesso de longo prazo à API Drive. Um token de atualização permite que seu app solicite novos tokens de acesso.

Salve os tokens de atualização em um armazenamento seguro de longo prazo e continue usando-os enquanto forem válidos.

Para mais informações, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.