lookerbot

لوكيربوت

يقوم Lookerbot بدمج Slack وLooker لوضع جميع بياناتك في متناول يدك.

باستخدام Lookerbot، يمكن لكل فرد في شركتك مشاركة البيانات والإجابة على الأسئلة بسهولة على الفور. يمكن لـ Lookerbot الإجابة على الأسئلة وإرسال التنبيهات والمزيد!

للحصول على نسخة تجريبية مجانية من Looker، انتقل إلى looker.com/free-trial.

سمات

يمكن العثور على معلومات تفصيلية حول كيفية التفاعل مع Lookerbot في مركز مساعدة Looker.

متطلبات

• Looker 4.12 أو الأحدث
• خادم ويب قادر على تشغيل تطبيقات Node.js لنشر تطبيق الروبوت عليه
  • مطلوب Node.js 6.10.3
  • الغزل مطلوب
• (اختياري) لعرض صور المخطط وبيانات الاعتماد الخاصة بخدمة تخزين مدعومة:
  • حساب Amazon S3 والحاوية ومفاتيح الوصول
    • التوثيق
    • تحتاج مفاتيح الوصول إلى أذونات s3:PutObjectAcl و s3:PutObject .
  • حساب تخزين Microsoft Azure ومفتاح الوصول
    • التوثيق
  • حساب Google Cloud Storage وبيانات الاعتماد
    • التوثيق

النشر

إنشاء روبوت جديد في سلاك

1. انتقل إلى https://api.slack.com/apps?new_classic_app=1 وقم بإنشاء تطبيق Classic Slack جديد. يستخدم Lookerbot واجهة Real Time Messaging API لذا يجب أن يكون تطبيق Classic Slack. نحن نسمي التطبيق Looker ولكن الأمر متروك لك.
2. انقر فوق علامة التبويب "OAuth and Permissions" وفي قسم النطاقات أضف النطاقات التالية باستخدام الزر "إضافة نطاق OAuth" - لا تنقر فوق الزر الأخضر "تحديث النطاقات"، حيث سيؤدي ذلك إلى تحويل التطبيق إلى النطاقات الجديدة سير العمل وسوف يكسر التطبيق الخاص بك! :
   1. channels:read
   2. chat:write:bot
   3. files:write:user
   4. team:read
   5. users:read
   6. commands (إذا كنت تخطط لتكوين أوامر الشرطة المائلة)
3. انتقل إلى "الصفحة الرئيسية للتطبيق" وانقر على "إضافة مستخدم Legacy Bot"
4. في أعلى صفحة "OAuth & Permissions"، انقر على "تثبيت التطبيق على مساحة العمل".
5. انقر فوق "السماح" للسماح لمساحة عمل Slack باستخدام التطبيق الذي تم إنشاؤه حديثًا.
6. في أعلى صفحة "OAuth & Permissions"، انسخ "Bot User OAuth Access Token" (ستحتاج إليه لاحقًا). ملاحظة: يجب أن يبدأ رمز الروبوت بـ xoxb- .
7. ضمن "المعلومات الأساسية"، يمكنك إضافة رمز ووصف لـ Lookerbot. وهنا الأيقونة التي نستخدمها.

افتراضيًا، تكون تطبيقات Slack داخلية لفريقك. لا تقم "بتوزيع" تطبيق Slack الخاص بك - فهذا سيجعله متاحًا لجميع مستخدمي Slack في العالم.

مهم

يرجى ملاحظة: لقد تغيرت بعض متغيرات البيئة أدناه. قد تحتاج إلى تعديلها من أجل الحفاظ على هذا العمل.

نشر هيروكو

أسرع طريقة لنشر الروبوت هي استخدام زر النشر الخاص بـ Heroku بنقرة واحدة، والذي سيوفر خادمًا لروبوتك. سيطالبك هذا بإعطاء التطبيق اسمًا فريدًا وإضافة مفتاح Slack API وتكوين جميع المتغيرات المطلوبة (راجع "متغيرات البيئة" أدناه).

بمجرد تعيين متغيرات البيئة ونشر الخادم، يجب أن يكون الروبوت جاهزًا للعمل! يمكنك أيضًا تكوين أوامر الشرطة المائلة بشكل اختياري.

استكشاف الأخطاء وإصلاحها

انظر قضايا التبعية على هيروكو؟ قم بتطبيق YARN_PRODUCTION=false كـ env. إلى النشر. راجع تقليم هيروكو لمزيد من التفاصيل.

