שיתוף נתונים דרך מרכז פעולות

בנוסף לשליחת תוכן ליעדים המובנים של Looker, אפשר להשתמש בפעולות – שנקראות גם שילובים – כדי לשלוח תוכן לשירותים של צד שלישי שמשולבים עם Looker דרך שרת של מרכז פעולות.

בדף הזה מוסבר על האפשרויות ליצירת פעולות מותאמות אישית שאפשר לבקש להוסיף ל-Looker Action Hub או להוסיף לשרת פרטי של מרכז הפעולות. בדף הזה מוסבר גם איך להתחיל הרצה של שרת מקומי של מרכז הפעולות כדי לבדוק את הפעולות המותאמות אישית או להפעיל שרת פרטי של מרכז הפעולות.

כדי להתחיל להשתמש בפעולות, אפשר:

אחרי שהפעולה מתווספת למרכז הפעולות, אדמין ב-Looker יכול להפעיל את הפעולה כדי להעביר תוכן מ-Looker לשירותים האלה.

אפשר גם להגדיר כמה מרכזי פעולות אם רוצים להשתמש בשילובים של Looker דרך Looker Action Hub וגם לארח פעולות פרטיות או מותאמות אישית משלכם. הפעולות של כל מרכז פעולות יופיעו בדף פעולות בחלונית ניהול.

‫Looker Action Hub

‫Looker מארח ומספק את Looker Action Hub, שרת חסר מצב שמטמיע את Looker's Action API וחושף פעולות פופולריות. כל נתון שהמשתמשים שולחים באמצעות פעולה יעבור עיבוד זמני בשרת של Looker Action Hub ולא במופע Looker שלכם.

‫Looker כבר משולב עם כמה שירותים. במאמר הגדרות אדמין – פעולות מוסבר איך להפעיל את השירותים הקיימים האלה.

הדרישות של Looker Action Hub

כדי להשתמש בשילובים של Looker, ל-Looker Action Hub צריכה להיות אפשרות לתקשר עם המכונה של Looker ולעמוד בדרישות של Looker Action Hub. אדמינים של מופעי אירוח בצד הלקוח צריכים לקחת בחשבון גורמים נוספים כשהם בוחרים להפעיל שילובים של Looker מ-Looker Action Hub, במיוחד שילובים שתומכים בתוצאות בהזרמה או שמשתמשים ב-OAuth.

ל-Looker Action Hub צריכה להיות אפשרות לשלוח ולקבל בקשות API בדרכים הבאות:

אם הפריסה של Looker לא יכולה להתמודד עם הבקשות האלה, או אם התכונה רשימת כתובות IP שאושרו מופעלת במופע Looker, כדאי להגדיר שרת מקומי של מרכז פעולות כדי להפעיל שילובי Looker פרטיים או פעולות בהתאמה אישית. אדמינים של מופעי אירוח בצד הלקוח יכולים גם לפרוס שרת פעולות מקומי במיוחד לפעולות סטרימינג ו-OAuth.

אם אתם משתמשים במכונה של Looker (Google Cloud core) שמוגדר בה רשימת כתובות IP שאפשר לגשת אליהן, צריך לסמן את התיבה Link Google services with this instance (קישור שירותי Google למכונה הזו) בכרטיסייה Details (פרטים) בדף Instance (מכונה) במסוף Google Cloud כדי להתחבר ל-Looker Action Hub.

בקשות מהמופע של Looker לרשת Looker Action Hub

בקשות ל-actions.looker.com מתפרשות ככתובת IP דינמית. בקשות יוצאות מהמכונה של Looker צריכות להגיע לנקודות הקצה הבאות:

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

כאשר name הוא השם הפרוגרמטי של הפעולה.

בקשות מהדפדפן של משתמש Looker לרשת Looker Action Hub

הדפדפן של משתמש Looker צריך להיות מסוגל לשלוח בקשות לנקודות הקצה הבאות של Looker Action Hub (לOAuth):

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

כאשר name הוא השם הפרוגרמטי של הפעולה.

בקשות מרשת Looker Action Hub למופע Looker

‫Looker Action Hub חייב לשלוח בקשות למופע Looker לפעולות שתומכות בתוצאות מוזרמות או שמשתמשות ב-OAuth.

פעולת סטרימינג מאפשרת לפעולה לצרוך שאילתות שמספקות את כל התוצאות. פעולות שמופעלות באמצעות OAuth משתמשות באימות לכל משתמש דרך תהליכי OAuth 2.0. פעולות OAuth חייבות לאחסן את פרטי הכניסה של המשתמשים במופע המקור של Looker, כי מרכז הפעולות של Looker הוא חסר מצב ורב-דיירים, והוא לא יאחסן פרטי כניסה ספציפיים למשתמשים מכל סוג שהוא.

