lookerbot
0.0.15
Lookerbot integra Slack e Looker para colocar todos os seus dados ao seu alcance.
Com o Lookerbot, todos na sua empresa podem compartilhar dados facilmente e responder perguntas instantaneamente. O Lookerbot pode responder perguntas, enviar alertas e muito mais!
Para uma avaliação gratuita do Looker, acesse looker.com/free-trial.
Informações detalhadas sobre como interagir com o Lookerbot podem ser encontradas na Central de Ajuda do Looker.
s3:PutObjectAcl e s3:PutObject .channels:readchat:write:botfiles:write:userteam:readusers:readcommands (se você planeja configurar comandos de barra)xoxb- .Por padrão, os aplicativos Slack são internos à sua equipe. Não “distribua” seu aplicativo Slack – isso o disponibilizará para todos os usuários do Slack no mundo.
Importante
Observação: algumas das variáveis de ambiente abaixo foram alteradas. Pode ser necessário ajustá-los para manter isso funcionando.
A maneira mais rápida de implantar o bot é usar o botão de implantação de um clique do Heroku, que provisionará um servidor para o seu bot. Isso solicitará que você dê um nome exclusivo ao aplicativo, adicione a chave de API do Slack e configure todas as variáveis necessárias (consulte "Variáveis de ambiente" abaixo).
Depois que as variáveis de ambiente forem definidas e o servidor implantado, o bot deverá estar pronto para funcionar! Você também pode configurar opcionalmente comandos de barra.
Solução de problemas
Veja problemas de dependência no heroku? Aplique
YARN_PRODUCTION=falsecomo env. para a implantação. Veja a poda de salto heroku para mais detalhes.
O bot é um aplicativo Node.js simples. O aplicativo precisa ser capaz de acessar a API da sua instância do Looker e a API do Slack. Se você tiver uma instância auto-hospedada do Looker, certifique-se de abrir a porta 19999 (ou core_port ) para acessar a API do Looker.
O bot é configurado inteiramente por meio de variáveis de ambiente. Você desejará configurar estas variáveis:
SLACK_API_KEY (obrigatório) – É aqui que você colocará o "Bot User OAuth Access Token". Você pode entrar no aplicativo Slack em “Instalar aplicativo”.
LOOKER_URL (obrigatório) – O URL da web da sua instância do Looker.
LOOKER_API_BASE_URL (obrigatório) – O endpoint da API da sua instância do Looker. Na maioria dos casos, este será o URL da web seguido por :19999/api/4.0 (substitua 19999 pelo seu core_port se for diferente).
LOOKER_API_CLIENT_ID (obrigatório) – O ID do cliente API do usuário com o qual você deseja que o bot seja executado. Isso requer a criação de um usuário de API ou de uma chave de API para um usuário existente no Looker.
LOOKER_API_CLIENT_SECRET (obrigatório) – O segredo do cliente API para o usuário com o qual você deseja que o bot seja executado. Isso requer a criação de um usuário de API ou de uma chave de API para um usuário existente no Looker.
LOOKER_CUSTOM_COMMAND_FOLDER_ID (opcional) – O ID de uma pasta que você gostaria que o bot usasse para definir comandos personalizados. Leia sobre como usar comandos personalizados na Central de Ajuda do Looker.
LOOKER_WEBHOOK_TOKEN (opcional) – O token de validação do webhook encontrado no painel de administração do Looker. Isso só será necessário se você estiver usando o bot para enviar webhooks agendados.
SLACK_SLASH_COMMAND_TOKEN (opcional) – Se você quiser usar comandos de barra ou mensagens interativas com o Lookerbot, forneça o token de verificação na seção "Informações básicas" das configurações do aplicativo. É assim que o bot verificará a integridade dos comandos de barra recebidos.
PORT (opcional) – A porta na qual o servidor web do bot será executado para aceitar comandos de barra. O padrão é 3333 .
Se desejar colocar essas variáveis de configuração no sistema de arquivos, você também pode colocá-las em um arquivo .env na raiz do projeto. As variáveis de ambiente terão precedência sobre as configurações .env se ambas estiverem presentes.
Existem algumas variáveis de ambiente que podem ser usadas para ajustar o comportamento:
LOOKER_SLACKBOT_LOADING_MESSAGES – Defina como false para desativar a postagem de mensagens de carregamento.
LOOKERBOT_DATA_ACTIONS_IN_MESSAGES – Defina como false para desativar a disponibilização de botões de ação de dados para usuários do Slack.
SLACKBOT_S3_BUCKET (opcional) – se você quiser usar o Lookerbot para postar imagens de visualização, forneça um nome de bucket do Amazon S3.
SLACKBOT_S3_BUCKET_REGION (opcional) – se você quiser usar o Lookerbot para postar imagens de visualização, forneça uma região de bucket do Amazon S3. O padrão é us-east-1 .
AWS_ACCESS_KEY_ID (opcional) – Se você quiser usar o Lookerbot para postar imagens de visualização, forneça uma chave de acesso do Amazon S3 que possa gravar no bucket fornecido.
AWS_SECRET_ACCESS_KEY (opcional) – Se você quiser usar o Lookerbot para postar imagens de visualização, forneça uma chave de acesso secreta do Amazon S3 que possa gravar no bucket fornecido.
AZURE_STORAGE_ACCOUNT (opcional) – Se você quiser usar o Microsoft Azure Storage para armazenar imagens de visualização postadas pelo Lookerbot, forneça o nome da sua conta do Azure Storage.
SLACKBOT_AZURE_CONTAINER (opcional) – Se você quiser usar o Microsoft Azure Storage para armazenar imagens de visualização postadas pelo Lookerbot, forneça o nome do contêiner na sua conta do Azure Storage que deseja usar.
AZURE_STORAGE_ACCESS_KEY (opcional) – Se estiver usando o Microsoft Azure Storage para armazenar imagens de visualização postadas pelo Lookerbot, forneça uma chave de acesso que possa gravar na conta e no contêiner do Azure Storage fornecidos.
GOOGLE_CLOUD_BUCKET (opcional) – Se você quiser usar o Google Cloud para armazenar imagens de visualização postadas pelo Lookerbot, forneça o nome do seu bucket.Se o Lookerbot estiver em execução no Google Compute Engine, nenhuma informação adicional será necessária se os escopos de API apropriados estiverem configurados.
Caso contrário, você poderá fornecer credenciais diretamente:
GOOGLE_CLOUD_PROJECT (opcional) - Se quiser usar o Google Cloud para armazenar imagens de visualização postadas pelo Lookerbot, forneça o nome do seu projeto.
GOOGLE_CLOUD_CREDENTIALS_JSON (opcional) – Se estiver usando o Google Cloud para armazenar imagens de visualização postadas pelo Lookerbot, forneça o conteúdo do arquivo JSON de credenciais obtido no site do Google Cloud.
Se sua instância do Looker usar um certificado autoassinado, o Lookerbot se recusará a se conectar a ele por padrão.
Definir a variável de ambiente NODE_TLS_REJECT_UNAUTHORIZED como 0 instruirá o Lookerbot a aceitar conexões com certificados inválidos. Certifique-se de ter avaliado minuciosamente as implicações de segurança desta ação para sua infraestrutura antes de definir esta variável.
Isso deve impactar apenas as implantações locais do Looker. Não defina esta variável de ambiente se o Looker hospedar sua instância.
Se desejar que o bot se conecte a várias instâncias do Looker, você poderá configurar o bot com a variável de ambiente LOOKERS . Esta variável deve ser uma matriz JSON de objetos JSON, cada um representando uma instância do Looker e suas informações de autenticação.
Os objetos JSON devem ter as seguintes chaves:
url deve ser o URL da web da instânciaapiBaseUrl deve ser o endpoint da APIclientID deve ser o ID do cliente da API do usuário com o qual você deseja que o bot seja executadoclientSecret deve ser o segredo dessa chave de APIcustomCommandFolderId é um parâmetro opcional, representando uma pasta que você gostaria que o bot usasse para definir comandos personalizados.webhookToken é um parâmetro opcional. É o token de validação do webhook encontrado no painel de administração do Looker. Isso só será necessário se você estiver usando o bot para enviar webhooks agendados.Aqui está um exemplo de JSON que se conecta a duas instâncias do Looker:
[{ "url" : " https://me.looker.com " , "apiBaseUrl" : " https://me.looker.com:19999/api/4.0 " , "clientId" : " abcdefghjkl " , "clientSecret" : " abcdefghjkl " },{ "url" : " https://me-staging.looker.com " , "apiBaseUrl" : " https://me-staging.looker.com:19999/api/4.0 " , "clientId" : " abcdefghjkl " , "clientSecret" : " abcdefghjkl " }] As variáveis LOOKER_URL , LOOKER_API_BASE_URL , LOOKER_API_CLIENT_ID , LOOKER_API_CLIENT_SECRET , LOOKER_WEBHOOK_TOKEN e LOOKER_CUSTOM_COMMAND_FOLDER_ID são ignoradas quando LOOKERS é definido.
Para executar o servidor:
yarn install para instalar dependênciasyarn start para iniciar o servidor bot. O servidor será executado até que você digite Ctrl+C para interrompê-lo. O Procfile incluído também permitirá que você execute o aplicativo usando o foreman ou o node-foreman. Essas bibliotecas também fornecem maneiras fáceis de criar scripts para uso com upstart , supervisord e systemd .
Os comandos de barra não são necessários para interagir com o bot. Você pode DM o bot diretamente ou mencioná-lo como:
@looker ajuda
e use todas as funcionalidades.
No entanto, os comandos Slash são um pouco mais fáceis de usar e permitem que o Slack seja preenchido automaticamente, então você provavelmente desejará configurá-los.
/slack/receive , portanto, se o seu servidor estiver em https://example.com , o URL seria https://example.com/slack/receive .SLACK_SLASH_COMMAND_TOKEN .Você pode usar o bot para enviar looks agendados para o Slack.
/slack/post/channel/my-channel-name/slack/post/group/my-channel-name/slack/post/dm/myusername Esses URLs são prefixados com o URL do seu servidor. (Se você usou a implantação do Heroku, este será o nome exclusivo do aplicativo que você escolheu). Portanto, se o seu servidor estiver em https://example.com e você quiser postar em um canal chamado data-science , a URL seria https://example.com/slack/post/channel/data-science .
LOOKER_WEBHOOK_TOKEN esteja configurada corretamente para o mesmo token de verificação encontrado no painel de administração do Looker.Por padrão, ações simples de dados aparecerão no Slack para visualizações de valor único. As ações de dados que possuem formulários não são suportadas atualmente.
Isso pode ser desabilitado por ação usando modelos Liquid na definição da ação para restringir o acesso a determinados usuários. Como alternativa, os botões de ação podem ser totalmente desativados com a variável de configuração do bot LOOKERBOT_DATA_ACTIONS_IN_MESSAGES .
Há uma configuração adicional rápida necessária para usar as ações de dados do Slack:
/slack/action , portanto, se o seu servidor estiver em https://example.com , o URL da solicitação seria https://example.com/slack/action .O servidor bot também implementa endpoints para permitir que você envie facilmente ações de dados para o Slack.
Aqui está um exemplo de algumas ações de dados que você pode implementar em seu LookML. (Substitua https://example.com pelo nome de host do seu bot.)
Para fazer uso disso, você precisará certificar-se de que a variável de ambiente LOOKER_WEBHOOK_TOKEN esteja configurada corretamente para o mesmo token de verificação encontrado no painel de administração do Looker, assim como acontece com os dados de agendamento.
dimension : value {
sql : CONCAT (${first_name}, ' ' , ${last_name}) ;;
# Let user choose a Slack channel to send to
action : {
label : " Send to Slack Channel "
url : " https://example.com/data_actions "
form_url : " https://example.com/data_actions/form "
param : {
name : " message "
value : " :signal_strength: I sent a value from Slack: {{rendered_value}} "
}
}
# Send to a particular Slack channel with a preset message
action : {
label : " Ping Channel "
url : " https://example.com/data_actions "
param : {
name : " message "
value : " :signal_strength: I sent a value from Slack: {{rendered_value}} "
}
param : {
name : " channel "
value : " #alerts "
}
}
# Ask the user for a message to send to a particular channel
action : {
label : " Ask a Question "
url : " https://example.com/data_actions "
form_param : {
name : " message "
default : " Something seems wrong... (add details) "
}
param : {
name : " channel "
value : " #alerts "
}
}
}Sugerimos criar um usuário da API do Looker especificamente para o Lookerbot e usar as credenciais da API desse usuário. Vale lembrar que todos que podem conversar com o seu Lookerbot possuem as permissões deste usuário . Se houver dados que você não deseja que as pessoas acessem via Slack, certifique-se de que o usuário não possa acessá-los usando os mecanismos de permissão do Looker.
Além disso, lembre-se de que quando o bot Looker responde a perguntas no Slack, os dados resultantes são transferidos para o Slack e agora ficam hospedados lá . Certifique-se de considerar cuidadosamente quais dados podem sair do Looker. O Slack mantém o histórico de mensagens de bate-papo em seus servidores e envia muitos tipos de notificações sobre mensagens por meio de outros serviços.
Para permitir que as visualizações apareçam no Slack, se configurado para isso, o bot as carrega como imagens no Amazon S3 com um URL extremamente longo gerado aleatoriamente. Qualquer pessoa com esse URL pode acessar a imagem a qualquer momento, embora seja extremamente difícil adivinhar.
Se você optar por remover os arquivos de imagem do S3, as mensagens do Slack que dependiam dessas imagens ficarão em branco.
.env na base do repositório.yarn installyarn startSolicitações pull são bem-vindas – adoraríamos ter ajuda para expandir a funcionalidade do bot.
Se você tiver algum problema com o bot, abra um problema para que possamos ajudá-lo!
