Como compartilhar dados em um hub de ações

Além de fornecer conteúdo para os destinos integrados do Looker, você pode usar ações, também conhecidas como integrações, para enviar conteúdo para serviços de terceiros integrados ao Looker usando um servidor de hub de ações.

As ações veiculadas por meio de um servidor de hub de ações são diferentes das ações de dados, que são definidas pelo parâmetro LookML action.

Esta página mostra as opções para criar ações personalizadas que podem ser solicitadas para adicionar ao Looker Action Hub ou adicionar seu próprio servidor do hub de ações privadas. Nesta página, também descrevemos como ativar um servidor de hub de ações local para testar suas ações personalizadas ou executar um servidor de hub de ação particular.

Para começar a usar ações, você pode:

• Use as ações disponíveis do Looker no Hub de ações do Looker.
• Crie e publique uma ação personalizada no Hub de ação do Looker para uso público.
• Crie e publique uma ação personalizada em um servidor do hub de ações privadas para uso particular.

Depois que a ação é adicionada ao hub de ações, um administrador do Looker pode ativá-la para uso na exibição de conteúdo do Looker nesses serviços.

Você também pode configurar vários hubs de ações se quiser usar as integrações do Looker pelo hub de ações do Looker e também hospedar suas próprias ações privadas ou personalizadas. As ações para cada hub de ações seriam exibidas na página Ações do painel Administrador.

Hub de ações do Looker

O Looker hospeda e fornece o Looker Action Hub, um servidor sem estado que implementa a API Looker Action e expõe ações populares. Todos os dados enviados pelos usuários usando uma ação serão processados temporariamente no servidor do hub de ações do Looker, e não na instância do Looker.

O Looker já está integrado a vários serviços. Consulte a página de documentação Configurações do administrador: ações para saber como ativar esses serviços.

Requisitos do Looker Action Hub

Para usar as integrações do Looker, o hub de ações do Looker precisa se comunicar com a instância do Looker e atender a estes requisitos. Os administradores de instâncias hospedadas pelo cliente talvez precisem considerar outros fatores ao ativar as integrações do Looker no hub de ações do Looker, principalmente as integrações compatíveis com os resultados transmitidos ou que usam o OAuth.

O hub de ações do Looker precisa ser capaz de enviar e receber solicitações de API das seguintes maneiras:

• Da instância do Looker para a rede do Looker Action Hub
• Do navegador do usuário do Looker para a rede do hub de ações do Looker
• Da rede do Looker Action Hub para a instância do Looker

Se a implantação do Looker não atender a essas solicitações ou se o recurso de lista de permissões de IP estiver ativado na instância do Looker, considere configurar um servidor de hub de ações local para exibir integrações do Looker ou ações personalizadas particulares. Os administradores de instâncias hospedadas pelo cliente também podem implantar um servidor de ação local especificamente para ações de OAuth e streaming.

Solicitações da instância do Looker para a rede do Looker Action Hub

As solicitações para actions.looker.com são resolvidas em um endereço IP dinâmico. As solicitações enviadas da instância do Looker precisam ser capazes de atingir os seguintes endpoints:

actions.looker.com/
actions.looker.com/actions/<name>/execute
actions.looker.com/actions/<name>/form

em que name é o nome programático da ação.

Solicitações do navegador do usuário do Looker para a rede do hub de ações do Looker.

O navegador do usuário do Looker precisa fazer solicitações para os endpoints do hub de ações do Looker para OAuth:

actions.looker.com/actions/<name>/oauth

em que name é o nome programático da ação.

Solicitações da rede do Looker Action Hub para a instância do Looker

O hub de ações do Looker precisa fazer solicitações à instância do Looker para ações que oferecem suporte a resultados transmitidos ou que usam OAuth.

Uma ação de streaming permite que a consulta consuma consultas que mostram Todos os resultados. As ações ativadas por OAuth usam autenticação por usuário com fluxos do OAuth 2.0. As ações do OAuth precisam armazenar as credenciais do usuário na instância do Looker de origem porque o hub de ações do Looker é sem estado e multilocatário e não armazena credenciais específicas do usuário.

