Поделиться через


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

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

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

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

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

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

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

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

Необходимые компоненты

  • Веб-приложение рабочей нагрузки пользовательского интерфейса

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

  • Манифест внешнего интерфейса рабочей нагрузки пользовательской нагрузки

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

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

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

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

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

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

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

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

  2. Клонируйте пример репозитория разработки рабочей нагрузки Microsoft Fabric.

    В следующем списке описывается макет каталога пакетов, компоненты и ресурсы:

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

    <repository folder>\Frontend> npm install
    
  4. Запустите сервер, выполнив следующую команду:

    <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, выполните следующие действия.

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

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

    Снимок экрана: значок

  3. Выберите Показать все.

    Снимок экрана: кнопка

  4. В разделе " Пример рабочей нагрузки" выберите карточку "Пример элемента ", чтобы создать элемент.

    Снимок экрана: карточка примера элемента.

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

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

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

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

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

Например:

  • Выполнение действия вызывает API action.execute() с именем действия. Действие. Функциональные возможности действия — показать уведомление.

  • Нажмите кнопку "Сохранить " на ленте, чтобы вызвать API dialog.open(). API открывает диалоговое окно, в котором пользователь вводит имя и сохраняет элемент в Fabric. Дополнительные сведения о диалоговом окне см. в разделе CRUD.

  • На кнопке "Получить параметры темы" отображается список конфигураций темы Fabric (с помощью API theme.get().

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

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

Примечание.

Изолированный iframe элемент поддерживает атрибуты allow-same-origin и allow-scripts.

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

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

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

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, передайте workloadClient дескриптор пакета SDK, который используется во всем коде.

Класс 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);
      };
      
  • Citrix:

      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 с этим типом.

Следующие операции предоставляются с помощью API ItemCrud.

CREATE

Чтобы выполнить пример вызова 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

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

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

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

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

UPDATE

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

DELETE

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

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

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

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

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

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

Отладка

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

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

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

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

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

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

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

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

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

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

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

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

  • notification.open
  • notification.hide
  • 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
  • itemSchedule.cancelItemJob
  • itemRecentRuns.open

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