Solução de problemas

Mesmo os desenvolvedores mais experientes raramente escrevem código corretamente na primeira tentativa, o que torna a solução de problemas uma parte importante do processo de desenvolvimento. Nesta seção, vamos abordar algumas técnicas que podem ajudar você a encontrar, entender e depurar erros nos seus scripts.

Mensagens de erro

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

Erros de sintaxe

Os erros de sintaxe são causados pela escrita de código que não segue a gramática do JavaScript, e 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('[email protected]',                     'Data in row ' + rowNumber,                     rowData); }

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

Falta um ")" após a lista de argumentos. (linha 4)

Esses tipos de erros geralmente são simples de resolver, já que são encontrados imediatamente e costumam ter causas simples. Não é possível salvar um arquivo que contenha erros de sintaxe. Isso significa que apenas código válido é salvo no 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 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 "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 seguinte erro é gerado ao executar o script:

E-mail inválido: john (linha 5)

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

Erros comuns

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

Serviço chamado 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 aparecer se você enviar muitos e-mails em um único dia. As cotas são definidas em níveis diferentes para contas pessoais, de domínio e premium e estão sujeitas a mudanças a qualquer momento sem aviso prévio do Google. Consulte os limites de cota para várias ações na documentação de cota do Apps Script.

Servidor indisponível. ou Ocorreu um erro no servidor. Tente novamente.

Há algumas possíveis causas para esses erros:

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

É necessário ter autorização para executar esta 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 é apresentada ao usuário. No entanto, quando um script é executado por um gatilho, 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 é mostrado.

Para autorizar o script, abra o editor de scripts e execute qualquer função. O prompt de autorização aparece para que você possa autorizar o projeto de script. Se o script tiver novos serviços não autorizados, você precisará autorizá-lo novamente.

Esse erro geralmente é causado por gatilhos que são acionados antes de o usuário autorizar. Se você não tiver acesso ao projeto de script (porque o erro está ocorrendo em um complemento que você usa, por exemplo), geralmente é possível autorizar o script usando o complemento de novo. Se um gatilho continuar sendo acionado e causando esse erro, você poderá remover seus gatilhos fazendo o seguinte:

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

Você também pode remover acionadores de complementos problemáticos desinstalando o complemento.

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

Os administradores de domínios Google Workspace podem desativar a API Drive no 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 usem complementos do Apps Script que usam o serviço do Drive ou o Advanced Drive Service, mesmo que o script tenha sido autorizado antes de o administrador desativar a API Drive.

No entanto, se um complemento ou web app que usa o serviço do Drive for publicado para instalação em todo o domínio e for instalado pelo administrador para alguns ou todos os usuários no domínio, as funções de script vão funcionar para esses usuários mesmo que a API Drive esteja desativada no domínio.

O script não tem permissão para acessar 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 resulta de uma chamada para Session.getActiveUser(). Também pode resultar de uma chamada para Session.getEffectiveUser() se o script estiver sendo executado em um modo de autorização diferente de AuthMode.FULL. Se esse aviso for sinalizado, as chamadas subsequentes para User.getEmail() vão retornar apenas "".

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

  • Em AuthMode.FULL, considere usar Session.getEffectiveUser() em vez disso.
  • 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 cliente do Google Workspace que começou a receber esse aviso de um gatilho instalável, verifique se o gatilho está sendo executado como um usuário na sua organização.

A biblioteca está ausente

Se você adicionar uma biblioteca popular ao script, poderá receber uma mensagem de erro informando que ela está faltando, mesmo que a biblioteca esteja listada como uma dependência do script. Isso pode acontecer quando muitas pessoas acessam a biblioteca ao mesmo tempo. Para evitar esse erro, tente uma das seguintes soluções:

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

Ocorreu um erro porque uma versão da biblioteca ou da implantação está ausente. Código do erro Not_Found

Essa mensagem de erro indica uma das seguintes situações:

  • A versão implantada do script foi excluída. Para atualizar a versão implantada do script, consulte Editar uma implantação com versão.
  • A versão de uma biblioteca usada pelo script foi excluída. Para verificar qual biblioteca está faltando, ao lado do nome dela, clique em Mais > Abrir em nova guia. A biblioteca ausente mostra uma mensagem de erro. Depois de encontrar a biblioteca que você precisa atualizar, faça uma das seguintes ações:
  • O script de uma biblioteca usada pelo seu script inclui outra biblioteca que usa uma versão excluída. Escolha uma destas opções:
    • Se você tiver acesso de edição à biblioteca usada pelo script, atualize a biblioteca secundária nesse script para uma versão atual.
    • Atualize a biblioteca para usar uma versão diferente. Consulte Atualizar uma biblioteca.
    • Remova a biblioteca do projeto de script e do código. Consulte Remover uma biblioteca.

Erro 400: invalid_scope ao chamar a API Google Chat com o serviço avançado

Se você encontrar Error 400: invalid_scope com a mensagem de erro Some requested scopes cannot be shown, isso significa que você não especificou nenhum escopo de autorização no arquivo appsscript.json do projeto do Apps Script. Na maioria dos casos, o Apps Script determina automaticamente quais escopos um script precisa, mas, ao usar o serviço avançado do Chat, é necessário adicionar manualmente ao arquivo de manifesto do projeto do Apps Script os escopos de autorização que o script usa. Consulte Definir escopos explícitos.

