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, leia 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

Configurar a tela de consentimento do OAuth e escolher escopos para definir quais informações são exibidas para usuários e revisores de apps e registrar seu app para poder publicá-lo mais tarde.

Escopos da API Drive

Para definir o nível de acesso concedido ao app, é necessário identificar e declarar os escopos de autorização. Um escopo de autorização é uma string de URI OAuth 2.0 que contém o nome do app do Google Workspace, o tipo de dados que ele acessa e o nível de acesso. Os escopos são as 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. Geralmente, escolha o escopo mais focado possível e evite solicitar escopos que o app não exige. Os usuários concedem mais acesso a escopos limitados e claramente descritos.

Quando possível, recomendamos o uso de escopos não confidenciais, porque eles concedem escopo de acesso por arquivo e restringem o acesso a recursos específicos necessários para um app.

A API Drive é compatível com os seguintes escopos:

Código do escopo Descrição Uso
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 Acessar e gerenciar os dados de configuração do app no Google Drive. Recomendado
Não sensível
https://www.googleapis.com/auth/drive.install Permitir que os apps apareçam como uma opção no menu "Abrir com" ou "Novo". Recomendado
Não confidencial
https://www.googleapis.com/auth/drive.file Crie novos arquivos do Drive ou modifique arquivos existentes que você abre com um app ou que o usuário compartilha com um app enquanto usa a API Google Picker ou o seletor de arquivos do app. Recomendado
Não sensível
https://www.googleapis.com/auth/drive.apps.readonly Visualize os aplicativos autorizados a acessar seu Google Drive. Sensível
https://www.googleapis.com/auth/drive Acessar e gerenciar todos os arquivos do Drive. Restrito
https://www.googleapis.com/auth/drive.readonly Acessar e fazer o download de todos os seus arquivos do Drive. Restrito
https://www.googleapis.com/auth/drive.activity Acesse e adicione ao registro de atividades de arquivos no seu Drive. Restrito
https://www.googleapis.com/auth/drive.activity.readonly Veja o registro de atividades dos arquivos no seu Drive. Restrito
https://www.googleapis.com/auth/drive.meet.readonly Acessar os arquivos do Drive criados ou editados pelo Google Meet. Restrito
https://www.googleapis.com/auth/drive.metadata Acessar e gerenciar metadados de arquivos no seu Drive. Restrito
https://www.googleapis.com/auth/drive.metadata.readonly Acessar os metadados dos arquivos no seu Drive. Restrito
https://www.googleapis.com/auth/drive.scripts Modifique o comportamento dos scripts do Google Apps Script. Restrito

A coluna "Usage" na tabela acima indica a sensibilidade de cada escopo, de acordo com as seguintes definições:

  • Recomendado / não confidencial: esses escopos fornecem o menor escopo de acesso de autorização e exigem apenas uma verificação básica do app. Para informações sobre esse requisito, consulte Requisitos de verificação.

  • Recomendado / sensível: esses escopos fornecem acesso a dados específicos do usuário do Google autorizados pelo usuário para o app. É necessário passar por uma verificação adicional do app. Para informações sobre esse requisito, consulte Requisitos de escopo sensível e restrito.

  • Restrito: esses escopos oferecem amplo acesso aos dados de usuário do Google e exigem que você passe por um processo de verificação de escopo restrito. Para informações sobre esse requisito, consulte a Política de dados do usuário dos serviços de API do Google e os Requisitos adicionais para escopos específicos da API. Se você armazenar dados de escopo restrito em servidores (ou transmitir), será necessário fazer uma avaliação de segurança.

Caso seu app exija acesso a outras APIs do Google, também é possível adicionar esses escopos. 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.

Verificação do OAuth

O uso de determinados escopos do OAuth pode exigir que seu app passe pela Central de Ajuda de Verificação de Apps OAuth. Leia as Perguntas frequentes sobre o app OAuth para determinar quando seu app precisa passar pela verificação e que tipo de verificação é necessário. Consulte também os Termos de Serviço do Google Drive.

Quando usar um escopo restrito

No Drive, apenas os seguintes tipos de app podem acessar os escopos restritos:

  1. Apps da Web e específicos para plataformas que oferecem sincronização local ou backup automático dos arquivos do Drive dos usuários.
  2. Aplicativos educacionais e de produtividade cuja interface do usuário possa envolver interação com arquivos do Drive (ou os metadados ou permissões deles). Os aplicativos de produtividade incluem gerenciamento de tarefas, anotações, comunicações de grupos de trabalho e aplicativos de colaboração em sala de aula.
  3. Relatórios e aplicativos de segurança que fornecem insights sobre 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 do escopo restrito.

Migrar um app atual de escopos restritos

Se você desenvolveu um app do Drive usando um dos escopos restritos, recomendamos migrar o app para usar um escopo não sensível, já que ele concede o escopo de acesso por arquivo e restringe o acesso a recursos específicos necessários por um app. Muitos apps funcionam com 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 OAuth drive.file

O uso do escopo do OAuth drive.file e da API Google Picker otimiza a experiência do usuário e a segurança do app.

O escopo drive.file do OAuth permite que os usuários escolham quais arquivos querem compartilhar com seu app. Isso oferece 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 visualizações e miniaturas de arquivos do Drive e uma janela modal inline para que os usuários nunca saiam do app principal.

  • Comodidade: os apps podem aplicar filtros a determinados tipos de arquivos do Drive (como Documentos Google, Planilhas e Fotos) ao usar um filtro nos arquivos do Google Picker.

Além disso, como drive.file não é sensível, ele permite um processo de verificação mais simplificado.

Salvar tokens de atualização

Salve os tokens de atualização em um armazenamento seguro de longo prazo e continue a usá-los enquanto eles permanecerem válidos.