Solução de problemas da API Looker

Observação: a partir do Looker 22.4, a API Looker 4.0 está disponível para todos os usuários. No Looker 23.18, a API Looker 3.1 foi removida.

Nesta página, você encontra procedimentos de solução de problemas para os seguintes problemas que podem ocorrer com a API Looker:

• O endpoint da API não está acessível
• O resultado da API é um texto sem sentido
• As chamadas de API não respondem
• Erros de codificação inválida
• Erros de método não encontrado
• Erros de solicitação inválida (400)
• Erros não autorizados (401)
• Erros "Proibido (403)"
• Erros "Não encontrado (404)"
• Erros "Método não permitido" (405)
• Erros de conflito (409)
• Erros de validação (422)
• Erros de "Muitas solicitações (429)"
• Erros internos do servidor (500)

Endpoint de API não está acessível

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

• Verificar suas credenciais da API
• Verificar o URL do host da API
• Verificar a porta da API
• Verificar o URL de chamada da API

Verificar suas credenciais de API

Se o endpoint de API Looker não estiver acessível, primeiro verifique se as credenciais da API estão corretas. Para conferir 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 à esquerda da página Administrador, role para baixo e clique em Usuários.
3. Procure seu nome de usuário na lista e clique nele para editar sua página de usuário.
4. Clique em Editar chaves de API. Você pode ver o ID do cliente e clicar no ícone de olho para conferir 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.

Verificar o URL da API

Outro problema comum ao acessar um endpoint de API é um URL de host da 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 que estão localizadas atrá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 ao usuário.

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

1. Clique no ícone Menu principal do Looker e selecione Administrador para abrir o painel Administrador.
2. Clique em API no painel Administrador.

3. Confira o URL do host da API.

   Se o campo URL do host da API estiver em branco, a 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 dele.

2. Insira o URL do host da API seguido por /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 padrão da API. 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 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, ele vai resultar em uma página da Web em branco, não em uma página de erro.

Você também pode verificar se chegou à 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 seu código. Verifique as chamadas de API e o código no script. Se estiverem corretos, 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 da API. A porta da API geralmente é 443 ou 19999. A porta da API precisa ter as mesmas configurações da 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 da API e da instância do Looker:

• Proxies
• Balanceadores de carga
• Firewalls

Verificar o URL da chamada de API

Verifique se você está usando o URL correto para a 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 padrão do host da API, o formato de um URL endpoint de API será:

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

É possível acessar o formato de URL para endpoints de API no API Explorer 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 "Get All Running Queries":

/api/4.0/running_queries

Portanto, o URL completo do endpoint de API para o endpoint "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 é um texto sem sentido

Se a API retornar uma resposta com texto ilegível, provavelmente você está vendo o conteúdo binário de um arquivo PDF, PNG ou JPG. Algumas bibliotecas HTTP REST presumem que as respostas da API serão arquivos de texto. Portanto, outros tipos de arquivos são mostrados como texto binário.

Nesse caso, você precisa garantir que sua biblioteca HTTP REST processe a resposta da API como dados binários, não como texto. Em alguns casos, isso pode significar definir uma flag na chamada de API para informar à biblioteca HTTP REST que é um resultado binário ou processar o resultado de uma maneira especial, como um fluxo ou 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 API Explorer, mas as chamadas de API não responderem, verifique se a configuração URL do host da API da sua 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 do Looker, descritas na página de documentação Configurações de administrador - API.

Erros de codificação inválida

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 em todo o processo, o cabeçalho Content-Type precisa ser definido como application/json.

O uso de um SDK do Looker resolve esse problema automaticamente.

Erros de método não encontrado

Se você receber um erro "Method Not Found", como method not found: all_looks(), a primeira coisa a verificar é a versão da API. Há várias chamadas de API novas ou removidas na API 4.0. Consulte o anúncio Disponibilidade geral da API Looker 4.0 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 não são reconhecidos. O problema geralmente é um JSON corrompido ou inválido, talvez um erro de análise. Na maioria dos casos, os erros 400 já passaram pela autenticação. Por isso, a mensagem de resposta de erro fornece informações mais específicas sobre o problema.

Erros não autorizados (401)

Um erro 401 Unauthorized em uma chamada de API significa que ela não foi autenticada corretamente. Para mais detalhes sobre a solução de problemas, consulte Como resolver erros 401? Artigo da comunidade.

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 não tem permissão. Retornar um erro 403 em vez de um erro 404 pode, em alguns casos, verificar a existência de uma análise detalhada, um painel ou um objeto do LookML específico quando o proprietário prefere que isso não seja conhecido. Para evitar isso, o Looker retorna um erro 404 nesses casos, e o erro acompanhante 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, você pode receber um erro 403. Por exemplo, se a instância do Looker estiver configurada com a porta padrão da API 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, em que é possível definir a porta da API.

Isso também pode acontecer quando você usa uma versão desatualizada da gema do SDK Ruby. Não deixe de atualizar essas gemas. 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 um usuário tentar se conectar a https://mycompany.looker.com:443/login, vai receber uma resposta 403.

Erros "Não encontrado" (404)

Um erro 404 Not Found é o erro padrão se algo der errado, geralmente com permissões. A mensagem de resposta para um erro 404 fornece poucas informações, se houver. Isso é intencional, já que os erros 404 são mostrados 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 elas podem ser usadas para mapear a "superfície de ataque" da API Looker.

Se as tentativas de login na API estiverem retornando erros 404, provavelmente é porque o ID do cliente ou a chave secreta do cliente da API não são válidos. Consulte Verificar suas credenciais de API nesta página. O endpoint REST de login da API é:

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

Se você estiver usando uma API de geração de código do Swagger ou um SDK do Looker, verifique se o valor de base_url está correto:

• Para um cliente Swagger codegen, 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 sua 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>
  

Você também pode receber um erro 404 depois de fazer login. Se você estiver conectado e receber um erro 404, isso significa que você não tem permissões para o comando da API que acabou de chamar.

Erros "Método não permitido" (405)

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

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

Por exemplo, isso pode acontecer no Looker se você tentar 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. Por isso, um erro 405 vai ocorrer.

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 fora do Looker ocorre ao fazer upload de um arquivo mais antigo do que o existente no servidor, resultando em um conflito de controle de versão.

Você pode encontrar esse erro no Looker ao tentar fazer o check-out de uma nova ramificação do 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 não passa nas verificações de dados realizadas. A solicitação tem um ou mais dos seguintes tipos de erros (a resposta de erro vai especificar os erros exatos):

• Campos ausentes: há um parâmetro obrigatório que não foi fornecido. A resposta de erro vai 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 uma análise detalhada e o ID da consulta fornecido na chamada da API não corresponder a uma consulta existente, 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 com o banco de dados precisam ser exclusivos. Se você tentar criar uma conexão de banco de dados com o nome de uma conexão já existente, vai receber um erro de validação com o código already_exists.

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

Confira 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 de "Muitas solicitações" (429)

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

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 atender à solicitação.

Essa resposta de erro é genérica. Normalmente, 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 você estiver vendo esse erro constantemente ao tentar interagir com o Looker, recomendamos que abra uma solicitação de suporte.