Solução de problemas

Mesmo o desenvolvedor mais experiente raramente escreve o 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 a encontrar, entender e depurar erros nos scripts.

Mensagens de erro

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

Erros de sintaxe

Erros de sintaxe são causados por códigos que não seguem a gramática do JavaScript. Esses erros são detectados assim que você tenta salvar o script. Por exemplo, o snippet de código abaixo 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ê recebe o seguinte erro:

) ausente após a lista de argumentos. (linha 4)

Esses tipos de erros geralmente são fáceis de resolver, porque são encontrados imediatamente e geralmente têm causas simples. Não é possível salvar um arquivo que contém erros de sintaxe, o que significa que apenas o 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 for executado. Por exemplo, o código abaixo 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 "joão" 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 que você está transmitindo para uma função não são escritos no código, mas são extraídos de uma planilha, formulário ou outra fonte de dados externa. O uso das 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 invocado muitas vezes: <nome da ação>

Esse erro indica que você excedeu a cota diária de uma determinada ação. Por exemplo, talvez você encontre esse erro se enviar muitos e-mails em um único dia. As cotas são definidas em níveis diferentes para contas de consumidor, de domínio e premium e estão sujeitas a alterações a qualquer momento sem aviso prévio do Google. Confira 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 causas possíveis 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 script que não tem uma mensagem de erro correspondente. Tente depurar o script e veja se você consegue 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 Bugs. Antes de informar um novo bug, pesquise para ver se ele já foi informado por outras pessoas.

É necessária autorização 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 scripts 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 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 é mostrado.

Para autorizar o script, abra o Editor de script e execute qualquer função. O prompt de autorização vai aparecer para que você possa autorizar o projeto do script. Se o script tiver novos serviços não autorizados, será necessário autorizar o script novamente.

Esse erro geralmente é causado por gatilhos que são acionados antes que o usuário os autorize. 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 novamente. Se um acionador continuar disparando e causando esse erro, remova seus acionadores:

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

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

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

Os administradores de Google Workspace domínios podem desativar a API 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 usem os 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 da desativação da API Drive pelo administrador.

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 for instalado pelo administrador para alguns ou todos os usuários no domínio, o script funcionará para esses usuários mesmo se a API Drive estiver desativada no domínio.

O script não tem permissão para receber 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 problema, 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 e parâmetro do evento.

  • Em AuthMode.FULL, considere usar 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 recebeu 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á ausente, mesmo que a biblioteca esteja listada como uma dependência do script. O motivo pode ser que muitas pessoas estão acessando a biblioteca ao mesmo tempo. Para evitar esse erro, tente uma das seguintes soluções:

  • Copie e cole o código da biblioteca no 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 da biblioteca, clique em Mais > Abrir em uma nova guia. A biblioteca ausente exibe uma mensagem de erro. Depois de encontrar a biblioteca que precisa ser atualizada, faça uma das seguintes ações:
  • O script de uma biblioteca que seu script usa 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 existente.
    • Atualize a biblioteca para usar uma versão diferente. Consulte Atualizar uma biblioteca.
    • Remova a biblioteca do projeto e do código do script. 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, significa que 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. No entanto, quando você usa o serviço avançado do Chat, é necessário adicionar manualmente os escopos de autorização que o script usa ao arquivo de manifesto do projeto do Apps Script. Consulte Como definir escopos explícitos.

Para resolver o erro, adicione os escopos de autorização apropriados 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"
]

As chamadas do UrlFetch para <URL> não são permitidas pelo administrador

Os administradores do Google Workspace podem ativar uma lista de permissões no Admin Console para controlar quais domínios externos você pode acessar 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 geram 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 os esperados. Estas são algumas estratégias para lidar com essas situações e investigar mais a fundo um script que não está sendo executado da maneira esperada.

Logging

Durante a depuração, muitas vezes é útil registrar informações conforme um projeto de 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 Logger e console mais básicos, que estão integrados ao editor do Apps Script.

Consulte o Guia de geração de registros 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 Google Cloud Error Reporting. Esse serviço permite pesquisar e filtrar mensagens de exceção criadas pelo projeto de script.

Para acessar o Error Reporting, consulte Ver os registros e os relatórios de erros do Cloud 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 podem ajudar a entender quais ações o script executou.

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

Verificar o status de serviço do Apps Script

Embora raros, às vezes serviços específicos do Google Workspace (como o Gmail ou o Drive) encontram problemas temporários que podem levar a interrupções no serviço. 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 interrupção do 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 os 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 que você destacou no script e que pode ter um problema. Quando um script é pausado, ele mostra o valor de cada variável naquele momento, permitindo inspecionar 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 à qual 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 um 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 Debug 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. É possível usar essa tabela para inspecionar dados como os valores dos parâmetros e as informações armazenadas em objetos.

Para controlar como o script é executado, na parte de cima do painel do depurador, use os botões "Step in", "Step over" e "Step out". Elas permitem executar o script uma linha por vez e inspecionar como os valores mudam ao longo do tempo.

Problemas com várias Contas do Google

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

  • Se você abrir o editor do Apps Script enquanto tiver feito login em mais de uma conta, o Google solicitará que você escolha a conta que quer usar.

  • Se você abrir um app da Web ou um complemento e tiver problemas de login múltiplo, tente uma destas soluções:

    • Saia de todas as suas Contas do Google e faça login apenas na 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 o 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 uma variedade de problemas, mas pode haver problemas que exigem ajuda extra para serem resolvidos. Consulte nossa página de suporte para informações sobre onde fazer perguntas e informar bugs.