הבקשות מ-Looker Action Hub למופע Looker מופיעות באופן הבא:

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

כתובות ה-URL האלה נוצרות במקום במופע Looker לפני שהן נשלחות אל Looker Action Hub. לכן, מרכז הפעולות של Looker צריך להיות מסוגל גם לפתור את <host_looker_url> לכתובת IP וגם לשלוח בקשות לרשת שבה נמצא מופע Looker שלכם.

ל-Looker Action Hub יש כתובות IP סטטיות ליציאה, שהבקשות תמיד יגיעו מהן: 35.153.89.114, ‏ 104.196.138.163 ו-35.169.42.87. אדמינים של מופעים שמתארחים ב-Looker והפעילו את רשימת ההיתרים של כתובות IP צריכים להוסיף את כתובות ה-IP האלה כדי להשתמש בפעולות שתומכות בתוצאות שמוזרמות או בפעולות שמשתמשות ב-OAuth.

שיקולים לגבי מופעים באירוח בצד הלקוח

כדי להשתמש בשילובים של Looker, Looker Action Hub צריך להיות מסוגל לתקשר עם המכונה של Looker ולעמוד בדרישות של Looker Action Hub. זה לא תמיד אפשרי במקרים של מופעי Looker באירוח בצד הלקוח, מסיבות שונות. אם לא מתאפשרת תקשורת דו-כיוונית בין Looker Action Hub לבין מופע Looker, יכול להיות ש-Looker Action Hub יציג התנהגות לא צפויה או לא רצויה, כמו שאילתות תקועות או פעולות לא זמינות.

כדי לפתור את הבעיה הפוטנציאלית של חוסר תקשורת בין Looker Action Hub לבין מופע Looker, אדמינים ב-Looker יכולים להטמיע אחד מהפתרונות שמוצגים בהמשך הדף הזה. הפתרון המתאים או השילוב המתאים של פתרונות תלוי בארכיטקטורה של מופע Looker:

  • אם אי אפשר לפתור את הבעיה במכונה שמתארחת אצל הלקוח באמצעות Looker Action Hub – כלומר, אם Looker Action Hub לא יכול לקבל בקשות מהמכונה של Looker – אדמינים של Looker יכולים לפנות למומחה מכירות של Google Cloud כדי להפעיל את תכונת הרישיון public_host_url. התכונה הזו ברישיון חושפת את אפשרות ההפעלה --public-host-url, שמאפשרת לאדמינים לציין שם מארח <public_host_url> שניתן לפתרון ושונה מהמופע <host_looker_url>. הפרמטר public_host_url מבטל את שם המארח עבור כתובות URL ספציפיות של קריאה חוזרת ב-Looker Action Hub, ומנתב את כתובות ה-URL האלה של הקריאה החוזרת דרך פרוקסי הפוך שמוגדר בו public_host_url כשם שניתן לפתרון באופן ציבורי. שרת ה-proxy ההפוך הזה מקבל בקשות רק מכתובות ה-IP הסטטיות ליציאה של Looker Action Hub. אדמינים ב-Looker שמשתמשים בשיטה הזו צריכים להוסיף לרשימת ההיתרים את כתובות ה-IP ליציאה שדרכן Looker Action Hub שולח בקשות למופע Looker: ‏ 35.153.89.114,‏ 104.196.138.163 ו-35.169.42.87.

  • אם כתובת ה-URL של מופע אירוח בצד הלקוח ניתנת לפתרון על ידי מופע Looker, אבל Looker Action Hub לא יכול לשלוח בקשות למופע Looker, יכול להיות שהמשתמשים לא יוכלו להגדיר או להשתמש בפעולות שתומכות בתוצאות בהזרמה או בפעולות שמשתמשות ב-OAuth. כדי לפתור את הבעיה, אדמינים ב-Looker צריכים להוסיף לרשימת ההיתרים את כתובות ה-IP של היציאה שדרכן מרכז הפעולות של Looker שולח בקשות למופע Looker: 35.153.89.114,‏ 104.196.138.163 ו-35.169.42.87.

  • אם אף אחד מהפתרונות שצוינו לא מתאים לארכיטקטורה של מופע Looker, אדמינים של Looker יכולים לפרוס מרכז פעולות באירוח בצד הלקוח לכל הפעולות או רק לפעולות שתומכות בתוצאות בהזרמה או שמשתמשות ב-OAuth.

  • כדי לפרוס מרכז פעולות באירוח בצד הלקוח, צריך לוודא שקובץ ה-JAR מאוחסן בשרת ציבורי כדי שה-Looker Action Hub יוכל לתקשר איתו. עם זאת, לא מומלץ להשתמש בפתרון הזה.

