Solução de problemas da API Looker

Nesta página, você verá os procedimentos para os seguintes problemas que pode encontrar com a API Looker:

O endpoint da API não está acessível

Se você não conseguir acessar um endpoint da API:

Verificar as credenciais da API

Se o endpoint da API Looker não for acessível, primeiro verifique se as credenciais da API estão corretas. Para ver suas credenciais de API:

  1. No Looker, acesse o painel Administrador selecionando a opção Administrador no painel de navegação à esquerda.
  2. No painel esquerdo da página Administrador, role para baixo e clique em Usuários.
  3. Procure seu nome de usuário na lista de usuários e clique nele para editar a página.
  4. Clique em Editar chaves de API. Você pode ver o ID do cliente e clicar no ícone de olho para ver o Segredo do cliente em cada chave de API configurada. Verifique se as credenciais da API correspondem às credenciais que você usa no seu script.

Verificar o URL da API

Outro problema comum em alcançar um endpoint de API é um URL de host de API incorreto. A maioria das instâncias do Looker usa o URL padrão da API. No entanto, as instalações do Looker que usam um caminho de API alternativo ou instalações do Looker localizadas por trás de um balanceador de carga (por exemplo, uma configuração de cluster) ou qualquer outro proxy podem não usar o URL padrão. Nesse caso, o URL do host da API deve indicar a porta e o nome do host da API direcionado ao usuário.

Os administradores do Looker podem ver o URL do host da API nas configurações de administrador da API, descritas em mais detalhes na página de documentação Configurações do administrador - API. Para ver o URL do host de API:

  1. Acesse o painel Administrador selecionando a opção Administrador no painel de navegação à esquerda.
  2. Clique em API no painel Administrador.

  3. Veja o URL do host da API.

    Se o campo URL do host da API estiver em branco, a instância do Looker usará o formato padrão, que é:

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

Para testar o URL do host da API:

  1. Abra um navegador no console do navegador. Este artigo do ConcreteCMS.org pode ser útil se você precisar saber como abrir um console para seu navegador.

  2. Digite o URL do host da API seguido de /alive. Por exemplo, se o URL do host da API for https://company.api.looker.com, insira:

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

    Se o campo URL do host da API estiver em branco, use o URL da API padrão. Por exemplo, para instâncias hospedadas no Google Cloud, Microsoft Azure e instâncias hospedadas na Amazon Web Services (AWS) criadas a partir de 07/07/2020, o caminho padrão da API Looker usa a porta 443:

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

    Para instâncias hospedadas na AWS e criadas antes de 7/07/2020, o caminho padrão da API Looker usa a porta 19999:

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

Se o URL do host da API estiver correto, este URL resultará em uma página da Web em branco, não em uma página de erro:

Você também pode verificar se atingiu a API analisando a resposta da rede no console do navegador. A resposta da rede precisa ser 200:

Se essas verificações falharem, o problema pode ser que você está chamando a API incorretamente ou que há outros erros no código. Verifique as chamadas de API e o código no seu script. Se isso acontecer, consulte a próxima seção sobre como verificar a portabilidade.

Verificar a porta da API

Se as verificações acima falharem e você tiver uma implantação do Looker hospedada pelo cliente, é possível que a porta da API precise ser aberta na infraestrutura de rede.

A porta da API precisa encaminhar ao servidor do Looker. Para implantações do Looker hospedadas pelo cliente, peça ao administrador da rede para verificar as configurações de porta da API. A porta de API costuma ser 443 ou 19999. A porta da API precisa ter as mesmas definições de configuração da porta da instância do Looker (9999 por padrão). Seu administrador de rede deve verificar se as seguintes configurações são as mesmas para a porta da API e a porta da instância do Looker:

  • Proxies
  • Balanceadores de carga
  • Firewalls

Verificar o URL de chamada da API

Verifique se você está usando o URL correto para sua chamada de API. O formato de um URL de endpoint da API é:

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

Se você estiver usando o URL do host padrão da API, o formato de um URL do endpoint da API será:

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

É possível ver o formato de URL para endpoints de API no API Explorer, no Portal do desenvolvedor do Looker ou na documentação de Referência da API.

Por exemplo, a Referência da API 4.0 fornece o seguinte caminho relativo para o endpoint "Ver todas as consultas em execução":

Portanto, o URL do endpoint da API completo da instância do Looker docsexamples.dev.looker.com é este:

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

