O Explorador de APIs do Looker é uma extensão, uma aplicação Web criada com componentes do Looker, que é desenvolvida através do framework de extensão do Looker e implementada através do Looker Marketplace.
O Explorador de APIs fornece os seguintes recursos para utilização com a API Looker:
- Documentação para todos os métodos e tipos da API Looker
- Declarações de métodos e tipos em todos os idiomas do SDK suportados
- Links para funções de exemplo do SDK que usam métodos de API
- Links para páginas do Explorador de APIs para métodos e tipos referenciados
- Uma função Run It que lhe permite executar chamadas de API diretamente e fornece o código para as chamadas de API, as respostas da API e as funções do SDK
- Uma ferramenta de comparação que mostra as diferenças nas versões da API Looker
O utilizador não tem de iniciar sessão na versão de extensão do Explorador de APIs, porque o Explorador de APIs usa a conta do utilizador ativo para pedidos de API. Isto garante que o utilizador só pode fazer as chamadas API às quais tem direito, ao mesmo tempo que elimina a necessidade de fornecer credenciais da API.
A funcionalidade sudo as another user do Looker também pode ser usada para fazer pedidos de API como um utilizador diferente para ajudar a diagnosticar problemas de acesso.
Instalar o Explorador de APIs
O Explorador de APIs está disponível no Marketplace do Looker.
Antes de instalar o API Explorer a partir do Marketplace, um administrador do Looker tem de ativar a funcionalidade Extension Framework.
A instalação de aplicações, como a extensão API Explorer, a partir do Marketplace requer que tenha as autorizações develop, manage_models e deploy. Depois de instalar o Explorador de APIs, qualquer utilizador com, pelo menos, a autorização access_data no modelo extension_api_explorer pode usar o Explorador de APIs. Cada utilizador pode ver todos os pontos finais da API no explorador de APIs, mas só pode executar os permitidos pelas respetivas autorizações.
Se o administrador do Looker tiver ativado a opção Instalação automática na página Marketplace na secção Plataforma do menu Administração do Looker, o Explorador de APIs é instalado automaticamente na sua instância. Além disso, sempre que estiverem disponíveis atualizações, estas são aplicadas automaticamente, o que garante que a versão do API Explorer na sua instância é a mais atual.
Se o administrador do Looker não tiver ativado a opção Instalação automática, tem de instalar o Explorador de APIs a partir do mercado do Looker.
Consulte a página de documentação Usar o mercado do Looker para ver instruções sobre como instalar uma extensão a partir do mercado do Looker. Pode garantir que tem sempre a versão mais atualizada do API Explorer acedendo ao Looker Marketplace, selecionando Gerir e selecionando o botão Atualizar junto à extensão.
Iniciar o Explorador de APIs
Depois de instalar o API Explorer, pode navegar para o mesmo a partir da secção Aplicações da barra lateral esquerda.
Navegar no Explorador de APIs
Na página inicial do Explorador de APIs, pode realizar as seguintes tarefas:
Use o menu pendente do seletor de idioma do SDK para escolher o idioma de programação no qual o API Explorer vai apresentar o método da API, as declarações de tipo e os resultados do código. O seletor é predefinido para Python no carregamento inicial. Se escolher Tudo no seletor de idiomas, o API Explorer apresenta uma vista com separadores para cada idioma suportado.
Use o menu pendente 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.
Introduza um termo de pesquisa no campo Pesquisar para limitar os Métodos e os Tipos apresentados apenas aos que incluem texto que corresponde ao seu termo de pesquisa.
Quando seleciona um método ou um tipo devolvido pela pesquisa, o termo de pesquisa é realçado no resumo do método ou do tipo.
Selecione o separador Métodos para apresentar as categorias de métodos da API. Pode expandir ou reduzir uma categoria de métodos para ver os métodos individuais na categoria.
Selecione o separador Tipos para apresentar os tipos de API. Os tipos não estão categorizados e são apresentados por ordem alfabética.
Selecione o botão Menu principal para ocultar ou mostrar o painel de navegação do Explorador de APIs.
Ver a documentação do método e do tipo da API
Quando seleciona uma categoria de método no separador Método, a categoria de método é expandida e mostra todos os métodos que pertencem a essa categoria.
Todos os métodos que estão nessa categoria são apresentados no painel principal. Pode optar por apresentar todos os métodos que se encontram na categoria ou selecionar o separador de um determinado tipo de método para filtrar a lista apenas para esse tipo de método.
Para ver 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 apresenta a documentação desse método.
Quando seleciona um tipo no separador Tipo, a documentação desse tipo é apresentada no painel principal.
Declarações de método e tipo
O API Explorer renderiza o método e as declarações de tipo do SDK no idioma do SDK escolhido no menu pendente do seletor de idioma do SDK. Se o seletor de idioma do SDK estiver definido como Todos, as declarações de métodos e tipos são apresentadas em todos os idiomas do SDK suportados, separadas por separadores.
Exemplos de SDK
O sdk-codegenrepositório do Looker tem uma pasta que contém exemplos do SDK do Looker. Se o repositório sdk-codegen tiver exemplos para um método, a página do Explorador de APIs do método apresenta uma secção Exemplos do SDK com links para os exemplos.
Se for selecionado um idioma de SDK específico, os exemplos para esse idioma são apresentados primeiro.
Também podem ser apresentados exemplos em Ruby e Java, embora estes não sejam idiomas do SDK.
Referências
A secçã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.
Usar o Run It para pedir e apresentar chamadas API
O API Explorer inclui um botão Executar que abre um painel a partir do qual pode pedir chamadas API e apresentar as respostas numa variedade de formatos suportados.
Quando seleciona o botão Executar, o API Explorer apresenta um separador Pedido, onde pode fornecer as entradas para o método da API.
Introduza a entrada pretendida e selecione Executar para executar a chamada da API.
Sempre que o método API puder alterar dados (para qualquer chamada REST que seja um
POST, umPATCH, umUPDATEou umDELETE), a caixa de verificação de confirmação de alteração de dados é apresentada e tem de ser selecionada antes de o pedido poder ser executado.
Quando o pedido é executado, o separador Resposta mostra os resultados.
Além disso, o separador Código mostra a sintaxe de chamada do SDK para o SDK escolhido no menu pendente do seletor de idiomas. Se o seletor de idioma do SDK estiver definido como Todos, a sintaxe de chamada do SDK é apresentada em todos os idiomas do SDK suportados, separados por separadores.
Tipos de visualização de respostas
As respostas do API Explorer incluem um tipo MIME que é usado para determinar como apresentar os resultados.
CSV e outros dados tabulares
Para dados CSV e JSON, o Looker executa um teste de forma para determinar se os dados cumprem os critérios de uma tabela. Se o Looker determinar que os dados da carga útil são tabulares, a apresentação predefinida da resposta é uma grelha de dados.
Selecione o separador Não processados para apresentar os dados não transformados.
JSON
Os payloads JSON podem ser tabulares, caso em que são apresentados numa grelha. Os cabeçalhos das colunas da consulta LookML são apresentados no formato <view_name>.<field_name>, em vez de apresentarem a etiqueta do campo.
Os payloads JSON complexos omitem a apresentação em grelha e mostram apenas o JSON não processado.
PNG e JPEG
Os formatos PNG e JPEG apresentam a visualização selecionada para a consulta e incluem todas as definições de visualização aplicadas. O exemplo seguinte é a saída PNG da mesma consulta apresentada anteriormente, mas com uma visualização de tabela. O JPEG é processado de forma semelhante.
SVG
Alguns pontos finais do Looker devolvem SVG, que também é suportado diretamente. Segue-se um exemplo do ponto final content_thumbnail no formato SVG, que devolve uma imagem de miniatura abstrata de um painel de controlo.
HTML
Os pedidos que devolvem código-fonte HTML apresentam o HTML de origem no separador Resposta.
Texto
Os pedidos que devolvem SQL ou outros formatos com o tipo MIME texto/simples são apresentados como texto simples no separador Resposta.
Comparar versões da API
O API Explorer inclui uma página que lhe permite comparar diferentes versões da API Looker para ver o que mudou entre as versões. 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 quer comparar com a versão base.
Selecione as opções da API que quer incluir na comparação para filtrar os métodos apenas para aqueles que têm diferenças nas opções que selecionar. As opções são as seguintes:
- Em falta: mostra todos os métodos que existem numa versão da API e que estão em falta na outra.
- Estado: mostra todos os métodos em que o estado do método foi alterado. Por exemplo, um método em que o estado foi alterado 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 que têm propriedades novas, removidas ou alteradas.
- Corpo: mostra as alterações aos 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 existe uma diferença e apresenta os métodos em que existe uma diferença.
Selecione um método para o expandir e a página de comparação apresenta uma diferença que mostra como o método mudou entre as versões.