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

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

Escopos da API 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 de URI do OAuth 2.0 que contém o nome do app do Google Workspace, os tipos de dados que ele acessa e o nível de acesso. Os escopos são as solicitações do app para trabalhar com os 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 pelo app. Em geral, 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 acesso mais rápido a escopos limitados e claramente descritos.

Quando possível, recomendamos o uso de escopos não confidenciais, 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 oferece suporte aos seguintes escopos:

Código do escopo	Descrição	Uso
`https://www.googleapis.com/auth/drive.appdata https://www.googleapis.com/auth/drive.appfolder`	Visualizar e gerenciar os próprios dados de configuração do aplicativo no Google Drive.	Recomendado Não confidencial
`https://www.googleapis.com/auth/drive.install`	Permitir que aplicativos apareçam como uma opção no menu "Abrir com" ou "Novo".	Recomendado Não confidencial
`https://www.googleapis.com/auth/drive.file`	Crie ou modifique arquivos do Drive abertos com um app ou que o usuário compartilha com um app usando a API Google Picker ou o seletor de arquivos do app.	Recomendado Não confidencial
`https://www.googleapis.com/auth/auth/drive.apps.readonly`	Visualize os apps autorizados a acessar seu Google Drive.	Sensível
`https://www.googleapis.com/auth/drive`	Veja e gerencie todos os seus arquivos do Google Drive.	Restrito
`https://www.googleapis.com/auth/drive.readonly`	Veja e faça 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 Google Drive.	Restrito
`https://www.googleapis.com/auth/drive.metadata`	Visualizar e gerenciar metadados de arquivos em seu Google Drive.	Restrito
`https://www.googleapis.com/auth/drive.metadata.readonly`	Ver 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 Etapas de preparação para a verificação.
Recomendados / sensíveis: esses escopos dão acesso a dados específicos de usuários do Google autorizados pelo usuário para seu app. Isso exige que você passe por outras verificações de apps. Para informações sobre esse requisito, consulte Etapas para apps que solicitam escopos sensíveis
Restrito: esses escopos fornecem 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 dados de escopo restrito em servidores (ou transmitir), será necessário passar por uma avaliação de segurança.

Se o app exigir acesso a outras APIs do Google, você também pode 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 seu app prossiga pelo processo de verificação do OAuth do Google. Leia as Perguntas frequentes sobre a verificação da API OAuth para determinar quando seu app precisa passar pela verificação e que tipo de verificação é necessária. 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 os 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 educacionais e de produtividade com interface do usuário que possa envolver interação com arquivos do Drive (ou com metadados ou permissões) Os aplicativos de produtividade incluem gerenciamento de tarefas, anotações, comunicações em grupo de trabalho e aplicativos de colaboração em sala de aula.
Aplicativos de relatórios e segurança que fornecem insights ao usuário ou ao 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 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 alteração. Se você estiver usando seu próprio seletor de arquivos, recomendamos mudar para a API Google Picker, que é totalmente compatível com escopos diferentes.

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

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 seu app.

O escopo drive.file do OAuth 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 deles é limitado e seguro. Por outro lado, exigir acesso amplo a todos os arquivos do Drive pode desencorajar a interação dos usuários com seu app. Veja 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 os escopos mais amplos do OAuth.
Recursos: a API Google Picker oferece uma interface semelhante à interface do Drive. Isso inclui várias visualizações que mostram prévias e miniaturas dos arquivos do Drive e uma janela modal inline para que os usuários nunca saiam do app principal.
Conveniência: os apps podem aplicar filtros para determinados tipos de arquivos do Google Drive (como Documentos, Planilhas e fotos) ao usar um filtro nos arquivos do seletor do Google.

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

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.