Автоматическая настройка установки приложения-шаблона

Приложения-шаблоны — отличный способ для клиентов начать получать аналитические сведения из своих данных. Шаблонные приложения быстро начинают работать, подключая пользователей к их данным. Приложения-шаблоны предоставляют им предварительно созданные отчеты, которые они могут настроить, если это необходимо.

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

Если вы являетесь поставщиком служб данных и создали приложение-шаблон, чтобы помочь клиентам приступить к работе со своими данными в службе, вы можете упростить установку приложения-шаблона. Вы можете автоматизировать настройку параметров приложения-шаблона. Когда клиент входит на портал, он выбирает специальную ссылку, которую вы подготовили. Эта ссылка:

• Запускает автоматизацию, которая собирает необходимые сведения.
• Предварительно настраивает параметры приложения-шаблона.
• Перенаправляет клиента в учетную запись Power BI, где они могут установить приложение.

Все, что нужно сделать, это выбрать Установить, пройти аутентификацию в источнике данных — и все готово!

Здесь показано взаимодействие с клиентами.

В этой статье описывается базовый поток, предварительные требования, основные шаги и API, необходимые для автоматизации настройки установки приложения-шаблона. Если вы хотите ознакомиться и приступить к работе, перейдите к руководству , в котором вы автоматизируете настройку установки приложения-шаблона с помощью простого примера приложения, которое мы подготовили, использующее функцию Azure.

Базовый поток для автоматической настройки

Базовый поток для автоматизации настройки установки приложения-шаблона выполняется следующим образом:

1. Пользователь входит на портал поставщика программного обеспечения и выбирает указанную ссылку. Это действие инициирует автоматизированный поток. Портал поставщика программного обеспечения подготавливает конфигурацию конкретного пользователя на этом этапе.
2. Поставщик программного обеспечения получает токен только для приложений на основе учетной записи службы (токена только для приложений), зарегистрированной в арендаторе поставщика ПО.
3. С помощью REST API Power BI isV создает запрос на установку, который содержит конфигурацию параметра для конкретного пользователя, подготовленную isV.
4. IsV перенаправляет пользователя в Power BI с помощью POST метода перенаправления, содержащего запрос на установку.
5. Пользователь перенаправляется в свою учетную запись Power BI с тикетом на установку и получает приглашение установить приложение-шаблон. Когда пользователь выбирает "Установить", для них устанавливается приложение-шаблон.

Предпосылки

Чтобы обеспечить предварительно настроенную установку для приложения-шаблона, необходимы следующие предварительные требования:

• Лицензия Power BI Pro. Если вы не зарегистрировались в Power BI Pro, зарегистрируйтесь на бесплатную пробную версию перед началом работы.

• Ваша собственная настройка клиента Microsoft Entra. Инструкции по настройке одного из них см. в статье "Создание клиента Microsoft Entra".

• Учетная запись службы (маркер только для приложений) зарегистрирована в предыдущем клиенте. Дополнительные сведения см. в статье об интеграции содержимого Power BI с использованием service principal и секрета приложения. Обязательно зарегистрируйте приложение в качестве серверного веб-приложения . Вы регистрируете серверное веб-приложение для создания секрета приложения. В этом процессе необходимо сохранить идентификатор приложения (ClientID) и секрет приложения (ClientSecret) для дальнейших действий.

• Параметризованное приложение шаблона, готовое к установке. Приложение-шаблон необходимо создать в том же арендаторе, в котором вы регистрируете приложение в Microsoft Entra ID. Дополнительные сведения см. в советах по шаблону приложения или создании приложения-шаблона в Power BI. В приложении-шаблоне необходимо учесть следующую информацию для дальнейших шагов.

  • Идентификатор приложения, ключ пакета и идентификатор владельца , как они отображаются в URL-адресе установки в конце процесса определения свойств приложения-шаблона при создании приложения. Вы также можете получить ту же ссылку, выбрав ссылку "Получить" в области управления выпусками приложения шаблона.
  • Имена параметров , как они определены в семантической модели приложения шаблона. Имена параметров — это строки, чувствительные к регистру, которые также можно получить на вкладке "Настройки параметров" при определении свойств приложения-шаблона или из параметров семантической модели в Power BI.

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

  Замечание

  Вы можете протестировать предварительно настроенное приложение установки в приложении-шаблоне, если приложение шаблона готово к установке, даже если оно еще недоступно в AppSource. Чтобы пользователи за пределами клиента могли использовать автоматическое приложение установки для установки приложения-шаблона, приложение-шаблон должно быть общедоступным в AppSource. Перед распространением приложения-шаблона с помощью создаваемого автоматического приложения установки обязательно опубликуйте его в Центре партнеров.

Основные шаги и API

Основные шаги по автоматизации настройки установки приложения-шаблона и необходимые API описаны в следующих разделах. Хотя большинство шагов выполняются с помощью REST API Power BI, примеры кода, описанные здесь, выполняются с помощью пакета SDK для .NET.

Шаг 1. Создание клиентского объекта Power BI

Использование REST API Power BI требует получения маркера доступа для служебного принципала из Microsoft Entra ID. Перед вызовами 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();
}

Шаг 4. Перемещение автоматизации в рабочую среду

Когда созданная вами автоматизация будет готова, не забудьте перенести ее в рабочую среду.

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

• Ознакомьтесь с нашим руководством, который использует простую функцию Azure для автоматизации настройки установки приложения-шаблона.
• Дополнительные вопросы? Попробуйте задать вопрос Сообществу Power BI.