בנוסף, יכול להיות שלא ניתן יהיה להשתמש בפעולות של OAuth וסטרימינג במופע Looker שמתארח אצל הלקוח אם המופע משתמש באישור SSL שהונפק על ידי רשות אישורים (CA) שלא מופיעה ברשימה הזו של אישורי בסיס.

פיתוח פעולה בהתאמה אישית

בקטע הזה מוסבר איך לכתוב ולבדוק פעולה מותאמת אישית באמצעות קוד המקור של Looker Action Hub. כדי לראות דוגמאות לקוד פונקציונלי, אפשר לבדוק את הפעולות הקיימות במאגר looker-open-source/actions ב-GitHub.

כדי ליצור פעולה מותאמת אישית:

  1. הגדרת מאגר פיתוח
  2. כתיבת הפעולה
  3. בדיקה של הפעולה
  4. פרסום והפעלה של הפעולה, ב-Looker Action Hub או בשרת פרטי משלכם של מרכז פעולות

כמו בכל פעולה, יכול להיות שתצטרכו להגדיר את מודלי LookML עם פרמטרים ספציפיים לפני שתוכלו להשתמש בפעולה כדי להעביר את הנתונים.

הגדרת מאגר פיתוח

מרכז הפעולות של Looker הוא שרת Node.js שנכתב ב-TypeScript, שכבה קטנה מעל JavaScript מודרני שמוסיפה מידע על סוגים כדי לעזור לזהות שגיאות בתכנות. אם אתם מכירים את JavaScript, רוב השפה של TypeScript אמורה להיות מוכרת לכם.

כדי להריץ את Looker Action Hub, צריך את התוכנות הבאות:

  • Node.js
  • ‫Node Version Manager‏ (NVM – לבחירת הגרסה המתאימה של Node.js)
  • ‫Yarn (לניהול יחסי תלות)

אחרי שמתקינים את התוכנה הנדרשת, אפשר להגדיר את סביבת הפיתוח. בדוגמה הבאה נעשה שימוש ב-Git.

  1. משכפלים את מאגר looker-open-source/actions באופן מקומי:

    git clone git@github.com:looker-open-source/actions.git

  2. יוצרים ספרייה עם שם הפעולה בספרייה actions/src/actions. לדוגמה:

    mkdir actions/src/actions/my_action

  3. מתחילים לאכלס את הספרייה בקבצים שנדרשים לביצוע הפעולה. דוגמה למבנה קובץ זמינה במאגר פעולות GitHub.

מומלץ להוסיף גם את הפרטים הבאים:

  • קובץ README עם הסבר על המטרה של הפעולה ועל אמצעי האימות שלה
  • סמל PNG שיוצג ב-Looker Action Hub (או ב-Action Hub פרטי במופע Looker שלכם) ובחלונות של העברת נתונים ב-Looker
  • כל הקבצים של הבדיקות שרוצים להריץ על קוד הפעולה – זה שונה מבדיקת הפעולה

כתיבת פעולה

דרישת עיצוב לשרת Looker Action Hub היא שהוא יישאר חסר מצב לחלוטין, ולכן אסור לאחסן מידע באפליקציית הפעולה או בשירות. כל המידע שנדרש לביצוע הפעולה צריך להיכלל בקריאות הבקשה של קובץ הפעולה.

התוכן המדויק של קובץ הפעולה משתנה בהתאם לשירות, לסוג או לרמה שבהם הפעולה מתבצעת, ולפורמטים של הנתונים או של ההדמיה שצריך לציין. אפשר גם להגדיר את הפעולה לתהליכי הרשאה של OAuth 2.0.

קבצי הפעולה מבוססים על שיטת ה-API‏ /execute. בקשות Looker API מקבלות DataActionRequest בכל פעם שמשתמש מבצע פעולה ב-Looker. ה-DataActionRequest מכיל את כל הנתונים והמטא-נתונים שנדרשים להפעלת הפעולה. יש גם שיטה /form שאפשר להשתמש בה כדי לאסוף מידע נוסף מהמשתמש לפני שהוא מבצע את הפעולה. השדות שציינתם ב-/form יופיעו בחלון הקופץ שליחה או תזמון כשמשתמשים יבחרו את הפעולה כיעד למסירת הנתונים שלהם.

כשכותבים את קובץ הפעולה, צריך לכלול בהגדרת הפעולה לפחות את הפרמטרים הבאים שמסומנים בתווית Required:

