Расширение внешнего интерфейса Microsoft Fabric

Пакет средств разработки рабочей нагрузки Microsoft Fabric можно использовать для создания рабочих нагрузок и создания пользовательских возможностей, которые расширяют возможности Fabric. Платформа Fabric предназначена для взаимодействия с независимыми возможностями поставщика программного обеспечения (ISV). Например, редактор элементов можно использовать для создания собственного, согласованного пользовательского интерфейса, внедряя внешний интерфейс поставщика программного обеспечения в контексте элемента рабочей области Fabric.

В этой статье вы используете пример репозитория для разработки рабочей нагрузки Microsoft Fabric как руководство для интеграции настраиваемого веб-приложения рабочей нагрузки UX с Microsoft Fabric. Проекты и подробные примеры помогают легко интегрировать собственные компоненты и действия пользовательского интерфейса в среду выполнения Fabric для эффективного экспериментирования и настройки.

Пример фронтенда проекта рабочей нагрузки UX — это стандартное веб-приложение React, включающее клиентский SDK для рабочей нагрузки в виде стандартного пакета npm для обеспечения функциональности.

IsV размещает и запускает проект внутри изолированного <iframe> элемента на портале Fabric. Здесь представлены варианты интерфейса, специфичные для независимого поставщика программного обеспечения (ISV), включая редактор элементов.

Пакет SDK предоставляет все необходимые интерфейсы, API-интерфейсы и функции начальной загрузки, необходимые для преобразования обычного веб-приложения в микро интерфейсное веб-приложение, которое легко работает на портале Fabric.

Пакет SDK предоставляет пример проекта рабочей нагрузки пользовательского интерфейса. Пример:

Демонстрирует, как использовать большинство доступных вызовов пакета SDK.
Демонстрирует пример расширяемой ленты на основе Fluent UI, соответствующей внешнему виду и поведению Fabric.
Позволяет легко настраивать.
Позволяет отслеживать изменения в Fabric в режиме реального времени, когда включён режим разработчика Fabric.

Предварительные требования

Веб-приложение для UX-нагрузки

Этот пакет построен на основе пользовательского интерфейса Fluent и предназначен для React.
Манифест фронтенда рабочей нагрузки UX

Внешний манифест рабочей нагрузки пользовательского интерфейса — это ресурс JSON, который предоставляет поставщик программного обеспечения. Файл содержит важные сведения о рабочей нагрузке, включая URL-адрес веб-приложения рабочей нагрузки и различные сведения о пользовательском интерфейсе, такие как отображаемое имя элемента isV и связанные значки. IsV может использовать файл манифеста для настройки того, что происходит при взаимодействии пользователей с элементами на портале Fabric.

В этом пакете файлы манифеста внешнего интерфейса находятся в папке пакета. Файл манифеста содержит подробное описание манифеста рабочей нагрузки и его компонентов.

Включение функции разработки рабочей нагрузки в Fabric

Администратор арендатора сначала должен включить функцию разработки рабочей нагрузки в настройках арендаторов. Эту функцию можно включить для всей организации или для определенных групп в организации. Для администратора клиента, чтобы включить функцию разработки рабочей нагрузки для определенных групп, выполните действия, описанные в разделе "Включить параметр клиента разработки".

Снимок экрана переключателя клиента разработки рабочих нагрузок.

Настройка внешнего интерфейса

Чтобы настроить внешний интерфейс проекта, выполните следующие действия.

Убедитесь, что установлены Node.js и npm. Установка npm должна быть версии 9 или более поздней. В противном случае установите последние версии Node.js и npm.
Клонируйте пример репозитория для разработки рабочих нагрузок Microsoft Fabric.

В следующем списке описывается макет каталога пакетов, компоненты и ресурсы:
- Пакет: расположение пакета рабочей нагрузки. Пакет содержит ресурсы фронтенда, включая манифесты и статические файлы.
- src: код рабочей нагрузки, включающий следующие ресурсы:
  - index.ts: основной файл инициализации, включая bootstrap и index.workerindex.ui iFrames (см. сведения далее в этой статье).
  - App.tsx: этот файл направляет пути к страницам. Например, /sample-workload-editor направляется в функцию SampleWorkloadEditor в разделе components.
  - ресурсы: расположение изображений (.jpg, .jpeg и png), на которые можно ссылаться в манифесте и отображаться в пользовательском интерфейсе. Например, assets/github.jpg указан в манифесте как значок продукта.
  - компоненты: расположение кода пользовательского интерфейса, включая представление редактора и другие представления, которые использует пример (лента, страница проверки подлинности и панели).
  - контроллер: контроллер вызывает API пакета SDK.
  - модели: контракты и модели, которые используются пользовательским интерфейсом и для взаимодействия с серверной частью шаблона.
