Tratamento de erros e mensagens para conectores da comunidade

Para oferecer uma boa experiência ao usuário, seu código precisa lidar com erros corretamente. Crie mensagens de erro acionáveis que descrevam as etapas corretivas para o usuário resolver o problema.

Neste documento, descrevemos os erros que podem ocorrer, como as mensagens de erro funcionam e como lidar corretamente com problemas no conector.

Observação: para saber mais sobre o tratamento de exceções em JavaScript, consulte a instrução try...catch.

Tipos de erros

Os tipos e as causas dos erros que um usuário pode encontrar ao usar seu conector geralmente se enquadram em uma destas três categorias:

  1. Erros internos do conector
  2. Erros externos do conector
  3. Erros do Data Studio

Os erros internos e externos do conector são tratados pelo desenvolvedor, já que ocorrem devido ao código criado por ele.

Erro interno do conector

Os erros internos ocorrem durante a execução do conector, por exemplo, se ele não puder analisar uma resposta da API durante o processamento de getData(). É preciso prever esses erros e resolvê-los com explicações fáceis de entender, quando aplicável.

Para mais informações sobre como resolver erros internos, consulte o artigo Práticas recomendadas para solucionar erros de conector.

Erro externo do conector

Os erros externos ocorrem após a execução do conector, por exemplo, quando uma solicitação getData() para três campos retorna dados apenas para dois. Embora o comando tenha sido processado, ele não atendeu à solicitação do Data Studio. É recomendável realizar testes completos para evitar esses erros.

Normalmente, é possível corrigir os erros externos do conector ao analisar os detalhes do problema (se disponíveis) e depurar o código para identificar o erro. Para mais informações sobre a depuração do seu conector, consulte Depurar seu código.

Erro do Data Studio

Os erros do Data Studio não são relacionados ao código do seu conector, por exemplo, quando um usuário tenta usar um gráfico de série temporal com uma fonte de dados sem dimensão de data/hora.

Se o erro não estiver diretamente relacionado ao conector, o desenvolvedor não conseguirá resolvê-lo. Para mais ajuda, acesse a Central de Ajuda do Data Studio.

Exibição de mensagens de erro

Exibição de detalhes do erro com base no status de administrador

Quando um conector gera um erro, o Data Studio exibe uma mensagem, dependendo do status de administração do usuário.

  • Se o usuário for um administrador, ele verá todos os detalhes, incluindo a mensagem e o tipo de erro e o stack trace.
  • Se o usuário não for um administrador, ele só verá detalhes se o erro incluir uma mensagem fácil de entender. Para saber mais sobre como mostrar mensagens de erro a usuários que não são administradores, consulte o artigo Exibição de erros ao usuário.

Exibição de erros ao usuário

Por padrão, somente os administradores dos conectores veem os detalhes do erro. Isso impede a divulgação acidental de informações confidenciais, como uma chave de API em um stack trace. Para exibir mensagens de erro a usuários que não são administradores, use newUserError() no serviço do Apps Script no Data Studio.

Exemplo:

try {
      // API request that can be malformed.
      getDataFromAPI();
    } catch (e) {
      DataStudioApp.createCommunityConnector()
          .newUserError()
          .setDebugText('Error fetching data from API. Exception details: ' + e)
          .setText('There was an error communicating with the service. Try again later, or file an issue if this error persists.')
          .throwException();

    }
    

Neste exemplo, setText() define o texto que será exibido para todos os usuários, e setDebugText() determina a mensagem que será mostrada apenas aos usuários administradores.

Práticas recomendadas para tratar erros do conector

Você deve capturar e manipular a maior quantidade possível de erros durante a execução do seu código de conector. Por exemplo, algumas operações comuns que podem causar erros ou um estado indesejável incluem o seguinte:

  • Uma tentativa de busca de URL com falha (erros temporários, tempos limite)
  • falta de dados disponíveis para o período solicitado;
  • impossibilidade de análise ou formatação dos dados da API;
  • revogação dos tokens de autorização.

Tratar erros recuperáveis

Os pontos de execução do conector que podem falhar, mas são recuperáveis, devem ser tratados. Por exemplo, se houver falha nas solicitações de uma API devido a um motivo não fatal (por exemplo, falha de carregamento do servidor), essa API deverá tentar a operação novamente antes de gerar um erro.

Detectar e exibir erros

Os erros não recuperáveis precisam ser detectados e exibidos novamente. É importante que essa reexibição do erro ajude os usuários a entender por que ele ocorreu. Se for possível corrigir o problema, os detalhes sobre a ação corretiva precisarão ser disponibilizados.

Consulte o artigo Exibição de erros ao usuário.

Registrar erros no Stackdriver

Use o Stackdriver para registrar erros e outras mensagens. Isso ajuda a entender as falhas, depurar os problemas e descobrir as exceções não tratadas.

Para saber mais sobre o Stackdriver Error Reporting, como ativar o registro de exceções para um script e como identificar com segurança os usuários para fins de depuração, consulte o artigo Como usar o Stackdriver Logging.

OBSOLETO: usar o prefixo DS_USER: para mensagens de erro seguras

Para exibir mensagens de erro fáceis de entender a usuários que não são administradores, inclua o prefixo DS_USER: junto com o texto. Ele identifica mensagens seguras para esse tipo de usuário e não está incluído na mensagem de erro real.

Os exemplos a seguir mostram um caso em que uma mensagem de erro é exibida aos usuários que não são administradores e outro em que ela só é mostrada aos usuários administradores:

data-studio/errors.gs
Ver no GitHub (em inglês)
// Admin and non-admin users will see the following error.
    try {
      // Code that might fail.
    } catch (e) {
      throw new Error('DS_USER:This will be shown to admin & non-admin.');
    }

    // Only admin users will see the following error.
    try {
      // Code that might fail.
    } catch (e) {
      throw new Error('This message will only be shown to admin users');
    }