As solicitações do hub de ações do Looker para uma instância do Looker têm os seguintes formatos:

GET <host_looker_url>/downloads/<random_40_char_token>
POST <host_looker_url>/action_hub_state/<random_40_char_token>

Esses URLs são gerados no local na instância do Looker antes de serem enviados ao hub de ações do Looker. Por isso, o Looker Action Hub precisa ser capaz de resolver <host_looker_url> para um endereço IP e fazer solicitações na rede em que a instância do Looker está localizada.

O hub de ações do Looker tem endereços IP de saída estáticos de onde as solicitações sempre virão: 35.153.89.114, 104.196.138.163 e 35.169.42.87. Os administradores de instâncias hospedadas pelo Looker que ativaram a lista de permissões de IP precisam adicionar esses endereços IP para usar ações compatíveis com os resultados transmitidos ou que usem o OAuth.

Considerações sobre instâncias hospedadas pelo cliente

Para usar as integrações do Looker, o hub de ações do Looker precisa se comunicar com a instância do Looker e atender a estes requisitos. Isso nem sempre é possível com as instâncias do Looker hospedadas pelo cliente, por vários motivos. Se a comunicação bidirecional entre o hub de ações do Looker e a instância do Looker não for possível, o hub de ações do Looker poderá apresentar comportamentos inesperados ou indesejados, como consultas pendentes ou ações indisponíveis.

Para resolver o possível problema do Looker Action Hub e não conseguir se comunicar com a instância do Looker, os administradores do Looker podem implementar uma das soluções apresentadas abaixo. A solução adequada ou a combinação delas depende da arquitetura da instância do Looker:

• Se a instância hospedada pelo cliente não puder ser resolvida pelo Looker Action Hub, ou seja, ele não poderá receber solicitações da instância, os administradores do Looker poderão consultar o gerente da conta do Looker para ativar o recurso de licença public_host_url. Esse recurso revela a opção de inicialização --public-host-url, que permite aos administradores especificar um nome de host <public_host_url> resolvido que seja diferente da instância <host_looker_url>. O public_host_url substitui o nome do host de alguns URLs de callback específicos do Looker Action Hub e os encaminha por um proxy reverso com o public_host_url como um nome que pode ser resolvido publicamente. Esse proxy reverso aceita somente solicitações dos endereços IP de saída estáticos do Looker Action Hub. Os administradores do Looker que usam esse método precisam adicionar à lista de permissões os endereços IP de saída dos quais o Looker Action Hub faz solicitações para a instância do Looker: 35.153.89.114, 104.196.138.163 e 35.169.42.87.

• Se o URL da instância hospedada pelo cliente for resolvido pela instância do Looker, mas o hub de ações do Looker não puder enviar solicitações à instância do Looker, talvez os usuários não consigam configurar ou usar ações que oferecem suporte a resultados transmitidos ou que usem o OAuth. Para resolver isso, os administradores do Looker precisam adicionar à lista de permissões os endereços IP de saída dos quais o hub de ações do Looker faz solicitações na instância do Looker: 35.153.89.114, 104.196.138.163 e 35.169.42.87.

• Se nenhuma das soluções acima for apropriada para a arquitetura de instância do Looker, os administradores do Looker podem implantar um hub de ações hospedado pelo cliente para todas as ações ou apenas para aquelas que oferecem suporte a resultados transmitidos ou que usam o OAuth.

• Para implantar um hub de ações hospedado pelo cliente, verifique se o arquivo JAR está hospedado em um servidor público para que o hub de ações do Looker possa se comunicar com ele. No entanto, o Looker não recomenda essa solução.

Outro motivo para que as ações de OAuth e streaming possam não ser utilizáveis em uma instância do Looker hospedada pelo cliente é se a instância usar um certificado SSL emitido por uma autoridade de certificação (CA) que não esteja nesta lista.

Como criar uma ação personalizada

Esta seção descreve as etapas a serem seguidas para escrever e testar uma ação personalizada usando o código-fonte do Looker Action Hub. Para ver exemplos de código funcionais, verifique as ações atuais no repositório looker-open-source/actions (em inglês) no GitHub.

