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
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.
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 precisa. Os usuários concedem acesso mais facilmente a escopos limitados e claramente descritos.
Quando possível, recomendamos usar escopos não sensíveis, já que 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 |
Ver 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 opção no menu "Abrir com" ou "Novo". | Recomendado Não sensível |
https://www.googleapis.com/auth/drive.file |
Criar ou modificar arquivos do Drive abertos com um app ou compartilhados com um app pelo usuário ao usar a API Google Picker ou o seletor de arquivos do app. | Recomendado Não sensível |
https://www.googleapis.com/auth/drive.apps.readonly |
Ver os apps autorizados a acessar seu Drive. | Sensível |
https://www.googleapis.com/auth/drive |
Ver e gerenciar todos os seus arquivos do Drive. | Restrito |
https://www.googleapis.com/auth/drive.readonly |
Ver e baixar todos os seus arquivos do Drive. | Restrito |
https://www.googleapis.com/auth/drive.activity |
Veja 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 de 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 |
Ver e gerenciar metadados dos arquivos no seu Drive. | Restrito |
https://www.googleapis.com/auth/drive.metadata.readonly |
Ver metadados de arquivos no Drive. | Restrito |
https://www.googleapis.com/auth/drive.scripts |
Mude o comportamento dos scripts do Google Apps Script. | Restrito |
A coluna "Uso" na tabela acima indica a sensibilidade de cada escopo, de acordo com as seguintes definições:
Recomendado / Não sensível: esses escopos fornecem o menor escopo de acesso de autorização e exigem apenas a verificação básica do app. Para mais 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 seu app. Eles exigem que você passe 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 mais informações sobre esse requisito, consulte a Política de dados do usuário dos serviços da API do Google e os Requisitos adicionais para escopos específicos da API. Se você armazenar (ou transmitir) dados de escopo restrito em servidores, será necessário passar por uma avaliação de segurança.
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.
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 apps OAuth para determinar quando o app precisa passar pela verificação e qual 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 aplicativos podem acessar escopos restritos:
- Apps da Web e específicos da plataforma que oferecem sincronização local ou backup automático dos arquivos do Drive dos usuários.
- Aplicativos de produtividade e educacionais cuja interface do usuário pode envolver interação com arquivos do Drive (ou metadados ou permissões). Os aplicativos de produtividade incluem gerenciamento de tarefas, anotações, comunicações de grupo de trabalho e aplicativos de colaboração em sala de aula.
- Aplicativos de relatórios e segurança que fornecem insights para 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 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 escopo de acesso por arquivo e restringe o acesso a recursos específicos necessários para um app. Muitos apps funcionam com 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 do OAuth drive.file
Usar o escopo do OAuth drive.file e 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 de interagir com seu app. Confira alguns motivos para usar o escopo drive.file:
Usabilidade: o escopo
drive.filefunciona 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.
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 usando-os enquanto eles forem válidos.