איך מתחילים להשתמש ברכיבי ויזואליזציה של Looker

הטמעה של תוכן Looker באמצעות מסגרות iframe היא רק אחת מהשיטות שבהן מפתחים יכולים להשתמש כשהם רוצים להוסיף לוח בקרה, Look או Explore לאפליקציית האינטרנט שלהם. במדריך הזה מוצגת שיטה נוספת למפתחים שרוצים להוסיף תרשים ב-Looker לאפליקציית React. המדריך הזה מבוסס על תבנית התחלה של Create React App ומשתמש ברכיבי תרשים ב-Looker.

במדריך הזה נסביר איך:

1. איך מקבלים את ה-slug של השאילתה מ-Looker
2. יצירת אפליקציית React עם רכיבי ויזואליזציה של Looker
3. יצירת שירות עזר בבק-אנד
4. הפעלת השרת ואפליקציית React

איך מקבלים את ה-slug של השאילתה מ-Looker

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

קבלת סלאג של שאילתה

צריך את מזהה השאילתה או את ה-slug שישמשו כמאפיין של רכיב הוויזואליזציה. במאמר הזה מוסבר איך אפשר לקבל את ה-slug של השאילתה מכתובת URL של ניתוח.

הגדרת CORS במופע Looker

שיתוף משאבים בין מקורות (CORS) נשלט על ידי אותה רשימת היתרים של דומיינים כמו הטמעה.

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

1. מנווטים אל Admin > Platform Embed (ניהול > הטמעה של הפלטפורמה) במכונה של Looker. לשם כך נדרשות הרשאות אדמין.
2. אפליקציית React פועלת כברירת מחדל בכתובת http://localhost:3000. כשמוסיפים את הכתובת הזו אל רשימת ההיתרים של דומיינים מוטמעים, אומרים ל-Looker לאשר בקשות מהאפליקציה ולהשיב לבקשות האלה באמצעות אותה כתובת. השלב הזה הוא חובה כי האפליקציה תשלח בקשות API למופע Looker, אחרת לא תהיה תקשורת בין Looker לבין האפליקציה.

יצירת אפליקציית React

הקצה הקדמי של ההדגמה הזו משתמש ב-Create React App כדי ליצור את אפליקציית React של דף יחיד. מריצים את הפקודות הבאות בתיקיית הבסיס של ההדגמה (get-started-viz-components) כדי ליצור את האפליקציה ולהתקין את יחסי התלות:

npx create-react-app frontend-react cd frontend-react npm i
@looker/visualizations npm i @looker/components @looker/components-data
styled-components

אחרי הרצת הפקודות האלה, מבנה התיקיות אמור להיראות כך:

בודקים את הקובץ package.json ומוודאים שגם react-dom מותקן. אם לא, מריצים את הפקודה npm i react-dom כדי להתקין אותו.

ה-package.json של ההדגמה הזו נראה כך:

{
  "name": "frontend-react",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@looker/components": "^4.0.3",
    "@looker/components-data": "^1.0.0",
    "@looker/sdk": "^22.16.0",
    "@looker/sdk-rtl": "^21.4.0",
    "@looker/visualizations": "^1.1.1",
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^12.1.0",
    "@testing-library/user-event": "^12.4.0",
    "i": "^0.3.7",
    "npm": "^8.19.2",
    "react": "^16.14.0",
    "react-dom": "^16.14.0",
    "react-scripts": "5.0.1",
    "styled-components": "^5.3.6",
    "web-vitals": "^2.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

הגדרת משתני הסביבה

יוצרים קובץ .env בספריית השורש של האפליקציה (./frontend-react) ומגדירים את המשתנים הבאים:

REACT_APP_LOOKER_API_HOST=https://your-looker-instance.looker.com
REACT_APP_BACKEND_SERVER=http://localhost:3001/

‫REACT_APP_BACKEND_SERVER היא הכתובת של שירות העזר של ה-Backend שבו נשתמש כדי לבצע קריאה ל-Looker API כדי לחלץ את טוקן הגישה.

‫REACT_APP_LOOKER_API_HOST היא הכתובת של מופע Looker שיקבל בקשות API מאפליקציית React.

אתחול SDK בצד הלקוח

אפליקציית React תשתמש ב-SDK כדי לשלוח בקשות API לשרת Looker. מכיוון שהפעולה הזו מתבצעת בקצה הקדמי, אפשר להשתמש בפונקציית העזר הבאה כדי לאתחל את sdk:

import { Looker40SDK } from '@looker/sdk'
import {
  AuthToken,
  AuthSession,
  BrowserTransport,
  DefaultSettings,
} from '@looker/sdk-rtl'

class SDKSession extends AuthSession {
  // This is a placeholder for the fetchToken function.
  // It is modified to make it useful later.
  async fetchToken() {
    return fetch('')
  }

  activeToken = new AuthToken()
  constructor(settings, transport) {
    super(settings, transport || new BrowserTransport(settings))
  }

  // This function checks to see if the user is already authenticated
  isAuthenticated() {
    const token = this.activeToken
    if (!(token && token.access_token)) return false
    return token.isActive()
  }

  // This function gets the current token or fetches a new one if necessary
  async getToken() {
    if (!this.isAuthenticated()) {
      const token = await this.fetchToken()
      const res = await token.json()
      this.activeToken.setToken(res.user_token)
    }
    return this.activeToken
  }

  // This function authenticates a user, which involves getting a new token
  // It returns a modified object with a new authorization header.
  async authenticate(props) {
    const token = await this.getToken()
    if (token && token.access_token) {
      props.mode = 'cors'
      delete props.credentials
      props.headers = {
        ...props.headers,
        Authorization: `Bearer ${this.activeToken.access_token}`,
      }
    }
    return props
  }
}

// This class sets the fetchToken to use the 'real' address of the backend server.
class SDKSessionEmbed extends SDKSession {
  async fetchToken() {
    return fetch(`${process.env.REACT_APP_BACKEND_SERVER}`)
  }
}

// This creates a new session with the 'real' address of the backend server.
const session = new SDKSessionEmbed({
  ...DefaultSettings,
  base_url: process.env.REACT_APP_LOOKER_API_HOST,
})

// This exports the SDK with the authenticated session
export const sdk = new Looker40SDK(session)

הטמעה של התצוגה החזותית באפליקציה

אחרי שיש לכם את ה-slug של השאילתה (בדוגמה שלנו זה Jlm4YHPeT3lLGA9UtHjZcA) של ההמחשה הוויזואלית ואובייקט sdk עבר אתחול, השלב הבא הוא להשתמש ברכיבי ההמחשה הוויזואלית של Looker כדי להטמיע את ההמחשה הוויזואלית באפליקציה ולעבד אותה:

import { sdk } from '../src/helpers/CorsSession'
import { Query, Visualization } from '@looker/visualizations'
import { DataProvider } from '@looker/components-data'
import { ComponentsProvider } from '@looker/components'

function App() {
  return (
    <>
      <h1>Get started with Looker visualization components</h1>
      <ComponentsProvider>
        <DataProvider sdk={sdk}>
          {/* Change this query slug to match your query slug */}
          <Query query="Jlm4YHPeT3lLGA9UtHjZcA">
            <Visualization />
          </Query>
        </DataProvider>
      </ComponentsProvider>
    </>
  )
}

export default App

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

יצירת שירות עזר לקצה העורפי

השלב האחרון הוא ליצור את שירות העזר לקצה העורפי שיקבל את הקריאה מהקצה הקדמי, ישתמש ב-Looker-Node SDK כדי לאמת את המשתמש, יחלץ את אסימון הגישה שלו וישלח אותו בחזרה לקצה הקדמי.

כדי לפשט את התהליך, נבנה שרת Node עם נקודת קצה אחת. השרת ישתמש בתלויות express,‏ cors ו-@looker/sdk-node. אפשר להריץ את הפקודות הבאות החל מתיקיית הבסיס (get-started-viz-components):

mkdir backend-node
cd backend-node
npm init -y
npm i express cors @looker/sdk-node

כדי לאמת את ה-SDK מהקצה העורפי, נשתמש בקובץ looker.ini. פרטים נוספים על אופן מילוי הקובץ זמינים בדף SDK-Node. אחרי הרצת הפקודות האלה, מבנה התיקיות אמור להיראות כך:

התג package.json צריך להיראות כך:

{
  "name": "looker-embed-backend",
  "version": "1.0.0",
  "description": "Backend helper service for getting started with Looker Viz components",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "author": "Looker",
  "license": "Apache-2.0",
  "dependencies": {
    "@looker/sdk-node": "^22.16.0",
    "cors": "^2.8.5",
    "express": "^4.18.2"
  }
}

בשלב הבא נוסיף את הקוד הזה לקובץ server.js חדש:

const cors = require('cors')
const express = require('express')
const { LookerNodeSDK } = require('@looker/sdk-node')

const port = 3001
const app = express()
// The following init40 method will authenticate using
// the looker.ini file
const sdk = LookerNodeSDK.init40()

app.use(
  cors({
    origin: '*',
  })
)
app.use(express.json())

app.get('/', async (req, res) => {
  const userId = await sdk.ok(sdk.me('id'))
  const accessToken = await sdk.login_user(userId.id)
  const user = {
    user_token: accessToken.value,
    token_last_refreshed: Date.now(),
  }
  res.json({ ...user })
})

app.listen(port, async () => {
  console.log(`Backend Server listening on port ${port}`)
})

הפעלת השרת ואפליקציית React

• פותחים טרמינל ועוברים לתיקייה backend-node ואז מריצים את הפקודה npm start
• פותחים טרמינל שני, עוברים לתיקייה frontend-react ומריצים את הפקודה npm start
• אחרי ששירות העזר של ה-backend ואפליקציית ה-React יפעלו, תוכלו לפתוח את הדפדפן ולעבור אל http://localhost:3000/ כדי לראות את ההדמיה שמוטמעת באפליקציה.

צפייה בקוד ב-GitHub