É possível criar uma ação personalizada das seguintes maneiras:

1. Como configurar um repositório de desenvolvimento
2. Gravar sua ação
3. Testar sua ação
4. Publicar e ativar sua ação no hub de ações do Looker ou no seu próprio servidor de hub de ações particular

Assim como acontece com qualquer ação, pode ser necessário configurar seus modelos LookML com parâmetros específicos antes de usar a ação para enviar seus dados.

Como configurar um repositório de desenvolvimento

O hub de ações do Looker é um servidor Node.js escrito em TypeScript, uma pequena camada sobre JavaScript moderno que adiciona informações de tipo para ajudar a detectar erros de programação. Se você já conhece o JavaScript, provavelmente conhece a maior parte da linguagem TypeScript.

A execução do hub de ações do Looker requer o seguinte software:

• Node.js
• Gerenciador de versões de nós (NVM, para selecionar a versão correta do Node.js)
• Yarn (para gerenciar as dependências)

Depois de instalar o software necessário, estará tudo pronto para configurar o ambiente de desenvolvimento. O exemplo abaixo usa o Git.

1. Clone o repositório looker-open-source/actions localmente:

   git clone [e-mail]:looker-open-source/actions.git
   

2. Crie um diretório com o nome da sua ação no diretório actions/src/actions. Exemplo:

   mkdir actions/src/actions/my_action
   

3. Comece a preencher o diretório com os arquivos necessários para executar sua ação. Consulte o repositório do GitHub de ações para ver um exemplo de estrutura de arquivos.

O Looker recomenda adicionar também:

• Um README para explicar a finalidade e os meios de autenticação para sua ação
• Ícone do PNG para exibir no Hub de ação do Looker (ou hub de ações particular na instância do Looker) e nas janelas de exibição de dados do Looker
• Todos os arquivos dos testes que você quer executar no código de ação. Isso é diferente de testar sua ação.

Como criar uma ação

Um requisito de design para o servidor do Action Hub do Looker é que ele permanece completamente sem estado. Portanto, não é permitido armazenar informações no aplicativo ou serviço de ação. Todas as informações necessárias para realizar a ação precisam ser fornecidas nas chamadas de solicitação do arquivo de ação.

O conteúdo exato do arquivo de ação varia de acordo com o serviço, o tipo ou o nível em que a ação opera e quais dados ou formatos de visualização precisam ser especificados. A ação também pode ser configurada para fluxos de autorização do OAuth 2.0.

Os arquivos de ação são baseados no método da API /execute. As solicitações da API Looker recebem um DataActionRequest sempre que um usuário executa a ação no Looker. O DataActionRequest contém todos os dados e metadados necessários para executar sua ação. Há também um método /form que pode ser usado para coletar outras informações do usuário antes da execução da ação. Os campos especificados em /form aparecerão no pop-up Send ou Schedule quando o usuário selecionar a ação como destino do envio de dados.

Se você estiver usando a API Looker Action, o formato desses parâmetros poderá ser diferente.

Ao gravar o arquivo de ação, inclua pelo menos os seguintes parâmetros marcados como Obrigatórios na definição da ação:

