Создание маркера внедрения

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

Создание маркера — это 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 Row Level Security (Cloud RLS)	✔ Главный пользователь ✖ Субъект-служба
RDL (отчеты с разбивкой на страницы)	✖ Главный пользователь ✔ Субъект-служба	Для создания маркера внедрения для RDL нельзя использовать главный пользователь.
Службы Analysis Services (AS) в локальном динамическом подключении	✔ Главный пользователь ✖ Субъект-служба	Пользователю, создающим маркер внедрения, также требуется одно из следующих разрешений: Разрешения администратора шлюза Разрешение олицетворения источника данных (ReadOverrideEffectiveIdentity)
Динамическое подключение к Службам Analysis Services (AS) Azure	✔ Главный пользователь ✖ Субъект-служба	Удостоверение пользователя, создающего маркер внедрения, не может быть переопределено. Пользовательские данные можно использовать для реализации динамической фильтрации RLS или безопасной фильтрации. Примечание. Субъект-служба должен указать свой идентификатор объекта в качестве эффективного удостоверения (имя пользователя RLS).
Единый вход	✔ Главный пользователь ✖ Субъект-служба	Явное удостоверение (единый вход) можно предоставить с помощью свойства BLOB-объекта удостоверения в эффективном объекте удостоверения.
Единый вход и облачный RLS	✔ Главный пользователь ✖ Субъект-служба	Необходимо указать следующее: Явное удостоверение (единый вход) в свойстве BLOB-объекта удостоверения в эффективном объекте удостоверения Эффективное удостоверение (RLS) (имя пользователя)

Примечание.

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

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

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

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

• На портале Power BI задайте для конечной точки XMLA значение "Только для чтения" или"Запись чтения", как описано в описании включения чтения и записи для емкости Premium. Это необходимо сделать только один раз на емкость.

• Создание маркера внедрения нескольких ресурсов

  • Укажите все идентификаторы наборов данных в запросе.
  • XmlaPermissions Задайте значение "Только для чтения" для каждой семантической модели в запросе.
  • Для каждого источника данных с поддержкой единого входа укажите большой двоичный объект удостоверения для источника данных.DatasourceIdentity

Продление маркеров до истечения срока действия

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

Панели мониторинга и плитки

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

Для этих API:

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

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

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

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

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

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

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

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

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

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

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

• Регистрация приложения
• Power BI Embedded для клиентов
• Внедрение содержимого Power BI с помощью субъекта-службы