Escopos de autorização dos complementos do Editor

Os usuários precisam autorizar complementos e outros aplicativos que acessam os dados ou atuam em nome deles. Quando um usuário executa um complemento pela primeira vez, a interface do complemento apresenta uma solicitação de autorização para iniciar o fluxo de autorização.

Durante esse fluxo, a solicitação informa ao usuário o que o aplicativo quer permissão para fazer. Por exemplo, um complemento pode querer permissão para ler o e-mail de um usuário ou criar eventos na agenda dele. O projeto de script do complemento define essas permissões individuais como escopos do OAuth.

Você declara escopos no seu manifesto usando strings de URL. Durante o fluxo de autorização, o Apps Script apresenta ao usuário uma descrição legível do escopo. Por exemplo, seu complemento pode usar o escopo "Ler o documento atual", que é escrito no manifesto como https://www.googleapis.com/auth/documents.currentonly. Durante o fluxo de autorização, um complemento com este escopo solicita que o usuário permita o complemento: Ver e gerenciar documentos em que este aplicativo foi instalado.

Observação :os escopos usados pelo Apps Script para os vários serviços se sobrepõem aos escopos usados pela API relacionada. Por exemplo, o serviço Agenda do Apps Script usa muitos dos mesmos escopos que a API Calendar. Procure os escopos que determinados métodos de serviço do Apps Script exigem na documentação de referência do Apps Script.

Como visualizar escopos

Para ver os escopos que seu projeto de script exige no momento, faça o seguinte:

1. Abra o projeto de script.
2. À esquerda, clique em Visão geral .
3. Confira os escopos em "Escopos OAuth do projeto".

Também é possível ver os escopos atuais do projeto de script no manifesto do projeto, no campo oauthScopes, mas somente se você tiver definido esses escopos explicitamente.

Definir escopos explícitos

O Apps Script determina automaticamente os escopos necessários para um script, verificando o código em busca de chamadas de função que exigem esses escopos. Para a maioria dos scripts, isso é suficiente e economiza tempo, mas para complementos publicados, é necessário ter um controle mais direto dos escopos.

Por exemplo, o Apps Script pode fornecer a um projeto de script de complemento o escopo muito permissivo https://mail.google.com por padrão. Quando um usuário autoriza um projeto de script com esse escopo, o projeto recebe acesso total à conta do Gmail do usuário. Para complementos publicados, você precisa substituir esse escopo por um conjunto mais limitado que atenda às necessidades dos complementos e nada mais.

Aviso :sempre use o conjunto de escopo menos permissivo possível. Para proteger as informações do usuário, complementos e outros aplicativos publicados nunca devem solicitar mais permissões de escopo do que são absolutamente necessárias. Os escopos exigidos pelo complemento são examinados durante o processo de revisão de complementos da publicação. Se o complemento usar escopos muito amplos, ele não será aprovado.

Para definir explicitamente os escopos usados no projeto de script, edite o arquivo de manifesto. O campo de manifesto oauthScopes é uma matriz de todos os escopos usados pelo complemento. Para definir os escopos do projeto, faça o seguinte:

1. Veja os escopos usados no momento. Determine quais mudanças precisam ser feitas, como usar um escopo mais restrito.
2. Abra o arquivo de manifesto do complemento.
3. Localize o campo de nível superior chamado oauthScopes. Se não estiver presente, você pode adicioná-lo.

4. O campo oauthScopes especifica uma matriz de strings. Para definir os escopos usados no projeto, substitua o conteúdo dessa matriz pelos escopos que você quer que ela use. Por exemplo, para um complemento de editor que estenda o Planilhas, você pode ter o seguinte:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/script.container.ui",
       "https://www.googleapis.com/auth/spreadsheets.currentonly"
     ],
     ...
   }
   

5. Salve as mudanças no arquivo de manifesto.

Verificação do OAuth

O uso de determinados escopos confidenciais do OAuth pode exigir que o complemento passe pela verificação do cliente OAuth antes de ser publicado. Para mais informações, consulte estes guias:

• Verificação do cliente OAuth para o Apps Script
• Apps não verificados
• Perguntas frequentes sobre a verificação do OAuth
• Serviço de APIs do Google: política de dados do usuário

Escopos restritos

Alguns escopos são restritos e estão sujeitos a outras regras que ajudam a proteger os dados do usuário. Se você pretende publicar um complemento do Gmail ou do Editor que use um ou mais escopos restritos, o complemento precisa obedecer a todas as restrições especificadas antes de ser publicado.

Analise a lista completa de escopos restritos antes de tentar publicar. Se o complemento usar qualquer um deles, você precisa obedecer aos requisitos adicionais para escopos específicos da API antes da publicação.

Observação: evite usar escopos restritos no seu complemento, se possível. É mais fácil passar na avaliação de complementos para publicação pública se você não os usar. Você pode usar escopos restritos livremente para complementos não públicos.

Escopos do complemento do editor

Quando você cria um complemento do Editor, os escopos necessários são determinados pelo serviço do Apps Script e pelos métodos usados pelo código do complemento. Por exemplo, um complemento do Planilhas pode precisar do escopo https://www.googleapis.com/auth/spreadsheets.readonly para ler informações de diferentes Planilhas Google.

O Apps Script determina automaticamente os escopos exigidos pelos serviços que você usa à medida que adiciona código ao projeto de script. Para os complementos do Editor, muitas vezes é possível confiar nessa coleta automática de escopos em vez de determinar os escopos por conta própria e defini-los explicitamente.

Se você não estiver definindo seus escopos explicitamente e o complemento do editor somente ler ou gravar no arquivo do editor aberto, adicione o seguinte comentário a um dos seus arquivos de projeto de script:

  /**
   * @OnlyCurrentDoc
   */

Esse comentário instrui o Apps Script a restringir os escopos do arquivo do editor definidos como currentonly. Por exemplo, se você adicionar esse comentário a um arquivo de projeto de script de complemento das Planilhas Google, estará especificando que o complemento só precisa de permissão para funcionar na planilha aberta atualmente, e não em outras planilhas que o usuário possa ter no Google Drive. Por outro lado, você não deve usar esse comentário se o complemento do Planilhas precisa ler ou gravar dados em uma planilha que o usuário não tenha aberto no momento.