Solução de problemas

Mesmo o desenvolvedor mais experiente raramente escreve código corretamente no primeiro experimento, tornando a solução de problemas uma parte importante do processo de desenvolvimento. Nesta seção, abordaremos algumas técnicas que podem ajudar você a encontrar, entender e depurar erros nos seus scripts.

Mensagens de erro

Quando seu script encontra um erro, uma mensagem de erro é exibida. A mensagem é acompanhada por um número de linha usado para solucionar o problema. Há dois tipos básicos de erros exibidos dessa forma: erros de sintaxe e erros de execução.

Erros de sintaxe

Os erros de sintaxe são causados pela escrita de um código que não segue o gramática JavaScript, e os erros são detectados assim que você tenta salvar o script. Por exemplo, o snippet de código a seguir contém um erro de sintaxe:

function emailDataRow(rowNumber) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var rowData = data[rowNumber-1].join(" ";
  MailApp.sendEmail('john@example.com',
                    'Data in row ' + rowNumber,
                    rowData);
}

O problema de sintaxe aqui é um caractere ) ausente no final da quarta linha. Ao tentar salvar o script, você verá o seguinte erro:

Falta ) depois da lista de argumentos. (linha 4)

Esses tipos de erros geralmente são simples de resolver, já que são encontrados imediatamente e geralmente têm causas simples. Não é possível salvar um arquivo que contenha erros de sintaxe, o que significa que apenas códigos válidos são salvos no seu projeto.

Erros de execução

Esses erros são causados pelo uso incorreto de uma função ou classe e só podem ser detectados depois que o script é executado. Por exemplo, o código a seguir causa um erro de tempo de execução:

function emailDataRow(rowNumber) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var rowData = data[rowNumber-1].join(" ");
  MailApp.sendEmail('john',
                    'Data in row ' + rowNumber,
                    rowData);
}

O código está formatado corretamente, mas estamos transmitindo o valor"quot;john"" para o endereço de e-mail ao chamar MailApp.sendEmail. Como esse não é um endereço de e-mail válido, o erro a seguir é gerado ao executar o script:

E-mail inválido: joão (linha 5)

O que torna esses erros mais difíceis de solucionar é que, muitas vezes, os dados transmitidos para uma função não são gravados no código, mas extraídos de uma planilha, de um formulário ou de outra fonte de dados externa. O uso das técnicas de depuração abaixo pode ajudar a identificar a causa desses erros.

Erros comuns

Veja abaixo uma lista de erros comuns e as causas deles.

Serviço invocado muitas vezes: <nome da ação>

Esse erro indica que você excedeu sua cota diária para uma determinada ação. Por exemplo, esse erro pode ocorrer se você enviar muitos e-mails em um único dia. As cotas são definidas em diferentes níveis para contas de consumidor, domínio e premier e estão sujeitas a alterações a qualquer momento sem um aviso anterior do Google. Veja os limites de cota para várias ações na documentação de cotas do Apps Script.

Servidor indisponível ou Erro no servidor. Tente novamente.

Existem algumas causas possíveis para esses erros:

  • Um sistema ou servidor do Google está temporariamente indisponível. Aguarde alguns instantes e tente executar o script novamente.
  • Há um erro em seu script que não tem uma mensagem de erro correspondente. Tente depurar seu script e veja se é possível isolar o problema.
  • Há um bug no Google Apps Script que está causando esse erro. Para ver instruções sobre como pesquisar e preencher relatórios de bugs, consulte Bugs. Antes de informar um novo bug, verifique se ele já foi informado por outras pessoas.

A autorização é necessária para executar essa ação.

Esse erro indica que o script não tem a autorização necessária para ser executado. Quando um script é executado no editor de script ou em um item de menu personalizado, uma caixa de diálogo de autorização é exibida ao usuário. No entanto, quando um script é executado a partir de um acionador, incorporado a uma página do Google Sites ou executado como um serviço, a caixa de diálogo não pode ser apresentada, e esse erro é exibido.

Para autorizar o script, abra o Editor de scripts e execute qualquer função. O prompt de autorização é exibido para autorizar o projeto de script. Se o script contiver novos serviços não autorizados, será necessário autorizar novamente o script.

Esse erro costuma ser causado por acionadores que são disparados antes do usuário ter autorizado. Se você não tiver acesso ao projeto do script (porque o erro ocorre para um complemento que você usa, por exemplo), geralmente é possível autorizar o script usando o complemento novamente. Se um gatilho continuar sendo disparado e causar esse erro, será possível remover seus gatilhos fazendo o seguinte:

Novo editor

  1. À esquerda do projeto do Apps Script, clique em Acionadores .
  2. À direita do acionador que você quer remover, clique em Mais > Excluir acionador.

Editor legado

  1. Selecione Editar > Todos os acionadores no editor do Apps Script. A caixa de diálogo resultante mostra todos os acionadores ativos em execução na sua conta.
  2. Encontre o acionador ofensivo na lista.
  3. Clique no ícone ao lado do nome do acionador para removê-lo.
  4. Clique em Salvar para gravar a exclusão.

Também é possível remover gatilhos de complementos problemáticos desinstalando o complemento.

Acesso negado: DriveApp ou A política de domínio desativou os apps do Drive de terceiros

Os administradores de Google Workspace domínios podem desativar o SDK do Drive para o domínio, o que impede que os usuários instalem e usem apps do Google Drive. Essa configuração também impede que os usuários possam utilizar complementos do Apps Script que usam o serviço do Drive ou o serviço avançado do Drive, mesmo que o script tenha sido autorizado antes do administrador desativar o SDK do Drive.

No entanto, se um complemento ou app da Web que usa o serviço do Drive for publicado para instalação em todo o domínio e instalado pelo administrador para alguns ou todos os usuários no domínio, o script aparecerá para eles mesmo que o SDK do Drive esteja desativado no domínio.

O script não tem permissão para obter a identidade do usuário ativo.

Indica que a identidade e o e-mail do usuário ativo não estão disponíveis para o script. Esse aviso é resultado de uma chamada para Session.getActiveUser(). Isso também pode resultar de uma chamada para Session.getEffectiveUser() se o script estiver em execução em um modo de autorização diferente de AuthMode.FULL. Se esse alerta for sinalizado, as chamadas subsequentes para User.getEmail() retornarão apenas ""

Há várias maneiras de resolver esse aviso, dependendo do modo de autorização em que o script está sendo executado. Esse modo é exposto em funções acionadas como a propriedade authMode do parâmetro de evento e.

  • Em AuthMode.FULL, use Session.getEffectiveUser().
  • Em AuthMode.LIMITED, verifique se o proprietário autorizou o script.
  • Em outros modos de autorização, evite chamar qualquer um dos métodos.
  • Se você é um Google Workspace cliente que está recebendo este alerta recentemente de um gatilho instalável, verifique se o gatilho está sendo executado como um usuário na sua organização.

Biblioteca ausente

Se você adicionar uma biblioteca conhecida ao seu script, poderá receber uma mensagem de erro informando que ela está ausente, mesmo que a biblioteca esteja listada como uma dependência do seu script. Isso pode ocorrer porque muitas pessoas estão acessando a biblioteca ao mesmo tempo. Para evitar esse erro, tente uma destas soluções:

  • Copie e cole o código da biblioteca no script e remova a dependência da biblioteca.
  • Copie o script e implante-o como uma biblioteca da sua conta. Lembre-se de atualizar a dependência do script original para a nova biblioteca em vez da pública.

Depurar

Nem todos os erros fazem com que uma mensagem de erro seja exibida. Pode haver um erro mais sutil em que o código é tecnicamente correto e pode ser executado, mas os resultados não são o que você espera. Veja algumas estratégias para lidar com essas situações e investigar melhor um script que não está sendo executado da maneira esperada.

Logging

Durante a depuração, geralmente é útil gravar informações à medida que o projeto de um script é executado. O Google Apps Script tem dois métodos para registrar informações: o serviço de geração de registros do Cloud e os serviços de console e registrador mais básicos integrados ao editor do Apps Script.

Consulte o guia do Logging para ver mais detalhes.

Error Reporting

As exceções que ocorrem devido a erros de tempo de execução são registradas automaticamente usando o serviço Google Cloud Error Reporting. Com esse serviço, é possível pesquisar e filtrar mensagens de exceção criadas pelo seu projeto de script.

Novo editor

Para acessar o Error Reporting, consulte Ver registros do Cloud e relatórios de erro no console do Google Cloud Platform.

Editor legado

Ative o Error Reporting na primeira vez que você selecionar Ver > Stackdriver Logging ou Ver > Stackdriver Error Reporting em um novo script.

Depois de ativados, as exceções que ocorrem devido a erros de tempo de execução são registradas automaticamente usando o serviço Google Cloud Stackdriver. Com esse serviço, é possível pesquisar e filtrar mensagens de exceção criadas pelo seu projeto de script. Acesse a interface do Stackdriver Error Reporting selecionando View > Stackdriver Error Reporting no editor do Apps Script.