פרמטר חובה תיאור סוג נתונים
name כן שם ייחודי לפעולה. השם הזה צריך להיות ייחודי לכל הפעולות ב-Looker Action Hub. מחרוזת
url כן כתובת URL אבסולוטית של נקודת הקצה /execute לפעולה הזו. מחרוזת
label כן תווית של הפעולה שקריאה לבני אדם. מחרוזת
supportedActionTypes כן רשימה של סוגי הפעולות שהפעולה תומכת בהם. הערכים התקפים הם "cell",‏ "query" ו-"dashboard". מחרוזת
formURL לא כתובת URL אבסולוטית של נקודת הקצה /form לפעולה הזו. מחרוזת
description לא תיאור הפעולה. מחרוזת
params לא מערך של parameters לפעולה. לכל פרמטר, כוללים את השם, התווית והתיאור בפורמט מחרוזת. אלה השדות שמופיעים בדף ההפעלה של הפעולה בחלונית Admin. כדי לנהל את האופן שבו משתמשים יכולים להעביר נתונים ליעד של פעולה, אתם יכולים לציין מאפיין משתמש שחייב להיות לו ערך מוגדר. parameters
supportedFormats לא רשימה של פורמטים של נתונים שהפעולה תומכת בהם. הערכים התקפים הם "txt", ‏ "csv", ‏ "inline_json", ‏ "json", ‏ "json_detail", "json_detail_lite_stream", "xlsx", "html", "wysiwyg_pdf", "assembled_pdf", and "wysiwyg_png". מחרוזת
supportedFormattings לא רשימה של אפשרויות עיצוב שהפעולה תומכת בהן. הערכים התקינים הם "formatted" ו-"unformatted". מחרוזת
supportedVisualizationFormattings לא רשימה של אפשרויות עיצוב של הוויזואליזציה שהפעולה תומכת בהן. הערכים התקינים הם "apply" ו-"noapply". מחרוזת
iconName לא URI של נתונים שמייצג תמונת סמל לפעולה. מחרוזת
requiredFields לא רשימה של תיאורים של שדות חובה שהפעולה הזו תואמת להם. אם יש כמה רשומות ברשימה הזו, הפעולה דורשת יותר משדה אחד. RequiredField
supportedDownloadSettings לא ערך בוליאני שקובע אם כתובת URL להורדה לשימוש חד-פעמי תישלח לפעולה כדי לאפשר סטרימינג בלתי מוגבל של נתונים. הפרמטר מוגדר על ידי הפרמטר usesStreaming, שהוא true/false בוליאני. אם usesStreaming = true, אז supportedDownloadSettings = url. אם usesStreaming = false, אז supportedDownloadSettings = push. בוליאני
usesOAuth לא ערך בוליאני שקובע אם הפעולה היא פעולת OAuth. ההגדרה הזו תקבע אם תישלח לפעולה קישור לשימוש חד-פעמי, כדי להגדיר את state למשתמש ספציפי עבור הפעולה הזו. בוליאני
usesStreaming לא ערך בוליאני שקובע אם הפעולה תומכת בתוצאות של שאילתות בסטרימינג. בודקים את העמודה משתמש בסטרימינג של נתונים (כן/לא) ברשימת השירותים המשולבים. יכול להיות שפעולות שמשדרות תוצאות ידרשו הגדרה של שרת מרכז פעולות מקומי. מידע נוסף זמין בדף שיטות מומלצות בנושא הגדרת מרכז פעולות מקומי לפעולות שמשתמשות ב-OAuth או בסטרימינג. בוליאני
minimumSupportedVersion לא גרסת Looker המינימלית שבה הפעולה תופיע ברשימת מרכז הפעולות בחלונית אדמין. מחרוזת

דוגמאות לפעולות מ-Looker Action Hub זמינות ב-GitHub לעיון.

סוגי הפעולות הנתמכים

