Fabric の監視ハブの設定

Microsoft Fabric ワークロード開発キットの監視ハブは、一元化された監視センターです。 監視ハブは、Fabric ユーザーが項目のバックグラウンド ジョブを追跡できるように設計されています。 詳細については、「監視ハブを使用する」を参照してください。

バックエンド

このセクションでは、監視ハブのバックエンド実装を設定する方法について説明します。

項目マニフェストで JobScheduler プロパティを定義する

ジョブのサポートを有効にするには、アイテムがサポートするジョブの種類を指定する必要があります。 JobScheduler プロパティを項目マニフェスト ファイルに追加します。 JobScheduler プロパティにより、項目に対して Fabric で管理されるジョブが有効になります。

次の表に、サポートされている JobScheduler 定義プロパティの概要を示します。

プロパティ	説明	有効値
OnDemandJobDeduplicateOptions	オンデマンド アイテム ジョブの重複除去オプションを設定します。	- None: ジョブを重複除去しません。 - PerArtifact: 同じ項目とジョブの種類に対して実行されているアクティブなジョブが 1 つだけであることを確認します。 - PerUser: 同じユーザーと項目に対してアクティブなジョブが 1 つだけ実行されていることを確認します。
ScheduledJobDeduplicateOptions	オンデマンド アイテム ジョブの重複除去オプションを設定します。	- None: ジョブを重複除去しません。 - PerArtifact: 同じ項目とジョブの種類に対して実行されているアクティブなジョブが 1 つだけであることを確認します。 - PerUser: 同じユーザーと項目に対してアクティブなジョブが 1 つだけ実行されていることを確認します。
ItemJobTypes	指定したプロパティを持つジョブの種類の一覧。	- Name: 独立系ソフトウェア ベンダー (ISV) によって完全にカスタマイズ可能なジョブの種類の名前。

ジョブ ワークロード API を実装する

ジョブと統合するには、ワークロードは Swagger 仕様で定義されているジョブ API を実装する必要があります。

3 つの Fabric API がジョブに関連しています。

---

ジョブ インスタンスを開始する

エンドポイント: POST /workspaces/{workspaceId}/items/{itemType}/{itemId}/jobTypes/{jobType}/instances/{jobInstanceId}

この API はジョブの実行を開始するために呼び出されます。

• 応答: この API は、ジョブがシステムによって正常にスケジュールされたことを示す 202 Accepted 状態を返します。

---

ジョブ インスタンス状態を取得する

エンド ポイント: GET /workspaces/{workspaceId}/items/{itemType}/{itemId}/jobTypes/{jobType}/instances/{jobInstanceId}

Fabric では、ポーリング メカニズムを使用してジョブ インスタンスの状態を追跡します。 この API は、進行中のジョブ インスタンスの状態を確認するために 1 分ごとに呼び出されます。 ジョブが正常に完了したか失敗したかに関わらず完了するとポーリングは停止します。

• 応答: この API は、現在のジョブ インスタンスの状態とともに 200 OK 状態を返します。 応答には、ジョブの状態、開始時刻と終了時刻、エラーの詳細 (ジョブが失敗した場合) が含まれます。

  サポートされているジョブの状態:

  • NotStarted
  • InProgress
  • Completed
  • Failed
  • Cancelled

  重要: ジョブが失敗した場合でも、この API は 200 OK 状態と Failed ジョブ状態を返します。

---

ジョブ インスタンスをキャンセルする

エンド ポイント: POST /workspaces/{workspaceId}/items/{itemType}/{itemId}/jobTypes/{jobType}/instances/{jobInstanceId}/cancel

この API は、進行中のジョブ インスタンスをキャンセルするときに呼び出します。

• 応答: この API は、現在のジョブ インスタンスの状態とともに 200 OK 状態を返します。 応答には、ジョブの状態、開始時刻と終了時刻、エラーの詳細 (ジョブが失敗した場合) が含まれます。

---

詳細

ジョブ配信不能数:

ジョブが 2 時間以内に開始されない場合、Fabric プラットフォームによって "配信不能" とマークされます。

実装例

これらの API の実装例については、サンプル リポジトリの JobsControllerImpl.cs を参照してください。

フロントエンド

このセクションでは、監視ハブのフロントエンド実装を設定する方法について説明します。

Fabric UI でジョブを実行します

バックエンド上の項目にジョブを統合すると、ユーザーはジョブの実行を開始できます。

Fabric でジョブを実行するには、次の 2 つのオプションがあります。

• スケジュールされた無人ジョブ。 このオプションは、共有 Fabric スケジューラ エクスペリエンスを介して一定の間隔で実行するようにユーザーによって定義されます。
• ワークロード UI と拡張機能クライアント SDK を使用したオンデマンドによる実行。

UI でのFabric スケジューラ エクスペリエンス

• エントリ ポイントのオプション:

  • コンテキスト メニューのスケジュールを使用します。

    

  • workloadClient.itemSettings.open を使用します (選択した設定 ID が Schedule の場合)。

• レイアウト

  

  1. 最後に成功した更新時刻と、次回の更新時刻。
  2. [更新] ボタン。
  3. 項目スケジュールの設定。

オンボード

手順 1: スケジュール コンテキスト メニュー項目を追加する

項目のコンテキスト メニューに [スケジュール] ボタンを表示するため、項目フロントエンド マニフェストの contextMenuItems プロパティに新しいエントリを追加します。

