Microsoft Fabric フロントエンドを拡張する

[アーティクル]
12/03/2024

Microsoft Fabric ワークロード開発キットを使用すると、ワークロードを構築し、Fabric エクスペリエンスを拡張するカスタム機能を作成できます。 Fabric プラットフォームは、独立系ソフトウェアベンダー (ISV) の機能との、相互運用ができるように設計されています。たとえば、アイテムエディターを使用すると、ISV のフロントエンドを Fabric ワークスペースアイテムのコンテキストに埋め込むことで、ネイティブで一貫性のあるユーザーエクスペリエンスを作成できます。

この記事では、カスタムの　UX ワークロード Web アプリを Microsoft Fabric と統合するためのガイドとして、Microsoft Fabric ワークロード開発サンプルリポジトリを使用しています。このプロジェクトと詳細な例は、効率的な実験とカスタマイズのために、ユーザー独自の UI コンポーネントとアクションを Fabric ランタイム環境にシームレスに統合するのに役立ちます。

サンプルの UX ワークロードプロジェクトのフロントエンドは、標準の React Web アプリであり、機能を実現するために、ワークロードクライアント SDK を標準の npm パッケージとして組み込んでいます。

ISV は、Fabric ポータルにあるサンドボックスの <iframe> 要素内で、プロジェクトをホストし実行します。これが、項目エディターなどの ISV 固有の UI エクスペリエンスとして提示されます。

SDK では、通常の Web アプリを Fabric ポータル内でシームレスに動作する Micro Frontend Web アプリに変換するために必要な、すべてのインターフェイス、API、およびブートストラップ関数が提供されます。

この SDK には、サンプルの UX ワークロードプロジェクトが用意されています。サンプルでは次のことが行われます。

大部分の使用可能な SDK 呼び出の使用方法が例示されます。
Fabric の外観に適合した、 Fluent UI ベースの拡張可能なリボンの例をデモンストレーションします。
簡単なカスタマイズが可能です。
Fabric 開発者モードが有効になっている場合は、Fabric の変更をリアルタイムで確認できます。

前提条件

UX ワークロード Web アプリ

このパッケージは Fluent UI 上に構築されたもので、React 用に設計されています。
UX ワークロードフロントエンドマニフェスト

UX ワークロードフロントエンドマニフェストは、ISV が提供する JSON リソースです。このファイルには、ワークロード Web アプリの URL や、ISV アイテムの表示名と関連するアイコンなどの UI の各種詳細を含む、ワークロードに関する重要な情報が含まれています。 ISV では、マニフェストファイルを使用して、ユーザーが Fabric ポータルでアイテムを操作した際の応答をカスタマイズできます。

このパッケージでは、フロントエンドマニフェストファイルは package フォルダーの中に置かれています。マニフェストファイルには、ワークロードマニフェストとそのコンポーネントの詳細な説明が記述されています。

Fabric でワークロード開発機能を有効にする

テナント管理者は、最初に、Microsoft Fabric 管理ポータルでワークロード開発機能を有効にする必要があります。この機能は、組織全体または組織内の特定のグループに対して有効にすることができます。テナント管理者の場合、特定のグループのワークロード開発機能を有効にするには、「開発テナント設定を有効にする」で説明されている手順を実行します。

ワークロード開発のテナントスイッチのスクリーンショット。

フロントエンドを設定する

サンプルプロジェクトフロントエンドを設定するには、次を行います。:

Node.jsと npm がインストールされていることを確認します。 npm は、バージョン 9 以降をインストールする必要があります。それ以外の場合は、Node.jsと npm の最新バージョンをインストールします。
Microsoft Fabric ワークロード開発サンプルリポジトリをクローンします。

次の一覧で、パッケージディレクトリのレイアウト、コンポーネント、およびリソースについて説明しています。
- Package: ワークロードパッケージの場所です。パッケージには、マニフェストや資産を含むフロントエンドリソースが含まれます。
- src: 次のリソースを含むワークロードコードです。
  - index.ts: bootstrap と index.worker、および index.ui iFrame を含むメイン初期化ファイルです (この記事で後述する詳細を参照)。
  - App.tsx: このファイルは、パスを各ページにルーティングします。たとえば、 /sample-workload-editor は components の下にある SampleWorkloadEditor 関数にルーティングされます。
  - assets: マニフェストで参照され UI に表示できる画像 (.jpg、.jpeg、png) の場所です。たとえば、assets/github.jpg は、製品のアイコンとしてマニフェスト内で設定されています。
  - components: サンプルで使用される、エディタービューやその他のビュー (リボン、認証ページ、パネル) などの UI コードの場所です。
  - controller: コントローラーは、SDK API を呼び出します。
  - models: UI で使用される、定型バックエンドの通信用のコントラクトとモデルです。
