Escopos de autorização para complementos do Editor

Os usuários precisam autorizar complementos e outros aplicativos que acessam os dados ou agem 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 fazer. Por exemplo, um complemento pode querer permissão para ler uma mensagem de e-mail do usuário ou criar eventos na agenda dele. O projeto do script do complemento define essas permissões individuais como escopos do OAuth.

Você declara escopos no manifest usando strings de URL. Durante o fluxo de autorização, o Apps Script apresenta uma descrição legível pelo usuário do escopo. Por exemplo, o complemento pode usar o escopo "Ler documento atual", que é gravado no manifesto como https://www.googleapis.com/auth/documents.currentonly. Durante o fluxo de autorização, um complemento com esse escopo pede que o usuário permita que o complemento acesse e gerencie documentos nos quais este aplicativo foi instalado.

Observação:o escopo currentonly só está disponível nos serviços do Apps Script. Isso não inclui os Advanced Services do Apps Script ou chamadas diretas para as APIs do Google Workspace.

Observação: os escopos que o Apps Script usa para os vários serviços se sobrepõem aos escopos usados pela API relacionada. Por exemplo, o serviço de agenda do Apps Script usa muitos dos mesmos escopos da API Calendar. É possível consultar os escopos que métodos de serviço específicos do Apps Script exigem na documentação de referência do Apps Script.

Como conferir escopos

Para conferir os escopos que seu projeto de script exige atualmente, faça o seguinte:

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

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

Como definir escopos explícitos

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

Por exemplo, o Apps Script pode conceder a um projeto de script complementar o escopo https://mail.google.com muito permissivo 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, é necessário substituir esse escopo por um conjunto mais limitado que atenda às necessidades dos complementos.

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

É possível definir explicitamente os escopos usados pelo projeto de script editando o arquivo manifest. 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. Confira os escopos usados pelo complemento. Determine quais mudanças precisam ser feitas, como usar um escopo mais estreito.
2. Abra o arquivo de manifesto do complemento.
3. Localize o campo de nível superior com a etiqueta oauthScopes. Se ele não estiver presente, adicione-o.

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

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

5. Salve as alterações no arquivo de manifesto.

Verificação do OAuth

O uso de determinados escopos sensíveis do OAuth pode exigir que seu complemento passe por uma verificação de cliente do OAuth antes da publicação. Para mais informações, consulte estes guias:

• Verificação de 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 regras adicionais que ajudam a proteger os dados do usuário. Se você pretende publicar um complemento do Gmail ou do Editor que usa um ou mais escopos restritos, ele precisa obedecer a todas as restrições especificadas antes de ser publicado.

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

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

Escopos do complemento do editor

Ao criar 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 das 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 necessários pelos serviços que você usa ao adicionar código ao projeto do script. Para complementos do editor, muitas vezes é possível usar essa coleta automática de escopos em vez de determinar os escopos e defini-los explicitamente.

Se você não estiver definindo seus escopos explicitamente e o complemento do editor só ler ou gravar no arquivo de 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 de 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 operar na planilha aberta no momento, e não em nenhuma outra que o usuário possa ter no Google Drive. Por outro lado, não use esse comentário se o complemento do Planilhas precisar ler ou gravar dados em uma planilha que o usuário não abriu.

Observação:o escopo currentonly só está disponível nos serviços do Apps Script. Isso não inclui os Advanced Services do Apps Script ou chamadas diretas para as APIs do Google Workspace.