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 Aplicativos do Looker para abrir o API Explorer e conferir a documentação atual da API. Se você ainda não instalou a extensão do API Explorer, faça isso na seção Aplicativos do Looker Marketplace.
Talvez usando o APIs Explorer, você tenha descoberto o melhor fluxo de trabalho para criar um Look de forma dinâmica, atualizar a consulta subjacente e programá-la para vários stakeholders na sua empresa. Uma próxima pergunta comum é: como faço para 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
Nesta página, mostramos como usar esses métodos.
Antes de começar: autenticação e portas
Independente de como você acessa a API do Looker, primeiro é necessário ter duas informações: sua autenticação pessoal da API (na forma de um ID e uma chave secreta do cliente) e o número da porta usada pela sua instância do Looker.
Para encontrar um ID e uma chave secreta do cliente:
- Se você for um administrador do Looker, acesse a página Usuários na interface do Looker para o usuário em questão e clique em Editar chaves.
- Se você não for um administrador do Looker, vai receber seu ID do cliente e chave secreta do cliente do administrador do Looker.
Para instâncias do Looker hospedadas no Google Cloud ou no Microsoft Azure e para instâncias hospedadas no Amazon Web Service (AWS) criadas a partir de 07/07/2020, o caminho padrão da API Looker usa a porta 443. Para instâncias do Looker hospedadas na AWS e criadas antes de 07/07/2020, o caminho padrão da API Looker usa a porta 19999.
Se você hospedar sua própria instância, verifique com o administrador do sistema o número da porta. Ele pode ser definido no campo URL do host da API do painel de administração 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 Como começar a usar a API Looker. Os exemplos a seguir usam uma porta de API 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 de cliente da API oficial do Looker em Python, Ruby, Typescript e JavaScript, Swift, Kotlin e R. Você pode encontrar o código-fonte e exemplos no repositório sdk-examples do GitHub do Looker.
Um SDK fornece ferramentas ou bibliotecas que permitem aos desenvolvedores interagir com uma determinada plataforma ou aplicativo. Nesse caso, os SDKs do Looker geralmente contêm APIs. Para usar um exemplo do desenvolvedor e autor da Web Kristopher Sandoval, "as APIs são linhas telefônicas, permitindo a comunicação dentro e fora da casa. O SDK é a casa em si e todo o conteúdo dela". Ele explica o que é um SDK e como isso 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ê pode querer ou precisar usar, e eles são empacotados de maneira que permite interagir com o Looker usando a linguagem de programação de sua escolha. Com as funções, é possível realizar as seguintes tarefas:
- Enviar dados para o Looker
- Extrair 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 dos nossos SDKs, se você usar uma 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, poderá ver todos os métodos e parâmetros aceitos ou retornados por eles. Ou consulte o repositório do SDK no GitHub para encontrar 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 curl para fazer solicitações HTTP e utilizar 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 enviam dados para o Looker, outros atualizam dados e outros excluem ou removem dados do Looker.
| Ação | Método |
| Criar |
POST
|
| Ler |
GET
|
| Atualizar |
PUT
|
| Excluir |
DELETE
|
Vamos começar a fazer curling. Para mais informações, o Zendesk tem um ótimo tutorial, Instalar e usar cURL (em inglês).
Para começar a fazer chamadas HTTP para a API Looker, a primeira coisa que você precisa fazer é chamar o endpoint login da API Looker usando seu ID e sua chave secreta do cliente. Isso cria um token de acesso. Em seguida, pegue esse token de acesso e transmita-o com cada chamada. O token de acesso garante que a chamada está 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ê vir 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 adequado, substituindo o<value>no exemplo de código. Por exemplo, no código a seguir, onde aparececlient_id=<value>&client_secret=<value>, substitua o primeiro<value>pelo seuclient_ide o segundo<value>pelo seuclient_secret.
Este é 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}
Receber o token significa 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, já pode fazer chamadas. Todos os endpoints estão listados por versão da API na documentação de referência da API Looker 4.0. Não se esqueça de que o site da comunidade do Looker é um ótimo recurso para perguntar a outros usuários do Looker como eles aproveitam a API, aprender práticas recomendadas ou compartilhar sucessos que você teve com a API com outros usuários.
Digamos que você queira criar um novo usuário. Para fazer isso:
- Escreva uma solicitação curl
POSTque 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 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
O -H significa cabeçalho, e o -d significa dados. Para mais informações sobre comandos curl, acesse este gist do GitHub.
Você acabou de criar um usuário com o nome, sobrenome e endereço de e-mail que têm os valores inseridos 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, aqui está um script que usa a biblioteca requests para receber uma análise usando o ID dela (o <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 Postman ou Paw permitem que os usuários interajam ou aproveitem os endpoints de API por meio de 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 sua chave secreta e ID do cliente. Em seguida, armazene o token de acesso como um token de portador para autorizar as chamadas de API a seguir, 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ê. Eles também vão executar o endpoint quando você clicar em Enviar.
Vá em frente! (Mas tome 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 danificar uma instância, embora ela possa ajudar a automatizar processos como criar ou reatribuir uma programação depois que um usuário sai da empresa.
Algumas coisas gerais a serem lembradas:
- Tenha cuidado ao editar permissões ou excluir usuários, principalmente em massa. É possível excluir ou bloquear muitos usuários, incluindo administradores, e essas ações não podem ser revertidas com facilidade.
- As chamadas de API aumentam o uso da instância. Portanto, tente programá-las para horários de folga e ter um desempenho ideal.
- Há um limite de arquivos abertos em cada servidor de instância. Portanto, é possível falhar uma instância com o uso irresponsável da API.
- Teste fluxos de trabalho e funções em pequena escala antes de adicioná-los à produção.
- Nunca compartilhe suas credenciais de API nem as deixe em um arquivo em que outros usuários possam acessá-las.
Se você tiver uma dúvida ou quiser compartilhar uma ideia legal, acesse a Comunidade do Looker. Entre em contato se tiver alguma sugestão de melhoria ou outros exemplos que você gostaria de adicionar à nossa documentação.