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

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

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

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

Параметры отображения

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

  • _autoupdate — задает время автообновления для дашбордов и чартов в секундах. По умолчанию они не обновляются автоматически. Работает только на активной вкладке браузера. Если для неактивной вкладки время автообновления уже наступило, оно выполнится, когда вкладка снова станет активной. Минимальная величина:

    • для дашбордов — 30 секунд;
    • для чартов — 15 секунд.

  • _theme — задает оформление объекта. Возможные значения:

    • light — для отображения в светлой теме;
    • dark — для отображения в темной теме.

  • _lang — у чартов определяет значение языка для меню, которое открывается при нажатии на значок . Возможные значения: ru или en.

Параметры передаются в формате <имя_параметра>=<значение>. Например, чтобы задать время автообновления 50 секунд, укажите: _autoupdate=50.

Параметр добавляется к адресу объекта после знака вопроса ? перед хешем с токеном. Их можно передавать вместе с неподписанными параметрами. Для передачи нескольких параметров перечислите их через знак амперсанда &.

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

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

    Примечание

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

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

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

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

      image

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

      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 — строковая константа идентификатора сервиса: ENTERPRISE_DATALENS_EMBEDDING_SERVICE_MARK.

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

        Важно

        • Генерируемый токен передается в составе заголовка сетевого запроса, поэтому его максимальный размер ограничен — 30 КБ. Учитывайте это при использовании подписанных параметров.
        • Для корректной работы в качестве значений параметров используйте только строку или массив строк.

        Пример:

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

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

      Примечание

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

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

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

      pip3 install cryptography
        pip3 install PyJWT

      Примечание

      Для корректной работы используйте PyJWT версии не ниже 2.0.0.

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

      import time
        import jwt
        import json
        ​
        private_key = b"""<закрытый_ключ>"""
        ​
        now = int(time.time())
        payload = {
           'embedId': "<идентификатор_объекта_встраивания>",
           'dlEmbedService': "ENTERPRISE_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: 'ENTERPRISE_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": "ENTERPRISE_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. Сформируйте ссылку для встраивания:

      <домен_DataLens>/embeds/chart#dl_embed_token=<токен>

      Где:

      • <домен_DataLens> — домен вашего корпоративного DataLens, например: https://enterprise.datalens.net.
      • <токен> — JWT-токен.
      <домен_DataLens>/embeds/dash#dl_embed_token=<токен>

      Где:

      • <токен> — JWT-токен.

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

    <iframe src="<домен_DataLens>/embeds/chart#dl_embed_token=<токен>" width="600" height="400" frameborder="0"></iframe>

    Где:

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

    Где:

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

    Примечание

    Если на сайте и в приложении, куда будет встроен чарт или дашборд, реализована политика доступа по белым спискам, добавьте домен <домен_DataLens> в список разрешенных.

Обновление токена без потери состояния фильтров

При замене JWT-токена в ссылке для встраивания фильтры на встроенном дашборде сбрасываются к значениям по умолчанию.

Чтобы обновить ссылку для встраивания без потери состояния фильтров, используйте метод postMessage.

Для обновления в ссылке JWT-токена отправьте в iframe с помощью метода postMessage объект вида:

{
            type: 'SECURE_EMBEDDING_TOKEN_UPDATE',
            token: <обновленный_токен>
        }

Где <обновленный_токен> — обновленный JWT-токен.

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

Пример:

const iframe = document.getElementById('ID_IFRAME');
        
        iframe.contentWindow.postMessage({
            type: 'SECURE_EMBEDDING_TOKEN_UPDATE',
            token: 'NEW_TOKEN'
        }, '<домен_DataLens>/');

Учитывайте время окончания действия токена при его обновлении.

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

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

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

<iframe src="<домен_DataLens>/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="<домен_DataLens>/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 можно указать, на какой вкладке открывать дашборд.
Предыдущая
Встраивание на корпоративном домене
Следующая
Обзор