Parâmetro	Obrigatório	Descrição	Tipo de dado
name	Sim	Um nome exclusivo para a ação. Ele deve ser exclusivo em todas as ações no Looker Action Hub.	string
url	Sim	Um URL absoluto do endpoint /execute para esta ação.	string
label	Sim	Um rótulo legível para a ação.	string
supportedActionTypes	Sim	Uma lista de tipos de ação com suporte da ação. Os valores válidos são "cell", "query" e "dashboard".	string
formURL	Não	Um URL absoluto do endpoint /form para esta ação.	string
description	Não	Descrição da ação.	string
params	Não	Matriz de parameters da ação. Inclua o nome, o rótulo e a descrição em formato de string para cada parâmetro. Esses são os campos que aparecem na página de ativação da ação no painel Administrador. Para gerenciar a forma como os usuários podem enviar dados para um destino de ação, é possível especificar um atributo do usuário para o qual um usuário precisa ter um valor definido.	parameters
supportedFormats	Não	Uma lista de formatos de dados compatíveis com a ação. Os valores válidos são "txt", "csv", "inline_json", "json" e "json_detail", "json_detail_lite_stream", "xlsx", "html", "wysiwyg_pdf", "assembled_pdf", and "wysiwyg_png"..	string
supportedFormattings	Não	Uma lista de opções de formatação compatíveis com a ação. Os valores válidos são: "formatted" e "unformatted".	string
supportedVisualizationFormattings	Não	Uma lista de opções de formatação de visualização compatíveis com a ação. Os valores válidos são: "apply" e "noapply".	string
iconName	Não	Um URI de dados que representa uma imagem de ícone para a ação.	string
requiredFields	Não	Uma lista de descrições de campos obrigatórios com os quais essa ação é compatível. Se houver várias entradas nessa lista, a ação exigirá mais de um campo.	RequiredField
supportedDownloadSettings	Não	Um booleano que determina se a ação será enviada um URL de download único para facilitar o streaming ilimitado de dados. O parâmetro é definido pelo parâmetro usesStreaming, que é um booleano true/false. Se usesStreaming = true, então supportedDownloadSettings = url. Se usesStreaming = false, então supportedDownloadSettings = push.	Booleano
usesOAuth	Não	Um booleano que determina se a ação é uma ação do OAuth. Isso determinará se a ação receberá um link de uso único para definir state para um usuário específico.	Booleano
usesStreaming	Não	Um booleano que determina se a ação é compatível com os resultados da consulta transmitidos. Verifique a coluna É possível transmitir resultados sim/não na lista de serviços integrados. As ações que fazem streaming de resultados podem exigir a configuração de um servidor de hub de ações local. Consulte a página Como configurar um hub de ação local para ações que usam OAuth ou streaming e confira as práticas recomendadas.	Booleano
minimumSupportedVersion	Não	A versão mínima do Looker em que a ação vai aparecer na lista do hub de ações do administrador.	string

Os exemplos das ações do hub de ações do Looker estão no GitHub para referência.

Tipos de ação compatíveis

O Looker oferece suporte a três tipos de ações, conforme especificado no parâmetro supportedActionTypes da sua ação: consulta, célula e painel.

• Uma ação no nível da consulta:envia uma consulta inteira. A Ação de segmento, por exemplo, é uma ação no nível da consulta.
• Ação no nível da célula:uma ação no nível da célula envia o valor de uma única célula específica em uma tabela de dados. Esse tipo de ação é diferente das ações de dados, que podem ser definidas para dimensões ou medidas usando o parâmetro action. Para enviar informações de uma célula específica em uma tabela, o Looker usa tags para mapear as ações para as células correspondentes. As ações precisam especificar quais tags são compatíveis com requiredFields. Para mapear ações e campos, os campos em LookML precisam especificar para quais tags eles são mapeados com o parâmetro tags do LookML. Por exemplo, a ação de mensagem do Twilio usa uma tag phone para que os desenvolvedores do LookML possam controlar em quais campos de número de telefone a ação será exibida.
• Uma ação no nível do painel:uma ação no nível do painel permite o envio de uma imagem de um painel. Por exemplo, a ação SendGrid envia imagens do painel por e-mail.

Adicionar atributos do usuário a ações personalizadas

Para ações personalizadas, adicione atributos do usuário no parâmetro params do arquivo de ação. Se o parâmetro for obrigatório, cada usuário precisará ter um valor para esse atributo definido na conta de usuário ou em um grupo de usuários a que eles pertencem, além da send_to_integration permissão, para ver a ação como uma opção de destino ao enviar ou programar conteúdo.

Para adicionar um atributo de usuário à sua ação:

1. Um administrador do Looker pode precisar criar o atributo de usuário correspondente ao user_attribute_param, caso ele ainda não exista.
2. Defina um valor válido para o atributo para usuários ou grupos de usuários que precisem enviar conteúdo ao seu destino de ação. Esses usuários também precisam ter as permissões send_to_integration.
3. O parâmetro params representa os campos de formulário que um administrador do Looker precisa configurar na página de ativação da ação da lista Ações no painel Administrador. No parâmetro params do arquivo de ação, inclua:

  params = [{
    description: "A description of the param.",
    label: "A label for the param.",
    name: "action_param_name",
    user_attribute_name: "user_attribute_name",
    required: true,
    sensitive: true,
  }]