- средства. Элементы, которые можно использовать для создания параметров и конфигураций.
  - webpack.config.js. Используйте этот файл для настройки локального сервера Node.js.
  - Веб-конфигурация и обработчик манифестов.
- validation: В примере используется validateSchema.js для проверки схем JSON-файлов продукта и элемента. Она настроена для работы на npm start.
В папке репозитория перейдите в папку Frontend , чтобы установить файлы проекта:
```
<repository folder>\Frontend> npm install
```
Запустите сервер, выполнив следующую команду:
```
<repository folder>\Frontend> npm start
```
Эта команда запускает локальныйсервер Node.js (с помощью webpack), к которому microsoft Fabric подключается, когда он находится в режиме разработчика.

Сведения о портах, отображаемых после запуска сервера, см. в заметках о локальном сервере узла.

Текущий порт — 60006.

После запуска сервера localhost перейдите по URL-адресу 127.0.0.1:60006/manifests , чтобы открыть агрегированный манифест, созданный в папке Frontend/Package .

При изменении файлов в папке Frontend/Package запустите npm start еще раз.

Этот параметр сохраняется в текущем браузере.

Пример "Hello world"

Чтобы запустить сценарий тестирования hello world, выполните следующие действия.

Запустите локальный сервер (выполните действия, описанные в разделе "Начало работы с примерами внешних и внутренних рабочих нагрузок") и убедитесь, что режим разработчика включен.
В меню рабочей области выберите значок Создать концентратор (иногда этот значок находится под значком многоточия Показать больше).
Выберите Показать все.
В разделе " Пример рабочей нагрузки" выберите карточку "Пример элемента ", чтобы создать элемент.

Новый элемент выглядит примерно так:

Снимок экрана интерфейса основного примера пользовательского интерфейса.

Ознакомьтесь с различными элементами управления, чтобы просмотреть возможности API Fabric WorkloadClient (пакет SDK для рабочей нагрузки):

Открытие уведомлений и диалоговых окон
Переход на страницы
Получение параметров темы и рабочей нагрузки
Выполнение действий

Большинство доступных функций пакета SDK настраиваются как действия кнопки или регистрируются как обратные вызовы. Результаты обычно представляют собой уведомление или окно сообщения, показывающие, что API был вызван.

Например:

Выполнить действие вызывает API action.execute() для действия с именем sample.Action. Функциональные возможности действия — показать уведомление.
Нажмите кнопку "Сохранить " на ленте, чтобы вызвать API dialog.open(). API открывает диалоговое окно, в котором пользователь вводит имя и сохраняет элемент в Fabric. Дополнительные сведения о диалоговом окне см. в разделе CRUD.
На кнопке "Получить параметры темы" отображается список конфигураций темы Fabric (с помощью API theme.get().

Пример пользовательского интерфейса рабочей нагрузки размещается в изолированном iframe элементе Fabric, который отображается в режиме разработчика для веб-страницы.

Снимок экрана с изображением встраивания iFrame.

Примечание.

Элемент iframe в песочнице поддерживает атрибуты allow-same-origin и allow-scripts.

Дополнительные сведения о sandbox и атрибутах см. в документации MDN Web Docs.

Изучение кода

В следующих разделах описываются элементы кода и соответствующие рекомендации.

bootstrap()

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

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
    window.close();
}

Каждое приложение рабочей нагрузки Fabric должно поддерживать инициализацию в двух режимах:

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

В @ms-fabric/workload-client API есть метод bootstrap(), чтобы упростить инициализацию. Метод bootstrap() внутренне определяет, загружается ли текущее приложение в режиме пользовательского интерфейса или в рабочем режиме. Затем вызывается соответствующий метод инициализации (initializeUI или initializeWorker). После завершения bootstrap() инициализации уведомляет платформу микро-интерфейсного интерфейса Fabric об успешной инициализации или сбое.

bootstrap({
    initializeWorker: (params) =>
        import('./index.worker').then(({ initialize }) => initialize(params)),
    initializeUI: (params) =>
        import('./index.ui').then(({ initialize }) => initialize(params)),
});

index.worker

index.worker — основная onAction регистрация. Он обрабатывает события, отправляемые узлом Fabric, которые активируются выполняемыми действиями.

