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

  • Статья

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

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

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

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

Примечание.

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

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

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

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

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

В разделе Generate TokenRequest описаны разрешения маркера в разделе 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 требуется ограниченное время для взаимодействия с ним. Чтобы предоставить пользователям непрерывный опыт, продлить (или обновить) маркер до истечения срока его действия.

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

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

    Для этих API:

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

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

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

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

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

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

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

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

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

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