em que user_attribute_name é o atributo do usuário definido no campo Nome na página Atributos do usuário da seção Usuários do painel Administrador. required: true significa que um usuário precisa ter um valor não nulo e válido definido para esse atributo do usuário para ver a ação ao entregar dados. sensitive: true significa que o atributo do usuário é criptografado e nunca exibido na IU do Looker depois de inserido. É possível especificar vários subparâmetros de atributos do usuário.

1. Implante as atualizações no servidor do hub de ações.
   • Se você estiver adicionando uma nova ação, um administrador do Looker precisará ativar a ação clicando no botão Ativar ao lado da ação na página Ações no painel Administrador.
   • Para atualizar uma ação existente, clique no botão Refresh. Em seguida, clique no botão Configurações.
2. Na página de configurações/ativação da ação, um administrador do Looker precisa configurar os campos do formulário de ação para extrair informações do atributo do usuário clicando no ícone do atributo do usuário à direita do campo apropriado e selecionando o atributo do usuário desejado.

Parâmetros requiredField em ações no nível da célula

Para ações no nível da célula, é possível configurar os campos LookML do modelo para fornecer dados a esse destino de ação especificando quais tags são compatíveis com a ação no parâmetro requiredFields do arquivo de ação.

Parâmetro	Obrigatório	Descrição	Tipo de dado
tag	Não	Se presente, corresponde a um campo que tem essa tag.	string
any_tag	Não	Se estiver presente, substitui tag e corresponde a um campo que tem uma das tags fornecidas.	string
all_tags	Não	Se estiver presente, substitui tag e corresponde a um campo que tem todas as tags fornecidas.	string

Formatos de dados compatíveis

A classe DataActionRequest define qual formato de entrega de dados está disponível para que a ação funcione. Para ações no nível da consulta, a solicitação contém um anexo que pode estar em vários formatos. A ação pode especificar um ou mais supportedFormats ou permitir que o usuário escolha o formato especificando todos os formatos possíveis. Para ações no nível da célula, o valor da célula estará presente em DataActionRequest.

Como configurar uma ação para o OAuth

As ações ativadas pelo OAuth não podem ser configuradas no hub de ações do Looker para instâncias do Looker que têm o recurso de lista de permissões de IP ativado ou que não acomoda os requisitos do hub de ações do Looker. Para mais informações sobre como configurar uma ação para o OAuth, consulte a página Como configurar um hub de ações local para ações que usam OAuth ou streaming.

Você pode configurar a ação para que os usuários façam a autenticação usando OAuth. O Looker Action Hub precisa continuar sem estado, mas é possível aplicar um estado usando uma solicitação do formulário da API Looker Action.

Fluxo do OAuth de ações do Looker

Para ações no hub de ações do Looker, é possível estender um OAuthAction em vez de um Hub.Action para definir um booleano que indica os métodos do OAuth necessários para autenticar um usuário em uma ação. Para cada ação ativada para OAuth ou estado, o Looker armazena um estado por usuário e por ação, de modo que cada ação e combinação de usuários tenha um evento OAuth independente.

O fluxo para criar ações geralmente envolve uma solicitação /form seguida por uma solicitação /execute. Para OAuth, a solicitação /form precisa ter um método para determinar se o usuário está autenticado no serviço de destino. Se o usuário já estiver autenticado, a ação retornará um /form normal de acordo com o que a solicitação /execute exigir. Se o usuário não for autenticado, a ação retornará um link que inicializará um fluxo de OAuth.

Como salvar o estado com o URL do OAuth

O Looker enviará uma solicitação POST HTTP com corpo vazio para o endpoint ActionList. Se a ação retornar uses_oauth: true na definição, ela receberá uma state_url de uso único em cada solicitação /form do Looker. O state_url é um URL especial de uso único que define o estado de um usuário para uma determinada ação.

