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.

Este documento descreve os erros que podem ocorrer, como as mensagens de erro funcionam e como lidar corretamente com os erros do 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 Looker Studio

Os erros internos e externos do conector são solucionados 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 tratar erros internos, consulte o artigo Práticas recomendadas para tratar 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 conector tenha sido executado, ele não atendeu à solicitação do Looker Studio. É recomendável realizar testes completos para evitar esses erros.

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

Erro no Looker Studio

Os erros do Looker Studio não estã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 Looker 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 Looker Studio mostra uma mensagem dependendo do status de administrador do usuário.

• Se o usuário for um administrador, ele verá todos os detalhes, incluindo a mensagem e o tipo de erro, bem como o rastreamento de pilha.
• Se o usuário não for um administrador, ele só verá detalhes se o erro incluir uma mensagem amigável. 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.

Importante :implemente isAdminUser() para identificar os administradores. Assim, cada usuário do conector mostra o nível de detalhes adequado.

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 mostrar mensagens de erro a usuários que não são administradores, use newUserError() no serviço Apps Script do Looker Studio.

Exemplos

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 solucionar 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:

• uma tentativa de busca de URL com falha (erros temporários, tempos limite etc.);
• 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 deverã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 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

Atenção: o uso desse recurso será suspenso e removido em junho de 2019. Migre para newUserError(). Consulte o artigo Exibição de erros ao usuário.

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 incluem um caso em que uma mensagem de erro é exibida aos usuários que não são administradores e outro em que somente os usuários administradores veem a mensagem:

data-studio/errors.gs

Ver no GitHub

// 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');
}

Observação: o prefixo DS_USER: só identifica mensagens seguras para usuários que não são administradores e não está incluído na mensagem de erro real exibida aos usuários.