Esta página foi traduzida pela API Cloud Translation.

Escopos

Os usuários precisam autorizar complementos e outros aplicativos que acessem os dados ou agir em nome deles. Quando um usuário executa um complemento pela primeira vez, o interface do usuário do complemento mostra um prompt de autorização para iniciar o fluxo de autorização.

Durante esse fluxo, o prompt informa ao usuário o que o aplicativo quer permissão para fazer. Por exemplo, um complemento pode querer permissão para ler um enviar uma mensagem de e-mail do usuário ou criar eventos na agenda. O 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 uma descrição legível do escopo para o usuário. Por exemplo, seu complemento do Google Workspace pode usar o erro "Ler a mensagem atual" , que é escrito no manifesto como https://www.googleapis.com/auth/gmail.addons.current.message.readonly: Durante fluxo de autorização, um complemento com esse escopo solicita que o usuário permita o complemento para: Acessar suas mensagens de e-mail quando o complemento estiver em execução.

Como visualizar escopos

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

Abra o projeto de script.
À esquerda, clique em Visão geral.
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 tipo oauthScopes campo, mas apenas se você tiver definido esses escopos explicitamente.

Definir escopos explícitos

O Apps Script verifica de modo automático quais escopos um script precisa verificar o código dele para chamadas de função que precisam delas. Para a maioria dos scripts, isso é suficientes e economiza tempo. No entanto, para complementos publicados, recomendamos controle mais direto dos escopos.

Por exemplo, o Apps Script pode dar a um projeto de script de complemento a opção mais permissiva escopo https://mail.google.com por padrão. Quando um usuário autoriza um script com esse escopo, ele recebe acesso total à conta do Gmail do Compute Engine. Para complementos publicados, é obrigatório substituir este escopo por um um conjunto limitado que atenda às necessidades dos complementos e nada mais.

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 seu projeto, faça o seguintes:

Veja os escopos usados atualmente pelo complemento. Determine o que mudanças 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 rotulado como oauthScopes. Se não estiver presente, em que você pode adicioná-lo.
O oauthScopes especifica uma matriz de strings. Para definir os escopos seu projeto usa, substitua o conteúdo dessa matriz pelos escopos que você que quer que ele 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 mudanças no arquivo de manifesto.

Verificação do OAuth

O uso de determinados escopos OAuth sensíveis pode exigir que o complemento seja aprovado Verificação do cliente OAuth antes de publicá-lo. Para mais informações, consulte estes guias:

Escopos restritos

Alguns escopos são restritos e estão sujeitos a regras adicionais que ajudam proteger os dados do usuário. Se você pretende publicar um Complemento do Gmail ou Editor que usa um ou mais escopos restritos, o complemento deve obedecer a todos os antes da publicação.

Consulte a lista completa de escopos restritos antes de tentar publicar. Se o complemento usar qualquer uma delas, você precisará obedecer com o Outros requisitos para escopos específicos da API antes da publicação.

Escopos da agenda

Confira abaixo escopos usados com frequência para complementos do Google Workspace que ampliam o Google Agenda.

Escopo
Acessar metadados de eventos	`https://www.googleapis.com/auth/calendar.addons.execute` Obrigatório se o complemento acessa metadados de eventos do Google Agenda. Permite para acessar 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 eventos gerados pelo usuário. Permite que o complemento acesse dados de eventos gerados pelo usuário. Esses dados são estará disponível apenas se o Campo do manifesto `addOns.calendar.eventAccess` está 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 eventos gerados pelo usuário. Esses dados são estará disponível apenas se o Campo do manifesto `addOns.calendar.eventAccess` está definido como `WRITE` ou `READ_WRITE`.

Escopos do Drive

Confira abaixo escopos usados com frequência para complementos do Google Workspace que ampliam 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 seleciona itens no Drive. Permite que o complemento leia metadados limitados sobre os itens de um usuário selecionados no Google Drive. Os metadados são limitados ao ID do item, título, tipo MIME, URL do ícone e se o complemento tem permissão para para acessar o item.
Acesso por arquivo	`https://www.googleapis.com/auth/drive.file` Recomendado se o complemento precisar acessar um Drive específico . Concede acesso por arquivo aos arquivos criados ou abertos pelo aplicativo usando a unidade avançada do Apps Script Serviço. Isso não permite o uso de ações semelhantes que utilizem o serviço básico do Drive, No entanto. A autorização é concedida por arquivo e é revogado quando o usuário desautoriza o app. Consulte a Exemplo de como solicitar 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 seleciona itens no Drive. Permite que o complemento leia metadados limitados sobre os itens de um usuário selecionados no Google Drive. Os metadados são limitados ao ID do item, título, tipo MIME, URL do ícone e se o complemento tem permissão para para acessar o item.

