מבוא ל-Embed SDK

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

ערכת Embed SDK מאפשרת הטמעה בדרכים הבאות:

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

בלי Embed SDK, אפשר להפעיל אירועים בתוכן Looker מוטמע או להגיב להם באמצעות אירועי JavaScript כמו dashboard:run:start או page:changed, שמתוארים בדף התיעוד בנושא אירועי JavaScript מוטמעים. מפתחים שמטמיעים תוכן Looker באמצעות אירועי JavaScript צריכים ליצור את רכיבי ה-HTML שבהם יופיע התוכן המוטמע, ולהסתמך על אירועי שידור (broadcast) של חלון לתקשורת בין אפליקציית האינטרנט לבין התוכן המוטמע.

חשוב לשים לב ש-Looker Embed SDK שונה מ-Looker API ומ-Looker API SDK:

• ‫Looker Embed SDK נמצא בקוד בצד הלקוח של אפליקציית האינטרנט שלכם ומנהל את ההקשר והתוכן של ההטמעה של Looker. ‫(Embed SDK לא מספק גישה ל-Looker API).
• ‫Looker API נמצא בשרת עם מופע Looker שלכם ומבצע פקודות בשרת Looker.
• ערכות SDK של לקוח Looker API נמצאות בקוד של אפליקציות שאינן דפדפנים, כדי לספק גישה לפונקציות של Looker API.

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

דוגמה מהירה

בדוגמה הזו, לוח בקרה עם מזהה 11 נוצר בתוך רכיב DOM עם המזהה embed_container. האירועים dashboard:run:start ו-dashboard:run:complete משמשים לעדכון המצב של ממשק המשתמש בחלון ההטמעה, ומוגדר סקריפט ללחצן עם מזהה run לשליחת הודעה dashboard:run ללוח הבקרה.

getEmbedSDK().init('looker.example.com', '/auth')

const setupConnection = (connection) => {
  document.querySelector('#run').addEventListener('click', () => {
    connection.asDashboardConnection().run()
  })
}

try {
  connection = await getEmbedSDK()
    .createDashboardWithId('11')
    .appendTo('#embed_container')
    .on('dashboard:run:start', () => updateStatus('Running'))
    .on('dashboard:run:complete', () => updateStatus('Done'))
    .build()
    .connect()
  setupConnection(connection)
} catch (error) {
  console.error('An unexpected error occurred', error)
}

דוגמה מלאה יותר מתוארת בדף התיעוד Embed SDK demo.

הגדרת Looker Embed SDK

‫Looker Embed SDK משתמש בתבנית של ממשק רציף. אחרי ההתקנה של ערכת ה-SDK להטמעה, יוצרים את התוכן המוטמע ומתחברים אליו. אחרי שהחיבור נוצר, יכול להיות שהאפליקציה המארחת תבצע פעולות בתוכן המוטמע.

התקנה של Embed SDK

אפשר להוריד את ספריית ה-SDK להטמעה של Looker דרך מנהל חבילות הצמתים (NPM) בכתובת https://www.npmjs.com/package/@looker/embed-sdk. עם זאת, אם רוצים לראות את קוד הדוגמה או את ההדגמה, צריך להשתמש במאגר Looker Embed SDK.

כדי להתקין את Looker Embed SDK באמצעות מאגר Looker Embed SDK, מבצעים את השלבים הבאים:

1. מתקינים את Node.js, אם עדיין לא התקנתם אותו.
2. מורידים או משכפלים את מאגר /looker-open-source/embed-sdk.
3. בחלון המסוף, נכנסים לספרייה /embed-sdk ומריצים את הפקודות הבאות:

npm install
npm start

יצירת התוכן המוטמע

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

getEmbedSDK().init('looker.example.com', '/auth')

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

התהליך מתחיל ביצירת הכלי לבניית לוחות בקרה באמצעות לוח בקרה id או באמצעות url שמפנה ללוח בקרה (שנוצר בתהליך שמתואר בדף התיעוד בנושא הטמעה עם חתימה).

getEmbedSDK().createDashboardWithId('id')

או

getEmbedSDK().createDashboardWithUrl('url')

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

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

.appendTo('#dashboard')

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

.on('dashboard:run:start',
  () => updateStatus('Running')
)
.on('dashboard:run:complete',
  () => updateStatus('Done')
)

יוצרים לקוח מוטמע על ידי קריאה לשיטת build:

.build()

התחברות לתוכן המוטמע

אחרי שהלקוח נוצר, קוראים ל-connect כדי ליצור את ה-iframe. תהליך החיבור יוצר את מאפיין src שמשמש לאייפרים בפועל. האופן שבו נוצר הערך src תלוי באופן האתחול של Embed SDK:

1. חתום: נקודת הקצה שצוינה בארגומנט השני של הקריאה ל-init נקראת. נקודת הקצה אמורה להחזיר כתובת URL חתומה של התחברות להטמעה.
2. ללא קובצי Cookie: נקודת הקצה או הפונקציה שמצוינות בארגומנט השני של הקריאה initCookieless נקראות. נקודת הקצה או הפונקציה אמורות להחזיר טוקנים ללא קובצי Cookie, במיוחד טוקנים של אימות וניווט. האסימונים מצורפים לכתובת ה-URL של ההתחברות להטמעה.
3. פרטי: החיבור להטמעה הוא פרטי אם לא מציינים את הארגומנט השני של הקריאה init. במקרה הזה, כתובת ה-URL נגזרת מהכלי ליצירת מודעות ומקושטת בפרמטרים שנדרשים להטמעה של Looker. בהטמעה פרטית, המשתמש אמור להיות מחובר כבר ל-Looker או שכתובת ה-URL להטמעה כוללת את הפרמטר allow_login_screen=true.

‫connect מחזיר Promise שמוביל לממשק החיבור של ה-iframe המוטמע.

  .connect()
  .then((connection) => {
    // Save the connection
  })
  .catch(console.error)

אינטראקציה

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

if (connection.getPageType() === 'dashboards') {
  connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
  connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
  connection.asExploreConnection().run()
}

אין צורך ליצור מחדש את ה-iframe כשצריך לטעון תוכן שונה. במקום זאת, אפשר להשתמש בשיטות החיבור loadDashboard, ‏loadLook, ‏loadExplore או loadUrl. השיטות loadDashboard, ‏loadLook ו-loadExplore מקבלות id. השיטה loadUrl מקבלת הטמעה URL, ואפשר להשתמש בשיטה הזו כדי לציין פרמטרים נוספים (כמו מסננים).

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

אם יש צורך ליצור iframe חדש, Embed SDK לא יקרא שוב לנקודות הקצה של החתימה או של קבלת הסשן. במקום זאת, הוא ייצור iframe src ישירות מהכלי לבניית אתרים. אם יהיה צורך ליצור סשן חדש של הטמעה, יהיה צריך לאתחל מחדש את Embed SDK באופן הבא:

getEmbedSDK(new LookerEmbedExSDK()).init('looker.example.com', '/auth')

נקודת קצה לאימות של כתובת URL חתומה

הקטע הזה לא רלוונטי להטמעה ללא קובצי Cookie. פרטים נוספים זמינים במאמר בנושא הטמעה ללא קובצי Cookie.

כדי להשתמש ב-Embed SDK, צריך לספק שירות לקצה העורפי שמטפל בחתימה של כתובת ה-URL להטמעה. שירות ה-SDK להטמעה קורא לשירות הזה כדי ליצור כתובת URL חתומה שייחודית למשתמש ששולח את הבקשה. תהליך ה-Backend יכול ליצור את כתובת ה-URL החתומה להטמעה בעצמו באמצעות סוד להטמעה, או ליצור את כתובת ה-URL באמצעות קריאה ל-Looker Create Signed Embed URL API. יצירה וחתימה ידניות של כתובות URL מאפשרות להימנע מהפעלת Looker API, וכך להקטין את זמן האחזור. הקריאה ל-Looker API דורשת פחות קוד וקל יותר לתחזק אותה.

דוגמה לשיטת עזר ב-JavaScript ליצירת כתובת URL חתומה, createSignedUrl(), נמצאת ב-server/utils/auth_utils.ts. השימוש בו הוא כדלקמן:

import { createSignedUrl } from './utils/auth_utils'

app.get('/looker_auth', function (req, res) {
  // It is assumed that the request is authorized
  const src = req.query.src
  const host = 'looker.example.com'
  const secret = ... // Embed secret from Looker Server Embed Admin page
  const user = ... // Embedded user definition
  const url = createSignedUrl(src, user, host, secret)
  res.json({ url })
})

אפשר לעיין בדוגמה של Python במאגר.

הגדרת אימות מתקדם של כתובות URL חתומות

הקטע הזה לא רלוונטי להטמעה ללא קובצי Cookie. פרטים נוספים זמינים במאמר בנושא הטמעה ללא קובצי Cookie.

אפשר להגדיר את נקודת הקצה (endpoint) של האימות כך שתאפשר כותרות בקשה בהתאמה אישית ותמיכה ב-CORS. לשם כך, מעבירים אובייקט אפשרויות לשיטה init.

getEmbedSDK().init('looker.example.com', {
  url: 'https://api.acme.com/looker/auth',
  headers: [{ name: 'Foo Header', value: 'Foo' }],
  params: [{ name: 'foo', value: 'bar' }],
  withCredentials: true, // Needed for CORS requests to Auth endpoint include Http Only cookie headers
})

פתרון בעיות

‫Embed SDK מבוסס על chatty. ‫Chatty משתמש בניפוי באגים לרישום ביומן. אפשר להפעיל את הרישום ביומן במסוף של הדפדפן באמצעות הפקודה הבאה:

localStorage.debug = 'looker:chatty:*'
```none

Note that both the parent window and the embedded content have separate local storage, so you can enable logging on one, the other, or both. You can disable logging with this command:

```javascript
localStorage.debug = ''