Resolução de problemas da API Looker

Esta página tem procedimentos de resolução de problemas para os seguintes problemas que pode encontrar com a API Looker:

Não é possível estabelecer ligação ao ponto final da API

Se não conseguir aceder a um ponto final da API:

Valide as suas credenciais da API

Se o seu ponto final da API Looker não estiver acessível, verifique primeiro se as suas credenciais da API estão corretas. Para ver as suas credenciais da API:

  1. No Looker, aceda ao painel Administração selecionando a opção Administração no painel de navegação do lado esquerdo.
  2. No painel esquerdo da página Administração, desloque a página para baixo e clique em Utilizadores.
  3. Pesquise o seu nome de utilizador na lista de utilizadores e clique nele para editar a sua página de utilizador.
  4. Clique em Editar chaves da API. Pode ver o ID de cliente e clicar no ícone de olho para ver o segredo do cliente de cada chave da API que configurou. Verifique se as credenciais da API correspondem às credenciais que está a usar no script.

Valide o URL da API

Outro problema comum ao aceder a um ponto final da API é um URL de anfitrião da API incorreto. A maioria das instâncias do Looker usa o URL predefinido para a API. No entanto, as instalações do Looker que usam um caminho da API alternativo ou as instalações do Looker localizadas atrás de um equilibrador de carga (por exemplo, uma configuração de cluster) ou qualquer outro proxy podem não usar o URL predefinido. Se for este o caso, o URL do anfitrião da API tem de indicar o nome de anfitrião e a porta da API direcionada ao utilizador.

Os administradores do Looker podem ver o URL do anfitrião da API nas definições de administrador da API (descritas mais detalhadamente na página de documentação Definições de administrador – API). Para ver o URL do anfitrião da API:

  1. Clique no ícone do menu principal do Looker e selecione Administração para abrir o painel Administração.
  2. Clique em API no painel Administração.

  3. Veja o URL do anfitrião da API.

    Se o campo URL do anfitrião da API estiver em branco, a sua instância do Looker usa o formato predefinido, que é:

    https://<instance_name>.cloud.looker.com:<port>

Para testar o URL do anfitrião da API:

  1. Abra um navegador e, em seguida, abra a consola do navegador.

  2. Introduza o URL do anfitrião da API seguido de /alive. Por exemplo, se o seu URL do anfitrião da API for https://company.cloud.looker.com, introduza:

    https://company.cloud.looker.com/alive

    Se o campo URL do anfitrião da API estiver em branco, use o URL da API predefinido. Por exemplo, para instâncias alojadas no Google Cloud, no Microsoft Azure e instâncias alojadas nos Amazon Web Services (AWS) que foram criadas a 07/07/2020 ou após essa data, o caminho da API Looker predefinido usa a porta 443:

    https://<instance_name>.cloud.looker.com:443/alive

    Para instâncias alojadas na AWS criadas antes de 07/07/2020, o caminho da API Looker predefinido usa a porta 19999:

    https://<instance_name>.cloud.looker.com:19999/alive

Se o URL do anfitrião da API estiver correto, este URL resulta numa página Web em branco e não numa página de erro.

Também pode verificar se acedeu à API consultando a resposta da rede na consola do navegador. A resposta da rede deve ser 200.

Se estas verificações falharem, o problema pode ser que esteja a chamar a API incorretamente ou que tenha outros erros no seu código. Verifique as chamadas API e o código no seu script. Se estiverem corretas, consulte a secção seguinte sobre a validação da porta.

Valide a porta da API

Se as verificações anteriores falharem e tiver uma implementação do Looker alojada pelo cliente, é possível que a porta da API tenha de ser aberta na infraestrutura de rede.

A porta da API deve ser encaminhada para o servidor do Looker. Para implementações do Looker alojadas pelo cliente, peça ao administrador de rede para verificar as definições da porta da API. A porta da API é mais comummente 443 ou 19999. A porta da API deve ter as mesmas definições de configuração que a porta da instância do Looker (9999 por predefinição). O administrador de rede deve verificar se as seguintes definições são iguais para a porta da API e para a porta da instância do Looker:

  • Proxies
  • Balanceadores de carga
  • Firewalls

Valide o URL da chamada da API

Verifique se está a usar o URL correto para a chamada da API. O formato de um URL de ponto final da API é:

<API Host URL>/api/<API version>/<API call>

Se estiver a usar o URL do anfitrião da API predefinido, o formato de um URL do ponto final da API é:

https://<instance_name>:<port>/api/<API version>/<API call>

Pode obter o formato do URL para os pontos finais da API no Explorador de APIs ou na documentação de referência da API.

Por exemplo, a referência da API 4.0 indica o seguinte caminho relativo para o ponto final Get All Running Queries:

/api/4.0/running_queries

Por conseguinte, o URL completo do ponto final da API para o ponto final Get All Running Queries na instância do Looker docsexamples.dev.looker.com seria o seguinte:

https://docsexamples.dev.looker.com:443/api/4.0/running_queries

O resultado da API é texto sem sentido

Se a API devolver uma resposta de texto confuso, é provável que esteja a ver o conteúdo binário de um ficheiro PDF, PNG ou JPG. Algumas bibliotecas REST HTTP partem do princípio de que as respostas da API são ficheiros de texto e, por isso, outros tipos de ficheiros são apresentados como texto binário.

Neste caso, tem de se certificar de que a sua biblioteca HTTP REST processa a resposta da API como dados binários e não como texto. Em alguns casos, isto pode significar definir uma flag na chamada API para indicar à biblioteca HTTP REST que se trata de um resultado binário ou pode significar processar o resultado de uma forma especial, como um fluxo de bytes ou uma matriz de bytes, em vez de atribuir o resultado a uma variável de string.

As chamadas da API não respondem

Se conseguir abrir o API Explorer, mas as suas chamadas API não responderem, verifique se a definição do URL do anfitrião da API da sua instância do Looker está definida corretamente. Os administradores do Looker podem ver o URL do anfitrião da API nas definições de administrador da API do Looker (descritas na página de documentação Definições de administrador – API).

Erros de codificação inválida

Se receber um erro de codificação ao tentar fazer uma chamada API, pode ter de definir o Content-Type adequado no cabeçalho durante o pedido. As normas do protocolo HTTP exigem que qualquer pedido POST, PUT ou PATCH contenha um cabeçalho Content-Type. Uma vez que a API Looker usa JSON em todo o lado, o cabeçalho Content-Type deve ser definido como application/json.

Tenha em atenção que a utilização de um SDK Looker resolve automaticamente esta questão por si.

Erros de método não encontrado

Se receber um erro Method Not Found, como method not found: all_looks(), a primeira coisa a verificar é a versão da API. Existem várias chamadas API que são novas na API 4.0 ou que foram removidas na API 4.0. Consulte o anúncio Looker API 4.0 disponível de forma geral para ver a lista de atualizações.

Erros de pedido inválido (400)

Um erro 400 Bad Request indica que os dados facultados numa chamada API são irreconhecíveis. Muitas vezes, o problema é um JSON danificado ou inválido, talvez um erro de análise. Na maioria dos casos, os erros 400 já passaram pela autenticação, pelo que a mensagem de resposta de erro fornece informações mais específicas sobre o erro.

Erros não autorizados (401)

Um erro 401 Unauthorized numa chamada da API significa que a chamada da API não está devidamente autenticada. Para mais detalhes de resolução de problemas, consulte o artigo Como posso resolver problemas de erros 401? Artigo da comunidade.

Erros de proibição (403)

A API Looker não devolve erros 403 sempre que um utilizador tenta aceder a um objeto LookML ou a outro conteúdo para o qual não tem autorização. A devolução de um erro 403 em vez de um erro 404 pode, em alguns casos, verificar a existência de um determinado objeto do LookML, painel de controlo ou Explore quando o proprietário pode preferir que isto não seja conhecido. Para evitar isto, o Looker devolve um erro 404 nestes casos e o erro que acompanha a IU do Looker indica: "Não foi possível encontrar a página que pediu. Não existe ou não tem autorização para vê-la."

Consoante o ambiente no qual a sua instância do Looker está alojada e a configuração da sua instância do Looker, o número da porta e o URL associado onde a API pode ser acedida podem ser diferentes. Quando usa um número de porta incorreto, pode ver um erro 403. Por exemplo, se a sua instância do Looker estiver configurada com a porta da API predefinida 443, a ligação a https://mycompany.looker.com/api/4.0/login, em vez de https://mycompany.looker.com:443/api/4.0/login, devolve um erro 403. Para instâncias alojadas pelo cliente, pode ler mais acerca das opções de arranque do Looker, onde pode definir a porta da API.

Isto também pode acontecer quando está a usar uma versão desatualizada do gem do SDK Ruby. Certifique-se de que mantém essas pedras preciosas atualizadas. Pode verificar em https://rubygems.org/gems/looker-sdk.

Isto também pode acontecer quando não inclui a parte /api/<version number>/ do URL. Neste caso, se um utilizador tentar estabelecer ligação a https://mycompany.looker.com:443/login, é apresentada uma resposta 403.

Erros Não encontrado (404)

Um erro 404 Not Found é o erro predefinido se algo correr mal, normalmente com as autorizações. A mensagem de resposta para um erro 404 fornece informações mínimas, se existirem. Isto é intencional, uma vez que os erros 404 são apresentados a pessoas com credenciais de início de sessão incorretas ou autorizações insuficientes. O Looker não quer fornecer informações específicas em mensagens de resposta 404, uma vez que estas informações podem ser usadas para mapear a "superfície de ataque" da API Looker.