Para resolver o erro, adicione os escopos de autorização adequados ao arquivo appsscript.json do projeto do Apps Script como parte da matriz oauthScopes. Por exemplo, para chamar o método spaces.messages.create, adicione o seguinte:

"oauthScopes": [   "https://www.googleapis.com/auth/chat.messages.create" ]

Chamadas de UrlFetch para <URL> não são permitidas pelo seu administrador

Os administradores do Google Workspace podem ativar uma lista de permissões no Admin Console para controlar quais domínios externos podem ser acessados pelo Apps Script.

Para resolver o erro, entre em contato com o administrador para que ele adicione o URL à lista de permissões.

Depuração

Nem todos os erros causam a exibição de uma mensagem de erro. Pode haver um erro mais sutil em que o código está tecnicamente correto e pode ser executado, mas os resultados não são o que você espera. Confira 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, muitas vezes é útil registrar informações enquanto um projeto de script é executado. O Google Apps Script tem dois métodos para registrar informações: o serviço do Cloud Logging e os serviços de console e Logger mais básicos, que são integrados ao editor do Apps Script.

Consulte o guia do Logging para 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 Error Reporting do Google Cloud. Com esse serviço, você pode pesquisar e filtrar mensagens de exceção criadas pelo projeto de script.

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

Execuções

Sempre que você executa um script, o Apps Script faz um registro da execução, incluindo os registros do Cloud. Esses registros ajudam a entender quais ações o script realizou.

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

Como verificar o status do serviço do Apps Script

Embora raros, às vezes serviços específicos do Google Workspace (como Gmail ou Drive) enfrentam problemas temporários que podem levar a interrupções. Quando isso acontece, os projetos do Apps Script que interagem com esses serviços podem não funcionar como esperado.

Para verificar se há uma falha temporária no serviço do Google Workspace, acesse o Painel de status do Google Workspace. Se houver uma interrupção, aguarde a resolução ou procure mais ajuda na Central de Ajuda do Google Workspace ou na documentação de Problemas conhecidos do Google Workspace.

Usar o depurador e pontos de interrupção

Para localizar problemas no script, execute-o no modo de depuração. Quando executado no modo de depuração, um script é pausado quando atinge um ponto de interrupção, que é uma linha destacada no script que você acha que pode ter um problema. Quando um script é pausado, ele mostra o valor de cada variável naquele momento, permitindo que você inspecione o funcionamento interno de um script sem precisar adicionar muitas instruções de registro.

Adicionar um ponto de interrupção

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

Executar um script no modo de depuração

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

Antes de executar a linha com o ponto de interrupção, o script pausa e mostra 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 de cima do painel do Debugger, use os botões "Entrar", "Pular" e "Sair". Com eles, é possível executar o script uma linha por vez e inspecionar como os valores mudam ao longo do tempo.

Erro: o código-fonte da linha atual não está disponível

O código-fonte da linha atual não está disponível

Esse erro aparece quando um arquivo de depuração ativo não está disponível. O Google Apps Script não é compatível com a exibição de scripts JavaScript (JS) gerados dinamicamente no editor de scripts, como os gerados usando eval() e new Function(). Esses scripts são criados e executados no mecanismo V8, mas não são representados como arquivos independentes no editor. Se você entrar nesses scripts, vai encontrar esse erro.

Por exemplo, considere o seguinte código:

function myFunction() {   eval('a=2'); }

Quando eval() é invocado, o argumento dele é tratado como código JS e executado como um script criado dinamicamente no mecanismo V8. Se você entrar em eval(), esse erro vai aparecer. Se o script incluir um comentário //# sourceURL, o nome dele será mostrado na pilha de chamadas. Caso contrário, ela vai aparecer como uma entrada sem nome.

Apesar da mensagem de erro, a sessão de depuração permanece ativa, e a execução pode continuar. Para continuar, avance para a etapa de entrada, saída ou retomada da execução. No entanto, esse erro continua aparecendo enquanto a execução permanecer no escopo do script dinâmico. Depois que a execução sai do script dinâmico, a depuração continua sem esse erro.

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 complementos e apps da Web. Não é possível fazer login múltiplo, ou seja, em várias Contas do Google ao mesmo tempo, em projetos, complementos ou apps da Web do Apps Script.

  • Se você abrir o editor do Apps Script enquanto estiver conectado a mais de uma conta, o Google vai pedir para você escolher a conta que quer usar.

  • Se você abrir um web app ou complemento e tiver problemas com o login múltiplo, tente uma das seguintes soluções:

    • Saia de todas as Contas do Google e faça login apenas na conta que tem o complemento ou app da Web que você quer 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 complemento ou app da Web que você quer acessar.

Receber ajuda

A depuração de um problema usando as ferramentas e técnicas listadas acima pode resolver vários problemas, mas talvez você encontre questões que exijam ajuda extra para serem resolvidas. Consulte nossa página de suporte para saber onde fazer perguntas e enviar bugs.