Esta página foi traduzida pela API Cloud Translation.

Escopos

Os usuários precisam autorizar complementos e outros aplicativos que acessem os dados deles ou agirem em nome deles. Quando um usuário executa um complemento pela primeira vez, a IU do complemento apresenta um prompt 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 a mensagem de e-mail ou criar eventos na agenda do usuário. 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 uma descrição legível do escopo para o usuário. Por exemplo, seu complemento do Google Workspace pode usar o escopo "Ler mensagem atual", que é escrito no manifesto como https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Durante o fluxo de autorização, um complemento com esse escopo pede ao usuário para permitir que o complemento: Ver suas mensagens de e-mail quando o complemento estiver em execução.

Como visualizar escopos

Para ver os escopos exigidos pelo projeto de script no momento, faça o seguinte:

Abra o projeto de script.
À esquerda, clique em Visão geral .
Veja os escopos em "Escopos do 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.

Como definir escopos explícitos

O Apps Script determina automaticamente de quais escopos um script precisa verificando o código em busca de chamadas de função que os exijam. Para a maioria dos scripts, isso é suficiente e economiza tempo, mas para complementos publicados, você precisa ter controle mais direto dos escopos.

Por exemplo, o Apps Script pode dar 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 não mais do que isso.

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

Ver os escopos que seu complemento usa atualmente. Determine quais alterações precisam ser feitas, como o uso de um escopo mais restrito.
Abra o arquivo de manifesto do complemento.
Localize o campo de nível superior com o rótulo oauthScopes. Se não estiver presente, é possível adicioná-lo.
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 que ela use. Por exemplo, em um complemento do Google Workspace que estende o Gmail, você pode ter o seguinte:
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
Salve as alterações no arquivo de manifesto.

Verificação do OAuth

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

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 usa um ou mais escopos restritos, o complemento precisa obedecer a todas as restrições especificadas antes da publicação.

Revise a lista completa de escopos restritos antes de tentar publicar. Se o complemento usar algum deles, será necessário obedecer aos requisitos adicionais para escopos de API específicos antes da publicação.

Escopos da agenda

Veja abaixo os escopos usados com frequência para os complementos do Google Workspace que estendem o Google Agenda.

Escopo
Acessar metadados do evento	`https://www.googleapis.com/auth/calendar.addons.execute` Obrigatório se o complemento acessar os metadados de eventos do Agenda. Permite que o complemento acesse metadados de eventos.
Ler dados de eventos gerados pelo usuário	`https://www.googleapis.com/auth/calendar.addons.current.event.read` Obrigatório se o complemento precisar ler dados de evento gerados pelo usuário. Permite que o complemento acesse dados de eventos gerados pelo usuário. Esses dados só estarão disponíveis se o campo do manifesto `addOns.calendar.eventAccess` estiver definido como `READ` ou `READ_WRITE`.
Gravar dados de eventos gerados pelo usuário	`https://www.googleapis.com/auth/calendar.addons.current.event.write` Obrigatório se o complemento precisar gravar dados de eventos gerados pelo usuário. Permite que o complemento edite dados de evento gerados pelo usuário. Esses dados só estarão disponíveis se o campo do manifesto `addOns.calendar.eventAccess` estiver definido como `WRITE` ou `READ_WRITE`.

Escopos do Drive

Veja abaixo os escopos usados com frequência para complementos do Google Workspace que estendem o Google Drive.

Escopo

Ler metadados do item selecionado

Escopo
Ler metadados do item selecionado	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` Obrigatório se o complemento implementar uma interface contextual acionada quando o usuário selecionar itens no Drive. Permite que o complemento leia metadados limitados sobre itens que um usuário selecionou no Google Drive. Os metadados são limitados ao código do item, título, tipo MIME, URL do ícone e se o complemento tem permissão para acessar o item.
Acesso por arquivo	`https://www.googleapis.com/auth/drive.file` Recomendado se o complemento precisar acessar arquivos individuais do Drive. Concede acesso por arquivo a arquivos criados ou abertos pelo app, usando o Serviço avançado de unidade do Apps Script. No entanto, isso não permite o uso de ações semelhantes por meio do serviço básico do Drive. A autorização de arquivos é concedida por arquivo e é revogada quando o usuário desautoriza o app. Veja o exemplo de solicitação de acesso a arquivos selecionados.

https://www.googleapis.com/auth/drive.addons.metadata.readonly

Obrigatório se o complemento implementar uma interface contextual acionada quando o usuário selecionar itens no Drive. Permite que o complemento leia metadados limitados sobre itens que um usuário selecionou no Google Drive. Os metadados são limitados ao código do item, título, tipo MIME, URL do ícone e se o complemento tem permissão para acessar o item.

Acesso por arquivo

https://www.googleapis.com/auth/drive.file

Recomendado se o complemento precisar acessar arquivos individuais do Drive. Concede acesso por arquivo a arquivos criados ou abertos pelo app, usando o Serviço avançado de unidade do Apps Script. No entanto, isso não permite o uso de ações semelhantes por meio do serviço básico do Drive. A autorização de arquivos é concedida por arquivo e é revogada quando o usuário desautoriza o app.

Veja o exemplo de solicitação de acesso a arquivos selecionados.

Escopos dos complementos do Gmail

Alguns escopos foram criados especificamente para os complementos do Google Workspace e ajudam a proteger os dados do Gmail do usuário. Você precisa adicionar esses escopos explicitamente ao manifesto do complemento, além de todos os outros necessários no código do complemento.