Se o usuário não estiver autenticado com o endpoint, o /form retornado precisará conter um form_field do tipo oauth_link que vai para o endpoint /oauth de uma ação. O state_url precisa ser criptografado e salvo como um parâmetro state no oauth_url retornado. Exemplo:

{
        "name": "login",
        "type": "oauth_link",
        "label": "Log in",
        "description": "OAuth Link",
        "oauth_url": "ACTIONHUB_URL/actions/my_action/oauth?state=encrypted_state_url"
}

Neste exemplo, o endpoint /oauth redireciona o usuário para o servidor de autenticação. O endpoint /oauth cria o redirecionamento no método oauthUrl(...) em uma ação do OAuth, conforme mostrado no Dropbox OauthUrl.

O parâmetro state que contém esse state_url criptografado precisa ser transmitido para o hub de ações do Looker.

Como salvar o estado com o URI de redirecionamento do hub de ações

No endpoint /oauth, um redirect_uri do hub de ação também é criado e transmitido para o método oauthUrl(...) da ação. Esse redirect_uri está no formato /actions/src/actions/my_maction/oauth_redirect e é o endpoint usado se a autenticação retornar um resultado.

Esse endpoint chamará o método oauthFetchInfo(...), que precisa ser implementado pelo método OauthAction para extrair as informações necessárias e tentar receber ou salvar qualquer estado ou auth recebido do servidor de autenticação.

O state descriptografa o state_url criptografado e o usa para POSTAR state de volta no Looker. Na próxima vez que um usuário solicitar uma ação, o estado recém-salvo será enviado ao hub de ações do Looker.

Como adicionar seus arquivos de ação ao repositório do Action Hub do Looker

Depois que seu arquivo de ação for gravado, no repositório do Action Hub do Looker:

1. Adicione o arquivo de ação (por exemplo, my_action.ts) a actions/src/actions/index.ts.

   import "./my_action/my_action.ts"
   

2. Adicione os requisitos do pacote Node.js usados na gravação da sua ação. Exemplo:

   yarn add aws-sdk
   yarn add express
   

3. Instale as dependências do Node.js no servidor do hub de ação do Looker.

   yarn install
   

4. Execute os testes que você criou.

yarn test

Como testar uma ação

Para um teste completo, você pode testar sua ação na instância do Looker hospedando um servidor de hub de ações particular. Esse servidor precisa estar na Internet pública com um certificado SSL válido e precisa ser capaz de iniciar e receber conexões ou solicitações HTTPS de e para o Looker. Para isso, use uma plataforma baseada na nuvem, como o Heroku, como mostrado no exemplo a seguir, ou qualquer plataforma que atenda aos requisitos mencionados acima.

Como configurar um servidor de hub de ação local

Neste exemplo, vamos executar a ação desenvolvida no repositório do GitHub looker-open-source/actions/src/actions e confirmar o código em uma nova ramificação do Git. Recomendamos que você trabalhe em ramificações para rastrear facilmente seu código e, se quiser, criar um PR com o Looker.

1. Para começar, crie sua ramificação e depois organize e confirme seu trabalho. Exemplo:

   git checkout -b my-branch-name
   git add file-names
   git commit -m commit-message
   

2. Neste exemplo, para enviar uma ramificação para o Heroku, configure o repositório do Git com o Heroku como uma opção remota na linha de comando:

   heroku login
   heroku create
   git push heroku
   

3. O Heroku retornará o URL público que agora hospeda o hub de ações para seu uso. Acesse o URL ou execute heroku logs para confirmar que o hub de ações está em execução. Se você esquecer o URL público, execute o seguinte na linha de comando:

   heroku info -s | grep web_url
   

   O Heroku retornará seu URL público. Por exemplo: https://my-heroku-action-server-1234.herokuapp.com

4. Na linha de comando, defina o URL base do hub de ações:

   heroku config:set ACTION_HUB_BASE_URL="https://my-heroku-action-server-1234.herokuapp.com"
   

5. Defina o rótulo do hub de ações:

   heroku config:set ACTION_HUB_LABEL="Your Action Hub"
   

