Com o API Explorer do Looker, os usuários podem testar chamadas de API quase instantaneamente sem precisar escrever uma única linha de código. Se você instalou a extensão do API Explorer no Looker Marketplace, clique em API Explorer no menu Applications do Looker para abrir o API Explorer e conferir a documentação atual da API. Se você não tiver instalado a extensão do API Explorer, faça isso na seção Aplicativos do Marketplace do Looker.
Talvez, ao usar o API Explorer, você tenha descoberto o melhor fluxo de trabalho para criar dinamicamente um visual, atualizar a consulta subjacente e programá-la para várias partes interessadas na sua empresa. Uma pergunta comum é: como executar essas chamadas ou funções fora do API Explorer? Há três maneiras comuns de acessar a API:
- Kits de desenvolvimento de software (SDKs) da API do Looker
- Solicitações HTTP
- Ferramentas de desenvolvimento de software
Esta página mostra como usar esses métodos.
Antes de começar: autenticação e portas
Independentemente de como você acessa a API do Looker, primeiro é necessário ter duas informações: sua autenticação pessoal de API (na forma de um ID e uma chave secreta do cliente) e o número da porta que sua instância do Looker usa.
Para encontrar um ID e uma chave secreta do cliente:
- Se você for administrador do Looker, acesse a página Usuários na interface do Looker para o usuário de seu interesse e clique em Editar chaves.
- Se você não for um administrador do Looker, vai receber o ID e a chave secreta do cliente do administrador.
Para instâncias do Looker hospedadas no Google Cloud ou no Microsoft Azure e para instâncias hospedadas na Amazon Web Service (AWS) criadas em 07/07/2020 ou depois dessa data, o caminho padrão da API do Looker usa a porta 443. Para instâncias do Looker hospedadas na AWS que foram criadas antes de 07/07/2020, o caminho da API do Looker padrão usa a porta 19999.
Se você hospedar sua própria instância, verifique o número da porta com o administrador do sistema. Ela pode ser definida no campo URL do host da API do painel administrativo do Looker. Para conferir isso, acesse o menu suspenso Administrador no Looker e selecione API.
Para mais informações sobre portas, acesse a página de documentação Primeiros passos com a API Looker. Os exemplos a seguir usam uma porta de API de 19999, mas você precisa confirmar a porta usada pela sua instância.
Opção 1: usar um kit de desenvolvimento de software (SDK) do Looker
O Looker oferece SDKs oficiais de cliente da API do Looker em Python, Ruby, Typescript e JavaScript, Swift, Kotlin e R. Você pode encontrar o código-fonte e exemplos no repositório do GitHub sdk-examples do Looker.
Um SDK fornece ferramentas ou bibliotecas que permitem que os desenvolvedores interajam com uma determinada plataforma ou aplicativo. Nesse caso, os SDKs do Looker geralmente contêm APIs. Para usar um exemplo do desenvolvedor da Web e autor Kristopher Sandoval, "as APIs são linhas telefônicas, permitindo a comunicação dentro e fora da casa. O SDK é a casa e todo o conteúdo dela." Ele explica o que é um SDK e como ele se relaciona com as APIs em um ótimo artigo, Qual é a diferença entre uma API e um SDK?
Os SDKs do Looker contêm todos os endpoints de API que você quer ou precisa usar e são empacotados de uma forma que permite interagir com o Looker usando a linguagem de programação que você escolher. Com as funções, você pode realizar as seguintes tarefas:
- Enviar dados para o Looker
- Receber dados do Looker
- Atualizar dados no Looker
- Excluir dados no Looker
Confira um exemplo de como atualizar um usuário com o SDK do Python:
-
Inicialize a sessão com
looker_sdk.init. -
Atualize o usuário com
sdk.update_user. Você transmite ouser_idpara especificar qual usuário quer atualizar. -
Use
models.WriteUserpara especificar como você quer atualizar o usuário.
#### Initialize API/SDK for more info go here: https://pypi.org/project/looker-sdk
from looker_sdk import methods40, models
sdk = looker_sdk.init40()
me = sdk.me()
# print(me)
new_friend = sdk.update_user(user_id=29,
body=models.WriteUser(first_name="newnew", last_name="new_again"))
print(new_friend)
Ao usar um SDK, se você usar um ambiente de desenvolvimento integrado (IDE) como o Visual Studio Code e clicar com o botão direito do mouse (F12 nas configurações padrão do Visual Studio Code) e selecionar ir para definições, será possível conferir todos os métodos e parâmetros aceitos ou retornados pelos métodos. Ou você pode encontrá-las no repositório do SDK no GitHub. Procure métodos e arquivos de modelo.
Opção 2: solicitações HTTP com curl ou uma biblioteca de solicitações
E se você não quiser escrever um script ou passar meses ou anos aprendendo uma nova linguagem de programação? Nesse caso, use o curl para fazer solicitações HTTP e usar a API do Looker.
Uma solicitação HTTP envia uma mensagem para um destino, que pode ser um servidor, um smartphone ou até mesmo uma smart TV. Há alguns tipos diferentes de solicitações HTTP. A forma como você usa essas solicitações com a API do Looker depende da natureza do método transmitido como parte da chamada de API. Alguns métodos fornecem dados, outros os enviam ao Looker, outros os atualizam e outros ainda excluem ou removem dados do Looker.
| Ação | Método |
| Criar |
POST
|
| Ler |
GET
|
| Atualizar |
PUT
|
| Excluir |
DELETE
|
Vamos começar a jogar curling. Para saber mais, a Zendesk tem um ótimo tutorial, Instalar e usar o cURL.
Para começar a fazer chamadas HTTP para a API Looker, primeiro você precisa chamar o endpoint login da API Looker usando o ID e o segredo do cliente. Isso cria um token de acesso. Em seguida, você recebe esse token de acesso e o transmite em cada chamada. O token de acesso garante que a chamada esteja vindo de um usuário autorizado.
Esta página usa algumas notações para indicar onde você deve substituir o texto no exemplo de código pelas suas informações. Os URLs de instâncias hospedadas pelo Looker têm o formatohttps://<hostname>.<subdomain>.<domain>.com. Quando você encontrar essa notação nos exemplos desta página, substitua a seção<hostname>.<subdomain>.<domain>.compelo URL da sua instância do Looker. Além disso, usamos a notação<value>para indicar onde você deve inserir o valor apropriado, substituindo o<value>no exemplo de código. Por exemplo, no código abaixo, onde mostraclient_id=<value>&client_secret=<value>, substitua o primeiro<value>porclient_ide o segundo<value>porclient_secret.
Confira o curl para receber o token de acesso:
curl -d "client_id=<value>&client_secret=<value>" https://<hostname>.<subdomain>.<domain>.com:19999/login
Esta é a resposta:
{"access_token":"ABCDEFGHIJLMNOP1234","token_type":"Bearer","expires_in":3600}
O recebimento do token indica que o Looker reconhece suas credenciais da API. O token é retornado com um valor expires_in, que indica por quanto tempo ele é válido. Geralmente,é de cerca de 60 minutos (3.600 segundos).
Agora que você tem um token de acesso, pode fazer as chamadas que quiser. Todos os endpoints são listados por versão da API na documentação da referência da API Looker 4.0. O site da comunidade do Looker é um ótimo recurso para fazer perguntas a outros usuários do Looker sobre como eles usam a API, aprender as práticas recomendadas ou compartilhar os sucessos que você teve com a API com outros usuários.
Digamos que você queira criar um novo usuário. As etapas para fazer isso:
- Escreva uma solicitação
POSTdo curl que transmita seu token para informar ao Looker que você está autorizado. - Inclua um corpo, neste caso formatado como JSON, para informar ao Looker quais atributos você quer que o novo usuário tenha. Há alguns campos obrigatórios para chamadas de API. Consulte a documentação de referência da API Looker 4.0.
- Termine a notação do curl com o endpoint que você quer usar, neste caso,
users.
curl -H "Authorization: token <value>
" -H "Content-Type: application/json" -d "{\"first_name\": \"<value>\",\"last_name\": \"<value>\", \"email\":\"<value>\"}" https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/users
-H significa "cabeçalho", e -d significa "dados". Para mais informações sobre os comandos do curl, acesse este gist do GitHub (em inglês).
Você acabou de criar um usuário com o nome, sobrenome e endereço de e-mail que têm os valores que você inseriu anteriormente.
E se você quiser escrever isso em um script para não precisar digitar esses comandos toda vez que quiser concluir esse fluxo de trabalho? Você pode usar uma linguagem de programação e uma biblioteca, como a biblioteca requests do Python.
Por exemplo, este é um script que usa a biblioteca requests para receber um Look usando o ID do Look (<value> na chamada looks), aplicar um novo filtro e fazer o download dos resultados como um arquivo CSV:
import requests
ID = '<value>'
SECRET = '<value>'
PARAMS = {'client_id':<value>,
'client_secret': <value>}
URL = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/login"
r = requests.post(url = <value>, params = <value>, verify=False)
data = r.json()
token = data['access_token']
print(token)
headers = {'Authorization': "Bearer " + token}
print(headers)
look_url = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/looks/<value>"
look = requests.get(look_url, headers=headers, verify=False)
json = look.json()
query = json['query']
### ADD MODEL HERE
### ADD FILTER
body = {
"model":"<value>",
"view":query['view'],
"fields":query['fields'],
"filters":{<value>}
}
print(body)
run_inline = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/queries/run/csv"
run_query = requests.post(run_inline, headers = headers, json=body, verify=False)
print(run_query._content)
print(run_query.url)
Opção 3: ferramentas de desenvolvimento de software
Ferramentas como o Postman ou o Paw permitem que os usuários interajam ou aproveitem os endpoints da API por uma interface gráfica do usuário (GUI). O mesmo processo se aplica a uma ferramenta de desenvolvimento de software e a solicitações HTTP. A primeira etapa é fazer login com a chave secreta e o ID do cliente. Em seguida, armazene o token de acesso como um token do portador para autorizar as chamadas de API seguintes, conforme mostrado aqui no Postman.
O Postman ou outras ferramentas de desenvolvimento de software (como o Paw) permitem especificar a autorização, o corpo, os parâmetros e os cabeçalhos nas interfaces e gerar a solicitação para você. Elas também vão executar o endpoint quando você clicar em send.
Vá em frente! Mas tenha cuidado.
Agora que você pode usar a API do Looker com um SDK, uma solicitação HTTP e uma ferramenta de desenvolvimento de software, teste tudo. No entanto, o uso inadequado da API pode causar danos a uma instância, embora ela possa ajudar a automatizar processos, como criar ou reatribuir uma programação depois que um usuário sai da sua empresa.
Algumas informações gerais para lembrar:
- Tenha cuidado ao editar permissões ou excluir usuários, principalmente em massa. É possível excluir ou bloquear muitos usuários, incluindo administradores, e ações como essa não podem ser revertidas com facilidade.
- As chamadas de API aumentam o uso da instância. Por isso, tente programá-las fora do horário de pico para ter um desempenho ideal.
- Há um limite de arquivos abertos em cada servidor de instância. Portanto, é possível fazer com que uma instância falhe com o uso inadequado da API.
- Teste fluxos de trabalho e funções em pequena escala antes de adicioná-los à produção.
- Nunca compartilhe suas credenciais de API ou deixe-as em um arquivo que outros usuários possam acessar.
Se você tiver dúvidas ou quiser compartilhar uma ideia legal, confira a Comunidade do Looker. Se você tiver sugestões de melhorias ou outros exemplos que gostaria de adicionar à nossa documentação, entre em contato.