النشر اليدوي

الروبوت هو تطبيق Node.js بسيط. يجب أن يكون التطبيق قادرًا على الوصول إلى كل من واجهة برمجة تطبيقات مثيل Looker وواجهة برمجة تطبيقات Slack. إذا كان لديك نسخة ذاتية الاستضافة من Looker، فتأكد من فتح المنفذ 19999 (أو core_port الخاص بك) من أجل الوصول إلى واجهة برمجة تطبيقات Looker.

متغيرات البيئة

يتم تكوين الروبوت بالكامل عبر متغيرات البيئة. ستحتاج إلى إعداد هذه المتغيرات:

• SLACK_API_KEY (مطلوب) - هذا هو المكان الذي ستضع فيه "رمز وصول OAuth لمستخدم Bot". يمكنك الدخول إلى تطبيق Slack ضمن "تثبيت التطبيق".

• LOOKER_URL (مطلوب) – عنوان URL للويب الخاص بمثيل Looker الخاص بك.

• LOOKER_API_BASE_URL (مطلوب) – نقطة نهاية واجهة برمجة التطبيقات لمثيل Looker الخاص بك. في معظم الحالات، سيكون هذا هو عنوان URL للويب متبوعًا بـ :19999/api/4.0 (استبدل 19999 بمنفذ core_port الخاص بك إذا كان مختلفًا).

• LOOKER_API_CLIENT_ID (مطلوب) – معرف عميل API للمستخدم الذي تريد تشغيل الروبوت به. يتطلب ذلك إنشاء مستخدم واجهة برمجة التطبيقات (API) أو مفتاح واجهة برمجة التطبيقات (API) لمستخدم حالي في Looker.

• LOOKER_API_CLIENT_SECRET (مطلوب) – سر عميل API للمستخدم الذي تريد تشغيل الروبوت به. يتطلب ذلك إنشاء مستخدم واجهة برمجة التطبيقات (API) أو مفتاح واجهة برمجة التطبيقات (API) لمستخدم حالي في Looker.

• LOOKER_CUSTOM_COMMAND_FOLDER_ID (اختياري) – معرف المجلد الذي تريد أن يستخدمه الروبوت لتحديد الأوامر المخصصة. اقرأ عن استخدام الأوامر المخصصة في مركز مساعدة Looker.

• LOOKER_WEBHOOK_TOKEN (اختياري) - رمز التحقق من صحة webhook الموجود في لوحة إدارة Looker. يعد هذا مطلوبًا فقط إذا كنت تستخدم الروبوت لإرسال خطافات الويب المجدولة.

• SLACK_SLASH_COMMAND_TOKEN (اختياري) – إذا كنت تريد استخدام أوامر الشرطة المائلة أو الرسائل التفاعلية مع Lookerbot، فقدم رمز التحقق من قسم "المعلومات الأساسية" في إعدادات التطبيق. هذه هي الطريقة التي سيتحقق بها الروبوت من سلامة أوامر الشرطة المائلة الواردة.

• PORT (اختياري) - المنفذ الذي سيعمل عليه خادم الويب الآلي لقبول أوامر الشرطة المائلة. الافتراضي هو 3333 .

إذا كنت ترغب في وضع متغيرات التكوين هذه على نظام الملفات بدلاً من ذلك، فيمكنك وضعها في ملف .env في جذر المشروع أيضًا. سيكون لمتغيرات البيئة الأولوية على إعدادات .env في حالة وجود كليهما.

سلوك التغيير والتبديل

هناك متغيران للبيئة يمكن استخدامهما لتعديل السلوك:

• LOOKER_SLACKBOT_LOADING_MESSAGES – اضبط هذا على false لتعطيل نشر رسائل التحميل.

• LOOKERBOT_DATA_ACTIONS_IN_MESSAGES – اضبط هذا على false لتعطيل إتاحة أزرار إجراءات البيانات لمستخدمي Slack.

(اختياري) خدمات التخزين لصور التصور

أمازون إس 3

• SLACKBOT_S3_BUCKET (اختياري) – إذا كنت تريد استخدام Lookerbot لنشر صور التصور، فقم بتوفير اسم حاوية Amazon S3.

• SLACKBOT_S3_BUCKET_REGION (اختياري) – إذا كنت تريد استخدام Lookerbot لنشر صور التصور، فقم بتوفير منطقة حاوية Amazon S3. الإعدادات الافتراضية لـ us-east-1 .