- tools: 設定と構成の作成に使用できる要素です。
  - webpack.config.js: このファイルを使用して、ローカル Node.js サーバーを構成します。
  - Web 構成とマニフェストのリーダー/プロセッサです。
- validation: このサンプルでは、validateSchema.js を使用して製品とアイテムの JSON ファイルスキーマを検証します。これは、npm start 上で実行するように構成されています。
リポジトリフォルダー内で、 Frontend フォルダーに移動し、プロジェクトファイルをインストールします。
```
<repository folder>\Frontend> npm install
```
次のコマンドを実行してサーバーを起動します。
```
<repository folder>\Frontend> npm start
```
このコマンドは、開発者モードの Microsoft Fabric が接続する、ローカルの Node.js サーバーを (webpack を使用することで) 起動します。

サーバーの起動後に表示されるポートの詳細については、ローカルホストサーバーの注意事項を参照してください。

現在のポートは 60006 です。

localhost サーバーが起動したら、URL 127.0.0.1:60006/manifests に移動して、 Frontend/Package フォルダーに作成された集計マニフェストを開きます。

Frontend/Package フォルダー内のファイルを変更した場合は、npm start をもう一度実行します。

この設定は、現在のブラウザに保持されます。

"Hello World" の例

"hello world" テストシナリオを実行するには、次を行います。

ローカルサーバーを起動し (「使用を開始する」の手順に従って、フロントエンドとバックエンドの両方のワークロードサンプルを実行します)、開発者モードが有効になっていることを確認します。
ワークスペースメニューで、 [ハブの作成] アイコンを選択します (このアイコンは、[さらに表示] エリプス内に表示される場合があります)。
すべて表示を選択します。
[サンプルワークロード]で、[サンプルアイテム] カードを選択し、アイテムを作成します。

新しい項目は、次の例のようになります。

[メインサンプル UI イメージインターフェイス] のスクリーンショット。

さまざまなコントロールを探索して、Fabric WorkloadClient API (ワークロード SDK) の機能を確認します。

通知とダイアログを開く
ページに移動
テーマとワークロードの設定内容を取得する
アクションを実行する

提供される SDK 機能のほとんどは、ボタンアクションとして構成されているか、コールバックとして登録されています。結果は通常、API が呼び出されたことを示す通知またはメッセージボックスです。

次に例を示します。

アクションの実行により、sample.Action という名前のアクションを使用する、 action.execute() API が呼び出されます。このアクションの機能は、通知を表示することです。
リボンの [保存] を選択して、dialog.open() API を呼び出します。この API は、ユーザーが名前を入力し Fabric にアイテムを保存するための、ダイアログを開きます。ダイアログの詳細情報については、「CRUD」セクションを参照してください。
[テーマ設定の取得] ボタンにより、(theme.get() API を介して) Fabric のテーマ構成の一覧が表示されます。

サンプルワークロード UI は、Web ページの開発者モードで表示される Fabric サンドボックスのiframe 要素でホストされます。

iFrame 埋め込みイメージのスクリーンショット。

Note

サンドボックスにある iframe 要素は、属性 allow-same-origin と allow-scripts をサポートしています。

サンドボックスと属性の詳細については、「MDN Web Docs」を参照してください。

コードの理解

次のセクションでは、コード要素と関連する考慮事項について説明します。

bootstrap()

ブートストラップの前に、パスをチェックしてウィンドウを閉じる必要があるかをチェックします。この手順は、認証 API を使用する場合に必要となります。

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

すべての Fabric ワークロードアプリは、次の 2 つのモードで初期化をサポートする必要があります。

UI モード: UI モードのアプリは、可視的な iFrame の中で読み込まれます。これは、独自のルート変更をリッスンして、ページ、パネル、ダイアログなど対応する UI コンポーネントをレンダリングします。
ワーカーモード: ワーカーモードのアプリは、非可視的な iFrame 内で実行されます。非可視的な iFrame は、主に外部コマンドを受信し、それらに応答するために使用されます。

