Usar o API Explorer

O Looker API Explorer é uma extensão, um aplicativo da Web criado usando componentes do Looker, desenvolvido com o framework de extensão do Looker e implantado por meio do Looker Marketplace.

A API Explorer fornece os seguintes recursos:

O usuário não precisa fazer login para a versão da extensão da API Explorer, porque ela usa a conta ativa do usuário para solicitações de API. Isso garante que o usuário possa executar apenas as chamadas de API em que tem direito e eliminar a necessidade de fornecer credenciais de API.

O recurso sudo as another user do Looker também pode ser usado para fazer solicitações de API como um usuário diferente para ajudar a diagnosticar problemas de acesso.

Como instalar a API Explorer

O APIs Explorer está disponível no Marketplace do Looker.

Antes de instalar o APIs Explorer do Marketplace, um administrador do Looker precisa ativar o recurso Extension Framework.

Para instalar aplicativos do Marketplace, como a extensão do APIs Explorer, você precisa ter as permissões develop, manage_models e deploy. Depois que o API Explorer for instalado, qualquer usuário com pelo menos a permissão access_data no modelo extension_api_explorer poderá usar o API Explorer. Cada usuário pode ver todos os endpoints de API no API Explorer, mas só pode executar aqueles permitidos pelas permissões.

Se o administrador do Looker tiver ativado a opção Instalação automática na página Marketplace na seção Plataforma do menu Administrador do Looker, a API Explorer será instalada automaticamente na sua instância. Além disso, sempre que houver atualizações disponíveis, elas serão aplicadas automaticamente, garantindo que a versão do APIs Explorer na instância seja a mais atual.

Se o administrador do Looker não tiver ativado a opção de instalação automática, você precisará instalar o APIs Explorer pelo Looker Marketplace.

Consulte a página de documentação Como usar o Looker Marketplace para ver instruções sobre como instalar uma extensão do Looker Marketplace. Para garantir que você tenha sempre a versão mais recente da API Explorer, acesse o Looker Marketplace, clique em Gerenciar e, em seguida, no botão Atualizar ao lado da extensão.

Como iniciar a API Explorer

Após instalar o APIs Explorer, você poderá navegar até ele das seguintes maneiras:

  1. Na lista de apps e extensões instalados no menu Procurar

  2. Na página Applications & Tools, que pode ser acessada no menu Browse (Procurar) e na barra lateral esquerda

  3. Se você for um administrador do Looker, também poderá acessar o APIs Explorer clicando no link Usar API Explorer na página Administrador da API do Looker.

Na página inicial do APIs Explorer, você pode realizar as seguintes tarefas:

  1. Use o menu suspenso do seletor de linguagem do SDK para escolher a linguagem de programação em que a API Explorer exibirá as declarações de método e tipo de API e os resultados do código. Por padrão, o seletor usa o Python no carregamento inicial. Se você escolher Todas no seletor de idioma, a API Explorer mostrará uma visualização com guias para cada idioma compatível.

  2. Use o menu suspenso de versões para escolher uma versão da API:

    - 4.0 - atual

A partir do Looker 22.4, a API Looker 4.0 está em disponibilidade geral. Com esta versão, a API 3.1 foi descontinuada e removida do APIs Explorer, tornando a API 4.0 a única versão disponível para visualização no APIs Explorer. Embora a página de comparação do API Explorer ainda exista para versões futuras, ela não funciona atualmente, já que a API 4.0 é a única versão disponível.

  1. Digite um termo de pesquisa no campo Pesquisa para limitar os Métodos e Tipos listados somente àqueles que incluem texto que corresponda ao termo de pesquisa:

    Ao selecionar um método ou tipo retornado pela pesquisa, o termo de pesquisa será destacado no método ou no resumo do tipo.

  2. Selecione a guia Métodos para exibir as categorias de método da API. Você pode expandir ou reduzir uma categoria de método para visualizar cada método na categoria.

  3. Selecione a guia Tipos para exibir os tipos de API. Os tipos não são categorizados e estão listados em ordem alfabética.

  4. Clique no ícone de três barras para ocultar ou mostrar o painel de navegação do APIs Explorer.

Ver o método e a documentação do tipo de API

Quando você seleciona uma categoria de método na guia Método, a categoria de método se expande e mostra todos os métodos nessa categoria:

  1. No painel principal, todos os métodos dessa categoria são mostrados. É possível exibir todos os métodos da categoria ou clicar na guia de um tipo específico para filtrar a lista apenas para esse tipo de método.

  2. Para ver a documentação de um método específico, escolha o nome dele no painel de navegação ou clique no método no painel principal.

Depois de selecionar um método específico, o APIs Explorer vai exibir a documentação desse método:

Quando você seleciona um tipo na guia Tipo, a documentação desse tipo é exibida no painel principal:

Declarações de método e tipo

