Através do API Explorer do Looker, os utilizadores podem testar chamadas API quase instantaneamente sem terem de escrever uma única linha de código. Se instalou a extensão API Explorer a partir do Looker Marketplace, pode clicar em API Explorer no menu Aplicações do Looker para abrir o API Explorer e ver a documentação da API atual. Se não tiver instalado a extensão API Explorer, pode instalá-la na secção Aplicações do Looker Marketplace.
Talvez, através da utilização do API Explorer, tenha descoberto o melhor fluxo de trabalho para criar dinamicamente um visual, atualizar a consulta subjacente e agendá-lo para várias partes interessadas na sua empresa. Uma pergunta seguinte comum é: como posso executar estas chamadas ou funções fora do API Explorer? Existem três formas comuns de aceder à API:
- Kits de desenvolvimento de software (SDKs) da API Looker
- Pedidos HTTP
- Ferramentas de programação de software
Esta página explica como usar estes métodos.
Antes de começar: autenticação e portas
Independentemente da forma como acede à API do Looker, precisa primeiro de duas informações: a sua autenticação pessoal da API (sob a forma de um ID do cliente e um segredo do cliente) e o número da porta que a sua instância do Looker usa.
Para encontrar um ID de cliente e um segredo do cliente:
- Se for administrador do Looker, visite a página Utilizadores na IU do Looker para o utilizador no qual tem interesse e aceda a Editar chaves.
- Se não for um administrador do Looker, recebeu o ID de cliente e o segredo do cliente do seu administrador do Looker.
Para instâncias do Looker alojadas no Google Cloud ou no Microsoft Azure, e para instâncias alojadas no Amazon Web Service (AWS) criadas a 07/07/2020 ou após essa data, o caminho da API Looker predefinido usa a porta 443. Para instâncias do Looker alojadas na AWS que foram criadas antes de 07/07/2020, o caminho da API Looker predefinido usa a porta 19999.
Se alojar a sua própria instância, verifique o número da porta junto do administrador de sistemas. Pode ser definido no campo URL do anfitrião da API do painel de administração do Looker. Pode ver esta situação acedendo ao menu pendente Administração no Looker e selecionando API.
Para mais informações sobre as portas, aceda à página de documentação Introdução à API Looker. Os exemplos seguintes usam uma porta da API de 19999, mas deve confirmar a porta usada pela sua instância.
Opção 1: use um software development kit (SDK) do Looker
O Looker oferece SDKs de cliente da API Looker oficiais em Python, Ruby, Typescript e JavaScript, Swift, Kotlin e R. Pode encontrar o código fonte e exemplos no sdk-examplesrepositório do GitHub do Looker.
Um SDK fornece ferramentas ou bibliotecas que permitem aos programadores interagir com uma determinada plataforma ou aplicação. Neste caso, os SDKs do Looker contêm geralmente APIs. Para usar um exemplo do programador Web e autor Kristopher Sandoval, "as APIs são linhas telefónicas que permitem a comunicação dentro e fora da casa. O SDK é a própria casa e todo o respetivo conteúdo." Ele explica o que é um SDK e como se relaciona com as APIs num excelente artigo, Qual é a diferença entre uma API e um SDK?
Os SDKs do Looker alojam todos os pontos finais da API que pode querer ou precisar de usar e são incluídos num pacote de forma a permitir-lhe interagir facilmente com o Looker através da linguagem de programação da sua escolha. As funções permitem-lhe realizar as seguintes tarefas:
- Envie dados para o Looker
- Obtenha dados do Looker
- Atualize dados no Looker
- Elimine dados no Looker
Segue-se um exemplo de como pode atualizar um utilizador com o SDK Python:
-
Inicialize a sessão com
looker_sdk.init. -
Atualize o utilizador com
sdk.update_user. Transmite o elementouser_idpara especificar o utilizador que quer atualizar. -
Use
models.WriteUserpara especificar como quer atualizar o utilizador.
#### 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 dos nossos SDKs, se usar um IDE como o Visual Studio Code e clicar com o botão direito do rato (F12 nas predefinições do Visual Studio Code) e, em seguida, selecionar aceder às definições, pode ver todos os métodos e todos os parâmetros aceites ou devolvidos pelos métodos. Em alternativa, pode vê-los no repositório GitHub do SDK. Procure métodos e ficheiros de modelos.
Opção 2: pedidos HTTP com curl ou uma biblioteca de pedidos
E se não quiser escrever um script nem passar meses ou anos a aprender uma nova linguagem de programação? Nesse caso, pode usar o curl para fazer pedidos HTTP e usar a API do Looker.
Um pedido HTTP envia uma mensagem para um destino, que pode ser um servidor, um telemóvel ou até mesmo a sua smart TV. Existem alguns tipos diferentes de pedidos HTTP. A forma como usa estes pedidos com a API do Looker depende da natureza do método que transmite como parte da chamada API. Alguns métodos fornecem dados, alguns enviam dados para o Looker, alguns atualizam dados e alguns eliminam ou removem dados do Looker.
| Ação | Método |
| Criar |
POST
|
| Ler |
GET
|
| Atualizar |
PUT
|
| Eliminar |
DELETE
|
Vamos começar a fazer curling. Para saber mais, o Zendesk tem um excelente tutorial, Instalar e usar o cURL.
Para começar a fazer chamadas HTTP para a API Looker, a primeira coisa que tem de fazer é chamar o ponto final login da API Looker com o ID do cliente e o segredo do cliente. Esta ação cria um token de acesso. Em seguida, recebe este token de acesso e transmite-o com cada chamada. O token de acesso garante que a chamada é proveniente de um utilizador autorizado.
Esta página usa algumas notações para indicar onde deve substituir o texto no exemplo de código pelas suas informações. Os URLs de instâncias alojadas no Looker têm o formatohttps://<hostname>.<subdomain>.<domain>.com. Quando vir esta notação nos exemplos desta página, substitua a secção<hostname>.<subdomain>.<domain>.compelo URL da sua instância do Looker. Além disso, usamos a notação<value>para indicar onde deve introduzir o valor adequado, substituindo o<value>no exemplo de código. Por exemplo, no código seguinte, onde é apresentadoclient_id=<value>&client_secret=<value>, substitua o primeiro<value>pelo seuclient_ide o segundo<value>pelo seuclient_secret.
Segue-se o comando curl para obter o token de acesso:
curl -d "client_id=<value>&client_secret=<value>" https://<hostname>.<subdomain>.<domain>.com:19999/login
Aqui está a resposta:
{"access_token":"ABCDEFGHIJLMNOP1234","token_type":"Bearer","expires_in":3600}
A receção do token indica que o Looker reconhece as suas credenciais da API. O token é devolvido com um valor expires_in, que indica durante quanto tempo o token é válido. Geralmente,é de cerca de 60 minutos (3600 segundos).
Agora que tem um token de acesso, pode fazer as chamadas que quiser. Todos os pontos finais estão listados por versão da API na documentação de referência da API Looker 4.0. Lembre-se de que o site da comunidade do Looker é um excelente recurso para fazer perguntas a outros utilizadores do Looker sobre como tiram partido da API, para aprender práticas recomendadas ou para partilhar sucessos que teve com a API com outros utilizadores.
Suponhamos que quer criar um novo utilizador. Para o fazer:
- Escreva um pedido curl
POSTque transmita o seu token para informar o Looker de que tem autorização. - Inclua um corpo, neste caso formatado como JSON, para indicar ao Looker os atributos que quer que o novo utilizador tenha. (Existem alguns campos obrigatórios para chamadas da API, por isso, consulte a documentação de referência da API Looker 4.0.)
- Termine a notação curl com o ponto final que 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
O -H significa cabeçalho e o -d significa dados. Para mais informações sobre comandos curl, aceda a este gist do GitHub.
Acabou de criar um utilizador com o nome próprio, o apelido e o endereço de email que têm os valores que introduziu anteriormente.
E se quiser escrever isto num script para não ter de escrever estes comandos sempre que quiser concluir este fluxo de trabalho? Pode usar uma linguagem de programação e uma biblioteca como a biblioteca requests do Python.
Por exemplo, segue-se um script que usa a biblioteca requests para obter um Look através do ID do Look (o <value> na chamada looks), aplicar um novo filtro e, em seguida, transferir os resultados como um ficheiro 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 programação de software
Ferramentas como o Postman ou o Paw permitem que os utilizadores interajam ou tirem partido dos pontos finais da API através de uma interface gráfica do utilizador (GUI). O mesmo processo aplica-se a uma ferramenta de desenvolvimento de software, tal como se aplica a pedidos HTTP. O primeiro passo é iniciar sessão com o segredo do cliente e o ID de cliente. Em seguida, armazene o token de acesso como um token de autorização para autorizar as chamadas API seguintes, conforme mostrado aqui no Postman.
O Postman ou outras ferramentas de desenvolvimento de software (como o Paw) permitem-lhe especificar a autorização, o corpo, os parâmetros e os cabeçalhos nas respetivas IUs e, em seguida, gerar o pedido por si. Também executam o ponto final quando toca em enviar.
Avançar! (Mas tenha cuidado)
Agora que pode usar a API do Looker através de um SDK, um pedido HTTP e uma ferramenta de desenvolvimento de software, avance e experimente! No entanto, tenha em atenção que, embora a utilização da API possa ajudar a automatizar processos como a criação ou a reatribuição de um horário após um utilizador sair da sua empresa, a utilização inadequada da API pode danificar uma instância.
Alguns aspetos gerais a ter em conta:
- Tenha cuidado ao editar autorizações ou eliminar utilizadores, especialmente em massa. É possível eliminar ou bloquear muitos utilizadores, incluindo administradores, e não é fácil reverter ações como esta.
- As chamadas API aumentam a utilização de instâncias, por isso, tente agendá-las para horas fora do horário de expediente para um desempenho ideal.
- Existe um limite de ficheiros abertos em cada servidor de instância, pelo que é possível falhar uma instância através de uma utilização irresponsável da API.
- Teste fluxos de trabalho e funções em pequena escala antes de os adicionar à produção.
- Nunca partilhe as suas credenciais da API nem as deixe num ficheiro onde outros utilizadores possam aceder às mesmas.
Se tiver uma pergunta ou quiser partilhar uma ideia interessante, consulte a comunidade do Looker. Não hesite em contactar-nos se houver algo que possamos melhorar ou se quiser adicionar outros exemplos à nossa documentação.