Acesso por arquivo

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

Recomendado se o complemento precisar acessar um Drive específico . Concede acesso por arquivo aos arquivos criados ou abertos pelo aplicativo usando a unidade avançada do Apps Script Serviço. Isso não permite o uso de ações semelhantes que utilizem o serviço básico do Drive, No entanto. A autorização é concedida por arquivo e é revogado quando o usuário desautoriza o app.

Consulte a Exemplo de como solicitar acesso a arquivos selecionados.

Escopos dos complementos do Gmail

Há alguns escopos que foram criados especificamente para Complementos do Google Workspace para proteger o Gmail dos usuários dados. Você deve adicionar esses escopos explicitamente ao manifesto do complemento, entre outros código do complemento necessário.

Confira abaixo escopos usados com frequência para complementos do Google Workspace que ampliam o Gmail. aqueles com o rótulo Obrigatório devem ser adicionados Manifesto de complemento do Google Workspace caso seu complemento seja estendido Gmail

Substitua o escopo https://mail.google.com, que é muito amplo, nos seus com um conjunto mais estreito de escopos que permitem as interações necessidades e nada mais.

Escopo
Criar novos rascunhos	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Obrigatório se o complemento usar gatilhos de ações do Compose. Permite que o complemento crie temporariamente novas mensagens de rascunho e respostas Consulte Escrever rascunhos de mensagens para mais detalhes. este escopo também é usado com frequência ações de escrita. 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 destinatários). Não permite a leitura do conteúdo da mensagem e exige um token de acesso. Obrigatório se o complemento usar metadados na ação de escrita e gatilhos. Para ações de composição, esse escopo será necessário se um gatilho de escrita for usado. precisa de acesso aos metadados. Na prática, esse escopo permite que um Compose acionar listas de destinatários de acesso (para, cc: e cco:) de uma resposta rascunho de e-mail.
Ler o conteúdo das mensagens abertas	`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. por exemplo, quando um item de menu de complemento é selecionado. Requer um acesso com base no token correto anterior.
Ler o conteúdo das conversas abertas	`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 no espaço aberto fio Requer um token de acesso.
Ler qualquer conteúdo e metadados de mensagens	`https://www.googleapis.com/auth/gmail.readonly` Ler todos os metadados e conteúdos de e-mails, 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 de e-mail inteira. Aviso: esta é uma questão muito ampla, escopo restrito. Use apenas se absolutamente necessário.

Tokens de acesso

Para proteger os dados do usuário, os escopos do Gmail usados Concessão exclusiva de complementos do Google Workspace acesso temporário aos dados do usuário. Para ativar o acesso temporário, você deve chamar o método função GmailApp.setCurrentMessageAccessToken(accessToken) usando um token de acesso como argumento. Você deve obter um token de acesso de um objeto de evento de ação.

Veja a seguir um exemplo de configuração de um token de acesso para permitir o acesso a os 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

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

Escopo
Acesso atual ao arquivo dos Documentos Google	`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 atual ao arquivo do app 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 atual ao arquivo das Apresentações Google	`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 se o complemento acessa a API Documentos, Planilhas, Apresentações ou Drive. Concede acesso por arquivo aos arquivos criados ou abertos pelo aplicativo usando a unidade avançada do Apps Script Serviço. Isso não permite o uso de ações semelhantes que utilizem o serviço básico do Drive, No entanto. A autorização é concedida por arquivo e é revogado quando o usuário desautoriza o aplicativo.

Outros escopos

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

Como referência, aqui está uma lista de escopos do Apps Script usados com frequência em com 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 `UrlFetch` solicitações. Isso também será necessário se o projeto fizer uso da 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 saiba a localidade e o fuso horário do usuário atual. Consulte Acesse 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 e gatilhos de detecção.
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 acesse um link em um app do Google Workspace enquanto o usuário interage com ele. Para saber mais, consulte Conferir prévias de links com ícones inteligentes
Criar recursos de terceiros	`https://www.googleapis.com/auth/workspace.linkcreate` Obrigatório se o complemento criar recursos em um serviço de terceiros. Permite que o projeto leia as informações enviadas pelos usuários o formulário de criação de recursos e e inserir um link para o recurso em um aplicativo do Google Workspace. Para saber mais, consulte Criar recursos de terceiros no menu "@".