A API Explorer renderiza as declarações de método e tipo do SDK no idioma escolhido no SDK suspenso. Se o seletor de idioma do SDK estiver definido como All, as declarações de método e tipo serão exibidas em todos os idiomas compatíveis do SDK, separados por tabulação:

Exemplos do SDK

O repositório sdk-codegen do Looker tem uma pasta que contém exemplos do SDK do Looker. Se o repositório sdk-codegen tiver exemplos de um método, a página da API Explorer do método exibirá uma seção Exemplos do SDK com links para os exemplos.

Se uma linguagem específica do SDK for selecionada, os exemplos dessa linguagem serão listados primeiro. Por exemplo, a tabela de exemplos do SDK a seguir mostra o Swift como a linguagem selecionada:

Alguns exemplos de Ruby e Java também podem ser exibidos, embora não sejam linguagens de SDK.

Referências

A seção Referências de cada método e tipo inclui links para as páginas do APIs Explorer de cada método ou tipo referenciado pelo método ou tipo original:

Como usar Run It para solicitar e exibir chamadas de API

A API Explorer inclui um botão Run It que abre um painel com as quais você pode solicitar chamadas de API e exibir as respostas em vários formatos compatíveis:

Quando você clica no botão Executar, o APIs Explorer mostra a guia Solicitação, onde você pode fornecer as entradas para o método da API:

Insira a entrada desejada e clique em Run para executar a chamada de API.

Sempre que o método da API pode alterar os dados (para qualquer chamada REST que seja POST, PATCH, UPDATE ou DELETE), a caixa de seleção de confirmação de alteração de dados aparece e precisa ser marcada antes da execução da solicitação.

Quando a solicitação é executada, a guia Resposta mostra os resultados:

Além disso, a guia Code mostra a sintaxe de chamada do SDK escolhida para o SDK, no menu suspenso do seletor de idiomas. Se o seletor de idioma do SDK estiver definido como All, a sintaxe de chamada do SDK será exibida em todos os idiomas compatíveis do SDK, separados por tabulação:

Tipos de exibição da resposta

As respostas do API Explorer incluem um tipo MIME usado para determinar como exibir os resultados.

CSV e outros dados tabulares

Para CSV e JSON, um teste simples de "shape" é realizado para determinar se os dados estão em uma tabela." Se os dados de payload parecerem uma tabela, a exibição padrão da resposta será uma grade de dados:

A guia Raw pode ser usada para exibir os dados não transformados:

JSON

Os payloads JSON podem ser "tabular," nesse caso, serão exibidos em uma grade. Os cabeçalhos da coluna para a consulta LookML são diferentes no formato JSON e no CSV:

Os payloads JSON complexos omitem a exibição em grade e exibem apenas o JSON bruto:

PNG e JPEG

Veja abaixo um exemplo da mesma consulta feita acima, renderizada no formato PNG. JPEG é processado da mesma forma:

SVG

Alguns endpoints do Looker retornam SVG, que também é diretamente compatível. Veja abaixo um exemplo do endpoint content_thumbnail no formato SVG:

HTML

O código-fonte HTML está destacado na guia Resposta:

Texto

As respostas SQL e outras digitadas em MIME como texto simples são exibidas desta forma:

Comparação de versões da API

A partir do Looker 22.4, a API Looker 4.0 está em disponibilidade geral. Com esta versão, a API 3.1 foi descontinuada e removida do APIs Explorer, tornando a API 4.0 a única versão disponível para visualização no APIs Explorer. Embora a página de comparação do API Explorer ainda exista para versões futuras, ela não funciona atualmente, já que a API 4.0 é a única versão disponível.

A API Explorer inclui uma página que permite comparar versões diferentes da API Looker e ver o que mudou entre as versões. Clique no triângulo no canto superior direito da página para abrir a página de comparação do APIs Explorer.

  1. Selecione a versão base e a que você quer comparar com a versão base.

  2. Selecione as opções de API que você quer incluir na comparação para filtrar os métodos apenas para aqueles que têm diferenças nas opções selecionadas. As opções são:

    • Falta: mostra todos os métodos que existem em uma versão da API e que estão ausentes na outra.
    • Status: mostra todos os métodos em que o status do método mudou. Por exemplo, um método em que o status mudou de beta para stable.
    • Parâmetros: mostra todos os métodos em que um ou mais parâmetros foram alterados.
    • Tipo: mostra os tipos que têm propriedades novas, removidas ou alteradas.
    • Corpo: mostra as alterações nos parâmetros do corpo.
    • Resposta: mostra todos os métodos em que houve uma mudança na resposta do método.

  3. A página de comparação mostra o número de métodos em que há uma diferença e os lista em que há essa diferença.

  4. Clique em um método para expandi-lo, e a página de comparação mostra uma comparação que mostra como o método mudou entre as versões.