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 serão exibidas aos usuários e revisores de apps e registre seu app para 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 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 os dados do Google Workspace, incluindo os dados da Conta do Google dos usuários.

Quando seu app é instalado, o usuário precisa validar os escopos usados pelo app. Em geral, é preciso escolher o escopo mais restrito possível e evitar a solicitação de escopos que seu app não exige. Os usuários concedem acesso a escopos limitados e claramente descritos.

Quando possível, recomendamos o uso de escopos não confidenciais, já que eles concedem escopo 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 próprios dados de configuração do aplicativo em seu Google Drive.	Recomendado Não confidencial
`https://www.googleapis.com/auth/drive.install`	Permitir que os aplicativos apareçam como uma opção no menu "Abrir com" ou "Novo".	Recomendado Não confidencial
`https://www.googleapis.com/auth/drive.file`	Criar ou modificar arquivos 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`	Veja os apps autorizados a acessar seu Drive.	Sensível
`https://www.googleapis.com/auth/drive`	Veja e gerencie todos os seus arquivos do 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 Drive.	Restrito
`https://www.googleapis.com/auth/drive.metadata`	Ver e gerenciar metadados de arquivos em seu Google Drive.	Restrito
`https://www.googleapis.com/auth/drive.metadata.readonly`	Ver metadados de arquivos em seu Google 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 oferecem o menor escopo de acesso de autorização e exigem apenas uma verificação básica de apps. Para mais informações sobre esse requisito, consulte Etapas de preparação para a verificação.
Recomendado / confidencial: esses escopos fornecem acesso a dados específicos do usuário do Google autorizados pelo usuário para seu app. Elas exigem que você faça uma verificação adicional de apps. Para mais informações sobre esse requisito, consulte Etapas para apps que solicitam escopos confidenciais
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 APIs 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, 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 seu app conclua o processo de verificação do OAuth do Google. Leia as perguntas frequentes sobre a verificação da API OAuth para determinar quando o app precisa passar pela verificação e o tipo de verificação necessário. Consulte também os Termos de Serviço do Google Drive.

Quando usar um escopo restrito

s 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 educacionais e de produtividade que têm uma interface do usuário que envolve 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 em grupo de trabalho e aplicativos de colaboração em sala de aula.
Aplicativos de relatórios e segurança que fornecem insights a 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 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 mudança. 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 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 dá a eles mais controle e confiança de que o acesso do app aos arquivos deles é 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. 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 você pode usá-lo da mesma forma que escopos do OAuth mais amplos.
Recursos: a API Google Picker oferece uma interface semelhante à IU do Drive. Isso inclui várias visualizações que mostram visualizações e miniaturas de 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 a determinados tipos de arquivo 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 simplificado.

Salvar tokens de atualização

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