Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Пакет средств разработки рабочей нагрузки 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. Эту функцию можно включить для всей организации или для определенных групп в организации. Для администратора клиента, чтобы включить функцию разработки рабочей нагрузки для определенных групп, выполните действия, описанные в разделе "Включить параметр клиента разработки".
Настройка внешнего интерфейса
Чтобы настроить внешний интерфейс проекта, выполните следующие действия.
Убедитесь, что установлены Node.js и npm. Установка npm должна быть версии 9 или более поздней. В противном случае установите последние версии Node.js и npm.
Клонируйте пример репозитория разработки рабочей нагрузки 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.
- модели: контракты и модели, используемые пользовательским интерфейсом, и для взаимодействия с серверной частью шаблонов.
- index.ts: основной файл инициализации, включая
- средства. Элементы, которые можно использовать для создания параметров и конфигураций.
- webpack.config.js. Используйте этот файл для настройки локального сервера Node.js.
- Веб-конфигурация и обработчик манифестов.
- проверка. Пример используется
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() с именем действия. Действие. Функциональные возможности действия — показать уведомление.
Нажмите кнопку "Сохранить " на ленте, чтобы вызвать API dialog.open(). API открывает диалоговое окно, в котором пользователь вводит имя и сохраняет элемент в Fabric. Дополнительные сведения о диалоговом окне см. в разделе CRUD.
На кнопке "Получить параметры темы" отображается список конфигураций темы Fabric (с помощью API theme.get().
Пример пользовательского интерфейса рабочей нагрузки размещается в изолированном iframe
элементе Fabric, который отображается в режиме разработчика для веб-страницы.
Примечание.
Изолированный 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
При выборе существующего элемента рабочей нагрузки в представлении рабочей области Структура переходит к маршруту, определенному в манифесте внешнего интерфейса вartifacts
path
>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, чтобы открыть средства разработчика браузера. Выберите вкладку Редактор.
Можно поместить точку останова в элементе 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.