O Looker API Explorer é uma extensão, um aplicativo da Web criado com componentes do Looker, desenvolvida com o framework de extensão do Looker e implantada por meio do Looker Marketplace.
O API Explorer fornece os seguintes recursos:
- Documentação de todos os métodos e tipos da API Looker
- Declarações de método e tipo em todos os idiomas compatíveis do SDK
- Links para exemplos de funções do SDK que usam métodos de API
- links para páginas do APIs Explorer de métodos e tipos referenciados
- Uma função Run It que permite executar chamadas de API diretamente e fornece o código para as chamadas de API, respostas da API e funções do SDK
- Uma ferramenta de comparação que mostra as diferenças nas versões da API Looker
O usuário não precisa fazer login na versão da extensão do API Explorer, pois ele usa a conta do usuário ativo para solicitações da API. Isso garante que o usuário só possa realizar as chamadas de API para as quais tem direito, eliminando também 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 o API Explorer
O API Explorer está disponível no Looker Marketplace.
Antes de instalar o API Explorer do Marketplace, um administrador do Looker precisa ativar o recurso Extension Framework.
Para instalar aplicativos do Marketplace, como a extensão API 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 visualizar todos os pontos de extremidade da API no API Explorer, mas pode executar apenas aqueles permitidos por suas permissões.
Se o administrador do Looker tiver ativado a opção Instalação automática na página Marketplace da seção Plataforma do menu Administrador, o API Explorer será instalado automaticamente na instância. Além disso, sempre que houver atualizações disponíveis, elas serão aplicadas automaticamente, garantindo que a versão do API Explorer na instância seja a mais atual.
Se o administrador do Looker não tiver ativado a opção Instalar automaticamente, você precisará instalar o API Explorer a partir do Looker Marketplace.
Consulte a página de documentação Usar o Looker Marketplace para ver instruções sobre como instalar uma extensão do Looker Marketplace. Para ter sempre a versão mais atualizada da API Explorer, acesse o Looker Marketplace, selecione Gerenciar e clique no botão Atualizar ao lado da extensão.
Como iniciar a API Explorer
Depois de instalar o API Explorer, navegue até a seção Aplicativos na barra lateral esquerda.
Como navegar no API Explorer
Na página inicial do API Explorer, é possível realizar as seguintes tarefas:
Use o menu suspenso do seletor de idiomas do SDK para escolher a linguagem de programação na qual o API Explorer exibirá declarações de método e tipo de API e resultados de códigos. O seletor assume como padrão o Python no carregamento inicial. Se você escolher Todos no seletor de idiomas, o API Explorer exibirá uma visualização com guias para cada idioma compatível.
Use o menu suspenso de versões para escolher uma versão da API:
- 4.0 - atual
- 3.1: legado
Selecione o botão Comparar especificações para abrir a página de comparação de versões da API.
Digite um termo de pesquisa no campo Pesquisar para limitar os Métodos e os Tipos listados somente àqueles que incluam texto correspondente ao termo de pesquisa.
Quando você selecionar um método ou tipo retornado pela pesquisa, o termo de pesquisa será destacado no resumo de método ou tipo.
Selecione a guia Métodos para exibir as categorias de método da API. Você pode expandir ou retrair uma categoria de método para visualizar os métodos individuais dela.
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.
Selecione o botão Menu principal para ocultar ou mostrar o painel de navegação do API Explorer.
Como visualizar a documentação da API e do método
Quando você seleciona uma categoria de método na guia Método, ela se expande e mostra todos os métodos dessa categoria.
Todos os métodos dessa categoria são exibidos no painel principal. Você pode optar por exibir todos os métodos da categoria ou selecionar a guia de um tipo de método específico para filtrar a lista de acordo com esse tipo de método.
Para visualizar a documentação de um método específico, escolha o nome do método no painel de navegação ou selecione o método no painel principal.
Depois de selecionar um método específico, o API Explorer exibirá a documentação para esse método.
Ao selecionar um tipo na guia Tipo, a documentação desse tipo é exibida no painel principal.
Declarações de método e tipo
O API Explorer renderiza as declarações de método e tipo do SDK no idioma escolhido no menu suspenso do seletor. 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, separadas por guias.
Exemplos de SDK
O repositório sdk-codegen do Looker tem uma pasta que contém exemplos de SDK do Looker. Se o repositório do sdk-codegen tiver exemplos de um método, a página da API Explorer do método exibirá uma seção de Exemplos de SDK com links para os exemplos.
Se um idioma específico do SDK for selecionado, os exemplos desse idioma serão listados primeiro.
Também podem ser exibidos exemplos de Ruby e Java, 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 a execução para solicitar e exibir chamadas de API
O API Explorer inclui um botão Executar, que abre um painel a partir do qual é possível solicitar chamadas de API e exibir as respostas em vários formatos compatíveis.
Quando você seleciona o botão Executar, o API Explorer exibe a guia Solicitação, em que você pode fornecer as entradas para o método da API.
Insira a entrada desejada e selecione Run para executar a chamada de API.
Sempre que o método da API pode alterar dados (para qualquer chamada REST que seja
POST,PATCH,UPDATEouDELETE), a caixa de seleção de confirmação de alteração de dados aparece e precisa ser marcada antes que a solicitação possa ser executada.
Quando a solicitação é executada, a guia Resposta mostra os resultados.
Além disso, a guia Código mostra a sintaxe de chamada do SDK escolhida no menu suspenso do seletor de idioma. Se o seletor de idiomas do SDK estiver definido como Todos, a sintaxe de chamada do SDK será exibida em todos os idiomas compatíveis do SDK, separados por guias.
Tipos de exibição de resposta
As respostas do API Explorer incluem um tipo MIME usado para determinar como exibir os resultados.
CSV e outros dados tabulares
Para dados CSV e JSON, o Looker realiza um teste de forma para determinar se os dados atendem aos critérios de uma tabela. Se o Looker determinar que os dados de payload são tabulares, a exibição padrão da resposta será uma grade de dados.
Selecione a guia Raw para exibir os dados não transformados.
JSON
Os payloads JSON podem ser tabulares e, nesse caso, serão exibidos em uma grade. Os cabeçalhos de coluna da consulta LookML são exibidos no formato <view_name>.<field_name> em vez de exibir o rótulo do campo.
Os payloads JSON complexos omitem a exibição da grade e mostram apenas o JSON bruto.
PNG e JPEG
Os formatos PNG e JPEG exibem a visualização selecionada para a consulta e incluem todas as configurações de visualização aplicadas. O próximo exemplo é a saída PNG da mesma consulta mostrada anteriormente, mas usando uma visualização de tabela. O JPEG é processado de maneira semelhante.
SVG
Alguns endpoints do Looker retornam SVG, que também é diretamente compatível. Veja a seguir um exemplo do endpoint content_thumbnail no formato SVG, que retorna uma imagem em miniatura abstrata de um painel.
HTML
As solicitações que retornam o código-fonte HTML exibem o HTML de origem na guia Resposta.
Texto
As solicitações que retornam SQL ou outros formatos MIME digitados como texto simples são exibidas como texto simples na guia Resposta.
Comparação de versões da API
O API Explorer inclui uma página que permite comparar diferentes versões da API Looker para ver o que mudou entre elas. Selecione o botão triangular Comparar especificações, localizado no canto superior direito da página, para abrir a página de comparação do API Explorer.
Selecione a versão de base da API e a versão da API que deseja comparar com a versão de base.
Selecione as opções de API que deseja incluir na comparação para filtrar os métodos somente àqueles que têm diferenças nas opções selecionadas. As opções são:
- Missing: 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
betaparastable. - Parâmetros — mostra todos os métodos em que um ou mais parâmetros do método foram alterados.
- Tipo: mostra os tipos com 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 alteração na resposta do método.
A página de comparação mostra o número de métodos em que há diferença e lista os métodos em que há essa diferença.
Selecione um método para expandi-lo. A página de comparação exibe uma comparação que mostra como o método mudou entre as versões.