Генерация токена встраивания

ОБЛАСТЬ ПРИМЕНЕНИЯ: Приложение владеет данными Пользователь владеет данными

Создание маркера — это REST API, который позволяет создать маркер для внедрения отчета Power BI или семантической модели в веб-приложение или на портале. Он может создать маркер для одного элемента или для нескольких отчетов или семантических моделей. Токен используется для авторизации вашего запроса к службе Power BI.

API Generate token использует одно удостоверение (мастер-пользователь или служебный принципал) для создания маркера для отдельного пользователя в зависимости от учетных данных этого пользователя в приложении (эффективное удостоверение).

После успешной проверки подлинности предоставляется доступ к соответствующим данным.

Примечание.

Создание маркера — это более новый API версии 2, который работает как для отчетов, так и для семантических моделей, а также для отдельных или нескольких элементов. Для панелей мониторинга и плиток используйте панели мониторинга v1 GenerateTokenInGroup и плитки GenerateTokenInGroup.

Защита данных

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

Мы рекомендуем использовать изоляцию на основе рабочей области с профилями, но если вы хотите использовать подход RLS, ознакомьтесь с разделом RLS в конце этой статьи.

Разрешения токена и безопасность

В API создания маркера раздел GenerateTokenRequest описывает разрешения маркера.

Уровень доступа

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

  • Чтобы разрешить пользователю создавать новые отчеты (либо SaveAs, либо CreateNew) в этой рабочей области, добавьте идентификатор рабочей области в токен внедрения.

Безопасность на уровне строк

При использовании безопасности на уровне строк (RLS) используемый идентификатор может отличаться от идентификатора служебного субъекта или основного пользователя, используемого для генерации токена. С помощью различных идентичностей можно отображать встроенную информацию в соответствии с пользователем, на которого вы нацеливаете. Например, в приложении можно попросить пользователей войти, а затем отобразить отчет, содержащий только сведения о продажах, если пользователь вошел в систему сотрудником по продажам.

Если вы используете RLS, вы можете иногда опустить удостоверение пользователя (параметр EffectiveIdentity). Если параметр EffectiveIdentity не используется, маркер имеет доступ ко всей базе данных. Этот метод можно использовать для предоставления доступа пользователям, таким как администраторы и руководители, у которых есть разрешение на просмотр всей семантической модели. Однако этот метод нельзя использовать в каждом сценарии. В следующей таблице перечислены различные типы RLS и показано, какой метод проверки подлинности можно использовать без указания удостоверения пользователя.

В таблице также показаны рекомендации и ограничения, применимые к каждому типу RLS.

Тип RLS Можно ли создать встраиваемый токен без указания эффективного идентификатора пользователя? Рекомендации и ограничения
Безопасность на уровне строк Cloud (Cloud RLS) ✔ Главный пользователь
✖ Сервисный принципал
RDL (отчеты с разбивкой на страницы) ✖ Главный пользователь
✔ Субъект-служба		 Для создания маркера для внедрения в RDL нельзя использовать пользователя с правами администратора.
Службы Analysis Services (AS) в локальном динамическом подключении ✔ Главный пользователь
✖ Сервисный принципал		 Пользователю, создающим маркер внедрения, также требуется одно из следующих разрешений:
  • Разрешения администратора шлюза
  • Разрешение олицетворения источника данных (ReadOverrideEffectiveIdentity)
    		•
    Прямое подключение к Azure Analysis Services (AS) ✔ Главный пользователь
    ✖ Субъект-служба    		 Идентификатор пользователя, генерирующего токен встраивания, не может быть изменён. Пользовательские данные можно использовать для реализации динамической фильтрации RLS или безопасной фильтрации.

    Примечание. Принципал-служба должен указать свой идентификатор объекта в качестве фактической личности (имя пользователя RLS).
    Единая аутентификация (SSO) ✔ Главный пользователь
    ✖ Субъект-служба    		 Явное удостоверение (единый вход) можно предоставить с помощью свойства BLOB-объекта удостоверения в эффективном объекте удостоверения.
    Единый вход (SSO) и облачное решение RLS ✔ Главный пользователь
    ✖ Субъект-служба    		 Необходимо указать следующее:
  • Явное удостоверение (SSO) в свойстве BLOB активного объекта удостоверения
  • Действительное удостоверение (RLS) (имя пользователя)
    		•

    Примечание.

    Субъекты-службы всегда должны предоставлять следующие возможности:

    • Идентификатор для любого элемента с семантической моделью RLS
    • Эффективное удостоверение RLS с определенным контекстным удостоверением (SSO) (для семантической модели единого входа)

    DirectQuery для семантических моделей Power BI

    Чтобы внедрить отчет Power BI с семантической моделью с подключением Direct Query к другой семантической модели Power BI:

    В этом сценарии все семантические модели должны находиться в рабочем пространстве премиум-класса. Маркеры пробного внедрения нельзя использовать для встраивания отчета этого типа.

    Обновите токены до истечения их срока действия

    Токены имеют ограничение по времени. Поэтому после внедрения элемента Power BI требуется ограниченное время для взаимодействия с ним. Чтобы предоставить пользователям непрерывный опыт, продлить (или обновить) маркер до истечения срока его действия.

    Информационные панели и плитки

    Токен генерации работает для отчетов и семантических моделей. Чтобы создать маркер внедрения для панели мониторинга или плитки, используйте версии 1 Dashboards GenerateTokenInGroup или Tiles GenerateTokenInGroup API. Эти API создают маркеры только для одного элемента одновременно. Невозможно создать маркер для нескольких элементов.

    Для этих API:

    • Используйте параметр accessLevel, чтобы определить уровень доступа пользователя.

      • Просмотр . Предоставление пользователям разрешений на просмотр.

      • Редактировать — предоставление пользователям разрешений на просмотр и редактирование (применяется только при генерации токена внедрения для отчета).

      • Create — предоставьте пользователю разрешения на создание нового отчета (применяется только при создании токена встраивания для создания отчета). Для создания отчета необходимо также указать параметр datasetId .

    • Используйте логическое значение allowSaveAs, чтобы пользователи могли сохранить отчет в качестве нового отчета. Этот параметр имеет значение false по умолчанию и применяется только при создании маркера внедрения для отчета.

    Рекомендации и ограничения

    • По соображениям безопасности срок действия токена внедрения устанавливается на оставшийся срок действия токена Microsoft Entra, используемого для вызова GenerateToken API. Таким образом, если вы используете один и тот же токен Microsoft Entra для создания нескольких маркеров внедрения, время существования созданных маркеров внедрения будет короче при каждом вызове.

    • Если внедренная семантическая модель и элемент находятся в двух разных рабочих областях, субъект-служба или главный пользователь должны быть по крайней мере членом обеих рабочих областей.

    • Для внедрения элементов с помощью Data Lake Storage (DLS) требуется версия 2 API создания маркеров.

    • Невозможно создать токен встраивания для My workspace.

    Связанный контент

    • Last updated on