Esta é a documentação do Looker. Para conferir a documentação do Looker Studio, acesse https://support.google.com/looker-studio.

Domine o API Explorer do Looker. E agora?

Com o API Explorer do Looker, os usuários podem testar chamadas de API quase instantaneamente sem precisar escrever uma linha de código sequer. Se você instalou a extensão API Explorer pelo Looker Marketplace, clique em API Explorer no menu Aplicativos do Looker para abrir a API Explorer e conferir a documentação atual da API. Se você não tiver instalado a extensão da API Explorer, poderá fazer o download dela na seção Aplicativos do Looker Marketplace.

Talvez usando o API Explorer, você tenha descoberto o melhor fluxo de trabalho para criar dinamicamente um Look, atualizar a consulta subjacente e programá-lo para várias partes interessadas 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

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 você precisa de duas informações: a autenticação da API pessoal (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ê é um administrador do Looker, acesse a página Usuários na interface do Looker para o usuário em que você tem interesse e clique em Editar chaves.
Caso não seja um administrador do Looker, você vai receber o ID e a chave secreta do cliente do administrador do Looker.

O mais importante a ser lembrado sobre o ID e a chave secreta do cliente é não compartilhar essas chaves com ninguém.

Para instâncias do Looker hospedadas no Google Cloud ou no Microsoft Azure e na 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 o número da porta com o administrador do sistema. Ele pode ser definido no campo URL do host da API do painel de administração do Looker. Para isso, acesse o menu suspenso Administrador no Looker e selecione API.

Para mais informações sobre portas, acesse a página de documentação Introdução à API Looker. Os exemplos a seguir usam uma porta de API de 19999, mas você deve confirmar a porta que está sendo usada pela sua instância.

Opção 1: usar um kit de desenvolvimento de software (SDK) do Looker

O Looker oferece SDKs oficiais do cliente da API Looker em Python, Ruby, Typescript e JavaScript, Swift, Kotlin e R. O código-fonte e exemplos estão disponíveis no repositório do sdk-examples no GitHub (em inglês) 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, "APIs são linhas telefônicas que permitem a comunicação dentro e fora de casa. O SDK é a própria casa e todo o seu conteúdo." Ele explica o que é um SDK e como isso se relaciona com APIs em um ótimo artigo, Qual é a diferença entre uma API e um SDK?

Os SDKs do Looker armazenam todos os endpoints de API que você pode querer ou precisar usar. Além disso, eles são empacotados de uma maneira que permite uma interação tranquila com o Looker usando a linguagem de programação que você escolher. As funções permitem que você execute as seguintes tarefas:

Enviar dados para o Looker
Receber dados do Looker
Atualizar dados no Looker
Excluir dados no Looker

Os detalhes mais granulares das diferenças entre essas ações serão discutidos na próxima seção.

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 o user_id para especificar qual usuário você quer atualizar.
Use models.WriteUser para 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 um ambiente de desenvolvimento integrado como o Visual Studio Code, clicar com o comando (F12 nas configurações padrão do Visual Studio Code) e selecionar acessar definições, poderá ver todos os métodos e parâmetros aceitos ou retornados pelos métodos. Também é possível consultar o 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 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 telefone ou até mesmo sua 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 ao Looker, alguns atualizam e outros excluem ou removem dados do Looker.

Ação	Método
Criar	`POST`
Ler	`GET`
Atualizar	`PUT`
Excluir	`DELETE`

Vamos começar o curl. Para entender melhor, o Zendesk tem um tutorial excelente, Como instalar e usar o cURL.

Para começar a fazer chamadas HTTP à API Looker, a primeira coisa a fazer é chamar o endpoint login da API Looker usando seu ID e chave secreta do cliente. Isso cria um token de acesso. Em seguida, transmita esse token de acesso a cada chamada. O token de acesso garante que a chamada seja proveniente de um usuário autorizado.

Esta página usa algumas anotaçõ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 formato https://<hostname>.<subdomain>.<domain>.com. Onde você vê essa notação nos exemplos desta página, substitua a seção <hostname>.<subdomain>.<domain>.com pelo URL da sua instância do Looker. Além disso, usamos a notação <value> para indicar onde você precisa inserir o valor apropriado, substituindo <value> no exemplo de código. Por exemplo, no código abaixo, em que ele mostra client_id=<value>&client_secret=<value>, substitua o primeiro <value> pelo client_id e o segundo <value> pelo client_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}

O recebimento do token informa que o Looker reconhece suas credenciais da API. O token é retornado com um valor expires_in, que indica por quanto tempo o token é válido. Geralmente,é em torno de 60 minutos (3.600 segundos).

Agora que você tem um token de acesso, é possível fazer as chamadas que quiser. Todos os endpoints estão listados por versão da API na documentação de referência da API Looker 4.0 (em inglês). Não se esqueça que 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 práticas recomendadas ou compartilhar sucessos com a API.

Digamos que você queira criar um novo usuário. Para isso, siga estas etapas:

Escreva uma solicitação POST em curl que transmite seu token para informar ao Looker que você tem autorização.
Inclua um corpo, neste caso formatado como JSON, para informar ao Looker quais atributos você quer que o novo usuário tenha. Existem alguns campos obrigatórios para chamadas de API. Portanto, consulte a documentação de referência da API Looker 4.0.
Encerre 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 -d significa dados. Para mais informações sobre comandos curl, acesse este gist do GitHub (em inglês).

Você acabou de criar um usuário com o nome, o sobrenome e o endereço de e-mail com os valores inseridos anteriormente.

E se você quiser escrever isso em um script para não precisar escrever esses comandos sempre que quiser concluir o fluxo de trabalho? É possível usar uma linguagem de programação e uma biblioteca, como a biblioteca requests do Python (link em inglês).

Por exemplo, este script usa a biblioteca requests para acessar um Look usando o ID do Look (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 o Postman ou Paw permitem que os usuários interajam ou aproveitem os endpoints de API por uma interface gráfica do usuário (GUI). O mesmo processo se aplica a uma ferramenta de desenvolvimento de software e às 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 que se seguem, como mostrado aqui no Postman.

A GUI do Postman, preenchida com um URL POST do Looker, uma chave secreta e um ID do cliente.

O Postman ou outras ferramentas de desenvolvimento de software (como o Paw) permitem que você especifique a autorização, o corpo, os parâmetros e os cabeçalhos na IU e gere a solicitação para você. Eles também executam o endpoint quando você clica em send.

Vamos lá! (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, faça testes. No entanto, saiba que, embora o uso da API possa ajudar a automatizar processos, como a criação ou reatribuição de uma programação depois que um usuário sai da empresa, o uso indevido da API pode causar danos a uma instância.

Alguns lembretes gerais:

Tenha cuidado ao editar permissões ou excluir usuários, principalmente em massa. É possível excluir ou bloquear muitos usuários, inclusive administradores, e ações como essa não podem ser facilmente revertidas.
As chamadas de API aumentam o uso da instância, portanto, tente programá-las para horários de folga para ter o desempenho ideal.
Há um limite de arquivos abertos em cada servidor da instância, então é possível causar uma falha em uma instância devido ao 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 que possa ser acessado por outros usuários.

Se você tiver alguma dúvida ou quiser compartilhar uma ideia legal, confira a Comunidade do Looker. Avise se houver algo que podemos melhorar ou se você gostaria de adicionar outros exemplos à nossa documentação.