Действия могут быть отправлены рабочей нагрузкой в Fabric, а затем вызваны обратно в обработчике onAction, либо могут быть инициированы узлом Fabric. Например, при нажатии кнопки "Создать пример элемента" — только интерфейсная часть, Fabric активирует действие open.createSampleWorkloadFrontendOnly, а onAction обработчик инициирует открытие главной страницы пользовательского интерфейса рабочей нагрузки. Текущее значение рабочей области objectId также передается в интерфейс, работающий только на стороне фронтенда.

Последовательность показана в следующем примере кода:

   workloadClient.action.onAction((message) => {
        switch (message.action) {
            /**
             * This opens the frontend-only experience, so you can experiment with the UI without using CRUD operations.
             * You can still save the item if the backend is connected and registered.
             */
            case 'open.createSampleWorkloadFrontendOnly':
                const { workspaceObjectId: workspaceObjectId1 } = data as ItemCreateContext;
                return workloadClient.page.open({
                    workloadName: 'Org.WorkloadSample',
                    route: {
                        path: `/sample-workload-frontend-only/${workspaceObjectId1}`,
                    },
                });

                // . . . elided for brevity . . .
            default:
                throw new Error('Unknown action received');
        }
    });

index.ui

Функция initialize() отрисовывает React DOM, в который встроена функция App. Чтобы вызвать методы API, передайте дескриптор SDK workloadClient, который используется по всему коду.

Класс FluentProvider обеспечивает согласованность стиля в различных элементах управления FluentUI. Приведем пример:

ReactDOM.render(
      <FluentProvider theme={fabricLightTheme}>
           <App
               history={history}
               workloadClient={workloadClient}
           />
       </FluentProvider>,
       document.querySelector("#root")
   );

Процесс разработки

Функция App направляет код в SampleWorkloadEditor. Функция возвращает значение для React.JSX.Element.
Функция содержит структуру пользовательского интерфейса. Структура пользовательского интерфейса содержит элементы управления лентой и страницей, такие как кнопки и поля ввода.
Информация, собранная от пользователя, сохраняется с помощью хука React useState().
Обработчики элементов управления пользовательского интерфейса вызывают SampleWorkloadController функции и передают соответствующие переменные состояния.
Для поддержки операций CRUD состояние созданного или загруженного элемента хранится в artifactItem вместе с workspaceObjectId и примером реализации переменных полезной нагрузки.

В следующих примерах используется API notification.open():

Состояние:

   const [apiNotificationTitle, setNotificationTitle] = useState<string>('');
   const [apiNotificationMessage, setNotificationMessage] = useState<string>('');

Пользовательский интерфейс.

Эти примеры настраивают определенные элементы пользовательского интерфейса:

Название:

<Field label="Title" validationMessage={notificationValidationMessage} orientation="horizontal" className="field">
    <Input size="small" placeholder="Notification Title" onChange={e => setNotificationTitle(e.target.value)} />
  </Field>

Кнопка "Отправить":

<Button icon={<AlertOn24Regular />} appearance="primary" onClick={() => onCallNotification()} > Send Notification </Button>

Обработчик:

function onCallNotification() {
  ... elided for brevity
   callNotificationOpen(apiNotificationTitle, apiNotificationMessage, undefined, undefined, workloadClient, setNotificationId);
};

Контроллер:

  export async function callNotificationOpen(
    title: string,
    message: string,
    type: NotificationType = NotificationType.Success,
    duration: NotificationToastDuration = NotificationToastDuration.Medium,
    workloadClient: WorkloadClientAPI,
    setNotificationId?: Dispatch<SetStateAction<string>>) {

    const result = await workloadClient.notification.open({
        notificationType: type,
        title,
        duration,
        message
    });
    if (type == NotificationType.Success && setNotificationId) {
        setNotificationId(result?.notificationId);
    }
}

Операции CRUD

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

Руководство по реализации серверной части подробно описывает настройку и использование серверной части.

Когда серверная часть запущена и работает, а тип Org.WorkloadSample.SampleWorkloadItem зарегистрирован в Fabric, вы можете выполнять операции CRUD для этого типа.

Следующие операции доступны через ItemCrud API.

СОЗДАТЬ

Чтобы выполнить пример вызова create, используйте следующий пример, показывающий сохранение элемента рабочей нагрузки в первый раз:

 const params: CreateItemParams = {
        workspaceObjectId,
        payload: { itemType, displayName, description, workloadPayload: JSON.stringify(workloadPayload), payloadContentType: "InlineJson", }
    };
 const result: CreateItemResult = await workloadClient.ItemCrud.createItem(params);

