Embed SDK 소개

참고: 이 페이지는 삽입 SDK 2.0.0의 참조입니다. 2.0.0 API는 Embed SDK 1.8.x와 하위 호환되지만 일부 기능의 기본 구현이 변경되었습니다. SDK 1.8.x는 여러 클래스를 내보냈습니다. SDK 2.0.0에서는 이러한 클래스를 지원 중단된 것으로 표시된 인터페이스로 대체합니다 (대체 인터페이스가 식별됨). 애플리케이션은 'I' 접두사가 있는 인터페이스를 사용하는 것이 좋습니다 (접두사가 있는 인터페이스는 접두사가 없는 인터페이스와 동일함). SDK 2.0.0으로 업그레이드된 애플리케이션은 이전과 같이 계속 작동하고 동작해야 합니다. API 개선사항을 활용하려면 리팩터링이 필요합니다. Embed SDK 2.0.0에는 다음과 같은 주요 변경사항이 포함되어 있습니다.

• 더 이상 대시보드, Explore, Look 간에 이동할 때 iframe을 다시 만들 필요가 없습니다. 대신 loadDashboard, loadLook, loadExplore, loadUrl 메서드를 사용하여 Looker iframe 내에서 이동할 수 있습니다.
• 이제 connect는 대시보드, Look 또는 Explore에만 관련된 연결이 아닌 통합 연결을 반환합니다. 통합 연결을 사용하면 임베딩 애플리케이션이 iframe 내부를 탐색하는 사용자를 감지할 수 있습니다.
• Looker 보고서 및 쿼리 시각화에 대한 추가 Looker 삽입 콘텐츠 지원이 추가되었습니다.

Looker의 Embed SDK는 웹 앱의 내장 대시보드, Look, 보고서, Explore를 관리하기 위해 브라우저 기반 웹 애플리케이션의 코드에 추가할 수 있는 함수 라이브러리입니다.

참고: Looker 보고서 기능이 사용 설정된 경우 Looker 보고서를 사용할 수 있습니다. 보고서는 서명된 임베디드 메서드, 쿠키 없는 임베디드 메서드 또는 비공개 임베디드 메서드를 사용하여 삽입할 수 있습니다. 자세한 내용은 Looker 보고서 삽입을 참고하세요.

Embed SDK는 다음과 같은 방식으로 임베딩을 용이하게 해줍니다.

• HTML 요소를 수동으로 만들지 않고도 삽입된 콘텐츠를 캡슐화할 수 있습니다.
• 교차 프레임 통신이 없도록 지점 간 통신 제공 Embed SDK는 전용 메시지 채널을 사용하여 호스트 웹페이지와 삽입된 Looker 콘텐츠 간의 교차 도메인 메시지를 전달합니다.

Embed SDK가 없으면 dashboard:run:start 또는 page:changed와 같은 JavaScript 이벤트를 사용하여 삽입된 Looker 콘텐츠의 이벤트를 호출하거나 응답할 수 있습니다. 이는 삽입된 JavaScript 이벤트 문서 페이지에 설명되어 있습니다. 자바스크립트 이벤트로 Looker 콘텐츠를 삽입하는 개발자는 삽입된 콘텐츠를 저장할 HTML 요소를 만들고 웹 앱과 삽입된 콘텐츠 간의 통신을 위해 창 브로드캐스트 이벤트를 사용해야 합니다.

Looker Embed SDK는 Looker API 및 Looker API SDK와 다릅니다.

• Looker Embed SDK는 웹 애플리케이션의 클라이언트 측 코드에 있으며 Looker 삽입 컨텍스트와 콘텐츠를 관리합니다. (Embed SDK는 Looker API에 대한 액세스를 제공하지 않습니다.)
• Looker API는 Looker 인스턴스와 함께 서버에 상주하며 Looker 서버에서 명령어를 실행합니다.
• Looker API 클라이언트 SDK는 Looker API 함수에 액세스할 수 있도록 브라우저 외의 애플리케이션 코드에 상주합니다.

Looker는 브라우저에서 이벤트를 웹 애플리케이션에 전달하는 순서를 제어하지 않습니다. 즉, 브라우저 또는 플랫폼 전체에 걸쳐 이벤트 순서가 보장되지 않습니다. 여러 브라우저의 이벤트 처리를 고려하여 JavaScript를 적절히 작성해야 합니다.

간단한 예시

이 예시에서는 ID가 11인 대시보드가 ID가 embed_container인 DOM 요소 내에 생성됩니다. dashboard:run:start 및 dashboard:run:complete 이벤트는 임베딩 창의 UI 상태를 업데이트하는 데 사용되며 ID가 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 데모 문서 페이지를 참조하세요.

Looker Embed SDK 설정

Looker Embed SDK는 익숙한 인터페이스 패턴을 사용합니다. Embed SDK를 설치한 후 삽입된 콘텐츠를 구성하고 삽입된 콘텐츠에 연결합니다. 연결이 설정되면 호스팅 애플리케이션이 삽입된 콘텐츠와 상호작용할 수 있습니다.