Veja abaixo os escopos usados com frequência para complementos do Google Workspace que estendem o Gmail. Os que têm o marcador Obrigatório precisam ser adicionados ao manifesto de complementos do Google Workspace se o complemento estender o Gmail.

Substitua também o escopo https://mail.google.com muito amplo no complemento por um conjunto mais restrito de escopos que permitem as interações necessárias para seu complemento e nada mais.

Escopo
Criar novos rascunhos	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Obrigatório se o complemento usar acionadores de ação de composição. Permite que o complemento crie temporariamente novos rascunhos de mensagens e respostas. Consulte Como escrever mensagens de rascunho para mais detalhes. Esse escopo também costuma ser usado com ações de composição. Requer um token de acesso.
Ler metadados de mensagens abertas	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` Concede acesso temporário aos metadados da mensagem aberta, como o assunto ou os destinatários. Não permite a leitura do conteúdo da mensagem e requer um token de acesso. Obrigatório se o complemento usar metadados em acionadores de ações de escrita. Para ações de composição, esse escopo será necessário se um acionador de escrita precisar de acesso a metadados. Na prática, esse escopo permite que um Compose acione listas de destinatários de acesso (para:, cc: e bcc:) de um rascunho de e-mail de resposta.
Ler o conteúdo da mensagem aberta	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Concede acesso ao conteúdo da mensagem aberta após uma interação do usuário, como quando um item de menu complementar é selecionado. Requer um token de acesso.
Ler conteúdo da conversa aberta	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` Concede acesso temporário aos metadados e ao conteúdo da mensagem aberta. Também concede acesso ao conteúdo de outras mensagens na linha de execução aberta. Requer um token de acesso.
Ler o conteúdo e os metadados da mensagem	`https://www.googleapis.com/auth/gmail.readonly` Ler os metadados e o conteúdo do e-mail, incluindo a mensagem aberta. Obrigatório se você precisar ler informações sobre outras mensagens, como ao realizar uma consulta de pesquisa ou ler uma conversa inteira. Aviso: este é um escopo restrito muito amplo. Use-a apenas se absolutamente necessário.

Tokens de acesso

Para proteger os dados do usuário, os escopos do Gmail usados nos complementos do Google Workspace só concedem acesso temporário aos dados do usuário. Para ativar o acesso temporário, chame a função GmailApp.setCurrentMessageAccessToken(accessToken) usando um token de acesso como argumento. É preciso conseguir um token de acesso de um objeto de evento de ação.

Veja a seguir um exemplo de como configurar um token de acesso para permitir acesso aos metadados de uma mensagem. O único escopo necessário para este exemplo é https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Escopos do editor

Veja abaixo os escopos usados com frequência para complementos do Google Workspace que estendem Documentos, Planilhas e Apresentações.

Escopo
Acesso atual ao arquivo do Documentos	`https://www.googleapis.com/auth/documents.currentonly` Obrigatório se o complemento acessar a API Apps Script Docs. Concede acesso temporário ao conteúdo do documento aberto.
Acesso ao arquivo do Planilhas	`https://www.googleapis.com/auth/spreadsheets.currentonly` Obrigatório se o complemento acessar a API Apps Script Sheets. Concede acesso temporário ao conteúdo da planilha aberta.
Acesso ao arquivo do Apresentações	`https://www.googleapis.com/auth/presentations.currentonly` Obrigatório se o complemento acessar a API Apps Script Slides. Concede acesso temporário ao conteúdo da apresentação aberta.
Acesso por arquivo	`https://www.googleapis.com/auth/drive.file` Obrigatório para o complemento usar o `onFileScopeGrantedTrigger` e para o acesso à API Documentos, Planilhas, Apresentações ou Drive. Concede acesso por arquivo a arquivos criados ou abertos pelo app, usando o Serviço avançado de unidade do Apps Script. No entanto, isso não permite o uso de ações semelhantes por meio do serviço básico do Drive. A autorização de arquivos é concedida por arquivo e é revogada quando o usuário desautoriza o app.

Outros escopos

Seu complemento pode exigir escopos adicionais se ele usar outros serviços do Apps Script. Na maioria dos casos, o Apps Script pode detectar esses escopos e atualizar o manifesto automaticamente. Ao editar a lista de escopos do manifesto, não remova nenhum escopo, a menos que você os substitua por uma alternativa mais apropriada, como um escopo mais restrito.

Para referência, veja uma lista de escopos do Apps Script que geralmente são usados com os complementos do Google Workspace:

Escopo
Ler o endereço de e-mail do usuário	`https://www.googleapis.com/auth/userinfo.email` Permite que o projeto leia o endereço de e-mail do usuário atual.
Permitir chamadas para serviços externos	`https://www.googleapis.com/auth/script.external_request` Permite que o projeto faça solicitações `UrlFetch`. Isso também será necessário se o projeto usar a biblioteca OAuth2 para Apps Script.
Ler a localidade e o fuso horário do usuário	`https://www.googleapis.com/auth/script.locale` Permite que o projeto aprenda a localidade e o fuso horário do usuário atual. Consulte Como acessar a localidade e o fuso horário do usuário para mais detalhes.
Criar acionadores	`https://www.googleapis.com/auth/script.scriptapp` Permite que o projeto crie acionadores.
Visualizar links de terceiros	`https://www.googleapis.com/auth/workspace.linkpreview` Obrigatório se o complemento visualizar links de um serviço de terceiros. Permite que o projeto veja um link dentro de um aplicativo do Google Workspace enquanto o usuário interage com ele. Para saber mais, consulte Visualizar links com ícones inteligentes.