Solução de problemas

Mesmo o desenvolvedor mais experiente raramente escreve código corretamente na primeira tentativa, tornando 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 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 erro exibidos dessa maneira: erros de sintaxe e erros de tempo de execução.

Erros de sintaxe

Os erros de sintaxe são causados por código que não segue a gramática 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('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:

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

Esses tipos de erros geralmente são simples de resolver, porque são encontrados imediatamente e normalmente têm causas simples. Não é possível salvar um arquivo com erros de sintaxe, o que significa que apenas um 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 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: joao (linha 5)

O que torna esses erros mais difíceis de solucionar é que, muitas vezes, os dados que você está transmitindo para uma função não são gravados no código, mas 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

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, talvez você encontre esse erro se enviar muitos e-mails em um único dia. As cotas são definidas em diferentes níveis para contas de consumidor, domínio e Google Premier e estão sujeitas a alterações a qualquer momento sem aviso prévio do Google. Você pode ver os limites de cota para várias ações na documentação de cotas do Apps Script.

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

Existem algumas causas possíveis para esses erros:

  • um servidor ou sistema do Google estiver 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 tente isolar o problema.
  • Há um bug no Google Apps Script que está causando esse erro. Para instruções sobre como pesquisar e registrar relatórios de bugs, consulte Bugs. Antes de informar um novo bug, pesquise se outras pessoas já relataram o problema.

É 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 por meio 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 script e execute qualquer função. A solicitação de autorização é exibida para que você autorize o projeto de script. Se o script tiver novos serviços não autorizados, será necessário autorizá-lo novamente.

Esse erro geralmente é causado por acionadores que são disparados antes da autorização do usuário. Se você não tiver acesso ao projeto de script (porque o erro está ocorrendo em um complemento usado, por exemplo), será possível autorizar o script usando o complemento novamente. Se um acionador continuar a ser disparado e causar esse erro, remova-os fazendo o seguinte:

  1. À esquerda do projeto do Apps Script, clique em Gatilhos .
  2. À direita do acionador 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 aplicativos de terceiros do Drive

Os administradores de Google Workspace domínios podem desativar a API Drive no próprio 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 usar os complementos do Apps Script que utilizam o serviço do Drive ou o serviço avançado do Drive, mesmo que o script tenha sido autorizado antes do administrador desativar a API 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 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(). Isso 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() retornarão apenas "".

Há várias maneiras de solucionar 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 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 não existe

Se você adicionar uma biblioteca conhecida 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 estejam 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 da sua conta. Atualize a dependência no script original para a nova biblioteca, e não para a pública.

Ocorreu um erro devido a uma versão da biblioteca ou da implantação 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 seu script, consulte Editar uma implantação com controle de versão.
  • A versão de uma biblioteca usada pelo script foi excluída. Para conferir qual biblioteca está faltando, ao lado do nome dela, clique em Mais > Abrir em uma nova guia. A biblioteca ausente fornece uma mensagem de erro. Depois de encontrar a biblioteca que você precisa atualizar, realize uma das seguintes ações:
  • O script de uma biblioteca usada por seu script inclui outra biblioteca que usa uma versão excluída. Escolha uma das seguintes opções:
    • Se você tiver acesso para editar a biblioteca usada pelo seu 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.

Error 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 você não especificou escopos 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"
]

Depuração

Nem todos os erros fazem com que uma mensagem de erro seja exibida. 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.

Geração de registros

Na depuração, geralmente é útil registrar informações durante a execução de um projeto de script. 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 ambiente 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

Toda vez que você executa um script, o Apps Script faz um registro da execução, incluindo os registros do Cloud. Esses registros podem ajudar você a entender quais ações o script executou.

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

Verificar o status de serviço do Apps Script

Embora raros, às vezes específicos do Google Workspace (como Gmail ou Drive) encontram problemas temporários que podem levar a interrupções do serviço. Quando isso ocorre, 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 uma interrupção do serviço estiver sendo ocorrendo, aguarde até que ela seja resolvida 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 ao atingir um ponto de interrupção, que é uma linha destacada no script e que você acha que pode ter um problema. Quando um script é pausado, ele exibe o valor de cada variável nesse momento, permitindo que você inspecione o funcionamento interno de um script sem precisar adicionar muitos log statements.

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 de parâmetros e as informações armazenadas em objetos.

Para controlar como o script é executado, na parte superior do painel do Debugger, use os botões "Entrar", "Pular" e "Sair". Eles 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 estiver conectado em mais de uma conta, o Google solicitará que você escolha a conta que quer usar.

  • Se você abrir um app da Web 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 naquela que tem o complemento ou o 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

Depurar um problema usando as ferramentas e técnicas listadas acima pode resolver uma variedade de problemas, mas pode haver questões que exigem alguma ajuda extra para serem resolvidas. Consulte nossa página de suporte para informações sobre onde fazer perguntas e informar bugs.