• AWS_ACCESS_KEY_ID (اختياري) – إذا كنت تريد استخدام Lookerbot لنشر صور التصور، فقم بتوفير مفتاح وصول Amazon S3 الذي يمكنه الكتابة إلى المجموعة المتوفرة.

• AWS_SECRET_ACCESS_KEY (اختياري) – إذا كنت تريد استخدام Lookerbot لنشر الصور المرئية، فقم بتوفير مفتاح وصول سري لـ Amazon S3 يمكنه الكتابة إلى المجموعة المتوفرة.

مايكروسوفت أزور

• AZURE_STORAGE_ACCOUNT (اختياري) - إذا كنت تريد استخدام Microsoft Azure Storage لتخزين الصور المرئية التي نشرها Lookerbot، فقم بتقديم اسم حساب Azure Storage الخاص بك.

• SLACKBOT_AZURE_CONTAINER (اختياري) - إذا كنت تريد استخدام Microsoft Azure Storage لتخزين الصور المرئية التي نشرها Lookerbot، فقم بتوفير اسم الحاوية داخل حساب Azure Storage الذي ترغب في استخدامه.

• AZURE_STORAGE_ACCESS_KEY (اختياري) - إذا كنت تستخدم Microsoft Azure Storage لتخزين الصور المرئية التي نشرها Lookerbot، فقم بتوفير مفتاح وصول يمكنه الكتابة إلى حساب Azure Storage والحاوية المتوفرة.

جوجل التخزين السحابي

• GOOGLE_CLOUD_BUCKET (اختياري) - إذا كنت تريد استخدام Google Cloud لتخزين الصور المرئية التي نشرها Lookerbot، فاذكر اسم المجموعة الخاصة بك.

إذا كان Lookerbot يعمل على Google Compute Engine، فلن تكون هناك حاجة إلى مزيد من المعلومات إذا تم إعداد نطاقات واجهة برمجة التطبيقات المناسبة.

بخلاف ذلك، يمكنك تقديم بيانات الاعتماد مباشرةً:

• GOOGLE_CLOUD_PROJECT (اختياري) - إذا كنت تريد استخدام Google Cloud لتخزين الصور المرئية التي نشرها Lookerbot، فاذكر اسم مشروعك.

• GOOGLE_CLOUD_CREDENTIALS_JSON (اختياري) - إذا كنت تستخدم Google Cloud لتخزين الصور المرئية التي نشرها Lookerbot، فقدم محتوى ملف بيانات الاعتماد JSON الذي حصلت عليه من موقع Google Cloud على الويب.

الشهادات الموقعة ذاتيًا أو غير الصالحة

إذا كان مثيل Looker الخاص بك يستخدم شهادة موقعة ذاتيًا، فسيرفض Lookerbot الاتصال بها افتراضيًا.

سيؤدي تعيين متغير البيئة NODE_TLS_REJECT_UNAUTHORIZED إلى 0 إلى توجيه Lookerbot لقبول الاتصالات ذات الشهادات غير الصالحة. الرجاء التأكد من قيامك بتقييم شامل للآثار الأمنية لهذا الإجراء على البنية الأساسية لديك قبل تعيين هذا المتغير.

يجب أن يؤثر هذا فقط على عمليات النشر المحلية لـ Looker. لا تقم بتعيين متغير البيئة هذا إذا كان Looker يستضيف مثيلك.

ربط الروبوت بمثيلات Looker المتعددة

إذا كنت تريد أن يتصل الروبوت بمثيلات متعددة من Looker، فيمكنك تكوين الروبوت باستخدام متغير بيئة LOOKERS . يجب أن يكون هذا المتغير عبارة عن مصفوفة JSON من كائنات JSON، يمثل كل منها مثيل Looker ومعلومات المصادقة الخاصة به.

يجب أن تحتوي كائنات JSON على المفاتيح التالية:

• يجب أن يكون url هو عنوان URL للويب الخاص بالمثيل
• يجب أن تكون apiBaseUrl هي نقطة نهاية واجهة برمجة التطبيقات
• يجب أن يكون clientID هو معرف عميل واجهة برمجة التطبيقات (API) للمستخدم الذي تريد أن يعمل الروبوت به
• يجب أن يكون clientSecret هو السر لمفتاح API هذا
• يعد customCommandFolderId معلمة اختيارية تمثل المجلد الذي تريد أن يستخدمه الروبوت لتحديد الأوامر المخصصة.
• webhookToken هي معلمة اختيارية. إنه رمز التحقق من صحة webhook الموجود في لوحة إدارة Looker. يعد هذا مطلوبًا فقط إذا كنت تستخدم الروبوت لإرسال خطافات الويب المجدولة.

