Solução de problemas da API Looker

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

Endpoint de API não está acessível

Se não for possível acessar um endpoint de API:

Verificar as credenciais da API

Se não for possível acessar o endpoint de API Looker, primeiro verifique se as credenciais da API estão corretas. Para ver suas credenciais da 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 o seu nome de usuário na lista de usuários e clique nele para editar a sua página de usuário.
  4. Clique em Editar chaves de API. Veja o ID do cliente e clique no ícone de olho para exibir a chave secreta do cliente de cada chave de API configurada. Verifique se as credenciais da API correspondem às que você está usando no script.

Verifique o URL da API

Outro problema comum para 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 para a API. No entanto, as instalações do Looker que usam um caminho alternativo de API ou as instalações 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 precisa indicar o nome do host e a porta da API voltada para o usuário.

O URL do host da API aparece para os administradores do Looker nas configurações do administrador da API. Isso é descrito em mais detalhes na página de documentação Configurações de administrador – API. Para ver o URL do host da 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, sua instância do Looker vai usar o formato padrão, que é:

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

Para testar o URL do host da API:

  1. Abra um navegador e o console do navegador.

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

    https://company.cloud.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, no Microsoft Azure e 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>.cloud.looker.com:443/alive

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

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

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

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

Se essas verificações falharem, talvez você esteja chamando a API incorretamente ou tenha outros erros no código. Verifique suas chamadas de API e o código em seu script. Se estiverem corretas, consulte a próxima seção sobre como verificar sua porta.

Verificar a porta da API

Se as verificações anteriores falharem e você tiver uma implantação do Looker hospedada pelo cliente, talvez seja necessário abrir a porta da API na infraestrutura de rede.

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

  • Proxies
  • Balanceadores de carga
  • Firewalls

Verifique o URL da chamada de API

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

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

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

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

Confira o formato do URL dos endpoints de API na API Explorer ou na documentação da Referência da API.

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

/api/4.0/running_queries

Portanto, o URL completo do endpoint de API para o endpoint "Receber todas as consultas em execução" 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 não faz sentido

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

Nesse caso, você precisa ter certeza de que sua biblioteca HTTP REST lida com a resposta da API como dados binários, não como texto. Em alguns casos, isso pode significar definir uma sinalização na chamada de API para informar à biblioteca HTTP REST que é um resultado binário, ou pode significar lidar com o resultado de uma maneira especial, 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ê conseguir abrir o APIs Explorer, mas as chamadas de API não responderem, verifique se a configuração URL do host da API da instância do Looker está definida corretamente. Os administradores do Looker podem conferir o URL do host da API nas configurações de administrador da API Looker, descritas na página de documentação Configurações de 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 adequado no cabeçalho durante a solicitação. Os padrões do 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.

O uso de um SDK do Looker processa automaticamente essa preocupação para você.

Erros de Método não encontrado

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. Há várias chamadas de API novas na API 4.0 ou que foram removidas na API 4.0. Consulte o anúncio sobre a API Looker 4.0 em geral para conferir a lista de atualizações.

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

Um erro 400 Bad Request indica que os dados fornecidos em uma chamada de API estão irreconhecíveis. O culpado geralmente é um JSON inválido ou inválido, talvez um erro de análise. A maioria dos erros 400 já passou na autenticação, portanto, a mensagem de resposta de erro fornecerá informações mais específicas sobre o erro.

Erros não autorizados (401)

Um erro 401 Unauthorized em uma chamada de API significa que a chamada de API não está devidamente autenticada. Para mais detalhes sobre solução de problemas, consulte a seção Como solucionar problemas 401?, Artigo da comunidade.

Erros "Proibido" (403)

A API Looker não retorna erros 403 sempre que um usuário tenta acessar um objeto LookML ou outro conteúdo sem permissão. Retornar um erro 403 em vez de 404 pode, em alguns casos, verificar a existência de um determinado Explore, dashboard ou objeto LookML quando o proprietário preferir que isso não seja conhecido. Para evitar isso, o Looker retorna um erro 404 nesses casos, e o erro na interface do Looker diz: "Não foi possível encontrar a página solicitada. Ela não existe ou você não tem permissão de visualização."

Dependendo do ambiente em que a instância do Looker está hospedada e da configuração dela, 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, vai retornar um erro 403. Para instâncias hospedadas pelo cliente, leia mais sobre as opções de inicialização do Looker (link em inglês), em que é possível definir a porta da API.

Isso também pode acontecer quando você usa uma versão desatualizada da gem do SDK do Ruby. Atualize essas pedras preciosas. Confira 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 o usuário tentar se conectar ao https://mycompany.looker.com:443/login, ele verá uma resposta 403.

Erros "Não encontrado" (404)

Um erro 404 Not Found é o padrão se algo der errado, geralmente relacionado a permissões. A mensagem de resposta para um erro 404 fornece o mínimo de informações, se houver. Isso é intencional, já que os erros 404 aparecem 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 Looker.

Se as tentativas de login de API estiverem retornando erros 404, é provável que a chave secreta ou o ID do cliente da API não sejam válidos. Consulte Verificar as credenciais da API anteriormente nesta página. O endpoint REST de login da API é o seguinte:

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

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

  • Para um cliente de codegen Swagger, o base_url precisa ser o seguinte:

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

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

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

Também é possível receber um erro 404 após fazer login. Se você fez login e recebeu um erro 404, isso significa que 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 conhece o método da 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 de 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 dashboard do LookML. Não é possível mudar o parâmetro id de um dashboard do LookML na API Looker. Por isso, ocorreria um erro 405.

Erros de conflito (409)

O código de status de resposta 409 Conflict indica um conflito de solicitação 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 não relacionado ao Looker ocorre no upload de um arquivo mais antigo do que o atual no servidor, resultando em um conflito de controle de versões.

Talvez você encontre esse erro no Looker ao tentar verificar uma nova ramificação git usando a API ou ao usar 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 realizadas. A solicitação tem um ou mais dos seguintes tipos de erro (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á faltando).
  • 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 um Look e o ID da consulta fornecido na chamada de API não corresponder a uma consulta atual, você vai 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 de conexão 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, um erro de validação será exibido com o código already_exists.

Consulte a mensagem de resposta de erro para mais detalhes sobre os campos que podem estar ausentes ou obrigatórios e quais podem ter valores inválidos. A mensagem de resposta vai mostrar todos os erros de validação ao mesmo tempo. Portanto, se houver 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 de API não tinha o campo dialect obrigatório e também tinha um valor inválido no db_timezone.

Erros em "Muitas 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 na postagem Existe um limite para o número de solicitações de API que você pode enviar de uma só vez?

Erros de Erro interno 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 atender à solicitação.

Essa resposta de erro é uma resposta "pega-tudo" genérica. Em geral, isso indica que o servidor não consegue encontrar um código de erro 5xx mais específico para retornar em resposta. Qualquer resposta 500 do Looker é inesperada. Portanto, se esse erro ocorrer com frequência ao tentar interagir com o Looker, recomendamos que você abra uma solicitação de suporte.