‫Looker תומך בשלושה סוגים של פעולות, כפי שמצוין בפרמטר supportedActionTypes של הפעולה: שאילתה, תא ולוח בקרה.

  • פעולה ברמת השאילתה: פעולה ששולחת שאילתה שלמה. לדוגמה, פעולת פילוח היא פעולה ברמת השאילתה.
  • פעולה ברמת התא: פעולה ברמת התא שולחת את הערך של תא ספציפי בטבלת נתונים. סוג הפעולה הזה שונה מפעולות על נתונים, שאפשר להגדיר למאפיינים או למדדים באמצעות הפרמטר action. כדי לשלוח מידע מתא ספציפי בטבלה, Looker משתמש בתגים כדי למפות פעולות לתאים המתאימים. בפעולות צריך לציין אילו תגים הן תומכות בהם ב-requiredFields. כדי למפות פעולות ושדות, צריך לציין בשדות ב-LookML לאילו תגים הם ממופים באמצעות פרמטר LookML‏ tags. לדוגמה, פעולת ההודעה של Twilio משתמשת בתג phone כדי שמפתחי LookML יוכלו לקבוע באילו שדות של מספרי טלפון תופיע פעולת Twilio.
  • פעולה ברמת מרכז הבקרה: פעולה ברמת מרכז הבקרה תומכת בשליחת תמונה של מרכז הבקרה. לדוגמה, הפעולה SendGrid שולחת תמונות של מרכז הבקרה באימייל.

הוספת מאפייני משתמש לפעולות מותאמות אישית

בפעולות בהתאמה אישית, אפשר להוסיף מאפייני משתמש בפרמטר params של קובץ הפעולה. אם הפרמטר נדרש, כל משתמש צריך להגדיר ערך למאפיין הזה בחשבון המשתמש שלו או בקבוצת המשתמשים שהוא משתייך אליה, בנוסף לsend_to_integration הרשאה, כדי שהפעולה תוצג כאפשרות יעד כששולחים או מתזמנים תוכן.

כדי להוסיף מאפיין משתמש לפעולה:

  1. יכול להיות שאדמין ב-Looker יצטרך ליצור את מאפיין המשתמש שמתאים ל-user_attribute_param אם הוא עדיין לא קיים.
  2. מגדירים ערך תקין למאפיין המשתמש עבור המשתמשים או קבוצות המשתמשים שצריכים להעביר תוכן ליעד הפעולה. (למשתמשים האלה צריכות להיות גם הרשאות send_to_integration).
  3. הפרמטר params מייצג את שדות הטופס שאדמין ב-Looker צריך להגדיר בדף ההפעלה של הפעולה מתוך רשימת הפעולות בחלונית האדמין. בפרמטר params של קובץ הפעולה, כוללים את הפרטים הבאים:
  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,
  }]

כאשר user_attribute_name הוא מאפיין המשתמש שמוגדר בשדה Name בדף User Attributes בקטע Users בחלונית Admin, ‏ required: true מציין שמשתמש צריך להגדיר ערך תקף שאינו null למאפיין המשתמש הזה כדי לראות את הפעולה כשהנתונים מועברים, ו-sensitive: true מציין שמאפיין המשתמש מוצפן ואף פעם לא מוצג בממשק המשתמש של Looker אחרי שהוא מוזן. אפשר לציין כמה פרמטרים משניים של מאפייני משתמש.

  1. פורסים את העדכונים בשרת של מרכז הפעולות.
    • אם מוסיפים פעולה חדשה, אדמין ב-Looker צריך להפעיל את הפעולה בלחיצה על הלחצן הפעלה לצד הפעולה בדף פעולות בחלונית אדמין.
    • אם אתם מעדכנים פעולה קיימת, אתם צריכים לרענן את רשימת הפעולות על ידי לחיצה על הלחצן רענון. לאחר מכן לוחצים על לחצן ההגדרות.
  2. בדף ההגדרות או ההפעלה של הפעולה, אדמין ב-Looker צריך להגדיר את שדות הטופס של הפעולה כדי לשלוף מידע ממאפיין המשתמש. לשם כך, לוחצים על סמל מאפיין המשתמש משמאל לשדה המתאים ובוחרים את מאפיין המשתמש הרצוי.

פרמטרים של requiredField פעולות ברמת התא

כדי להגדיר פעולות ברמת התא, אפשר להגדיר את שדות ה-LookML של המודל כך שיעבירו נתונים ליעד הפעולה. לשם כך, צריך לציין אילו תגים הפעולה תומכת בהם בפרמטר requiredFields של קובץ הפעולה.

פרמטר חובה תיאור סוג הנתונים
tag לא אם התג הזה קיים, הוא תואם לשדה שיש לו את התג הזה. מחרוזת
any_tag לא אם הוא קיים, הוא מחליף את tag ומתאים לשדה שיש לו אחד מהתגים שסופקו. מחרוזת
all_tags לא אם הפרמטר קיים, הוא מחליף את tag ומתאים לשדה שיש בו את כל התגים שצוינו. מחרוזת

פורמטים נתמכים של נתונים

