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 no Looker Marketplace.
A 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 da API Explorer para métodos e tipos referenciados
- Uma função Run It que permite executar chamadas de API diretamente e fornecer 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, já que ele usa a conta do usuário ativo para as solicitações da API. Isso garante que o usuário possa realizar apenas as chamadas de API às quais tem direito, além de 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. Isso ajuda a diagnosticar problemas de acesso.
Como instalar a API Explorer
A API Explorer está disponível no Marketplace do Looker.
Antes de instalar a API Explorer no Marketplace, um administrador do Looker precisa ativar o recurso Extension Framework.
A instalação de aplicativos (como a extensão da API Explorer) no Marketplace requer as permissões develop, manage_models e deploy. Depois que a API Explorer for instalada, qualquer usuário com pelo menos a permissão access_data no modelo extension_api_explorer vai poder usar a API Explorer. Cada usuário pode ver todos os endpoints de API na API Explorer, mas só pode executar aqueles permitidos pelas permissões deles.
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 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 recente.
Se o administrador do Looker não tiver ativado a opção Instalação automática, você vai precisar instalar o API Explorer pelo Looker Marketplace.
Consulte a página de documentação Como usar o Marketplace do Looker para conferir instruções sobre como instalar uma extensão desse Marketplace. Para garantir que você tenha sempre 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 a API Explorer
Depois de instalar o API Explorer, você pode navegar até ele a partir da seção Aplicativos da barra lateral esquerda.
Como navegar no API Explorer
Na página inicial da API Explorer, é possível realizar as seguintes tarefas:
Use o menu suspenso do seletor de linguagem do SDK para escolher a linguagem de programação em que o API Explorer exibirá declarações de método e tipo da API e os resultados do código. Por padrão, o seletor é definido como Python no carregamento inicial. Se você escolher Todos no seletor de idioma, 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
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 Pesquisa para limitar os Métodos e Tipos listados apenas àqueles que incluem texto que corresponda ao 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 exibir as categorias de método da API. Você pode expandir ou reduzir uma categoria de método para visualizar os métodos individuais nela.
Selecione a guia Tipos para exibir 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 visualizar a documentação do tipo e método da API
Quando você seleciona uma categoria de método na guia Método, a categoria se expande e mostra todos os métodos que estão nela.
Todos os métodos que estão nessa categoria são mostrados no painel principal. Você pode optar por mostrar 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 aquele tipo de método.
Para acessar 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 exibe 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
O API Explorer renderiza as declarações de método e tipo do SDK no idioma do SDK escolhido no menu suspenso do seletor de idioma 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 todos os idiomas compatíveis do SDK, 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 de um método, a página "API Explorer" desse 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 para esse idioma vão ser listados primeiro.
Pode haver também exemplos em Ruby e Java, embora não sejam linguagens SDK.
Referências
A seção Referências de cada método e tipo inclui links para as páginas da API 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 Executar que abre um painel em que você pode solicitar chamadas de API e exibir as respostas em vários formatos compatíveis.
Quando você seleciona o botão Run It, o API Explorer exibe uma guia Request, onde é possível fornecer as entradas ao método da 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 será exibida e precisará 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 Código mostra a sintaxe de chamada do SDK para o 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 vai ser mostrada em todos os idiomas compatíveis do SDK, separadas por guias.
Tipos de exibição de resposta
As respostas da API Explorer incluem um tipo MIME que é 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, nesse caso, eles são exibidos em uma grade. Os cabeçalhos das colunas para a consulta do LookML são mostrados no formato <view_name>.<field_name>, em vez de mostrar 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 as configurações de visualização aplicadas. O próximo exemplo é a saída em PNG da mesma consulta mostrada anteriormente, mas usando uma visualização de tabela. O formato JPEG é processado da mesma forma.
SVG;
Alguns endpoints do Looker retornam SVG, que também tem suporte direto. Confira 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 do tipo MIME como texto simples são exibidas como texto simples na guia Resposta.
Como comparar versões da API
A API Explorer inclui uma página que permite comparar diferentes versões da API Looker para conferir 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 base da API e a versão da API que você quer comparar.
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 nas opções selecionadas. As opções são:
- Ausente: mostra todos os métodos que existem em uma versão da API e que estão faltando na outra.
- Status: mostra todos os métodos em que o status 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 foram alterados.
- Tipo: mostra os tipos que têm propriedades novas, removidas ou alteradas.
- Corpo: mostra 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á 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 exibirá uma comparação que mostra como o método mudou entre as versões.