Автоматическая настройка установки приложения-шаблона
Приложения-шаблоны — отличный способ для клиентов начать получать аналитические сведения из своих данных. Приложения-шаблоны быстро получают их и работают, подключая их к своим данным. Приложения-шаблоны предоставляют им предварительно созданные отчеты, которые они могут настроить, если это необходимо.
Клиенты не всегда знакомы с подробными сведениями о том, как подключиться к данным. Наличие этих сведений при установке приложения-шаблона может быть точкой боли для них.
Если вы являетесь поставщиком служб данных и создали приложение-шаблон, чтобы помочь клиентам приступить к работе со своими данными в службе, вы можете упростить установку приложения-шаблона. Вы можете автоматизировать настройку параметров приложения-шаблона. Когда клиент входит на портал, он выбирает специальную ссылку, которую вы подготовили. Эта ссылка:
- Запускает автоматизацию, которая собирает необходимые сведения.
- Предварительно настраивает параметры приложения-шаблона.
- Перенаправляет клиента в учетную запись Power BI, где они могут установить приложение.
Все, что нужно сделать, — установить и пройти проверку подлинности в источнике данных, и они хороши для работы!
Здесь показано взаимодействие с клиентами.
В этой статье описан базовый поток, предварительные требования и основные шаги и API, необходимые для автоматизации настройки установки приложения-шаблона. Если вы хотите ознакомиться и приступить к работе, перейдите к руководству , в котором вы автоматизируете настройку установки приложения-шаблона с помощью простого примера приложения, которое мы подготовили, использующее функцию Azure.
Базовый поток действий
Базовый поток автоматизации настройки установки приложения-шаблона выглядит следующим образом:
Пользователь входит на портал поставщика программного обеспечения и выбирает указанную ссылку. Это действие инициирует автоматизированный поток. Портал поставщика программного обеспечения подготавливает конфигурацию конкретного пользователя на этом этапе.
Поставщик программного обеспечения получает маркер только для приложений на основе субъекта-службы (маркера только для приложений), зарегистрированного в клиенте поставщика услуг.
С помощью REST API Power BI isV создает запрос на установку, который содержит конфигурацию параметра для конкретного пользователя, подготовленную isV.
IsV перенаправляет пользователя в Power BI с помощью
POSTметода перенаправления, содержащего запрос на установку.Пользователь перенаправляется в учетную запись Power BI с запросом на установку и запрашивает установку приложения-шаблона. Когда пользователь выбирает "Установить", для них устанавливается приложение-шаблон.
Примечание.
Хотя значения параметров настраиваются isV в процессе создания билета на установку, учетные данные, связанные с источником данных, предоставляются только пользователем на заключительных этапах установки. Это соглашение предотвращает их предоставление третьим лицам и обеспечивает безопасное подключение между пользователем и источниками данных приложения-шаблона.
Необходимые компоненты
Чтобы обеспечить предварительно настроенную установку для приложения-шаблона, необходимы следующие предварительные требования:
Лицензия Power BI Pro. Если вы не зарегистрированы в Power BI Pro, зарегистрируйтесь для получения бесплатной пробной версии, прежде чем начать.
Ваш собственный клиент Microsoft Entra настроен. Инструкции по настройке одного из них см. в статье "Создание клиента Microsoft Entra".
Субъект-служба (маркер только для приложений), зарегистрированный в предыдущем клиенте. Дополнительные сведения см. в статье Внедрение содержимого Power BI с субъектом-службой и секретом приложения. Обязательно зарегистрируйте приложение в качестве серверного веб-приложения . Вы регистрируете серверное веб-приложение для создания секрета приложения. В этом процессе необходимо сохранить идентификатор приложения (ClientID) и секрет приложения (ClientSecret) для дальнейших действий.
Параметризованное приложение шаблона, готовое к установке. Приложение-шаблон необходимо создать в том же клиенте, в котором вы регистрируете приложение в идентификаторе Microsoft Entra. Дополнительные сведения см. в советах по шаблону приложения или создании приложения-шаблона в Power BI. В приложении-шаблоне необходимо заметить следующие сведения для следующих шагов:
- Идентификатор приложения, ключ пакета и идентификатор владельца, как они отображаются в URL-адресе установки в конце процесса определения свойств приложения-шаблона при создании приложения. Вы также можете получить ту же ссылку, выбрав ссылку "Получить" в области управления выпусками приложения шаблона.
- Имена параметров, как они определены в семантической модели приложения шаблона. Имена параметров — это строки с учетом регистра, которые также можно получить на вкладке "Параметр Параметры" при определении свойств приложения-шаблона или из параметров семантической модели в Power BI.
Чтобы протестировать рабочий поток автоматизации, добавьте субъект-службу в рабочую область приложения-шаблона в качестве Администратор.
Примечание.
Вы можете протестировать предварительно настроенное приложение установки в приложении-шаблоне, если приложение шаблона готово к установке, даже если оно еще недоступно в AppSource. Чтобы пользователи за пределами клиента могли использовать приложение автоматической установки для установки приложения-шаблона, приложение-шаблон должно быть общедоступным в Marketplace приложений Power BI. Перед распространением приложения-шаблона с помощью создаваемого автоматического приложения установки обязательно опубликуйте его в Центре партнеров.
Основные шаги и API
Основные шаги по автоматизации настройки установки приложения-шаблона и необходимые API описаны в следующих разделах. Хотя большинство шагов выполняются с помощью REST API Power BI, примеры кода, описанные здесь, выполняются с помощью пакета SDK для .NET.
Шаг 1. Создание клиентского объекта Power BI
Использование REST API Power BI требует получения маркера доступа для субъекта-службы из идентификатора Microsoft Entra. Перед вызовами REST API Power BI необходимо получить маркер доступа Microsoft Entra для приложения Power BI. Чтобы создать клиент Power BI с маркером доступа, необходимо создать объект клиента Power BI, который позволяет взаимодействовать с REST API Power BI. Объект клиента Power BI создается путем упаковки AccessToken с помощью объекта Microsoft.Rest.TokenCredentials .
using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;
using Microsoft.PowerBI.Api.V2;
var tokenCredentials = new TokenCredentials(authenticationResult.AccessToken, "Bearer");
// Create a Power BI client object. It's used to call Power BI APIs.
using (var client = new PowerBIClient(new Uri(ApiUrl), tokenCredentials))
{
// Your code goes here.
}
Шаг 2. Создание билета на установку
Создайте запрос на установку, который используется при перенаправлении пользователей в Power BI. API, используемый для этой операции, — ЭТО API CreateInstallTicket .
Пример создания билета на установку и настройку приложения-шаблона доступен в файле InstallTemplateApp/InstallAppFunction.cs в примере приложения.
В следующем примере кода показано, как использовать REST API createInstallTicket для шаблона.
using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;
// Create Install Ticket Request.
InstallTicket ticketResponse = null;
var request = new CreateInstallTicketRequest()
{
InstallDetails = new List<TemplateAppInstallDetails>()
{
new TemplateAppInstallDetails()
{
AppId = Guid.Parse(AppId),
PackageKey = PackageKey,
OwnerTenantId = Guid.Parse(OwnerId),
Config = new TemplateAppConfigurationRequest()
{
Configuration = Parameters
.GroupBy(p => p.Name)
.ToDictionary(k => k.Key, k => k.Select(p => p.Value).Single())
}
}
}
};
// Issue the request to the REST API using .NET SDK.
InstallTicket ticketResponse = await client.TemplateApps.CreateInstallTicketAsync(request);
Шаг 3. Перенаправление пользователей в Power BI с помощью билета
После создания билета установки вы будете использовать его для перенаправления пользователей в Power BI, чтобы продолжить установку и настройку приложения шаблона. Вы используете перенаправление метода на URL-адрес установки приложения шаблона с запросом POST в тексте запроса.
Существуют различные документированные методы выдачи перенаправления с помощью POST запросов. Выбор одного или другого зависит от сценария и взаимодействия пользователей с порталом или службой.
Простой пример, в основном используемый для тестирования, использует форму со скрытым полем, которое автоматически отправляется при загрузке.
<html>
<body onload='document.forms["form"].submit()'>
<!-- form method is POST and action is the app install URL -->
<form name='form' action='https://app.powerbi.com/....' method='post' enctype='application/json'>
<!-- value should be the new install ticket -->
<input type='hidden' name='ticket' value='H4sI....AAA='>
</form>
</body>
</html>
Следующий пример ответа примера приложения содержит запрос на установку и автоматически перенаправляет пользователей в Power BI. Ответ этой функции Azure совпадает с формой автоматической самостоятельной отправки, которую мы видим в предыдущем примере HTML.
...
return new ContentResult() { Content = RedirectWithData(redirectUrl, ticket.Ticket), ContentType = "text/html" };
}
...
public static string RedirectWithData(string url, string ticket)
{
StringBuilder s = new StringBuilder();
s.Append("<html>");
s.AppendFormat("<body onload='document.forms[\"form\"].submit()'>");
s.AppendFormat("<form name='form' action='{0}' method='post' enctype='application/json'>", url);
s.AppendFormat("<input type='hidden' name='ticket' value='{0}' />", ticket);
s.Append("</form></body></html>");
return s.ToString();
}
Примечание.
Существуют различные методы перенаправления POST браузера. Всегда следует использовать самый безопасный метод, который зависит от потребностей службы и ограничений. Помните, что некоторые формы небезопасного перенаправления могут привести к раскрытию проблем безопасности пользователей или служб.
Шаг 4. Перемещение автоматизации в рабочую среду
Когда вы готовы к работе с автоматизацией, обязательно переместите ее в рабочую среду.
Связанный контент
- Ознакомьтесь с нашим руководством, который использует простую функцию Azure для автоматизации настройки установки приложения-шаблона.
- Есть еще вопросы? Попробуйте попросить Сообщество Power BI.