6. O Looker usa um token de autorização para se conectar ao hub de ações. Gere o token na linha de comando:

   heroku run yarn generate-api-key
   

   Se você não estiver usando o Heroku, como neste exemplo, use:

   yarn generate-api-key
   

   O Heroku retornará seu token de autorização. Por exemplo: Authorization: Token token="abcdefg123456789"

7. Defina o secret do hub de ação usando a chave do secret:

   heroku config:set ACTION_HUB_SECRET="abcdefg123456789"
   

   Implantações hospedadas pelo cliente podem exigir a configuração de variáveis de ambiente adicionais não documentadas aqui.

8. Para adicionar a ação à sua instância local do Looker, acesse Administrador > Ações.

   • Na parte inferior da lista de ações, clique em Adicionar Action Hub.
   • Insira o URL do hub de ações e, se quiser, uma chave secreta.
   • Encontre sua ação na lista Ações no menu Administrador do Looker.
   • Selecione Ativar.

Se a ação exigir que tipos específicos de dados sejam transmitidos do Looker, configure todos os modelos para incluir o parâmetro tags apropriado.

Agora você já pode testar sua ação.

Como testar ações no nível do painel e da consulta

Na instância do Looker, configure o modelo LookML com tags, se necessário. Crie e salve um visual. Na visualização salva, clique no menu superior direito e selecione Enviar com sua ação como destino. Se você tiver um formulário de entrega, o Looker o renderizará na janela Enviados.

Clique em Enviar teste para enviar os dados. O status da ação aparecerá no Histórico do Programador no painel Administrador. Se ocorrer um erro na sua ação, ela será exibida no painel Administrador, e o Looker enviará um e-mail com a mensagem de erro para o usuário que enviou a ação.

Como testar ações no nível da célula

Configure um campo LookML com as tags adequadas para sua ação. Na instância do Looker, execute uma consulta que inclua esse campo. Encontre o campo na tabela de dados. Clique em ... na célula e selecione Enviar no menu suspenso. Se houver erros, você precisará fazer uma atualização completa na tabela de dados depois de resolvê-los.

• Se a ação for exibida sem erros, você está pronto para publicá-la.
• Se você quiser continuar hospedando sua ação com privacidade, publique no hub de ações particulares.
• Se quiser publicar a ação para ser usada por todos os clientes do Looker, consulte a seção sobre Como publicar no hub de ações do Looker.

Como publicar e ativar uma ação personalizada

Há duas opções de publicação para ações personalizadas:

• Publicar no Hub de ações do Looker: sua ação estará disponível para qualquer pessoa que usar o Looker.
• Publicar em um servidor de hub de ações particular: disponibiliza a ação apenas na instância do Looker.

Depois que a ação for publicada, será possível ativá-la na página Ações no painel Administrador.

Como publicar no hub de ações do Looker

Essa abordagem é a mais fácil e funciona para qualquer ação que você quiser disponibilizar para qualquer pessoa que use o Looker.

Depois que sua ação for testada, envie uma PR para o repositório looker-open-source/actions no GitHub.

1. Digite este comando:

   git push <your fork> <your development branch>
   

2. Crie sua solicitação de envio com o repositório looker-open-source/actions como destino.

3. Preencha o formulário de envio do Looker Marketplace e do Action Hub. Para mais informações sobre os requisitos do formulário, consulte Como enviar conteúdo para o Marketplace do Looker.

   O Looker analisará seu código de ação. Reservamo-nos o direito de recusar seu PR, mas podemos ajudar com quaisquer problemas que você tenha e oferecer sugestões de melhorias. Em seguida, mesclamos o código no repositório looker-open-source/actions e o implantamos no actions.looker.com. Depois de implantado, o código ficará disponível para todos os clientes do Looker.

4. Ative a ação na instância do Looker para que ela seja exibida como uma opção para entrega de dados.

Como publicar em um servidor de hub de ação particular

Se você tiver ações personalizadas que são particulares para sua empresa ou caso de uso, não adicione sua ação ao repositório looker-open-source/actions. Em vez disso, crie um hub de ações privadas usando o mesmo framework Node.js que você usou para testar a ação.