O resultado da API é um texto sem sentido

Se a API retornar uma resposta de texto sem sentido, é provável que você esteja vendo o conteúdo binário de um arquivo PDF, PNG ou JPG. Algumas bibliotecas HTTP HTTP presumem que as respostas da API serão arquivos de texto e outros tipos de arquivos são exibidos como texto binário.

Nesse caso, você precisa ter certeza de que sua biblioteca HTTP REST processa a resposta da API como dados binários, não como texto. Em alguns casos, isso pode significar a definição de uma sinalização na chamada de API para informar à biblioteca REST HTTP que é um resultado binário ou lidar com o resultado de uma maneira especial, como como um stream de bytes ou como uma matriz de bytes, em vez de atribuir o resultado a uma variável de string.

As chamadas de API não respondem

Se você consegue abrir o APIs Explorer, mas as chamadas de API não respondem, verifique se a configuração do URL do host da API da instância do Looker está definida corretamente. Os administradores do Looker podem ver o URL do host da API nas configurações de administrador da API do Looker, conforme descrito na página de documentação Configurações do administrador - API.

Erros de codificação inválidos

Se você receber um erro de codificação ao tentar fazer uma chamada de API, talvez seja necessário definir o Content-Type corretamente no cabeçalho durante a solicitação. Os padrões de protocolo HTTP exigem que qualquer solicitação POST, PUT ou PATCH contenha um cabeçalho Content-Type. Como a API Looker usa JSON, o cabeçalho Content-Type precisa ser definido como application/json.

Use um SDK do Looker (em inglês) para resolver automaticamente esse problema.

Erros de método não encontrados

Se você receber um erro de método não encontrado, como method not found: all_looks(), a primeira coisa a ser verificada é a versão da API. Existem várias chamadas de API novas na API 4.0 ou que foram removidas na API 4.0. Consulte o anúncio API Looker 4.0 com disponibilidade geral para ver a lista de atualizações.

Erros de solicitação inválida (400)

Um erro 400 Bad Request indica que os dados fornecidos na chamada de API são irreconhecíveis. O culpado é muitas vezes inválido ou JSON inválido, talvez um erro de análise. Na maioria dos casos, os erros 400 já passaram na autenticação, então a mensagem de resposta fornecerá informações mais específicas sobre o erro.

Erros proibidos (403)

A API Looker não retorna erros 403 sempre que um usuário tenta acessar um objeto LookML ou outro conteúdo para o qual ele não tem permissão. Retornar um erro 403 em vez de um erro 404 pode, em alguns casos, verificar a existência de um determinado objeto Explorar, painel ou LookML quando o proprietário preferir que isso não seja conhecido. Para evitar que isso aconteça, o Looker retorna um erro 404 nestes casos, e o erro complementar na IU do Looker diz: "Não foi possível encontrar a página solicitada. Ele não existe ou você não tem permissão para visualizá-lo."

Dependendo do ambiente em que sua instância do Looker está hospedada e da configuração da instância do Looker, o número da porta e o URL associado em que a API pode ser acessada podem ser diferentes. Ao usar um número de porta incorreto, o erro 403 pode ser exibido. Por exemplo, se a instância do Looker estiver configurada com a porta de API padrão 443, a conexão com https://mycompany.looker.com/api/4.0/login, em vez de https://mycompany.looker.com:443/api/4.0/login, retornará um erro 403. Leia sobre as opções de inicialização do Looker para saber como definir a porta da API em instâncias hospedadas pelo cliente.

Isso também pode acontecer quando você estiver usando uma versão desatualizada da gem do SDK do Ruby. Mantenha essas joias atualizadas. Você pode conferir em https://rubygems.org/gems/looker-sdk.

Isso também pode acontecer quando você não inclui a parte /api/<version number>/ do URL. Nesse caso, se um usuário tentar se conectar a https://mycompany.looker.com:443/login, ele verá uma resposta 403.

Erros "Não encontrados" (404)

O erro 404 Not Found é o padrão se algo der errado, geralmente com permissões como permissões. A mensagem de resposta para um erro 404 fornece o mínimo de informações, se houver. Isso é intencional, já que erros 404 são exibidos para pessoas com credenciais de login incorretas ou permissões insuficientes. O Looker não quer fornecer informações específicas em mensagens de resposta 404, já que essas informações podem ser usadas para mapear a "superfície de ataque" da API do Looker.