Se as tentativas de início de sessão na API estiverem a devolver erros 404, é muito provável que o ID de cliente da API ou o segredo do cliente não seja válido (consulte a secção Valide as suas credenciais da API anteriormente nesta página). O ponto final REST de início de sessão da API é o seguinte:

  • https://<your-looker-hostname>:<port>/api/4.0/login

Se estiver a usar uma API Swagger codegen ou um SDK Looker, certifique-se de que o valor base_url está correto:

  • Para um cliente de geração de código Swagger, o base_url deve ser o seguinte:

    • https://<your-looker-hostname>:<port>/api/4.0/

  • Para implementações do SDK Looker que usam um looker.ini, o valor de api_version deve ser 4.0 e o valor de base_url deve ser igual ao URL da API da sua instância do Looker no formato https://<your-looker-hostname>:<port>. Segue-se um exemplo de ficheiro looker.ini:

    # api_version should be 4.0
api_version=4.0
base_url=https://<your-looker-hostname>:<port>

Também pode receber um erro 404 depois de iniciar sessão. Se tiver sessão iniciada e receber um erro 404, significa que não tem autorizações para o comando API que acabou de chamar.

Erros de método não permitido (405)

Um erro 405 Method Not Allowed indica que o servidor conhece o método de pedido, mas o recurso de destino não suporta este método.

O servidor tem de gerar um campo de cabeçalho Allow numa resposta com o código de estado 405. O campo tem de conter uma lista de métodos suportados pelo recurso de destino.

Por exemplo, pode encontrar esta situação no Looker se tentar usar o ponto final update_dashboard() para atualizar os metadados de um painel de controlo do LookML. Não é possível alterar o parâmetro id de um painel de controlo do LookML através da API Looker, pelo que ocorreria um erro 405.

Erros de conflito (409)

O código de estado de resposta 409 Conflict indica um conflito de pedido com o estado atual do recurso de destino.

É mais provável que ocorram conflitos em resposta a um pedido PUT. Um exemplo comum não relacionado com o Looker deste erro ocorre quando carrega um ficheiro mais antigo do que o existente no servidor, o que resulta num conflito de controlo de versões.

Pode encontrar este erro no Looker quando tentar consultar um novo ramo do Git através da API ou quando usar pontos finais como create_group() ou create_dashboard(). Nestes casos, verifique se o objeto que está a tentar criar já existe.

Erros de validação (422)

Os erros de validação ocorrem quando algo no pedido falhou nas verificações de dados realizadas. O pedido tem um ou mais dos seguintes tipos de erros (a resposta de erro especifica os erros exatos):

  • Campos em falta: existe um parâmetro obrigatório que não foi fornecido (a resposta de erro indica o campo em falta).
  • Inválido: o valor fornecido não corresponde a um valor existente ou não está no formato correto. Por exemplo, se tentar criar um relatório detalhado e o ID da consulta que fornecer na chamada da API não corresponder a uma consulta existente, recebe um erro de validação.
  • Já existe: a chamada API está a tentar criar um objeto com um ID ou um nome que já está presente na sua instância do Looker. Por exemplo, os nomes das associações de bases de dados têm de ser exclusivos. Se tentar criar uma nova ligação à base de dados que use o nome de uma ligação existente, recebe um erro de validação com o código already_exists.

Consulte a mensagem de resposta de erro para ver detalhes sobre os campos que podem estar em falta ou ser obrigatórios, ou os campos que podem ter valores inválidos. A mensagem de resposta fornece todos os erros de validação em simultâneo. Assim, se tiver campos em falta e campos incorretos, a resposta de erro apresenta todos os problemas com a chamada da API.

Segue-se um exemplo de resposta:

{
  "message": "Validation Failed",
  "errors": [
    {
    "field": "dialect",
    "code": "missing_field",
    "message": "This field is required.",
    "documentation_url": "http://docs.looker.com/"
    },
    {
    "field": "db_timezone",
    "code": "invalid",
    "message": "Must specify a database timezone when user timezones are activated.",
    "documentation_url": "http://docs.looker.com/"
    }
  ],
    ...

Neste caso, a chamada da API não tinha o campo dialect obrigatório e também tinha um valor inválido no campo db_timezone.

Erros "Demasiados pedidos" (429)

O código de estado de resposta 429 Too Many Requests indica que o utilizador enviou demasiados pedidos num determinado período ("limite de taxa"). Pode ler mais acerca das políticas de limitação de taxa do Looker na publicação da comunidade do Looker Existe um limite para o número de pedidos API que pode enviar em simultâneo?

Erros internos do servidor (500)

O código de resposta 500 Internal Server Error indica que o servidor encontrou uma condição inesperada que o impediu de satisfazer o pedido.

Esta resposta de erro é uma resposta genérica "catch-all". Normalmente, isto indica que o servidor não consegue encontrar um código de erro 5xx mais específico para devolver na resposta. Qualquer resposta 500 do Looker é inesperada. Por isso, se estiver a ver este erro de forma consistente enquanto tenta interagir com o Looker, recomendamos que abra um pedido de apoio técnico.