É possível configurar o servidor do hub de ações interno na sua própria infraestrutura ou usar uma plataforma de aplicativos baseada na nuvem (exemplo usado no Heroku). Não se esqueça de bifurcar o Hub de ação do Looker para seu servidor de hub de ações particular antes da implantação.

Como configurar um modelo LookML para usar com uma ação

Para ações personalizadas e ações disponíveis no Looker Action Hub, você precisa identificar os campos de dados relevantes usando o parâmetro tags no modelo do LookML.

A página Ações no painel Administrador fornecerá informações sobre as tags necessárias para o serviço, se houver.

Por exemplo, a integração com o Zapier declara que ele funciona com qualquer consulta (links em inglês). Não é necessário adicionar o parâmetro tags a um campo no seu modelo LookML.

O serviço Enviar mensagem do Twilio, no entanto, envia uma mensagem para uma lista de números de telefone. Ele requer uma consulta que inclua um campo de número de telefone e use o parâmetro tags para identificar qual campo na consulta contém números de telefone. Para identificar um campo de número de telefone em LookML, especifique tags: ["phone"] para esse campo. O campo LookML para um número de telefone pode ser parecido com este:

dimension: phone {
  tags: ["phone"]
  type: string
  sql: ${TABLE}.phone ;;
}

Identifique os campos obrigatórios no seu modelo LookML com o parâmetro tags para que os usuários possam usar o serviço para enviar dados.

Como enviar dados com uma ação

Há várias maneiras de enviar os dados, dependendo do nível em que a ação opera. As ações funcionam no nível do campo, da consulta ou do painel e podem funcionar em um ou mais níveis. Cada ação listada na página Ações do painel Administrador tem uma descrição de como ela é usada. É possível:

• Exibir uma célula de dados
• Mostrar um painel ou uma consulta inteiros (com base em um recurso Olhar ou Explorar)

Entregando dados da célula

As ações no campo são indicadas na página Ações do painel Administrador por uma descrição que inclui "A ação pode ser usada com campos" ou Sim na coluna Usar dos campos da lista de serviços integrados.

As ações no nível do campo são projetadas para entregar uma célula de dados para o serviço especificado. Elas funcionam de maneira semelhante às ações de dados, mas são veiculadas por meio da API Looker Action. Em vez de definir um parâmetro action do LookML para uma dimensão ou medida, é preciso configurar o modelo do LookML marcando os campos relevantes com as informações fornecidas na coluna Tags desta ação na lista de serviços integrados.

Depois de ativar os campos de serviço e de inclusão de tag no modelo LookML, é possível:

1. Veja os dados que você quer exibir em um painel, uma visualização ou um painel "Explorar". Se o serviço especificar "A ação pode ser usada com consultas que têm um campo marcado...", sua consulta ou um dos blocos do painel de controle deve incluir um ou mais campos com qualquer tag obrigatória.

2. O campo com tags em cada célula da seção "Visualizar", "Bloco do painel" ou "Explorar" terá uma lista suspensa, indicada por reticências (...). Clique nas reticências para ver as ações disponíveis nesse link.

3. Na seção AÇÕES, clique no serviço em que você quer receber os dados da linha.

Exibição de dados do painel ou da consulta

As ações no nível da consulta são indicadas na página Ações do painel Administrador por uma descrição que inclui "A ação pode ser usada com consultas que têm um campo marcado..." ou "A ação pode ser usada com qualquer consulta". De acordo com a coluna Pode enviar ou programar na lista de serviços integrados, é possível exibir Todas as linhas (visual ou "Explorar"). As ações no nível da consulta são projetadas para enviar todos os resultados da consulta de um recurso Explorar ou Look para o serviço especificado.

As ações no nível do painel são indicadas na página Ações do painel Administrador por uma descrição que inclui "A ação pode ser usada com qualquer painel". De acordo com a coluna Pode enviar ou programar na lista de serviços integrados, é possível exibir Um painel. As ações no nível do painel são projetadas para enviar um painel ao serviço especificado.

Ative o serviço e, se necessário, os campos de tag no modelo LookML.

Para criar uma aparência ou análise, confira a página Como exibir aparências e explorações.

Para fornecer painéis, consulte as páginas de documentação Como fornecer painéis legados e Como programar e enviar painéis.