Встраивание непубличных объектов
Примечание
Функциональность доступна только в рамках тарифного плана Business.
Вы можете безопасно встроить непубличные чарты и дашборды на сайт или в приложение с помощью специальных ссылок с JWT-токеном
Встраивание непубличных объектов работает только в новой объектной модели DataLens на уровне воркбуков и доступно только администратору воркбука.
Встраивание не поддерживается для непубличных объектов, которые построены на основе следующих подключений:
-
Примечание
Дашбордом или чартом на основе данных Метрики или AppMetrica можно поделиться.
Как встроить непубличный объект
-
Создайте ключ для встраивания:
Примечание
Один ключ можно использовать для встраивания нескольких объектов.
-
Перейдите на главную страницу
DataLens. -
На панели слева выберите
Коллекции и воркбуки. -
Откройте воркбук, в котором расположен объект для встраивания.
-
В верхней части интерфейса нажмите значок
и выберите Ключи для встраивания. -
В открывшемся окне:
-
Нажмите кнопку
Создать ключ. -
Введите название ключа и нажмите кнопку Создать.
-
Внизу нажмите кнопку Скачать файл с ключом или скопируйте значение ключа.
Важно
После закрытия окна все данные из него будут потеряны.
Новый ключ для встраивания появится в списке.
-
-
-
Настройте встраивание для непубличного объекта:
Примечание
Для каждого объекта можно настроить несколько встраиваний.
-
В строке с нужным объектом нажмите значок
и выберите Настройки встраивания. -
В открывшемся окне нажмите кнопку
Новое встраивание. -
В окне настроек укажите:
Для чартаДля дашборда-
Название — введите название встраивания.
-
Ключ — выберите созданный ранее ключ для встраивания.
-
Выберите Режим работы параметров по умолчанию:
- Всё разрешено (по умолчанию) — все неподписанные параметры разрешены, кроме запрещенных;
- Всё запрещено — все неподписанные параметры запрещены, кроме разрешенных.
На подписанные параметры из токена эти ограничения не действуют.
-
(опционально) Запрещённые параметры — укажите названия неподписанных параметров, которые не будут работать при встраивании чарта. Доступно для режима Всё разрешено.
-
(опционально) Разрешённые параметры — укажите названия неподписанных параметров, которые можно передавать в ссылке для встраивания. Параметры, которые не указаны в этом списке, будут проигнорированы при попытке передать их в ссылке для встраивания. Доступно для режима Всё запрещено.
- Название — введите название встраивания.
- Ключ — выберите созданный ранее ключ для встраивания.
- (опционально) Запрещённые параметры — укажите названия неподписанных параметров, которые не будут работать при встраивании дашборда. На подписанные параметры из токена эти ограничения не действуют. По умолчанию в ссылке для встраивания можно передавать любые параметры, которые указаны в настройках дашборда.
-
-
Нажмите кнопку Создать. В колонке ID скопируйте идентификатор объекта встраивания, а затем нажмите Закрыть.
-
-
Создайте токен:
-
Подготовьте 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" } }
-
-
Чтобы создать JWT-токен, подпишите подготовленный payload закрытым ключом, который был получен ранее при создании ключа для встраивания.
Примечание
Используйте при создании JWT алгоритм
PS256
.Для создания JWT-токена используйте примеры кода:
PythonNode.jsGoУстановите модуль
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) }
-
Сформируйте ссылку для встраивания:
Для чартаДля дашбордаhttps://datalens.yandex.cloud/embeds/chart#dl_embed_token=<токен>
Где
<токен>
— JWT-токен.https://datalens.yandex.cloud/embeds/dash#dl_embed_token=<токен>
Где
<токен>
— JWT-токен.
-
-
Добавьте ссылку для встраивания на свой сайт или в приложение. Например:
Для чартаДля дашборда<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
— неподписанные параметры.
Неподписанные параметры будут проигнорированы в ссылке для встраивания, если:
- название параметра есть в списке запрещенных в режиме Всё разрешено;
- название параметра нет в списке разрешенных в режиме Всё запрещено.
Названия параметра есть в списке запрещенных.
Рекомендации
При встраивании непубличных объектов придерживайтесь следующих рекомендаций:
-
Значения по умолчанию передавайте через параметры в ссылке.
-
Учитывайте, что приоритет значения параметра в ссылке выше, чем значение подписанного параметра с таким же названием.
-
Чтобы запретить изменение значения параметра:
Для чартаДля дашборда-
Добавьте подписанный параметр с нужным значением в токен.
-
В настройке встраивания для чарта:
- в режиме Всё разрешено добавьте этот параметр в список запрещенных;
- в режиме Всё запрещено не добавляйте этот параметр в список разрешенных.
- Добавьте подписанный параметр с нужным значением в токен.
- В настройке встраивания для дашборда добавьте этот параметр в список запрещенных.
-
Особенности встраивания дашбордов
При встраивании дашбордов учитывайте следующие особенности:
- Встроенные дашборды открываются только в режиме просмотра. У них скрыта панель навигации и меню
у чартов. - При открытии встроенного дашборда действуют его настройки.
- На встроенном дашборде работают только те параметры, которые указаны в настройках дашборда.
- Нельзя передать состояние отфильтрованных чартов в параметре
state
. - В ссылке для встраивания нельзя указать заголовок дашборда.
- В ссылке для встраивания в параметре
tab
можно указать, на какой вкладке открывать дашборд.