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

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

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

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

• Запускает автоматизацию, которая собирает необходимые сведения.
• Предварительно настраивает параметры приложения-шаблона.
• Перенаправляет клиента в учетную запись 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 с субъектом-службой и секретом приложения. Обязательно зарегистрируйте приложение в качестве серверного веб-приложения . Вы регистрируете серверное веб-приложение для создания секрета приложения. В этом процессе необходимо сохранить идентификатор приложения (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 .

• Шаблонные приложения 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.