המחלקה DataActionRequest מגדירה את פורמט מסירת הנתונים שזמין לפעולה. במקרה של פעולות ברמת השאילתה, הבקשה תכלול קובץ מצורף שיכול להיות בכמה פורמטים. בפעולה אפשר לציין פורמט אחד או יותר של supportedFormats או לאפשר למשתמש לבחור את הפורמט על ידי ציון כל הפורמטים האפשריים. בפעולות ברמת התא, הערך של התא יופיע ב-DataActionRequest.

הגדרת פעולה ל-OAuth

אתם יכולים להגדיר את הפעולה כך שהמשתמשים יוכלו לבצע אימות לפעולה באמצעות OAuth. למרות ש-Looker Action Hub צריך להישאר בלי שמירת מצב, אפשר לאכוף מצב באמצעות בקשת טופס מ-Looker Action API.

תהליך הרשאה באמצעות OAuth בפעולות ב-Looker

בפעולות ב-Looker Action Hub, אפשר להרחיב OAuthAction במקום Hub.Action כדי להגדיר ערך בוליאני שמציין אילו שיטות OAuth נדרשות לאימות משתמש בפעולה. לכל פעולה שמופעל בה OAuth או שמופעל בה מצב, Looker שומר מצב לכל משתמש ולכל פעולה, כך שלכל שילוב של פעולה ומשתמש יש אירוע OAuth עצמאי.

תהליך יצירת הפעולות כולל בדרך כלל בקשת /form ואחריה בקשת /execute. ב-OAuth, לבקשת /form צריכה להיות שיטה לקביעה אם המשתמש מאומת בשירות היעד. אם המשתמש כבר מאומת, הפעולה צריכה להחזיר /form רגיל בהתאם למה שנדרש בבקשת /execute. אם המשתמש לא מאומת, הפעולה מחזירה קישור שיפעיל תהליך OAuth.

שמירת מצב באמצעות כתובת ה-URL של OAuth

‫Looker ישלח בקשת HTTP POST עם גוף ריק לנקודת הקצה ActionList. אם הפעולה מחזירה uses_oauth: true בהגדרה שלה, אז הפעולה תקבל state_url לשימוש חד-פעמי בכל בקשת /form מ-Looker. ‫state_url היא כתובת URL מיוחדת לשימוש חד-פעמי, שמגדירה את מצב המשתמש לפעולה מסוימת.

אם המשתמש לא מאומת בנקודת הקצה, התוצאה /form שמוחזרת צריכה להכיל form_field מסוג oauth_link שמופנה לנקודת הקצה /oauth של פעולה. הפרמטר state_url צריך להיות מוצפן ולהישמר כפרמטר state ב-oauth_url שמוחזר. לדוגמה:

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

בדוגמה הזו, נקודת הקצה /oauth מפנה את המשתמש לשרת האימות. נקודת הקצה /oauth יוצרת את ההפניה האוטומטית בשיטה oauthUrl(...) בפעולת OAuth, כמו שמוצג ב-Dropbox OauthUrl.

הפרמטר state שמכיל את הנתונים המוצפנים state_url צריך לעבור אל Looker Action Hub.

שמירת מצב באמצעות ה-URI של ההפניה האוטומטית במרכז הפעולות

בנקודת הקצה /oauth, נוצר גם redirect_uri עבור מרכז הפעולות והוא מועבר ל-method‏ oauthUrl(...) של הפעולה. הערך של redirect_uri הוא מהצורה /actions/src/actions/my_maction/oauth_redirect, וזו נקודת הקצה שמשמשת אם האימות מחזיר תוצאה.

נקודת הקצה הזו תקרא לשיטה oauthFetchInfo(...), שצריכה להיות מיושמת על ידי השיטה OauthAction כדי לחלץ את המידע הדרוש ולנסות לקבל או לשמור כל מצב או auth שהתקבלו משרת האימות.

‫state מפענח את state_url המוצפן ומשתמש בו כדי לשלוח בקשת POST של state בחזרה אל Looker. בפעם הבאה שמשתמש ישלח בקשה לפעולה הזו, המצב שנשמר יישלח אל Looker Action Hub.

הוספת קובצי הפעולות למאגר Looker Action Hub

אחרי שכותבים את קובץ הפעולה, במאגר Looker Action Hub:

  1. מוסיפים את קובץ הפעולה (לדוגמה, my_action.ts) ל-actions/src/actions/index.ts.

    import "./my_action/my_action.ts"

  2. מוסיפים את כל דרישות החבילה של Node.js שבהן השתמשתם בכתיבת הפעולה. לדוגמה:

    yarn add aws-sdk
yarn add express

  3. מתקינים את יחסי התלות של Node.js בשרת Looker Action Hub.

    yarn install

  4. מריצים את הבדיקות שכתבתם.

yarn test

בדיקת פעולה

