lookerbot
0.0.15
Lookerbot intègre Slack et Looker pour mettre toutes vos données à portée de main.
Avec Lookerbot, tous les membres de votre entreprise peuvent facilement partager des données et répondre instantanément aux questions. Lookerbot peut répondre aux questions, envoyer des alertes et bien plus encore !
Pour un essai gratuit de Looker, rendez-vous sur looker.com/free-trial.
Des informations détaillées sur la façon d’interagir avec Lookerbot sont disponibles dans le centre d’aide Looker.
s3:PutObjectAcl et s3:PutObject .channels:readchat:write:botfiles:write:userteam:readusers:readcommands (si vous envisagez de configurer des commandes slash)xoxb- .Par défaut, les applications Slack sont internes à votre équipe. Ne « distribuez » pas votre application Slack – cela la rendra disponible à tous les utilisateurs Slack du monde.
Important
Veuillez noter : certaines des variables d'environnement ci-dessous ont changé. Vous devrez peut-être les ajuster pour que cela continue de fonctionner.
Le moyen le plus rapide de déployer le bot consiste à utiliser le bouton de déploiement en un clic d'Heroku, qui fournira un serveur pour votre bot. Cela vous demandera de donner un nom unique à l'application, d'ajouter la clé API Slack et de configurer toutes les variables requises (voir « Variables d'environnement » ci-dessous).
Une fois les variables d’environnement définies et le serveur déployé, le bot devrait être prêt à fonctionner ! Vous pouvez également éventuellement configurer des commandes slash.
Dépannage
Vous voyez des problèmes de dépendance sur Heroku ? Appliquez
YARN_PRODUCTION=falsecomme env. au déploiement. Voir l'élagage heroku pour plus de détails.
Le bot est une simple application Node.js. L'application doit être capable d'atteindre à la fois l'API de votre instance Looker et l'API de Slack. Si vous disposez d'une instance auto-hébergée de Looker, assurez-vous d'ouvrir le port 19999 (ou votre core_port ) afin d'accéder à l'API Looker.
Le bot est entièrement configuré via des variables d'environnement. Vous souhaiterez configurer ces variables :
SLACK_API_KEY (obligatoire) – C'est ici que vous placerez le « jeton d'accès OAuth de l'utilisateur du bot ». Vous pouvez accéder à l'application Slack sous « Installer l'application ».
LOOKER_URL (obligatoire) – L'URL Web de votre instance Looker.
LOOKER_API_BASE_URL (obligatoire) – Le point de terminaison API de votre instance Looker. Dans la plupart des cas, il s'agira de l'url web suivie de :19999/api/4.0 (remplacez 19999 par votre core_port s'il est différent).
LOOKER_API_CLIENT_ID (obligatoire) – L'ID client API de l'utilisateur sous lequel vous souhaitez que le bot s'exécute. Cela nécessite la création d'un utilisateur API ou d'une clé API pour un utilisateur existant dans Looker.
LOOKER_API_CLIENT_SECRET (obligatoire) – Le secret client de l'API pour l'utilisateur sous lequel vous souhaitez que le bot s'exécute. Cela nécessite la création d'un utilisateur API ou d'une clé API pour un utilisateur existant dans Looker.
LOOKER_CUSTOM_COMMAND_FOLDER_ID (facultatif) – L'ID d'un dossier que vous souhaitez que le bot utilise pour définir des commandes personnalisées. Découvrez comment utiliser les commandes personnalisées dans le centre d'aide Looker.
LOOKER_WEBHOOK_TOKEN (facultatif) – Le jeton de validation du webhook trouvé dans le panneau d'administration de Looker. Ceci n'est requis que si vous utilisez le bot pour envoyer des webhooks programmés.
SLACK_SLASH_COMMAND_TOKEN (facultatif) – Si vous souhaitez utiliser des commandes slash ou des messages interactifs avec Lookerbot, fournissez le jeton de vérification dans la section « Informations de base » des paramètres de l'application. C'est ainsi que le bot vérifiera l'intégrité des commandes slash entrantes.
PORT (facultatif) – Le port sur lequel le serveur Web du bot s'exécutera pour accepter les commandes slash. La valeur par défaut est 3333 .
Si vous souhaitez plutôt placer ces variables de configuration sur le système de fichiers, vous pouvez également les placer dans un fichier .env à la racine du projet. Les variables d'environnement auront priorité sur les paramètres .env si les deux sont présentes.
Il existe quelques variables d'environnement qui peuvent être utilisées pour modifier le comportement :
LOOKER_SLACKBOT_LOADING_MESSAGES – Définissez ceci sur false pour désactiver la publication des messages de chargement.
LOOKERBOT_DATA_ACTIONS_IN_MESSAGES – Définissez ceci sur false pour désactiver la mise à disposition des boutons d'action sur les données pour les utilisateurs de Slack.
SLACKBOT_S3_BUCKET (facultatif) – Si vous souhaitez utiliser Lookerbot pour publier des images de visualisation, fournissez un nom de compartiment Amazon S3.
SLACKBOT_S3_BUCKET_REGION (facultatif) – Si vous souhaitez utiliser Lookerbot pour publier des images de visualisation, fournissez une région de compartiment Amazon S3. La valeur par défaut est us-east-1 .
AWS_ACCESS_KEY_ID (facultatif) – Si vous souhaitez utiliser Lookerbot pour publier des images de visualisation, fournissez une clé d'accès Amazon S3 qui peut écrire dans le compartiment fourni.
AWS_SECRET_ACCESS_KEY (facultatif) – Si vous souhaitez utiliser Lookerbot pour publier des images de visualisation, fournissez une clé d'accès secrète Amazon S3 qui peut écrire dans le compartiment fourni.
AZURE_STORAGE_ACCOUNT (facultatif) - Si vous souhaitez utiliser Microsoft Azure Storage pour stocker les images de visualisation publiées par Lookerbot, indiquez le nom de votre compte Azure Storage.
SLACKBOT_AZURE_CONTAINER (facultatif) - Si vous souhaitez utiliser Microsoft Azure Storage pour stocker les images de visualisation publiées par Lookerbot, indiquez le nom du conteneur dans votre compte Azure Storage que vous souhaitez utiliser.
AZURE_STORAGE_ACCESS_KEY (facultatif) : si vous utilisez Microsoft Azure Storage pour stocker des images de visualisation publiées par Lookerbot, fournissez une clé d'accès qui peut écrire dans le compte et le conteneur Azure Storage fournis.
GOOGLE_CLOUD_BUCKET (facultatif) : si vous souhaitez utiliser Google Cloud pour stocker les images de visualisation publiées par Lookerbot, indiquez le nom de votre compartiment.Si Lookerbot s'exécute sur Google Compute Engine, aucune autre information ne devrait être nécessaire si les étendues d'API appropriées sont configurées.
Sinon, vous pouvez fournir directement vos identifiants :
GOOGLE_CLOUD_PROJECT (facultatif) : si vous souhaitez utiliser Google Cloud pour stocker des images de visualisation publiées par Lookerbot, indiquez le nom de votre projet.
GOOGLE_CLOUD_CREDENTIALS_JSON (facultatif) : si vous utilisez Google Cloud pour stocker des images de visualisation publiées par Lookerbot, fournissez le contenu du fichier JSON d'informations d'identification que vous avez obtenu sur le site Web de Google Cloud.
Si votre instance Looker utilise un certificat auto-signé, Lookerbot refusera de s'y connecter par défaut.
Définir la variable d'environnement NODE_TLS_REJECT_UNAUTHORIZED sur 0 demandera à Lookerbot d'accepter les connexions avec des certificats non valides. Veuillez vous assurer d'avoir soigneusement évalué les implications de sécurité de cette action pour votre infrastructure avant de définir cette variable.
Cela ne devrait avoir un impact que sur les déploiements sur site de Looker. Ne définissez pas cette variable d'environnement si Looker héberge votre instance.
Si vous souhaitez que le bot se connecte à plusieurs instances de Looker, vous pouvez configurer le bot avec la variable d'environnement LOOKERS . Cette variable doit être un tableau JSON d'objets JSON, chacun représentant une instance Looker et ses informations d'authentification.
Les objets JSON doivent avoir les clés suivantes :
url doit être l'URL Web de l'instanceapiBaseUrl devrait être le point de terminaison de l'APIclientID doit être l'ID client API de l'utilisateur sous lequel vous souhaitez que le bot s'exécuteclientSecret devrait être le secret de cette clé APIcustomCommandFolderId est un paramètre facultatif, représentant un dossier que vous souhaitez que le bot utilise pour définir des commandes personnalisées.webhookToken est un paramètre facultatif. Il s'agit du jeton de validation du webhook trouvé dans le panneau d'administration de Looker. Ceci n'est requis que si vous utilisez le bot pour envoyer des webhooks planifiés.Voici un exemple de JSON qui se connecte à deux instances 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 " }] Les variables LOOKER_URL , LOOKER_API_BASE_URL , LOOKER_API_CLIENT_ID , LOOKER_API_CLIENT_SECRET , LOOKER_WEBHOOK_TOKEN et LOOKER_CUSTOM_COMMAND_FOLDER_ID sont ignorées lorsque LOOKERS est défini.
Pour exécuter le serveur :
yarn install pour installer les dépendancesyarn start pour démarrer le serveur du bot. Le serveur fonctionnera jusqu'à ce que vous tapiez Ctrl+C pour l'arrêter. Le Procfile inclus vous permettra également d'exécuter l'application en utilisant Foreman ou Node-Foreman. Ces bibliothèques fournissent également des moyens simples de créer des scripts à utiliser avec upstart , supervisord et systemd .
Les commandes Slash ne sont pas nécessaires pour interagir avec le bot. Vous pouvez DM le bot directement ou mentionner le bot comme :
Aide @looker
et utilisez toutes les fonctionnalités.
Cependant, les commandes Slash sont un peu plus conviviales à utiliser et permettent à Slack de se compléter automatiquement, vous souhaiterez donc probablement les configurer.
/slack/receive , donc si votre serveur est sur https://example.com , l'URL serait https://example.com/slack/receive .SLACK_SLASH_COMMAND_TOKEN .Vous pouvez utiliser le bot pour envoyer des looks programmés à Slack.
/slack/post/channel/my-channel-name/slack/post/group/my-channel-name/slack/post/dm/myusername Ces URL sont préfixées par l'URL de votre serveur. (Si vous avez utilisé le déploiement Heroku, ce sera le nom unique de l'application que vous avez choisi). Ainsi, si votre serveur est sur https://example.com et que vous souhaitez publier sur un canal appelé data-science , l'URL serait https://example.com/slack/post/channel/data-science .
LOOKER_WEBHOOK_TOKEN est correctement définie sur le même jeton de vérification que celui trouvé dans le panneau d'administration de Looker.Par défaut, des actions de données simples apparaîtront dans Slack pour les visualisations de valeurs uniques. Les actions de données comportant des formulaires ne sont actuellement pas prises en charge.
Cela peut être désactivé pour chaque action en utilisant des modèles Liquid dans la définition de l'action pour restreindre l'accès à certains utilisateurs. Alternativement, les boutons d'action peuvent être entièrement désactivés avec la variable de configuration du bot LOOKERBOT_DATA_ACTIONS_IN_MESSAGES .
Une configuration supplémentaire rapide est nécessaire pour utiliser les actions de données de Slack :
/slack/action , donc si votre serveur est sur https://example.com , l'URL de la demande serait https://example.com/slack/action .Le serveur de bot implémente également des points de terminaison pour vous permettre d'envoyer facilement des actions de données à Slack.
Voici un exemple de quelques actions de données que vous pourriez implémenter dans votre LookML. (Remplacez https://example.com par le nom d'hôte de votre bot.)
Pour utiliser cela, vous devrez vous assurer que la variable d'environnement LOOKER_WEBHOOK_TOKEN est correctement définie sur le même jeton de vérification que celui trouvé dans le panneau d'administration de Looker, tout comme pour les données de planification.
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 "
}
}
}Nous vous suggérons de créer un utilisateur de l'API Looker spécifiquement pour Lookerbot et d'utiliser les informations d'identification API de cet utilisateur. Il convient de rappeler que toutes les personnes pouvant parler à votre Lookerbot disposent des autorisations de cet utilisateur . S'il y a des données auxquelles vous ne souhaitez pas que les gens accèdent via Slack, assurez-vous que l'utilisateur ne peut pas y accéder à l'aide des mécanismes d'autorisation de Looker.
Gardez également à l’esprit que lorsque le bot Looker répond aux questions dans Slack, les données résultantes sont transférées dans Slack et y sont désormais hébergées . Assurez-vous d’examiner attentivement quelles données sont autorisées à quitter Looker. Slack conserve l'historique des messages de discussion sur ses serveurs et envoie de nombreux types de notifications concernant les messages via d'autres services.
Pour permettre aux visualisations d'apparaître dans Slack, s'il est configuré pour cela, le robot les télécharge sous forme d'images sur Amazon S3 avec une URL extrêmement longue générée de manière aléatoire. Toute personne disposant de cette URL peut accéder à cette image à tout moment, même si cela devrait être extrêmement difficile à deviner.
Si vous choisissez de supprimer les fichiers image de S3, les messages Slack qui reposaient sur ces images seront vides.
.env à la base du dépôt.yarn installyarn startLes Pull Requests sont les bienvenues – nous serions ravis d’avoir de l’aide pour étendre les fonctionnalités du bot.
Si vous rencontrez des problèmes avec le bot, veuillez ouvrir un ticket afin que nous puissions vous aider !
