Esta página foi traduzida pela API Cloud Translation.

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 OAuth 2.0 para autorização

Configure a tela de permissão OAuth e escolha os escopos para definir quais informações serão exibidas aos usuários e revisores, além de registrar o app para que você possa publicá-lo mais tarde.

Escopos da API do Drive

Para definir o nível de acesso concedido ao 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 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 os 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 restrito possível e evite solicitar escopos que não são necessários para o app. 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`	Visualize e gerencie os dados de configuração do próprio aplicativo em seu Google Drive.	Recomendado Não confidencial
`https://www.googleapis.com/auth/drive.install`	Permita que 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ê abra com um app ou que o usuário compartilhe com um app usando a API Google Picker ou o seletor de arquivos do app.	Recomendado Não confidencial
`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`	Visualize e gerencie todos os seus arquivos do Google Drive.	Restrito
`https://www.googleapis.com/auth/drive.readonly`	ver e fazer o download de todos os seus arquivos do Drive;	Restrito
`https://www.googleapis.com/auth/drive.activity`	Veja e adicione itens ao registro de atividades dos 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`	Veja e gerencie metadados de arquivos em seu Google Drive.	Restrito
`https://www.googleapis.com/auth/drive.metadata.readonly`	Veja metadados de arquivos no seu Drive.	Restrito
`https://www.googleapis.com/auth/drive.scripts`	Modifique 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 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 / confidencial: esses escopos dão acesso a dados do usuário específicos do Google que são autorizados pelo usuário para seu app. Eles exigem que você passe por outras verificações do app. Para informações sobre esse requisito, consulte Requisitos de escopo sensível e restrito.
Restrito: esses escopos dão amplo acesso aos dados do 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 ou transmitir dados de escopo restrito em servidores, precisará passar por uma avaliação de segurança.

Caso seu app precise de acesso a outras APIs do Google, também é possível adicionar esses escopos. Para mais informações sobre os escopos da API 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 o app prossiga para a Central de Ajuda sobre a 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 aplicativo podem acessar escopos restritos:

Apps específicos da plataforma e da Web que fornecem sincronização local ou backup automático dos arquivos do Drive dos usuários.
Aplicativos educacionais e de produtividade com uma interface do usuário que pode envolver a interação com arquivos do Google Drive (ou com os metadados ou permissões deles). Os aplicativos de produtividade incluem gerenciamento de tarefas, anotações, comunicações em grupo e aplicativos de colaboração em sala de aula.
Aplicativos de relatórios e segurança que fornecem insights do usuário ou do cliente 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 qualquer um dos escopos restritos, recomendamos migrar o app para usar um escopo não confidencial, já que ele concede um 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 é totalmente compatível com diferentes escopos.

Benefícios do escopo `drive.file` do OAuth

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

O escopo drive.file do OAuth permite que os usuários escolham quais arquivos querem compartilhar com o 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 amplo acesso a todos os arquivos do Drive pode desencorajar os usuários de interagir com o 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 é possível usá-lo da mesma maneira que escopos mais amplos do OAuth.
Recursos: a API Google Picker oferece uma interface parecida com a interface do Drive. Ele inclui várias visualizações que mostram visualizações e miniaturas de arquivos do Drive, além de uma janela modal inline para que os usuários nunca saiam do app principal.
Conveniência: os apps podem aplicar filtros em determinados tipos de arquivo do Drive (como Documentos, Planilhas e fotos Google) ao usar um filtro nos arquivos do Google Picker.

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

Salvar tokens de atualização

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