إليك مثال JSON الذي يتصل بمثيلين من 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 " }]

يتم تجاهل المتغيرات LOOKER_URL و LOOKER_API_BASE_URL و LOOKER_API_CLIENT_ID و LOOKER_API_CLIENT_SECRET و LOOKER_WEBHOOK_TOKEN و LOOKER_CUSTOM_COMMAND_FOLDER_ID عند تعيين LOOKERS .

تشغيل الخادم

لتشغيل الخادم:

1. تأكد من تثبيت Node.js
2. yarn install لتثبيت التبعيات
3. yarn start لبدء خادم بوت. سيتم تشغيل الخادم حتى تكتب Ctrl+C لإيقافه.

سيسمح لك Procfile المضمن أيضًا بتشغيل التطبيق باستخدام رئيس العمال أو رئيس عمال العقدة. توفر هذه المكتبات أيضًا طرقًا سهلة لإنشاء البرامج النصية لاستخدامها مع upstart و supervisord و systemd .

تكوين أوامر القطع

أوامر الشرطة المائلة ليست مطلوبة للتفاعل مع الروبوت. يمكنك إرسال رسالة مباشرة للبوت أو ذكر البوت مثل:

@المساعدة

واستخدام كافة الوظائف.

ومع ذلك، فإن أوامر Slash أكثر سهولة في الاستخدام وتسمح لـ Slack بالإكمال التلقائي، لذلك ربما ترغب في إعدادها.

1. انتقل إلى https://api.slack.com/apps وابحث عن تطبيقك.
2. اختر "أوامر الشرطة المائلة" وانقر على "إنشاء أمر جديد".
3. قم بإنشاء أمر لاستخدامه في برنامج Looker bot. نحن نستخدم /looker ولكن الأمر متروك لك.
4. قم بتعيين عنوان URL إلى أي مكان يستضيف خادم الروبوت الخاص بك (إذا استخدمت Heroku لإعداد الخادم، فسيكون هذا هو اسم التطبيق الفريد الذي اخترته). المسار إلى نقطة نهاية أمر الشرطة المائلة هو /slack/receive ، لذا إذا كان خادمك موجودًا على https://example.com ، فسيكون عنوان URL هو https://example.com/slack/receive .
5. ضمن الإعدادات، اختر "تثبيت التطبيق" مرة أخرى، ثم "إعادة تثبيت التطبيق" وقم بالمصادقة.
6. ضمن "المعلومات الأساسية"، احصل على رمز التحقق. ستستخدم هذا لتعيين متغير البيئة SLACK_SLASH_COMMAND_TOKEN .

جدولة البيانات إلى Slack

يمكنك استخدام الروبوت لإرسال المظاهر المجدولة إلى Slack.

1. انقر فوق "جدول زمني" في نظرة
2. اضبط "الوجهة" على "Webhook"
3. اترك "التنسيق" مضبوطًا على الوضع الافتراضي. يتم تجاهل اختيار التنسيق.
4. أدخل عنوان URL الخاص بالويب هوك للخادم الذي قمت بإعداده.

• النشر على القنوات العامة /slack/post/channel/my-channel-name
  • (يجب دعوة Lookerbot إلى هذه القناة للنشر فيها.)
• النشر في المجموعات الخاصة /slack/post/group/my-channel-name
  • (يجب دعوة Lookerbot إلى هذه المجموعة للنشر فيها.)
• لتوجيه رسالة إلى المستخدم /slack/post/dm/myusername

تكون عناوين URL هذه مسبوقة بعنوان URL الخاص بخادمك. (إذا استخدمت نشر Heroku، فسيكون هذا هو اسم التطبيق الفريد الذي اخترته). لذا، إذا كان خادمك موجودًا على https://example.com وتريد النشر على قناة تسمى data-science ، فسيكون عنوان URL هو https://example.com/slack/post/channel/data-science .

5. ستحتاج إلى التأكد من تعيين متغير البيئة LOOKER_WEBHOOK_TOKEN بشكل صحيح على نفس رمز التحقق الموجود في لوحة إدارة Looker.

إجراءات البيانات

تنفيذ إجراءات البيانات من Slack