כדי לבצע בדיקה מלאה, אפשר לנסות את הפעולה מול מופע Looker על ידי אירוח שרת פרטי של מרכז פעולות. השרת הזה צריך להיות באינטרנט הציבורי עם אישור SSL תקף, וצריכה להיות לו אפשרות ליזום ולקבל חיבורים או בקשות HTTPS אל Looker ומ-Looker. לשם כך, אפשר להשתמש בפלטפורמה מבוססת-ענן כמו Heroku, כפי שמוצג בדוגמה הבאה. אפשרות אחרת היא להשתמש בכל פלטפורמה שעומדת בדרישות שצוינו למעלה.

הגדרת שרת של מרכז פעולות מקומי

בדוגמה הזו, נבצע את הפעולה שפיתחנו במאגר looker-open-source/actions/src/actions GitHub ונבצע קומיט של הקוד להסתעפות Git חדשה. מומלץ לעבוד על תכונות באמצעות ענפים כדי שתוכלו לעקוב בקלות אחרי הקוד, ואם תרצו, ליצור בקלות בקשת מיזוג באמצעות Looker.

  1. כדי להתחיל, יוצרים את הענף, מעבירים את העבודה לאזור ההכנה ומבצעים commit. לדוגמה:

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

  2. בדוגמה הזו, כדי לשלוח ענף ל-Heroku, מגדירים את מאגר ה-Git עם Heroku כאפשרות מרוחקת בשורת הפקודה:

    heroku login
heroku create
git push heroku

  3. מערכת Heroku תחזיר את כתובת ה-URL הציבורית שבה מתארח עכשיו מרכז הפעולות, לשימושכם. כדי לוודא שמרכז הפעולות פועל, נכנסים לכתובת ה-URL או מריצים את הפקודה heroku logs. אם שכחתם את כתובת ה-URL הציבורית, אתם יכולים להריץ את הפקודה הבאה בשורת הפקודה:

    heroku info -s | grep web_url

    מערכת Heroku תחזיר את כתובת ה-URL הציבורית שלכם. לדוגמה: https://my-heroku-action-server-1234.herokuapp.com

  4. בשורת הפקודה, מגדירים את כתובת ה-URL הבסיסית של מרכז הפעולות:

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

  5. מגדירים את התווית של מרכז הפעולות:

    heroku config:set ACTION_HUB_LABEL="Your Action Hub"

  6. ‫Looker משתמש בטוקן הרשאה כדי להתחבר למרכז הפעולות. יוצרים את הטוקן בשורת הפקודה:

    heroku run yarn generate-api-key

    אם אתם לא משתמשים ב-Heroku, כמו בדוגמה הזו, אתם צריכים להשתמש בפקודה הבאה:

    yarn generate-api-key

    מערכת Heroku תחזיר את טוקן ההרשאה. לדוגמה: Authorization: Token token="abcdefg123456789"

  7. מגדירים את הסוד של מרכז הפעולות באמצעות המפתח הסודי:

    heroku config:set ACTION_HUB_SECRET="abcdefg123456789"

    יכול להיות שיהיה צורך בהגדרת משתני סביבה נוספים שלא מתועדים כאן בפריסות באירוח בצד הלקוח.

  8. כדי להוסיף את הפעולה למופע המקומי של Looker, עוברים אל Admin (אדמין) > Actions (פעולות).

    • בתחתית רשימת הפעולות, לוחצים על הוספת מרכז פעולות.
    • מזינים את כתובת ה-URL של מרכז הפעולות ואם רוצים, גם מפתח סודי.
    • מחפשים את הפעולה ברשימה Actions בתפריט Admin ב-Looker.
    • לוחצים על Enable.

אם הפעולה שלכם דורשת העברה של סוגי נתונים ספציפיים מ-Looker, הקפידו להגדיר את המודלים כך שיכללו את הפרמטר המתאים tags.

עכשיו אפשר לבדוק את הפעולה.

בדיקה של פעולות ברמת לוח הבקרה וברמת השאילתה

במכונה של Looker, מגדירים את מודל LookML באמצעות תגים, אם צריך. יוצרים Look ושומרים אותו. ב-Look השמור, לוחצים על התפריט בפינה השמאלית העליונה ובוחרים באפשרות שליחה עם הפעולה כיעד. אם יש לכם טופס למשלוח, הוא יוצג ב-Looker בחלון Sent (נשלח).

לוחצים על שליחת בדיקה כדי להעביר את הנתונים. הסטטוס של הפעולה יופיע בהיסטוריית התזמון בחלונית ניהול. אם הפעולה שלכם נתקלת בשגיאה, היא תוצג בחלונית Admin, ו-Looker ישלח אימייל עם הודעת השגיאה למשתמש ששלח את הפעולה.