{
    "name": "schedule"
}

ステップ 2: アイテムスケジュール設定を追加する

フロントエンド マニフェストの項目設定プロパティに新しい schedule エントリを追加します。

"schedule": {
    "itemJobType": "ScheduledJob",
    "refreshType": "Refresh"
}

• itemJobType: 項目ジョブ定義 XML ファイルで定義されている項目ジョブの種類。
• refreshType: [更新] ボタンの表示を指定します。 3 つのオプションから選択します。Refresh と Run を使用して更新ボタンと表示名を有効にするか、[更新] ボタンを無効にする None を設定します。

ジョブ Javascript API

ワークロードでは、スケジュールされた非アテンド型ジョブに加えて、ジョブをオンデマンドで実行したり、スケジュールされたジョブをオンデマンドで開始したりできます。 拡張機能クライアントの一部として、一連の API を利用できます。

• スケジュールされた ジョブ API:

  • getItemScheduledJobs(objectId: string): Promise<ItemSchedule>
  • createItemScheduledJobs(createItemScheduledJobs: CreateItemScheduleParams): Promise<ItemSchedule>
  • updateItemScheduledJobs(updateItemScheduleParams: UpdateItemScheduleParams): Promise<ItemSchedule>

• 特定のジョブ インスタンス API:

  • runItemJob(jobParams: RunItemJobParams): Promise<ItemJobInstance>
  • cancelItemJob(jobParams: CancelItemJobParams): Promise<CancelItemJobResult>
  • getItemJobHistory(getHistoryParams: GetItemJobHistoryParams): Promise<ItemJobHistory>

Note

getItemJobHistory は、現在 Fabric に格納されている状態のジョブを返します。 現在、Fabric はポーリングのみに依存しているため、状態が最新ではない可能性があることに注意してください。 できるだけ早く最も正確な状態を UI に反映させる必要がある場合は、バックエンドから直接状態を取得することをお勧めします。

監視ハブとの統合

データの準備ができたら、項目ジョブが監視ハブに自動的に表示されます。 次の手順では、フィルター ウィンドウに成果物の種類を追加して、ジョブに対してユーザーが実行できるアクションを構成して実装します。

監視ハブのフィルター ウィンドウでアイテムを有効にします。

項目をフィルター ウィンドウに追加するには、項目フロントエンド マニフェストで新しいプロパティを定義し、supportedInMonitoringHub を trueに設定します。

ジョブのクイック アクションとの統合

ユーザーは、取り消し、再試行、詳細の取得など、ジョブに対して一連の操作を実行できます。

ワークロード チームは、項目フロントエンド マニフェストで itemJobConfig プロパティを設定することで、有効にするプロパティを決定します。 設定されていない場合、アイコンは表示されません。

たとえば、すべてのジョブ アクションをサポートするサンプル項目に追加した構成は、このセクションの後半に表示されます。

ユーザーがサンプル項目ジョブの [キャンセル] アイコンを選択すると、指定されたアクション item.job.cancel が呼び出されます。 拡張機能 Fabric.WorkloadSample に対するジョブ関連のコンテキストは、ジョブを実際に取り消すためにワークロードによって実装されます。

また、Fabric プラットフォームは、ユーザーに結果を通知するために、このアクションからの応答を想定します。

"itemJobActionConfig": {
    "registeredActions": {
        "detail": {
            "extensionName": "Fabric.WorkloadSample",
                "action": "item.job.detail"
        },
        "cancel": {
            "extensionName": "Fabric.WorkloadSample",
                "action": "item.job.cancel"
        },
        "retry": {
            "extensionName": "Fabric.WorkloadSample",
                "action": "item.job.retry"
        }
    }
}

ジョブ詳細ウィンドウ

ワークロード チームが詳細情報に対するアクションを登録すると、Fabric は、その情報をサイド パネルに表示できるように、ワークロード アクションが特定の形式でデータを返すと想定します。

現在、プレーン テキストまたはハイパーリンクのキーと値のペアがサポートされています。

• ジョブ アクションの処理例については、サンプル リポジトリにある index.worker.ts を参照してください。 ファイルで、item.jobで始まるアクションを検索します。

最近の実行

Fabric は、監視ハブにジョブの状態を表示するだけでなく、共有ユーザー エクスペリエンスを提供して、特定の項目の最近の実行を表示します。

エントリ ポイント:

• コンテキスト メニュー>[最近の実行]

  

• workloadClient.itemRecentRuns.open を使用する。

オンボード

手順 1: recentRuns コンテキスト メニュー項目を追加する

項目メニューに [最近の実行] ボタンを表示するには、項目フロントエンド マニフェストの contextMenuItems プロパティに新しいエントリを追加します。

例:

{
    "name": "recentruns"
}

手順 2: 項目 recentRun 設定の追加

フロントエンド マニフェストのアーティファクト設定プロパティに新しく、recentRun エントリを追加します。

例:

"recentRun": {
     "useRecentRunsComponent": true,
}

サンプル アイテム リボンでのジョブ統合。

UI ワークロード サンプルの一部として、項目リボンにジョブ専用のセクションを追加しました。

このリボンの実装例については、サンプル リポジトリにある ItemTabToolbar.tsx を参照してください。

関連するコンテンツ

• 監視ハブを使用する