Пример реализации сохраняет созданный элемент в artifactItem.

Элемент создается в выбранной рабочей области. Рабочая область должна быть назначена емкости, заданной в конфигурации серверной части. Дополнительные сведения см. в документации по серверной части.

Попытка создать элемент в не совместимой рабочей области завершается ошибкой:

Обратный вызов onCreateFabricItem в бэкенде блокирует вызов CREATE. Сбой в этой точке приводит к сбою операции, и элемент не создается в Fabric. Дополнительные сведения см. в документации по отладке и устранению неполадок серверной части.
В настоящее время сохраненный элемент не отображается в рабочей области автоматически. Чтобы просмотреть сохраненный элемент в рабочей области, обновите страницу.

GET

При выборе существующего элемента рабочей нагрузки в представлении рабочей области Структура переходит к маршруту, определенному в манифесте внешнего интерфейса вartifacts>editor>path:

"items": [
  {
   "name": "Org.WorkloadSample.SampleWorkloadItem",
   "editor": {
    "workload": "Org.WorkloadSample",
    "path": "/sample-workload-editor"
   },

При вызове itemCrud.getItemданные загружаются как из серверной части Fabric, так и серверной части рабочей нагрузки. Данные из обоих источников загружаются в artifactItem объект открытого графического интерфейса.

Снимок экрана: открытие существующих элементов в рабочей области.

ОБНОВЛЕНИЕ

Чтобы обновить существующий элемент, используйте itemCrud.updateItem. Полезная нагрузка рабочей нагрузки обновляется бэкендом рабочей нагрузки. В Fabric после обновления изменяется только lastModifiedTime элемента.

Удалить

Операцию можно вызвать либо delete в представлении рабочей области Fabric как общее действие, доступное для всех элементов, либо посредством явного вызова из рабочей нагрузки к itemCrud.deleteItem.

Оба типа вызовов обрабатываются через обратный вызов onDeleteItem бэкенда рабочей нагрузки.

Просмотр действия проверки подлинности

В редакторе образца рабочей нагрузки можно просмотреть действия аутентификации.

Перед использованием API проверки подлинности настройте приложение для проверки подлинности с помощью идентификатора Microsoft Entra.

Кроме того, убедитесь, что файл env.dev настроен правильно. Дополнительные сведения см. в разделе "Настройка локального манифеста рабочей нагрузки" и получение маркера для приложения.

Отладка

Чтобы просмотреть элементы iframe worker и пользовательского интерфейса, в браузере нажмите F12, чтобы открыть инструменты разработчика. Выберите вкладку Источники.

Снимок экрана: отладка файлов в Visual Studio Code.

Можно поместить точку останова в элементе iframe рабочей роли и просмотреть основной switch элемент входящего действия. Вы также можете отлаживать элемент iframe пользовательского интерфейса. Например, можно выполнить отладку кода внутри SampleWorkloadEditor.

Элементы управления пользовательским интерфейсом Fluent

В компонентах UX используются элементы управления Fluent UI, чтобы обеспечить визуальную согласованность с Fabric и упростить разработку. Пример проекта рабочей нагрузки содержит примеры использования наиболее распространенных элементов управления.

Дополнительные сведения см. в разделе "Пользовательский интерфейс Fluent".

Настройка внешнего манифеста

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

Для примера рабочей нагрузки манифест загружается в Fabric в режиме разработчика. Разделы манифеста, определения и примеры манифеста отображаются в файлах внешнего манифеста.

Изменения записей манифеста, параметров действий и обновлений визуальных ресурсов отображаются в режиме реального времени после обновления страницы.

Поддерживаемые API-интерфейсы клиентского пакета SDK

Поддерживаются следующие API:

notification.open
Скрыть уведомление
panel.open
panel.close
action.onAction
action.execute
navigation.navigate
navigation.onNavigate
navigation.onBeforeNavigateAway
navigation.onAfterNavigateAway
page.open
dialog.openDialog
dialog.openMessageBox
dialog.close
theme.get
theme.onChange
settings.get
settings.onChange
errorHandling.openErrorDialog
errorHandling.handleRequestFailure
itemCrud.createItem
itemCrud.getItem
itemCrud.updateItem
itemCrud.deleteItem
itemSchedule.runItemJob
расписаниеЭлемента.отменитьЗадачуЭлемента
Открыть недавние запуски

Дополнительные сведения см. в разделе @ms-fabric/workload-client package.

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

Были ли сведения на этой странице полезными?

Last updated on 2026-04-29