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 |
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:
- Apps da Web e específicos para plataformas que oferecem sincronização local ou backup automático dos arquivos do Drive dos usuários.
- 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.
- 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.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 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.