Se as tentativas de login da API retornarem erros 404, é provável que o ID do cliente da API3 ou a chave secreta do cliente não seja válido. Consulte Verificar as credenciais da API anteriormente nesta página. Dependendo da versão da API em uso, o endpoint REST de login da API é um dos seguintes:

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

Se você estiver usando uma API gena do Swagger ou um SDK do Looker, verifique se o valor base_url está correto:

  • Para um cliente de códigogen do Swagger, o base_url precisa ser um dos seguintes, dependendo da versão da API em uso:
    • https://<your-looker-hostname>:<port>/api/4.0/
    • https://<your-looker-hostname>:<port>/api/3.1/

  • Para implementações do SDK do Looker que usam um looker.ini, o valor de api_version deve ser 4.0 ou 3.1, e o valor de base_url deve ser o mesmo que o URL da sua API de instância do Looker no formato https://<your-looker-hostname>:<port>. Veja a seguir um exemplo de arquivo looker.ini:

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

Também é possível receber um erro 404 depois de fazer login. Se você fez login e recebe um erro 404, isso significa que você não tem permissões para o comando de API que acabou de chamar.

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

Um erro 405 Method Not Allowed indica que o servidor sabe o método de solicitação, mas o recurso de destino não é compatível com esse método.

O servidor precisa gerar um campo de cabeçalho Allow em uma resposta do código de status 405. O campo precisa conter uma lista de métodos compatíveis com o recurso de destino.

Por exemplo, uma maneira de encontrar isso no Looker seria se você tentasse usar o endpoint update_dashboard() para atualizar os metadados de um painel do LookML. Não é possível mudar o parâmetro id de um painel do LookML usando a API Looker. Portanto, há um erro 405.

Erros de conflito (409)

O código de status da resposta 409 Conflict indica um conflito de solicitações com o estado atual do recurso de destino.

É mais provável que ocorram conflitos em resposta a uma solicitação PUT. Um exemplo comum desse erro ocorre quando você faz upload de um arquivo mais antigo do que o existente no servidor, resultando em um conflito de controle de versões.

Esse erro pode ocorrer no Looker ao tentar verificar uma nova ramificação git usando a API ou usando endpoints como create_group() ou create_dashboard(). Nesses casos, verifique se o objeto que você está tentando criar já existe.

Erros de validação (422)

Os erros de validação ocorrem quando algo na solicitação falha nas verificações de dados. A solicitação tem um ou mais dos seguintes tipos de erros (a resposta de erro especificará os erros exatos):

  • Campos ausentes: há um parâmetro obrigatório que não foi fornecido (a resposta de erro informará qual campo está ausente).
  • Inválido: o valor fornecido não corresponde a um valor existente ou não está no formato correto. Por exemplo, se você tentar criar uma aparência e o ID da consulta fornecido na chamada de API não corresponder a uma consulta existente, você receberá um erro de validação.
  • Já existe: a chamada de API está tentando criar um objeto com um ID ou nome que já está presente na sua instância do Looker. Por exemplo, os nomes das conexões de banco de dados precisam ser exclusivos. Se você tentar criar uma nova conexão de banco de dados que use o nome de uma conexão atual, receberá um erro de validação com o código already_exists.

Veja a mensagem de resposta de erro para detalhes sobre quais campos podem estar ausentes ou obrigatórios ou quais campos podem ter valores inválidos. A mensagem de resposta informará todos os erros de validação ao mesmo tempo. Portanto, se você tiver campos ausentes e incorretos, a resposta de erro listará todos os problemas com a chamada de API.

Veja 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/"
    }
  ],
    ...

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

Muitos erros de solicitações (429)

O código de status de resposta 429 Too Many Requests indica que o usuário enviou muitas solicitações em um determinado período ("limitação de taxa"). Leia mais sobre as políticas de limitação de taxa do Looker no artigo da comunidade do Looker Há um limite para o número de solicitações de API que podem ser enviadas de uma só vez?.

Erros internos de erro de servidor (500)

O código de resposta 500 Internal Server Error indica que o servidor encontrou uma condição inesperada que impediu a conclusão da solicitação.

Esta resposta de erro é uma resposta "catch-all" genérica. Isso costuma indicar que o servidor não consegue encontrar um código de erro 5xx mais específico para retornar em resposta. Como qualquer resposta 500 do Looker é inesperada, se você vir esse erro de forma consistente ao tentar interagir com o Looker, recomendamos entrar em contato com o suporte do Looker.