Embed SDK 설치

https://www.npmjs.com/package/@looker/embed-sdk에서 노드 패키지 관리자(NPM)를 통해 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

삽입된 콘텐츠 구성

먼저 Looker 서버 주소와 서명된 Looker 삽입 로그인 URL을 생성할 삽입 애플리케이션 서버의 엔드포인트를 사용하여 SDK를 초기화합니다. 이러한 서버는 모든 삽입된 콘텐츠에서 사용됩니다. 비공개 삽입의 경우 서명 엔드포인트를 생략합니다.

참고: 브라우저 클라이언트에서 Looker 서버에 연결하는 데 필요한 포트 번호를 포함합니다. 예: looker.example.com:443

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

그런 다음 일련의 단계를 사용하여 매개변수를 정의해 삽입된 콘텐츠를 빌드합니다. 이러한 매개변수 중 일부는 선택사항이며, 일부는 필수 항목입니다.

이 프로세스는 대시보드 id 또는 대시보드(서명된 삽입 문서 페이지에 설명된 프로세스에 의해 생성됨)를 참조하는 url로 빌더를 만드는 것으로 시작됩니다.

getEmbedSDK().createDashboardWithId('id')

또는

getEmbedSDK().createDashboardWithUrl('url')

그런 다음 빌더에 속성을 추가하여 설정을 완료할 수 있습니다.

참고: create[ContentType]WithUrl 함수는 Embed SDK 2.0.0부터 서명된 삽입과 쿠키 없는 삽입 모두에서 사용할 수 있습니다. Embed SDK 2.0.0 이전에는 쿠키 없는 삽입이 create[ContentType]WithId만 지원했습니다.

예를 들어 웹페이지에 Looker 삽입 UI를 삽입할 위치를 지정할 수 있습니다. 다음 호출은 ID 값이 dashboard인 HTML 요소 내에 Looker 삽입 UI를 배치합니다.

.appendTo('#dashboard')

이벤트 핸들러를 추가합니다.

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

build 메서드를 호출하여 삽입된 클라이언트를 만듭니다.

.build()

삽입된 콘텐츠에 연결

클라이언트가 빌드되면 connect를 호출하여 iframe을 만듭니다. 연결 프로세스는 실제 iframe에 사용되는 src 속성을 만듭니다. src 값이 생성되는 방식은 삽입 SDK가 초기화되는 방식에 따라 달라집니다.

1. 서명됨: init 호출의 두 번째 인수로 지정된 엔드포인트가 호출됩니다. 엔드포인트는 서명된 임베디드 로그인 URL을 반환해야 합니다.
2. 쿠키 없음: initCookieless 호출의 두 번째 인수로 지정된 엔드포인트 또는 함수가 호출됩니다. 엔드포인트 또는 함수는 쿠키 없는 토큰, 특히 인증 및 탐색 토큰을 반환해야 합니다. 토큰이 임베드 로그인 URL에 추가됩니다.
3. 비공개: init 호출의 두 번째 인수가 제공되지 않으면 삽입 연결이 비공개입니다. 이 경우 URL은 빌더에서 파생되며 Looker 삽입에 필요한 매개변수로 장식됩니다. 비공개 삽입의 경우 사용자가 이미 Looker에 로그인했거나 또는 삽입 URL에 allow_login_screen=true 매개변수가 포함되어야 합니다.

connect는 삽입된 iframe의 연결 인터페이스로 확인되는 Promise을 반환합니다.

  .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 인증 엔드포인트

이 섹션은 쿠키 없는 삽입에는 적용되지 않습니다. 자세한 내용은 쿠키 없는 삽입을 참고하세요.

Embed SDK를 사용하려면 삽입 URL의 서명을 처리하는 백엔드 서비스를 제공해야 합니다. 이 서비스는 요청하는 사용자에게 고유한 서명된 URL을 생성하기 위해 Embed SDK에 의해 호출됩니다. 백엔드 프로세스는 삽입 보안 비밀을 사용하여 서명된 삽입 URL을 직접 생성할 수도 있고, Looker 서명된 삽입 URL 생성 API를 호출하여 URL을 생성할 수도 있습니다. URL을 수동으로 생성하고 서명하면 Looker API 호출을 방지하여 지연 시간을 줄일 수 있습니다. Looker API를 호출하면 코드가 더 적게 필요하고 유지관리가 더 쉽습니다.

서명된 URL(createSignedUrl())을 생성하는 도우미 메서드의 JavaScript 예는 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 고급 인증 구성

이 섹션은 쿠키 없는 삽입에는 적용되지 않습니다. 자세한 내용은 쿠키 없는 삽입을 참고하세요.

init 메서드에 옵션 객체를 전달하여 커스텀 요청 헤더와 CORS 지원을 허용하도록 인증 엔드포인트를 구성할 수 있습니다.

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 = ''