A API Explorer do Looker é uma extensão, um aplicativo da Web criado com componentes do Looker, desenvolvido com o framework de extensões do Looker e implantado no Marketplace do Looker.
O API Explorer fornece os seguintes recursos para uso com a API Looker:
- Documentação de todos os métodos e tipos da API Looker
- Declarações de método e tipo em todas as linguagens compatíveis do SDK
- Links para exemplos de funções do SDK que usam métodos de API
- Links para páginas do API Explorer de tipos e métodos referenciados
- Uma função Run It que permite executar chamadas de API diretamente e fornece o código para as chamadas de API, respostas de API e funções do SDK
- Uma ferramenta de comparação que mostra as diferenças nas versões da API do Looker
Não é necessário que o usuário faça login na versão de extensão do API Explorer, porque ele usa a conta do usuário ativo para solicitações de API. Isso garante que o usuário só possa realizar as chamadas de API às quais tem direito, ao mesmo tempo em que elimina a necessidade de fornecer credenciais de API.
O recurso sudo como outro usuário 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 APIs Explorer
O API Explorer está disponível no Marketplace do Looker.
Antes de instalar o API Explorer no Marketplace, um administrador do Looker precisa ativar o recurso Extension Framework.
Para instalar aplicativos, como a extensão do API Explorer, no Marketplace, 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á usá-lo. Cada usuário pode ver todos os endpoints da API no APIs Explorer, mas só pode executar os que têm permissão.
Se o administrador do Looker tiver ativado a opção Instalação automática na página do Marketplace, na seção Plataforma do menu Administrador do Looker, o APIs 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 sua instância seja a mais atual.
Se o administrador do Looker não tiver ativado a opção Instalação automática, você vai precisar instalar o APIs Explorer pelo Marketplace do Looker.
Consulte a página de documentação Como usar o Marketplace do Looker para ver instruções sobre como instalar uma extensão do Marketplace do Looker. Para garantir que você sempre tenha a versão mais atualizada do API Explorer, acesse o Marketplace do Looker, selecione Gerenciar e clique no botão Atualizar ao lado da extensão.
Como iniciar o APIs Explorer
Depois que o API Explorer for instalado, você poderá acessá-lo na seção Aplicativos da barra lateral esquerda.
Como navegar no API Explorer
Na página inicial do APIs Explorer, você pode realizar as seguintes tarefas:
Use o menu suspenso do seletor de idiomas do SDK para escolher a linguagem de programação em que o API Explorer vai exibir o método e as declarações de tipo da API e os resultados do código. O seletor usa Python por padrão no carregamento inicial. Se você escolher Todos no seletor de idioma, o API Explorer vai mostrar uma visualização com guias para cada idioma com suporte.
Use o menu suspenso da versão para escolher uma versão da API:
- 4.0 - atual
Selecione o botão Compare Specifications para abrir a página de comparação de versões da API.
Digite um termo no campo Pesquisar para limitar os Métodos e Tipos listados aos que incluem texto que corresponda ao seu termo de pesquisa.
Quando você seleciona um método ou tipo retornado pela pesquisa, o termo de pesquisa é destacado no resumo do método ou tipo.
Selecione a guia Métodos para mostrar as categorias de método da API. Você pode expandir ou reduzir uma categoria de método para visualizar os métodos individuais na categoria.
Selecione a guia Tipos para mostrar os tipos de API. Os tipos não são categorizados e sã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 conferir a documentação de tipo e método da API
Quando você seleciona uma categoria de método na guia Método, a categoria é expandida e mostra todos os métodos que estão nela.
Todos os métodos dessa categoria são mostrados no painel principal. Você pode optar por exibir todos os métodos que estão na categoria ou selecionar a guia de um tipo de método específico para filtrar a lista apenas para esse tipo de método.
Para conferir a documentação de um método específico, escolha o nome dele no painel de navegação ou selecione o método no painel principal.
Depois que você seleciona um método específico, o API Explorer mostra a documentação dele.
Quando você seleciona um tipo na guia Tipo, a documentação dele é 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 de idiomas do SDK. Se o seletor de idioma do SDK estiver definido como Todos, as declarações de método e tipo serão exibidas em todas as linguagens de SDK com suporte, separadas por guias.
Exemplos de SDK
O repositório sdk-codegen do Looker tem uma pasta com exemplos do SDK do Looker. Se o repositório sdk-codegen tiver exemplos para um método, a página do API Explorer do método exibirá uma seção 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 aparecer exemplos em Ruby e Java, embora essas não sejam linguagens do SDK.
Referências
A seção Referências de cada método e tipo inclui links para as páginas do API Explorer de cada método ou tipo referenciado pelo método ou tipo original.
Como usar o Run It para solicitar e mostrar chamadas de API
O API Explorer inclui um botão Run It que abre um painel em que você pode solicitar chamadas de API e mostrar as respostas em vários formatos compatíveis.
Quando você seleciona o botão Executar, o API Explorer exibe uma guia Solicitação, em que você pode fornecer as entradas para o método de API.
Insira a entrada desejada e selecione Executar para executar a chamada de API.
Sempre que o método da API puder mudar dados (para qualquer chamada REST que seja
POST,PATCH,UPDATEouDELETE), a caixa de seleção de confirmação de mudança de dados vai aparecer e precisará 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 Code mostra a sintaxe de chamada do SDK escolhido no menu suspenso do seletor de idioma. Se o seletor de idioma do SDK estiver definido como Todos, a sintaxe de chamada do SDK será mostrada em todos os idiomas com suporte, separados por guias.
Tipos de exibição de resposta
As respostas do API Explorer incluem um tipo MIME que é usado para determinar como mostrar 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 do payload são tabulares, a exibição padrão da resposta será uma grade de dados.
Selecione a guia Raw para mostrar 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 do LookML são mostrados no formato <view_name>.<field_name>, em vez de exibir o rótulo do campo.
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 têm suporte direto. 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 esse código na guia Resposta.
Texto
As solicitações que retornam SQL ou outros formatos MIME digitados como texto simples são mostradas como texto simples na guia Resposta.
Comparação de versões da API
O APIs Explorer inclui uma página que permite comparar diferentes versões da API Looker para saber 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 APIs Explorer.
Selecione a versão base da API e a versão da API que você quer comparar com a versão base.
Selecione as opções de API que você quer incluir na comparação para filtrar os métodos e mostrar apenas os que têm diferenças. 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 foi alterado. 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 tipos com propriedades novas, removidas ou alteradas.
- Corpo: mostra mudanças nos parâmetros do corpo.
- Resposta: mostra todos os métodos em que houve uma mudança na resposta do método.
A página de comparação mostra o número de métodos em que há uma diferença e lista os métodos em que há uma diferença.
Selecione um método para expandi-lo. A página de comparação vai mostrar uma diferença que mostra como o método mudou entre as versões.