בדיקת פעולות ברמת התא

מגדירים שדה LookML עם התגים המתאימים לפעולה. במכונה של Looker, מריצים שאילתה שכוללת את השדה הזה. מוצאים את השדה בטבלת הנתונים. לוחצים על הסמל … בתא ובוחרים באפשרות שליחה מהתפריט הנפתח. אם מופיעות שגיאות, צריך לבצע רענון מלא של טבלת הנתונים אחרי שמתקנים את השגיאות.

פרסום והפעלה של פעולה בהתאמה אישית

יש שתי אפשרויות לפרסום פעולות בהתאמה אישית:

אחרי שמפרסמים את הפעולה, אפשר להפעיל אותה מהדף פעולות בחלונית ניהול.

פרסום ב-Looker Action Hub

הגישה הזו היא הכי קלה והיא מתאימה לכל פעולה שרוצים להפוך לזמינה לכל מי שמשתמש ב-Looker.

אחרי שתבדקו את הפעולה, תוכלו לשלוח בקשת מיזוג (PR) אל מאגר looker-open-source/actions ב-GitHub.

  1. מזינים את הפקודה הבאה:

    git push <your fork> <your development branch>

  2. יוצרים את בקשת המשיכה עם מאגר looker-open-source/actions בתור היעד.

  3. ממלאים את טופס השליחה של Looker Marketplace ו-Action Hub. מידע נוסף על הדרישות בנוגע לטופס זמין במאמר שליחת תוכן אל Looker Marketplace.

    צוות Looker יבדוק את קוד הפעולה. אנחנו שומרים לעצמנו את הזכות לדחות את ה-PR, אבל נוכל לעזור לכם בכל בעיה שתיתקלו בה ולהציע הצעות לשיפור. לאחר מכן נמזג את הקוד למאגר looker-open-source/actions ונפרוס אותו ב-actions.looker.com. אחרי פריסת הקוד, הוא יהיה זמין לכל לקוחות Looker.

  4. מפעילים את הפעולה במופע Looker, כדי שהיא תופיע כאפשרות להעברת נתונים.

פרסום בשרת פרטי של מרכז הפעולות

אם יש לכם פעולות בהתאמה אישית שרלוונטיות רק לחברה או לתרחיש השימוש שלכם, אל תוסיפו אותן למאגר looker-open-source/actions. במקום זאת, יוצרים מרכז פעולות פרטי באמצעות אותה מסגרת Node.js שבה השתמשתם כדי לבדוק את הפעולה.

אתם יכולים להגדיר את שרת מרכז הפעולות הפנימי בתשתית שלכם או באמצעות פלטפורמת אפליקציות מבוססת-ענן (בדוגמה שלנו השתמשנו ב-Heroku). אל תשכחו ליצור Fork של Looker Action Hub לשרת פרטי של מרכז פעולות לפני הפריסה.

הגדרת מודל LookML לשימוש בפעולה

גם בפעולות מותאמות אישית וגם בפעולות שזמינות ב-Looker Action Hub, צריך לזהות את שדות הנתונים הרלוונטיים באמצעות הפרמטר tags במודל LookML. בדף פעולות בחלונית ניהול יופיע מידע על התגים שנדרשים לשירות, אם יש כאלה.

לדוגמה, שילוב של Twilio Send Message שולח הודעה לרשימה של מספרי טלפון. בדף פעולות בחלונית ניהול, בשילוב מוצג הטקסט המשני 'אפשר להשתמש בפעולה עם שאילתות שיש להן שדה שתויג phone'.

המשמעות היא שהשירות Twilio Send Message דורש שאילתה שתכלול שדה של מספר טלפון, ושייעשה בה שימוש בפרמטר tags כדי לזהות איזה שדה בשאילתה מכיל מספרי טלפון. כדי לזהות שדה של מספר טלפון ב-LookML, מציינים tags: ["phone"] בשדה הזה. קוד ה-LookML של שדה מספר הטלפון יכול להיראות כך:

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

אם מדובר בשילוב שלא דורש תגים, יוצג הכיתוב המשני 'אפשר להשתמש בפעולה עם כל שאילתה' בדף פעולות בחלונית ניהול.

חשוב להגדיר את הפרמטר tags במודל LookML לכל השדות הנדרשים, כדי שהמשתמשים יוכלו להשתמש בשירות לשליחת נתונים.

המאמרים הבאים

איך מעבירים את התוכן של Look או של Explore או של מרכז בקרה לשירות משולב