@ms-fabric/workload-client API は、初期化手順を簡略化する bootstrap() メソッドを提供します。 bootstrap() メソッドは、現在のアプリが UI モードとワーカーモードのどちらで読み込まれているかを内部的に検出します。その後、適切な初期化メソッド (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 ハンドラーがワークロードのメイン UI ページを開きます。また、現在のワークスペースの 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() 関数は、App 関数が埋め込まれている React DOM をレンダリングします。 API 呼び出しを行うため、コード全体で使用される workloadClient SDK ハンドルを渡します。

この FluentProvider クラスは、使用されているさまざまな FluentUI コントロール間でスタイルの一貫性を確保します。次に例を示します。

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

開発フロー

App 関数は、コードを SampleWorkloadEditor にルーティングします。この関数は、React.JSX.Element の値を返します。
この関数には UI 構造体が含まれています。 UI 構造体には、ボタンや入力フィールドなど、リボンとページのコントロールが含まれています。
ユーザーから収集された情報は、React useState() フックを介して保存されます。
UI コントロールのハンドラーは、SampleWorkloadController 関数を呼び出し、関連する状態変数を渡します。
CRUD 操作をサポートするために、作成あるいは読み込みが行われたアイテムの状態が、workspaceObjectId とペイロード変数のサンプル実装と共にartifactItem に保存されます。

次の例では、notification.open() API を使用しています。

都道府県:

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

UI:

次の例では、特定の UI 要素の構成を行います。

タイトル:

<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>

Handler:

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

ワークスペースビューで既存のサンプルワークロードのアイテムを選択すると、Fabric は、artifacts>editor>path でフロントエンドマニフェストに定義されているルートに移動します:

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

itemCrud.getItem を呼び出すと、Fabric バックエンドとワークロードバックエンドの両方からデータが読み込まれます。両方のソースからのデータは、開いている GUI の artifactItem オブジェクトに読み込まれます。

ワークスペース内の既存の項目を開くスクリーンショット。

UPDATE

既存のアイテムを更新するには、itemCrud.updateItem を使用します。ワークロードペイロードは、ワークロードバックエンドによって更新されます。 Fabric では、更新後にアイテムの lastModifiedTime のみが変更されます。

DELETE

delete 操作は、Fabric のワークスペースビューで (すべてのアイテム向けに提供されている一般的なアクションとして) 呼び出すか、ワークロードから itemCrud.deleteItem への明確な呼び出しを介して呼び出すことができます。

どちらの呼び出しも、ワークロードバックエンドの onDeleteItem コールバックを通過します。

認証アクティビティを表示する

サンプルワークロードエディターでは、認証アクティビティを表示することができます。

認証 API を使用する前に、アプリで、Microsoft Entra ID を使用した認証を行うように構成します。

また、env.dev ファイルが適切に構成されていることを確認します。詳細については、「ワークロードのローカルマニフェストを構成しアプリケーションのトークンを取得する」を参照してください。

デバッグ

ワーカーと UI の iFrame 要素を表示するには、ブラウザーで F12 を選択し、ブラウザー開発者ツールを開きます。 [ ソース ] タブを選択します。

Visual Studio Code でのファイルデバッグのスクリーンショット。

ワーカー iFrame にブレークポイントを配置し、着信アクションでの主な switch を確認できます。また、UI の iFrame 要素をデバッグすることもできます。たとえば、SampleWorkloadEditor 内のコードをデバッグできます。

Fluent UI コントロール

UX ワークロードでは、Fluent UI コントロールを使用して、Fabric との視覚的な一貫性と、開発のしやすさを実現しています。このサンプルワークロードプロジェクトでは、最も一般的なコントロールの使用例が提供されています。

詳細については、「Fluent UI」を参照してください。

フロントエンドマニフェストのカスタマイズ

フロントエンドマニフェストには、ワークロードのフロントエンド的な側面 (製品の外観、名前、ビジュアルアセット、使用可能なアクションなど) を記述します。フロントエンドマニフェストは、Fabric とワークロード間における主要な接点です。

このサンプルワークロードの場合、マニフェストは開発者モードの Fabric に読み込まれます。マニフェストのセクション、定義、および例は、フロントエンドマニフェストファイルの中に示されています。

マニフェストのエントリやアクション設定の変更、およびビジュアルアセットの更新の内容は、ページ更新後にリアルタイムで表示されます。

クライアント SDK でサポートされている API

次の 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 パッケージ」を参照してください。

次の方法で共有

Microsoft Fabric フロントエンドを拡張する

前提条件

Fabric でワークロード開発機能を有効にする

フロントエンドを設定する

"Hello World" の例

コードの理解

bootstrap()

index.worker

index.ui

開発フロー

CRUD 操作

作成

GET

UPDATE

DELETE

認証アクティビティを表示する

デバッグ

Fluent UI コントロール

フロントエンドマニフェストのカスタマイズ

クライアント SDK でサポートされている API

フィードバック

その他のリソース

次の方法で共有

Microsoft Fabric フロントエンドを拡張する

前提条件

Fabric でワークロード開発機能を有効にする

フロントエンドを設定する

"Hello World" の例

コードの理解

bootstrap()

index.worker

index.ui

開発フロー

CRUD 操作

作成

GET

UPDATE

DELETE

認証アクティビティを表示する

デバッグ

Fluent UI コントロール

フロントエンド マニフェストのカスタマイズ

クライアント SDK で サポートされている API

関連するコンテンツ

フィードバック

その他のリソース

フロントエンドマニフェストのカスタマイズ

クライアント SDK でサポートされている API