Связаться с намиПодключиться

Встраивание непубличных объектов

Статья создана
Обновлена 10 декабря 2024 г.

Примечание

Функциональность доступна только в рамках тарифного плана Business.

Вы можете безопасно встроить непубличные чарты и дашборды на сайт или в приложение с помощью специальных ссылок с JWT-токеном.

Встраивание непубличных объектов работает только в новой объектной модели DataLens на уровне воркбуков и доступно только администратору воркбука.

Встраивание не поддерживается для непубличных объектов, которые построены на основе следующих подключений:

Как встроить непубличный объект

  1. Создайте ключ для встраивания:

    Примечание

    Один ключ можно использовать для встраивания нескольких объектов.

    1. Перейдите на главную страницу DataLens.

    2. На панели слева выберите Коллекции и воркбуки.

    3. Откройте воркбук, в котором расположен объект для встраивания.

    4. В верхней части интерфейса нажмите значок и выберите Ключи для встраивания.

      image

    5. В открывшемся окне:

      1. Нажмите кнопку Создать ключ.

      2. Введите название ключа и нажмите кнопку Создать.

      3. Внизу нажмите кнопку Скачать файл с ключом или скопируйте значение ключа.

        Важно

        После закрытия окна все данные из него будут потеряны.

        Новый ключ для встраивания появится в списке.

  2. Настройте встраивание для непубличного объекта:

    Примечание

    Для каждого объекта можно настроить несколько встраиваний.

    1. В строке с нужным объектом нажмите значок и выберите Настройки встраивания.

      image

    2. В открывшемся окне нажмите кнопку Новое встраивание.

    3. В окне настроек укажите:

      • Название — введите название встраивания.

      • Ключ — выберите созданный ранее ключ для встраивания.

      • Выберите Режим работы параметров по умолчанию:

        • Всё разрешено (по умолчанию) — все неподписанные параметры разрешены, кроме запрещенных;
        • Всё запрещено — все неподписанные параметры запрещены, кроме разрешенных.

        На подписанные параметры из токена эти ограничения не действуют.

      • (опционально) Запрещённые параметры — укажите названия неподписанных параметров, которые не будут работать при встраивании чарта. Доступно для режима Всё разрешено.

      • (опционально) Разрешённые параметры — укажите названия неподписанных параметров, которые можно передавать в ссылке для встраивания. Параметры, которые не указаны в этом списке, будут проигнорированы при попытке передать их в ссылке для встраивания. Доступно для режима Всё запрещено.

      • (опционально) Разрешить экспорт данных — включите отображение меню, которое позволяет экспортировать данные, представленные на чарте. Для экспорта данных в правом верхнем углу чарта нажмите → Сохранить как и выберите формат: XLSX, CSV или Markdown.

      • Название — введите название встраивания.

      • Ключ — выберите созданный ранее ключ для встраивания.

      • (опционально) Запрещённые параметры — укажите названия неподписанных параметров, которые не будут работать при встраивании дашборда. На подписанные параметры из токена эти ограничения не действуют. По умолчанию в ссылке для встраивания можно передавать любые параметры, которые указаны в настройках дашборда.

        Примечание

        Если на дашборде есть селекторы с запрещенными параметрами, при встраивании такие селекторы будут недоступны для использования.

      • (опционально) Разрешить экспорт данных — включите отображение меню, которое позволяет экспортировать данные, представленные на чарте. Для экспорта данных в правом верхнем углу чарта нажмите → Сохранить как и выберите формат: XLSX, CSV или Markdown.

    4. Нажмите кнопку Создать. В колонке ID скопируйте идентификатор объекта встраивания, а затем нажмите Закрыть.

  3. Создайте токен:

    1. Подготовьте payload для токена — полезную нагрузку, которая содержит информацию об объекте встраивания. Полезная нагрузка содержит следующие поля:

      • embedId — идентификатор объекта встраивания.

      • iat — время выписки токена JWT в формате Unix Timestamp.

      • exp — время окончания действия токена в формате Unix Timestamp.

        Важно

        Токены, в которых разница между exp и iat превышает 10 часов, считаются невалидными.

      • dlEmbedService — строковая константа идентификатора сервиса: YC_DATALENS_EMBEDDING_SERVICE_MARK.

      • (опционально) params — подписанные параметры чарта, которые передаются в составе токена. Их нельзя изменить без повторной генерации токена.

        Пример:

        {
  "embedId": "ieez7********",
  "iat": 1516239022,
  "exp": 1516240822,
  "dlEmbedService": "YC_DATALENS_EMBEDDING_SERVICE_MARK",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

    2. Чтобы создать JWT-токен, подпишите подготовленный payload закрытым ключом, который был получен ранее при создании ключа для встраивания.

      Примечание

      Используйте при создании JWT алгоритм PS256.

      Для создания JWT-токена используйте примеры кода:

      Установите модуль cryptography для работы с алгоритмом PS256:

      pip3 install cryptography

      Выполните код:

      import time
import jwt
import json
​
private_key = b"""<закрытый_ключ>"""
​
now = int(time.time())
payload = {
   'embedId': "<идентификатор_объекта_встраивания>",
   'dlEmbedService': "YC_DATALENS_EMBEDDING_SERVICE_MARK",
   'iat': now,
   'exp': now + 360,
   "params": {  }}
   ​
# JWT generation.
encoded_token = jwt.encode(
   payload,
   private_key,
   algorithm='PS256',
   )

print(encoded_token)

      Установите пакет jsonwebtoken с помощью npm:

      npm install jsonwebtoken

      Выполните код:

      const privateKey = `<закрытый_ключ>`;

const now = Math.floor(Date.now() / 1000);
const payload = {
embedId: '<идентификатор_объекта_встраивания>',
dlEmbedService: 'YC_DATALENS_EMBEDDING_SERVICE_MARK',
iat: now,
exp: now + 360,
params: {},
};

const jwt = require('jsonwebtoken');

const encodedToken = jwt.sign(payload, privateKey, {
algorithm: 'PS256',
});

console.log(encodedToken);

      Установите пакет jwt-go:

      go install github.com/golang-jwt/jwt/v5@latest

      Выполните код:

      
package main

import (
  "fmt"
  "time"

  "github.com/golang-jwt/jwt/v5"
)

func main() {
  privateKey, err := jwt.ParseRSAPrivateKeyFromPEM([]byte(`<закрытый_ключ>`))

  now := time.Now().Unix()
  payload := jwt.MapClaims{
      "embedId":        "<идентификатор_объекта_встраивания>",
      "dlEmbedService": "YC_DATALENS_EMBEDDING_SERVICE_MARK",
      "iat":            now,
      "exp":            now + 360,
      "params":         map[string]interface{}{},
  }

  token := jwt.NewWithClaims(jwt.SigningMethodPS256, payload)
  signedToken, err := token.SignedString(privateKey)
  if err != nil {
      fmt.Println("Error generating token:", err)
      return
  }

  fmt.Println(signedToken)
}

    3. Сформируйте ссылку для встраивания:

      https://datalens.yandex.cloud/embeds/chart#dl_embed_token=<токен>

      Где <токен> — JWT-токен.

      https://datalens.yandex.cloud/embeds/dash#dl_embed_token=<токен>

      Где <токен> — JWT-токен.

  4. Добавьте ссылку для встраивания на свой сайт или в приложение. Например:

    <iframe src="https://datalens.yandex.cloud/embeds/chart#dl_embed_token=<токен>" width="600" height="400" frameborder="0"></iframe>

    Где:

    • src — URL встраивания.
    • <токен> — JWT-токен.
    • width — ширина чарта.
    • height — высота чарта.
    • frameborder — наличие рамки для чарта.
    <iframe src="https://datalens.yandex.cloud/embeds/dash#dl_embed_token=<токен>" width="600" height="400" frameborder="0"></iframe>

    Где:

    • src — URL встраивания.
    • <токен> — JWT-токен.
    • width — ширина дашборда.
    • height — высота дашборда.
    • frameborder — наличие рамки для дашборда.

Неподписанные параметры

По умолчанию в ссылке для встраивания объекта можно передавать любые параметры, кроме явно запрещенных. Они указываются в URL перед хешем с токеном. Это позволяет изменять некоторые параметры виджета или дашборда на стороне клиента без повторного создания токена.

Например, если в чарте или дашборде используются параметры from и to для фильтрации по времени, можно передавать эти параметры в ссылке для встраивания перед хешем с токеном:

<iframe src="https://datalens.yandex.cloud/embeds/chart?from=2022-01-01&to=2023-02-05#dl_embed_token=<токен>" width="600" height="400" frameborder="0"></iframe>

Где:

  • src — URL встраивания.
  • <токен> — JWT-токен.
  • from=2022-01-01&to=2023-02-05 — неподписанные параметры.
<iframe src="https://datalens.yandex.cloud/embeds/dash?from=2022-01-01&to=2023-02-05#dl_embed_token=<токен>" width="600" height="400" frameborder="0"></iframe>

Где:

  • src — URL встраивания.
  • <токен> — JWT-токен.
  • from=2022-01-01&to=2023-02-05 — неподписанные параметры.

Неподписанные параметры будут проигнорированы в ссылке для встраивания, если:

  • название параметра есть в списке запрещенных в режиме Всё разрешено;
  • название параметра нет в списке разрешенных в режиме Всё запрещено.

Названия параметра есть в списке запрещенных.

Рекомендации

При встраивании непубличных объектов придерживайтесь следующих рекомендаций:

  • Значения по умолчанию передавайте через параметры в ссылке.

  • Учитывайте, что приоритет значения параметра в ссылке выше, чем значение подписанного параметра с таким же названием.

  • Чтобы запретить изменение значения параметра:

    1. Добавьте подписанный параметр с нужным значением в токен.

    2. В настройке встраивания для чарта:

      • в режиме Всё разрешено добавьте этот параметр в список запрещенных;
      • в режиме Всё запрещено не добавляйте этот параметр в список разрешенных.
    1. Добавьте подписанный параметр с нужным значением в токен.
    2. В настройке встраивания для дашборда добавьте этот параметр в список запрещенных.

Особенности встраивания дашбордов

При встраивании дашбордов учитывайте следующие особенности:

  • Встроенные дашборды открываются только в режиме просмотра. У них скрыта панель навигации и по умолчанию скрыто меню у чартов. Включите опцию Разрешить экспорт данных в настройках встраивания, чтобы у чартов отображалось меню , которое позволяет экспортировать данные, представленные на чарте.
  • При открытии встроенного дашборда действуют его настройки.
  • На встроенном дашборде работают только те параметры, которые указаны в настройках дашборда.
  • Нельзя передать состояние отфильтрованных чартов в параметре state.
  • В ссылке для встраивания нельзя указать заголовок дашборда.
  • В ссылке для встраивания в параметре tab можно указать, на какой вкладке открывать дашборд.
Предыдущая
Публичное встраивание
Следующая
Стилизация интерфейса