Execuções

Novo editor

Sempre que você executa um script, o Apps Script grava uma execução, inclusive os registros do Cloud. Esses registros ajudam você a entender quais ações o script realizou.

Para ver as execuções do seu script no projeto do Apps Script, à esquerda, clique em Execuções .

Editor legado

Sempre que você executa um script, o Apps Script grava uma execução, inclusive os registros do Cloud. Esses registros ajudam você a entender quais ações o script realizou. Para ver as execuções do script, selecione Ver > execuções no editor do Apps Script. Isso abre o painel Execuções do script no painel do Apps Script.

Verificar o status do serviço do Apps Script

Embora sejam raros, às vezes serviços Google Workspace específicos (como Gmail ou Drive) encontram problemas temporários que podem levar a falhas temporárias de serviços. Quando isso ocorre, os projetos do Apps Script que interagem com esses serviços podem não funcionar como esperado.

É possível verificar se há uma Google Workspace falha no serviço consultando o Google Workspace Painel de status. Se houver uma interrupção, você precisará aguardar até que ela seja resolvida ou buscar ajuda adicional na Google Workspace Central de Ajuda ou na documentação de Google Workspace Problemas conhecidos.

Usar o depurador e pontos de interrupção

Para localizar problemas no seu script, execute-o no modo de depuração. No modo de depuração, um script é pausado quando atinge um ponto de interrupção, que é uma linha destacada no script que pode ser um problema. Quando um script é pausado, ele exibe o valor de cada variável naquele momento, permitindo que você inspecione o trabalho interno de um script sem ter que adicionar muitos log statements.

Adicionar um ponto de interrupção

Novo editor

Para adicionar um ponto de interrupção, passe o cursor sobre o número da linha em que você quer adicionar o ponto de interrupção. À esquerda do número da linha, clique no círculo. A imagem abaixo mostra um exemplo de ponto de interrupção adicionado a um script:

Adicionar um ponto de interrupção

Editor legado

Para adicionar um ponto de interrupção, clique no número da linha em que você quer pausar.

Executar um script no modo de depuração

Novo editor

Para executar o script no modo de depuração, clique em Depurar na parte superior do editor.

Antes de o script executar a linha com o ponto de interrupção, ele pausa e exibe uma tabela de informações de depuração. Use essa tabela para inspecionar dados, como os valores de parâmetros e as informações armazenadas em objetos.

Para controlar como o script é executado, na parte superior do painel Debugger, use os botões "Step in", "Step over" e "Step out". Assim, você consegue executar o script uma linha por vez e inspecionar como os valores mudam ao longo do tempo.

Editor legado

Para executar o script no modo de depuração, clique no ícone de bug (Ícone de bug) na barra de ferramentas. Antes de executar a linha com o ponto de interrupção, o script pausa e exibe uma tabela de informações de depuração.

Essa tabela permite inspecionar os valores dos parâmetros como row e email, bem como as informações armazenadas no objeto data. Observe que a variável rowData ainda não tem um valor atribuído, porque o script pausado antes dessa linha ser executada.

Quando o script é pausado, um conjunto extra de botões é exibido na barra de ferramentas que permite controlar como o script é executado. Usando os botões "quot;step in", "step over" e "step out" você pode executar o script uma linha de cada vez, permitindo que você inspecione como os valores mudam ao longo do tempo.

Problemas com várias Contas do Google

Se você fizer login em várias Contas do Google ao mesmo tempo, poderá ter problemas para acessar seus projetos, complementos e apps da Web do Apps Script. O login múltiplo ou o login em várias Contas do Google de uma só vez não é compatível com o Apps Script, complementos ou apps da Web.

Para corrigir problemas de login múltiplo, tente uma destas soluções:

  • Saia de todas as suas Contas do Google e faça login apenas na conta que tem o projeto do Apps Script, o complemento ou o app da Web que você precisa acessar.
  • Abra uma janela anônima no Google Chrome ou uma janela de navegação privada equivalente e faça login na Conta do Google que tem o projeto do Apps Script, o complemento ou o app da Web que você precisa acessar.

Receber ajuda

Depurar um problema usando as ferramentas e técnicas listadas acima pode resolver uma variedade de problemas, mas pode haver outros problemas que você precisa de ajuda extra para resolvê-los. Consulte nossa página de suporte para ver informações sobre onde fazer perguntas e registrar bugs.