Получение маркеров доступа

8 мин

Для получении маркера доступа, который всегда необходим приложению для внедрения содержимого Power BI, нужно получить токен Azure AD. При использовании сценария Для клиентов приложение использует токен Azure AD для создания токена внедрения.

Следует четко понимать:

Маркер доступа для сценария Для организации — это токен Azure AD, который содержит утверждения, которые приложение использует для идентификации предоставленных разрешений.
Маркер доступа для сценария Для клиентов — это токен внедрения, который представляет факты о содержимом Power BI и о том, как ваше приложение может получить к нему доступ. Приложение создает токен внедрения с помощью операции REST API для Power BI, которая требует токен Azure AD.

Получение токенов Azure AD

Используйте библиотеку проверки подлинности Майкрософт (MSAL) для разработки логики приложения, которое получает токены Azure AD из платформы удостоверений Майкрософт. MSAL поддерживает различные архитектуры приложений и платформ, в том числе .NET, JavaScript, Java, Python, Android и iOS.

Совет

При разработке веб-приложения ASP.NET Core рекомендуется использовать библиотеку веб-проверки подлинности Майкрософт. Эта библиотека представляет собой набор пакетов, известных как Microsoft.Identity.Web. Ее можно установить из NuGet или Visual Studio.

Существуют различные методы получения токены Azure AD с помощью MSAL. Для некоторых из них необходимо вмешательство пользователя через веб-браузер, в то время как для других оно не требуется. Как правило, выбор способа получения маркера Azure AD зависит от того, является ли приложение общедоступным клиентским приложением (например, классическим или мобильным приложением) или конфиденциальным клиентским приложением (например, веб-приложением). Сценарий внедрения также влияет на ваш выбор.

В этом уроке не описаны методы получения маркеров Azure AD. Дополнительные сведения см. в статье Получение и кэширование маркеров с помощью библиотеки проверки подлинности Майкрософт (MSAL).

Совет

Если примеры приложений для настройки внедрения соответствуют требованиям вашего приложения, рекомендуем скопировать пример кода для получения токенов Azure AD.

Чтобы разрешить приложению получать маркеры Azure AD, его файл конфигурации должен содержать следующие параметры:

TenantId — требуется только для субъекта-службы. Это идентификатор TenantID Azure AD.
ClientId — обязательный. Это идентификатор ApplicationID Azure AD (ClientID).
ClientSecret или ClientCertificate — требуется только для субъекта-службы.
PbiUsername — требуется только для главной учетной записи пользователя.
PbiPassword — требуется только для главной учетной записи пользователя.

Важно!

Независимо от того, используются ли сертификаты, секреты клиента или учетные данные главной учетной записи пользователя, необходимо предпринять меры по защите их от несанкционированного доступа и использования. Мы рекомендуем использовать Azure Key Vault для защиты криптографических ключей, сертификатов и секретов в облаке.

Получение токенов внедрения

Используйте операцию GenerateTokenRequestV2 из REST API для Microsoft Power BI для запроса токена внедрения. Существуют и другие связанные операции, которые создают токены внедрения для других типов контента Power BI. Для всех операций API требуется маркер Azure AD.

Совет

При разработке приложения .NET рекомендуется установить пакет Microsoft.PowerBI.Api. Его можно установить из NuGet или Visual Studio.

Рассмотрим следующий код, демонстрирующий создание токена внедрения. Токен содержит утверждения для всех отчетов и наборов данных из рабочей области и позволяет пользователям приложения создавать или изменять отчеты. В частности, он выполняет следующие действия:

Подключается к Power BI.
Объявляет переменную с именем reportTokenRequests для хранения запросов маркера отчета.
Перечисляет все отчеты в рабочей области, создавая список объектов (с помощью вспомогательного класса EmbeddedReport). Каждый объект описывает идентификатор отчета, имя и URL-адрес внедрения. Приложению требуется идентификатор отчета для создания маркера. Имя требуется для представления пользователям в меню, а URL-адрес внедрения необходим для внедрения отчета. Код добавляет в переменную reportTokenRequests запрос токена отчета, разрешающий редактирование отчета.
Объявляет переменную с именем datasetTokenRequests для хранения запросов токена набора данных.
Перечисляет все наборы данных в рабочей области, создавая список объектов (с помощью вспомогательного класса EmbeddedDataset). Каждый объект описывает идентификатор набора данных, имя и URL-адрес внедрения. Приложению требуется идентификатор набора данных для создания токена. Имя может потребоваться, чтобы представить его пользователям в меню, а URL-адрес внедрения необходим для внедрения набора данных. Код добавляет в переменную запрос datasetTokenRequests токена набора данных.
Создает запрос токена рабочей области (требуется, когда пользователи создают отчеты), добавляемый в переменную workspaceRequests.
Использует метод GenerateTokenRequestV2 для объединения запросов токенов отчета, запросов токенов набора данных и запроса токена рабочей области.
Использует GenerateTokenAsync для создания токена внедрения.
Сохраняет токен внедрения в строковую переменную.

// Connect to Power BI
var client = GetPowerBiClient();

// Get reports in the workspace
var reports = (await client.Reports.GetReportsInGroupAsync(_workspaceId)).Value;

var reportList = new List<EmbeddedReport>();
var reportTokenRequests = new List<GenerateTokenRequestV2Report>();

foreach (var report in reports)
{
    reportList.Add(new EmbeddedReport
    {
        Id = report.Id.ToString(),
        Name = report.Name,
        EmbedUrl = report.EmbedUrl
    });

    reportTokenRequests.Add(new GenerateTokenRequestV2Report(report.Id, allowEdit: true));
}

// Get datasets in the workspace
var datasets = (await client.Datasets.GetDatasetsInGroupAsync(_workspaceId)).Value;

var datasetList = new List<EmbeddedDataset>();
var datasetTokenRequests = new List<GenerateTokenRequestV2Dataset>();

foreach (var dataset in datasets)
{
    datasetList.Add(new EmbeddedDataset
    {
        Id = dataset.Id.ToString(),
        Name = dataset.Name,
        EmbedUrl = dataset.QnaEmbedURL
    });

    datasetTokenRequests.Add(new GenerateTokenRequestV2Dataset(dataset.Id));
}

// Generate token request for the workspace
var workspaceRequests = new GenerateTokenRequestV2TargetWorkspace[] {
    new GenerateTokenRequestV2TargetWorkspace(_workspaceId)
};

// Bundle token requests for reports, datasets, and the workspace
var tokenRequest = new GenerateTokenRequestV2(
    reports: reportTokenRequests,
    datasets: datasetTokenRequests,
    targetWorkspaces: workspaceRequests
);

// Generate the embed token
string embedToken = (await client.EmbedToken.GenerateTokenAsync(tokenRequest)).Token;

Приложение должно выводить значение переменной embedToken на HTML-страницу внедрения. Затем логика на стороне клиента может использовать токен внедрения для внедрения содержимого в элемент div.

Примечание

См. модуль Внедрение содержимого Power BI.

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

Дополнительные сведения см. в статье Внедрение токена — создание токена.

Обновление токенов доступа

Маркеры доступа имеют время истечения срока действия. После создания у пользователей приложений есть ограниченное время для взаимодействия с использующим их содержимым Power BI. Для удобства пользователей приложения оно должно обновлять маркеры доступа до истечения срока действия с помощью клиентского API Power BI.

Примечание

Сведения о клиентских API см. в модуле Интеграция содержимого с помощью клиентских API Power BI.

Дополнительные сведения см. в разделе Обновление токена доступа.

Изучение других ресурсов

Дополнительные сведения watch в серии видео "Руководство разработчиков Power BI по безопасности Azure AD". Эта серия состоит из шести видео, которые охватывают углубленный теории. Ее подготовил Тед Паттисон, который является членом группы консультантов по клиентам Power BI в корпорации Майкрософт.

Продолжить

Получение токенов Azure AD

Получение токенов внедрения

Обновление токенов доступа

Изучение других ресурсов

Обратная связь