افتراضيًا، ستظهر إجراءات البيانات البسيطة في Slack لتصورات القيمة الفردية. إجراءات البيانات التي تحتوي على نماذج غير مدعومة حاليًا.

يمكن تعطيل هذا على أساس كل إجراء باستخدام القالب السائل في تعريف الإجراء لتقييد الوصول إلى مستخدمين معينين. وبدلاً من ذلك، يمكن تعطيل أزرار الإجراءات بالكامل باستخدام متغير تكوين الروبوت LOOKERBOT_DATA_ACTIONS_IN_MESSAGES .

هناك تكوين إضافي سريع مطلوب لاستخدام إجراءات البيانات من Slack:

1. انتقل إلى https://api.slack.com/apps وابحث عن تطبيقك.
2. اختر "الرسائل التفاعلية" وقم بتمكين هذه الميزة.
3. بالنسبة إلى "عنوان URL للطلب"، قم بتعيين عنوان URL إلى أي مكان يستضيف خادم الروبوت الخاص بك (إذا كنت تستخدم Heroku لإعداد الخادم، فسيكون هذا هو اسم التطبيق الفريد الذي اخترته). المسار لطلبات الرسائل التفاعلية هو /slack/action ، لذا إذا كان الخادم الخاص بك موجودًا على https://example.com ، فسيكون عنوان URL للطلب هو https://example.com/slack/action .
4. قم بتكوين Slash Command Token كما هو موضح هنا.

إرسال رسائل Slack عبر إجراءات البيانات

يقوم خادم الروبوت أيضًا بتنفيذ نقاط النهاية للسماح لك بإرسال إجراءات البيانات بسهولة إلى Slack.

فيما يلي مثال لبعض إجراءات البيانات التي يمكنك تنفيذها في LookML الخاص بك. (استبدل https://example.com باسم مضيف برنامج الروبوت الخاص بك.)

للاستفادة من هذا، ستحتاج إلى التأكد من تعيين متغير البيئة LOOKER_WEBHOOK_TOKEN بشكل صحيح على نفس رمز التحقق المميز الموجود في لوحة إدارة Looker، تمامًا كما هو الحال مع جدولة البيانات.

 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 "
    }
  }

}

الوصول إلى البيانات

نقترح إنشاء مستخدم Looker API خصيصًا لـ Lookerbot، واستخدام بيانات اعتماد API الخاصة بهذا المستخدم. تجدر الإشارة إلى أن كل من يمكنه التحدث إلى Lookerbot الخاص بك لديه أذونات هذا المستخدم . إذا كانت هناك بيانات لا تريد أن يصل إليها الأشخاص عبر Slack، فتأكد من عدم تمكن المستخدم من الوصول إليها باستخدام آليات الأذونات الخاصة بـ Looker.

ضع في اعتبارك أيضًا أنه عندما يجيب برنامج Looker bot على الأسئلة في Slack ، تنتقل البيانات الناتجة إلى Slack ويتم استضافتها الآن هناك . تأكد من النظر بعناية في البيانات المسموح لها بمغادرة Looker. يحتفظ Slack بسجل رسائل الدردشة على خوادمه ويدفع العديد من أنواع الإشعارات حول الرسائل عبر خدمات أخرى.

للسماح بظهور المرئيات في Slack، إذا تم تكوينها للقيام بذلك، يقوم الروبوت بتحميلها كصور إلى Amazon S3 باستخدام عنوان URL طويل جدًا تم إنشاؤه عشوائيًا. يمكن لأي شخص لديه عنوان URL هذا الوصول إلى تلك الصورة في أي وقت، على الرغم من أنه سيكون من الصعب للغاية تخمينها.

إذا اخترت إزالة ملفات الصور من S3، فستكون رسائل Slack التي تعتمد على تلك الصور فارغة.

التشغيل محليا من أجل التنمية

1. قم بتثبيت Node.js على جهازك المحلي.
2. قم بتثبيت الغزل على جهازك المحلي.
3. أضف متغيرات البيئة الخاصة بك إلى ملف يسمى .env في قاعدة الريبو.
4. تثبيت التبعيات مع yarn install
5. تشغيل الروبوت مع yarn start

المساهمة

نرحب بطلبات السحب - ونود أن نحصل على مساعدة في توسيع وظائف الروبوت.

إذا كان لديك أي مشكلة مع البوت، يرجى فتح مشكلة حتى نتمكن من مساعدتك!