mlv-operations-cli

テレメトリ — 必須。 すべての api.fabric.microsoft.com 呼び出しには、 x-ms-fabric-skill: mlv-operations-cli（az rest の場合：--headers "x-ms-fabric-skill=mlv-operations-cli"）を含める必要があります。 すべての LRO ポーリング、fabric_lro、再試行も対象です。スニペットでは省略されていますが、必ず追加してください。

更新の確認 — セッションごとに 1 回（必須） セッション中にこのスキルを初めて使用するときは、先に check-updates スキルを実行してください。

• GitHub Copilot CLI / VS Code：check-updates スキルを呼び出します。
• Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルとリモートの package.json のバージョンを比較します。
• このセッション中にすでに確認済みの場合はスキップします。

重要な注意事項

1. ワークスペース名から詳細（ID を含む）を確認するには、すべてのワークスペースを一覧表示してから、JMESPath フィルタリングを使用します。
2. ワークスペース ID とレイクハウス名からレイクハウスの詳細（ID を含む）を確認するには、そのワークスペース内のすべてのレイクハウスを一覧表示してから、JMESPath フィルタリングを使用します。
3. MLV の検出に関する制約：現在、レイクハウス内の MLV を一覧表示するパブリック REST API はありません。スケジュールの CRUD／トリガー／ステータス確認には、ワークスペース ID とレイクハウス ID のみが必要です。リネージの一部を更新するには、まず MLV 実行定義を作成または再利用し、その mlvExecutionDefinitionId を executionData に渡します。

MLV 操作 — CLI スキル

用語の対応

Fabric には、3 つのマテリアライズドビューの概念があります。文脈に応じて区別してください。

ユーザーの文脈	ユーザーの表現	実際の意味	振り分け先
Spark / Lakehouse	「マテリアライズドビュー」	Materialized Lake View（MLV）	このスキル（mlv-operations-cli）
Spark / Lakehouse	「マテリアライズドレイクビュー」	MLV	このスキル
Spark / Lakehouse	「Spark マテリアライズドビュー」	MLV	このスキル
Spark / Lakehouse	「MV」または「MLV」	MLV	このスキル
Spark / Lakehouse	「CREATE MATERIALIZED LAKE VIEW」	MLV DDL（作成）	spark-authoring-cli
Spark / Lakehouse	「マテリアライズドビューをスケジュールする」	MLV のスケジュール設定	このスキル
Spark / Lakehouse	「ビューを更新する」	MLV のオンデマンド更新	このスキル
KQL / Eventhouse	「マテリアライズドビュー」	KQL マテリアライズドビュー	eventhouse-cli
SQL DW / Warehouse	「マテリアライズドビュー」	Fabric ではサポートされていません	非対応であることを説明

区別のルール：ユーザーがレイクハウス、ノートブック、Spark、Delta、または MLV に言及した場合は、Materialized Lake View（このスキル）です。KQL、Eventhouse、または Kusto に言及した場合は、KQL マテリアライズドビュー（別のスキル）です。Warehouse または SQL DW に言及した場合は、サポートされていないことを説明してください。

デフォルト：文脈が不明確な場合（レイクハウス、Spark、KQL、Warehouse への言及がない場合）は、先に「Lakehouse（Materialized Lake View）と Eventhouse（KQL Materialized View）のどちらを使用していますか？」とユーザーに確認してください。

Fabric REST API を使用して、MLV の更新スケジュール、実行定義、監視を管理します。このスキルは、スケジュール設定、一部更新の構成、監視操作を対象とするパブリック API のプレビュー対応を提供し、MLV 更新ワークフローの自動化を可能にします。

このスキルでできること

✅ 完全対応（14 個の REST API）

1. スケジュール管理（レイクハウスごと — デフォルトでは MLV 系列全体を更新します）

   • 更新スケジュールを作成（Cron 間隔、毎日、毎週、毎月）
   • レイクハウスのスケジュール一覧を取得
   • ID でスケジュールの詳細を取得
   • 既存のスケジュールを更新（頻度、有効状態を変更）
   • スケジュールを削除
   • executionData.mlvExecutionDefinitionId を指定して系列の一部を更新

2. ジョブ実行

   • オンデマンド更新を開始（即時実行）
   • フィルターを指定してジョブ実行履歴を一覧表示
   • ジョブのステータスと進行状況を取得
   • 実行中のジョブをキャンセル
   • executionData.mlvExecutionDefinitionId を指定してオンデマンドで系列の一部を更新

3. MLV 実行定義

   • 選択した MLV、選択した上流レイクハウス、更新モード、Spark 環境の再利用可能な実行定義を作成
   • 実行定義を一覧表示
   • 実行定義の詳細を取得
   • 実行定義にパッチを適用（部分更新。省略されたフィールドは既存の値を保持します）
   • 実行定義を削除。リンクされたスケジュールは API によって削除されます

4. 安全性と UX

   • スケジュールの作成や更新の開始前に、ユーザー参加型の確認を行います
   • 複雑な複数 MLV の操作について、段階的に計画します
   • 役立つ提案を添えて、エラーに繰り返し対処します
   • 実行前にスケジュールの影響をプレビューします

❌ 非対応（UI が必要 — REST API なし）

• MLV の検出：レイクハウス内の MLV を一覧表示できません（API は 404 を返します）
• ビジュアル系列の確認：ポータルの依存関係グラフを直接取得できません
• データ品質メトリクス：DQ メトリクスを取得できません（API は 404 を返します）
• スキーマの検証：スキーマが有効かどうかを確認できません（プロパティがありません）

回避策：ユーザーがレイクハウス ID と MLV テーブル名を明示的に指定します。検出タスクには Fabric Lakehouse UI を使用し、その後、選択した MLV 名と上流レイクハウスを MLV 実行定義に設定します。

目次

タスク	参照	備考
ルール — 最初に読み、常に従ってください	SKILL.md § Must	必ず読むこと — このスキルの6つのルール
Fabric でワークスペースとアイテムを検索する	COMMON-CLI.md § Finding Workspaces and Items in Fabric	必須 — まずリンクを読むこと［名前からワークスペース ID を検索する場合や、名前、アイテムの種類、ワークスペース ID からアイテム ID を検索する場合に必要］
Fabric のトポロジーと主要な概念	COMMON-CORE.md § Fabric Topology & Key Concepts
環境 URL	COMMON-CORE.md § Environment URLs
認証とトークンの取得	COMMON-CORE.md § Authentication & Token Acquisition	対象ユーザーが誤っていると 401 が発生します。認証に関する問題があれば、事前に読んでください
ジョブのスケジュール設定	COMMON-CLI.md § Job Scheduling	URL は /jobs/{jobType}/schedules です。endDateTime は必須です
ジョブの実行	COMMON-CLI.md § Job Execution
az rest による Fabric コントロールプレーン API	COMMON-CLI.md § Fabric Control-Plane API via az rest	必ず --resource https://api.fabric.microsoft.com を渡してください。指定しないと az rest は失敗します
ページネーションのパターン	COMMON-CLI.md § Pagination Pattern
注意点とトラブルシューティング（CLI 固有）	COMMON-CLI.md § Gotchas & Troubleshooting (CLI-Specific)	az rest の対象ユーザー、シェルのエスケープ、トークンの有効期限
クイックリファレンス：az rest テンプレート	COMMON-CLI.md § Quick Reference: az rest Template
MLV 公開 API リファレンス	MS Learn: Manage Fabric materialized lake views with public APIs	スケジュール、オンデマンド更新、ジョブインスタンス、MLV 実行定義に関する公式ドキュメント

評価モード：ユーザープロンプトに「I pre-approve」または「proceed without confirmation」が含まれている場合は、ヒューマン・イン・ザ・ループの確認を省略して、直接実行します。これにより、自動テストが可能になります。

必須事項

1. ヒューマン・イン・ザ・ループによる確認

操作を実行する前に、必ずプレビューを表示して確認を求めてください。

• スケジュールの作成：スケジュールの種類、間隔／時刻、レイクハウス ID、開始／終了時刻、全リネージュまたは実行定義のスコープを表示します
• 実行定義の作成：選択した MLV、選択した上流レイクハウス、更新モード、Spark 環境を表示します
• 更新のトリガー：レイクハウス ID と、全リネージュを更新するのか、名前付きの実行定義のサブセットを更新するのかを表示します
• スケジュールの削除：スケジュール ID を表示し、削除の確認を求めます
• 実行定義の削除：定義 ID を表示し、関連付けられたスケジュールも削除されることを警告します

確認オプション：

• Allow — この操作を1回実行します
• Decline — この操作をスキップします
• Allow in this thread — 現在の会話でのすべての操作を自動的に許可します

例：

I'm about to create a refresh schedule:

  Lakehouse ID: abc-123-def
  Type: Daily
  Time: 02:00 UTC
  Start: 2026-06-20
  End: 2027-06-20
  Scope: Full MLV lineage (default)

Proceed? [Allow / Decline / Allow in this thread]

2. REST API をドキュメントどおりに使用する

ベース URL：https://api.fabric.microsoft.com/v1

重要：スケジュール、オンデマンドトリガー、実行定義、履歴一覧の各エンドポイントは、ワークスペースとレイクハウスのスコープです。オンデマンドトリガーは、ステータスのポーリングとキャンセルに使用する、アイテムのスコープの Location URL を返します。スケジュールまたはオンデマンド実行では、デフォルトで MLV のリネージ全体が更新されます。選択した MLV または選択した上流のレイクハウスを更新するには、MLV 実行定義を作成し、その mlvExecutionDefinitionId を executionData に渡します。

スケジュールのエンドポイント：

• POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules — スケジュールを作成
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules — スケジュールを一覧表示
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — スケジュールを取得
• PATCH /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — スケジュールを更新
• DELETE /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id} — スケジュールを削除

ジョブインスタンスのエンドポイント：

• POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances — オンデマンド更新をトリガー（executionData は任意。ジョブ ID を含む 202 と Location ヘッダーを返す）
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances — ジョブ履歴を一覧表示
• GET /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId} — トリガーの Location からジョブのステータスを取得
• POST /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId}/cancel — 実行中のジョブをキャンセル

MLV 実行定義のエンドポイント：

• POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions — 選択したリネージの実行定義を作成
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions — 実行定義を一覧表示
• GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions/{mlvExecutionDefinitionId} — 実行定義を取得
• PATCH /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions/{mlvExecutionDefinitionId} — 実行定義を部分更新
• DELETE /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions/{mlvExecutionDefinitionId} — 実行定義と、リンクされたスケジュールを削除

ジョブタイプの不一致に注意：ジョブ履歴では、スケジュールされた MLV 実行が jobType: "MaterializedLakeViews" として表示される場合がありますが、公開されているジョブスケジューラーのパスでは refreshMaterializedLakeViews が使われます。履歴に表示された値を POST /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances?jobType=MaterializedLakeViews にコピーしないでください。このアイテムレベルの呼び出しは InvalidJobType を返します。

参照：MS Learn：MLV バックグラウンドジョブ

3. 認証

すべてのスケジュール操作（作成／更新／削除、トリガー、ステータス確認、キャンセル）は、ユーザー ID（az login）と サービスプリンシパル／マネージド ID の両方をサポートします。ワークスペースの共同作成者または管理者ロールが必要です。

4. Lakehouse のスケジュール制限と実行定義のスコープ

Preview REST scheduler は、Lakehouse スコープでの更新スケジュールをサポートしています。1 つの Lakehouse には最大 20 個のスケジュールを設定でき、MLV のリネージには有効な更新スケジュールを 1 つだけ設定できます。ユーザーが一部を対象とするスケジュールを求めている場合は、選択した MLV と上流の Lakehouse を含む MLV 実行定義を作成し、その mlvExecutionDefinitionId をスケジュールまたはオンデマンドの executionData で指定します。実行定義は更新のスコープを設定するものであり、スケジューラーの制限を回避するものではありません。

5. MLV の検出 — ユーザーから名前を提示してもらう必要があります

GET /materializedLakeViews は 404 を返します。あらかじめユーザーに Lakehouse ID とテーブル名を尋ねてください。

6. 実行履歴の診断ワークフロー

ユーザーから「更新が失敗した理由は何ですか？」または「実行履歴を表示してください」と尋ねられた場合は、次の手順に従ってください。

1. 最近の実行を一覧表示：GET /instances — ステータス、開始時刻と終了時刻を含むジョブインスタンスを返します
2. 実行の概要を表示：実行 ID、ステータス、開始時刻、終了時刻、期間を記載した表を表示します
3. 失敗した実行を選択：複数ある場合は、どれを調査するかユーザーに尋ねます
4. エラーコードを読み取る：失敗したインスタンスから failureReason.errorCode と failureReason.message を抽出します
5. 次の手順を提案：エラーコードに基づいて提案します。
   • MLV_SPARK_SESSION_REQUEST_SUBMISSION_FAILED → キャパシティの空き状況と Spark プールの構成を確認します
   • MLV_SELECTED_NOT_FOUND → MLV テーブルが削除または名前変更されているため、存在を確認します
   • その他の Spark エラー → OOM、データの偏り、シャッフルのスピルに関する診断のため、spark-operations-cli に引き継ぎます
6. ビューごとの詳細：API が返すのはリネージレベルのステータスのみです。ビューごとのステータス（個々の MLV のうち、どれが失敗したか）は UI の「最近の実行」ページで確認できます。ビューごとの詳細を確認するには、ユーザーをそのページに案内してください

実行ステータス（API の値）：NotStarted、InProgress、Completed、Failed、Cancelled、Deduped

注：実行履歴の保持期間には制限がある場合があります。古い実行が見つからない場合は、Lakehouse UI の「最近の実行」ページを確認してください。

推奨事項

• 定期的な更新には Lakehouse のスケジュールを使用 — 対話型のワークフローでは、ユーザーを Lakehouse → Materialized lake views → Manage → Schedules に案内してください。REST API は、プログラムによる自動化や CI/CD が必要な場合にのみ使用します。
• 時刻を正確に指定するには Daily/Weekly タイプを使用（例：「毎日午前 2 時」）
• Cron タイプと間隔の指定は 1 日に複数回実行する場合にのみ使用（例：「60 分ごと」）
• 段階的に計画する — 目的を確認し、スケジュールを提案してプレビューを表示し、承認後に実行します
• エラーに反復的に対処する — 失敗した場合は、何が起きたのかを説明し、実行可能な修正方法を提案します
• 各スケジュールでタイムゾーンを明示（localTimeZoneId）
• 拡張リネージを利用した Lakehouse 間のスケジュール設定 — MLV が複数の Lakehouse にまたがる場合は、下流の Lakehouse のリネージビューからスケジュールを設定します。拡張リネージでは、依存関係の順序に従って上流の依存関係が自動的に更新されます。各 Lakehouse に個別のスケジュールを設定するよりも、この方法を優先してください。

回避事項

• 実行定義なしでテーブルごとのスケジュール設定が可能だと主張すること — デフォルトではリネージ全体が対象です。選択したサブセットを対象にするには、保存済みの実行定義が必要です
• Cron 形式の文字列式（例：0 2 * * *） — API は Cron 文字列ではなく、構造化されたタイプを使用します
• オンデマンド更新で JSON レスポンスが返ると想定すること — Location ヘッダーのジョブ ID のみを伴う 202 が返されます
• エラーを通知せずに処理すること — エラーは必ず説明してください
• ノートブックやパイプラインからスケジュールを設定すること — MLV の定期更新には Lakehouse のスケジュールを使用します。SQL の REFRESH ... FULL は、1 回限りの手動トラブルシューティングにのみ使用します。

スケジュールのペイロード構造

スケジュールの作成（POST /schedules）

エンドポイント：POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules

{
  "enabled": true,
  "configuration": {
    "type": "Cron",
    "interval": 60,
    "startDateTime": "2026-06-20T00:00:00",
    "endDateTime": "2027-06-20T23:59:59",
    "localTimeZoneId": "UTC"
  }
}

サブセットのリネージスケジュール：実行定義に記録された MLV／上流のレイクハウスのみを更新する場合は、executionData を含めます。

{
  "enabled": true,
  "configuration": {
    "type": "Cron",
    "interval": 60,
    "startDateTime": "2026-06-20T00:00:00",
    "endDateTime": "2027-06-20T23:59:59",
    "localTimeZoneId": "UTC"
  },
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

主なフィールド：

• enabled：作成時にスケジュールを有効にするには true を指定します
• type："Cron"、"Daily"、"Weekly"、"Monthly" のいずれか
• interval：（Cron のみ）更新間隔（分単位。例：60 = 1 時間ごと、120 = 2 時間ごと）
• times：（Daily／Weekly／Monthly）"HH:MM" 形式の時刻の配列。例：["02:00"]
• weekdays：（Weekly のみ）例：["Monday", "Wednesday", "Friday"] — 曜日はパスカルケースで指定します
• recurrence：（Monthly のみ）繰り返し間隔。例：1（毎月）
• occurrence：（Monthly のみ）例：{"occurrenceType": "DayOfMonth", "dayOfMonth": 1}
• localTimeZoneId：Windows のタイムゾーン名 — "UTC"、"Central Standard Time"、"India Standard Time" など
• startDateTime：スケジュールが有効になる日時（ISO 8601 のローカル時刻。タイムゾーンは localTimeZoneId で指定します）
• endDateTime：必須 — スケジュールの有効期限
• executionData.mlvExecutionDefinitionId：省略可能。実行定義に記録された選択済みのリネージのみを更新します

Daily の例（「毎日午前 2 時」の場合に推奨）：

{ "enabled": true, "configuration": { "type": "Daily", "times": ["02:00"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

Weekly の例（平日の午前 6 時）：

{ "enabled": true, "configuration": { "type": "Weekly", "times": ["06:00"], "weekdays": ["Monday", "Friday"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

Monthly の例（毎月 1 日の午前 0 時）：

{ "enabled": true, "configuration": { "type": "Monthly", "recurrence": 1, "occurrence": {"occurrenceType": "DayOfMonth", "dayOfMonth": 1}, "times": ["00:00"], "startDateTime": "2026-06-20T00:00:00", "endDateTime": "2027-06-20T23:59:59", "localTimeZoneId": "UTC" } }

警告：Monthly では "days": [1, 15] を使用しないでください。これを使用すると 400 InvalidConfiguration が返されます。上記のように recurrence と occurrence を使用してください。

スケジュールの更新（PATCH /schedules/{id}）

エンドポイント：PATCH /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules/{id}

{
  "enabled": true,
  "configuration": {
    "type": "Cron",
    "interval": 120,
    "startDateTime": "2026-06-20T00:00:00",
    "endDateTime": "2027-06-20T23:59:59",
    "localTimeZoneId": "UTC"
  }
}

注記：更新 API では enabled と完全な configuration（部分的なパッチではなく全置換）の両方が必要です。常にすべてのフィールドを送信してください。

MLV 実行定義

ユーザーが特定の MLV の更新、選択した上流のレイクハウスの追加、Spark 環境の固定、またはデフォルトの全リネージ更新とは別の更新モードの選択を希望する場合は、実行定義を使用します。

MLV 実行定義の作成

エンドポイント：POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/mlvexecutiondefinitions

{
  "displayName": "Gold Chain - Sales",
  "description": "Nightly refresh for selected gold-layer MLVs",
  "settings": {
    "environment": {
      "referenceType": "ById",
      "itemId": "<environmentId>",
      "workspaceId": "<environmentWorkspaceId>"
    },
    "refreshMode": "Optimal"
  },
  "currentLakehouseExecutionContext": {
    "mode": "Selected",
    "selectedMlvs": [
      "dbo.gold_sales_summary",
      "dbo.gold_sales_daily"
    ]
  },
  "extendedLineageExecutionContext": {
    "mode": "All"
  }
}

実行コンテキストのモード：

• currentLakehouseExecutionContext.mode："All" または "Selected"。"Selected" の場合は、完全修飾名で selectedMlvs を指定します。
• extendedLineageExecutionContext.mode："All" または "Selected"。"Selected" の場合は、referenceType、itemId、workspaceId を含むオブジェクトを selectedLakehouses に指定します。
• settings.refreshMode："Optimal" または "Full"。
• settings.environment：省略可能。ID で指定する Spark 環境への参照です。

更新時の動作：PATCH /mlvexecutiondefinitions/{id} は部分更新です。指定したフィールドのみが変更され、省略したフィールドの既存の値は保持されます。これは、enabled と完全な configuration が必要なスケジュールの PATCH とは異なります。

削除時の動作：DELETE /mlvexecutiondefinitions/{id} を実行すると、その実行定義にリンクされたスケジュールも削除されます。削除する前に警告してください。

オンデマンド更新をトリガーする（POST /instances）

エンドポイント：POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances

リクエストボディ：全リネージ更新の場合は不要です。依存関係の順序に従って、MLV のリネージ全体を更新します。

一部更新のリクエストボディ：

{
  "executionData": {
    "mlvExecutionDefinitionId": "<mlvExecutionDefinitionId>"
  }
}

ジョブ履歴をトリガーの仕様として使用しないでください：最近の実行履歴に jobType: "MaterializedLakeViews" と表示されることがありますが、これは履歴／ステータスのラベルにすぎません。オンデマンド更新では、必ずこのレイクハウススコープのエンドポイントを呼び出してください。汎用アイテムジョブ API（POST /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances?jobType=MaterializedLakeViews）で履歴のラベルを再利用すると、既知の InvalidJobType エラーにより処理が進まなくなります。

トリガーのレスポンスには、アイテムスコープの Location URL（/items/{lakehouseId}/jobs/instances/{jobInstanceId}）が含まれます。ポーリングとキャンセルには、そのまま使用してください。レイクハウススコープの GET（/lakehouses/{lakehouseId}/jobs/instances/{jobInstanceId}）も代替手段として文書化されており、同じインスタンスを返しますが、現在、サービスは Location ヘッダーにその形式を返しません。

レスポンス：202 Accepted — ジョブインスタンス ID は Location レスポンスヘッダーに含まれます：

Location: https://api.fabric.microsoft.com/v1/workspaces/{wsId}/items/{lakehouseId}/jobs/instances/{jobInstanceId}
Retry-After: 60

ステータスをポーリングするには、Location ヘッダーの URL（またはそのレイクハウススコープの同等の URL）を使用します：

GET /workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{jobInstanceId}

ジョブインスタンスのステータス値：

ステータス	意味
NotStarted	ジョブはキューに入っていますが、まだ開始していません
InProgress	ジョブは実行中です
Completed	ジョブは正常に完了しました
Failed	ジョブは失敗しました（failureReason を確認してください）
Cancelled	ジョブはユーザーによってキャンセルされました
Deduped	別の更新がすでに進行中だったため、スキップされました

注：公開されている GET /lakehouses/{id}/jobs/refreshMaterializedLakeViews/instances が返すジョブインスタンスでは、MS Learn に従って jobType: "RefreshMaterializedLakeViews" が使用されます。一部のアイテムレベルの履歴画面では、実環境でのテスト時に jobType: "MaterializedLakeViews" が返されることがあります。古い履歴を調査するときはどちらの値でも絞り込めますが、オンデマンドのトリガー jobType として MaterializedLakeViews を使用しないでください。

ステータス表示の制限：ジョブインスタンスのステータスは Monitor ハブのステータスを反映するため、MLV の実行履歴 UI と異なる場合があります。たとえば、MLV の実行履歴で Skipped と表示されるステータスが、Monitor ハブ API では Cancelled/Canceled と表示されることがあります。

スケジュール設定（UI または API で追加できるオプション）：

• 最適な更新（デフォルト：オン）— Fabric が MLV ごとに増分更新か全体更新かを自動的に選択します
• 拡張リネージ — 1 つのスケジュールから、複数のレイクハウスにまたがるチェーンを依存関係の順序に従って更新します

ワークフローの例

ワークフロー 1：毎晩の更新をスケジュールする

ユーザーのプロンプト：「CustomerVoice レイクハウスの sales_monthly MLV が毎日午前 2 時に更新されるようにスケジュールしてください」

エージェントの手順：

1. GET /workspaces と JMESPath を使用して、「CustomerVoice」のワークスペース ID を検索します
2. GET /workspaces/{id}/lakehouses と JMESPath を使用して、レイクハウス ID を検索します
3. スコープを確認します：「デフォルトの全リネージスケジュールを設定しますか。それとも、sales_monthly のみを対象とする MLV 実行定義を作成しますか？」
4. ユーザーが一部スコープを選択した場合は、currentLakehouseExecutionContext.mode = "Selected" および selectedMlvs = ["dbo.sales_monthly"]（またはユーザーが指定した実際の完全修飾 MLV 名）を含む実行定義を作成し、その mlvExecutionDefinitionId をスケジュールの executionData に含めます。
5. プレビューを表示します：

   Creating schedule:
     Lakehouse: CustomerVoice (ID: xyz-456-ghi)
     Scope: Full lineage OR execution definition <id>
     Type: Daily, Time: 02:00 UTC
     Start: Now
     End: 1 year from now
   
   Proceed? [Allow / Decline]
   

6. 「許可する」が選択されたら、スケジュールのペイロードを POST し、スケジュール ID を返します
7. 報告します：「スケジュールを作成しました（ID：sched-789）。スコープ：全リネージ、または実行定義 。」

ワークフロー 2: 即時更新をトリガーする

ユーザープロンプト: 「lakehouse xyz-456-ghi の inventory_daily MLV を今すぐ更新して」

エージェントの手順:

1. lakehouse ID が有効であることを確認する (GET /lakehouses/{id})
2. スコープを明確にし、プレビューを表示する:

   Triggering on-demand refresh:
     Lakehouse ID: xyz-456-ghi
     Scope: Full lineage OR execution definition <id>
   
   Do you want the default full-lineage refresh, or only `inventory_daily` through an execution definition? Proceed? [Allow / Decline]
   

3. ユーザーがサブセットを選択した場合は、inventory_daily の実行定義を作成または再利用し、その ID を executionData で送信します。それ以外の場合は、ボディなしで POST /instances を実行します。Location ヘッダーからジョブ ID を取得します。
4. Location ヘッダーで返されたアイテムスコープの URL、またはそのドキュメント化された lakehouse スコープの同等 URL GET /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/instances/{jobId} を使用してポーリングし、進捗を表示します。
5. 報告: 「✅ 更新が 2 分 34 秒で完了しました」または「❌ 更新に失敗しました: [エラーメッセージ]」

ワークフロー 3: ユーザーが MLV ごとのスケジュール設定を求める (制限事項を説明する)

ユーザープロンプト: 「bronze_sales、silver_sales、gold_sales をそれぞれ午前 2 時、午前 3 時、午前 4 時に更新するようスケジュールして」

エージェントの手順:

1. 制限事項を説明する:

   These views are a dependency chain, so schedule them as one lineage refresh
   rather than at separate times. Lakehouse scheduling refreshes dependencies in
   the required order.
   
   Options:
     1. Single Daily schedule at 2 AM (refreshes all 3 in order)
     2. If the MLVs are independent, create separate execution definitions and
        schedules within the lakehouse's 20-schedule limit
     3. If they're in separate lakehouses, create one schedule per lakehouse
   
   Which would you prefer?
   

2. ユーザーがオプション 1 を選んだ場合: "times": ["02:00"] を指定して Daily スケジュールを 1 つ作成する
3. ユーザーがオプション 2 を選んだ場合: MLV が独立していることを確認し、実行定義とスケジュールを作成する
4. ユーザーがオプション 3 を選んだ場合: それぞれの lakehouse ID を確認し、スケジュールを作成する

ワークフロー 4: スケジュールの一覧表示と削除

ユーザープロンプト: 「自分のスケジュールを表示して、古くなっていれば削除して」

エージェントの手順:

1. ユーザーにワークスペースと lakehouse を尋ねる (スケジュールをグローバルに一覧表示することはできません)
2. GET /workspaces/{wsId}/lakehouses/{lhId}/jobs/refreshMaterializedLakeViews/schedules
3. レスポンスを解析し (通常はリネージごとに 1 つのスケジュール)、詳細を表示する:

   Active schedule on lakehouse 'CustomerVoice':
     - ID: sched-111 (created 2025-10-15, type: Daily, time: 02:00)
   
   Delete this schedule? [Allow / Decline]
   

4. 「許可」の場合: DELETE /schedules/{id} を実行し、確認する
5. 報告: 「✅ スケジュールを削除しました」

よくあるエラーと修正方法

エラー: 400 Bad Request — 無効な間隔

メッセージ: "The interval '0' is invalid. Interval must be between 1 and 5270400 (10 years in minutes)."

修正方法:

Interval must be a valid number of minutes between 1 and 5,270,400 (10 years).

Common intervals:
  60 = hourly
  1440 = daily (24 hours)
  10080 = weekly (7 days)

Would you like me to adjust the interval to a valid value?

エラー: 409 Conflict — スケジュールがすでに存在する

メッセージ: "A schedule already exists for this lakehouse"

修正方法:

A schedule is already active for this lakehouse. Options:
  1. Update existing schedule (change interval/time)
  2. Delete and recreate (replaces schedule)
  3. Leave as-is (no change)

Which would you prefer?

エラー: 404 Not Found — Lakehouse ID が無効

メッセージ: "Lakehouse 'wrong-id-123' not found in workspace 'abc-456'"

修正方法:

The lakehouse ID you provided doesn't exist. Let me list available lakehouses:

[Call GET /workspaces/{id}/lakehouses, show table]

Which lakehouse should I use?

エラー: 403 Forbidden — 権限が拒否された

メッセージ: "User does not have permission to create schedules in this workspace"

修正方法:

You need Workspace Contributor or Admin role to create schedules.

Current permissions: Viewer (read-only)
Required: Contributor or Admin

Contact your workspace admin to request elevated permissions.

ユーザー向けのヒント

1. Lakehouse ID を確認する

オプション A: REST API 経由

az rest --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses" \
  --method GET

レスポンスから自分の lakehouse の id を抽出します。

オプション B: Fabric UI 経由

1. Fabric ポータルで lakehouse を開く
2. 設定 (歯車アイコン) をクリックする
3. プロパティから「Lakehouse ID」をコピーする

2. 一般的なスケジュール構成

ニーズ	種類	主要フィールド
毎時	Cron	"interval": 60
毎日午前 2 時	Daily	"times": ["02:00"]
平日午前 6 時	Weekly	"times": ["06:00"], "weekdays": ["Monday","Friday"]
毎月 1 日	Monthly	"recurrence": 1, "occurrence": {"occurrenceType": "DayOfMonth", "dayOfMonth": 1}

3. ジョブ履歴を監視する

最近の更新ジョブを一覧表示します (COMMON-CLI.md § クイックリファレンス: az rest テンプレート に従って認証します):

# See COMMON-CLI.md for authentication setup
az rest --resource https://api.fabric.microsoft.com \
  --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/instances" \
  --method GET

Note: インスタンス一覧 API は OData クエリパラメーター ($top、$orderby、$filter) をサポートしていません。取得後にクライアント側で結果を並べ替えたりフィルター処理したりしてください。ページネーションには continuationToken を使用します。

4. タイムゾーンに関する考慮事項

デフォルト: スケジュールは、指定がない限り UTC を使用します。

ベストプラクティス: 混乱を避けるため、常にタイムゾーンを明示的に指定してください:

{
  "configuration": {
    "localTimeZoneId": "Central Standard Time"
  }
}

有効なタイムゾーン: Windows のタイムゾーン名 (例: "Central Standard Time"、"Pacific Standard Time"、"India Standard Time")。Windows Default Time Zones レジストリを使用してください。

関連するスキル

• spark-authoring-cli：Fabric ノートブックで MLV を作成します（作成側）
• check-updates：スキルパッケージが最新かどうかを確認します（セッションごとに 1 回実行）

制限事項と今後のロードマップ

現在の制限事項（2026-06-18 時点）

機能	状態	回避策
レイクハウス内の MLV を一覧表示する	❌ API が 404 を返します	ユーザーがテーブル名を手動で指定します
選択した MLV を更新する／系譜のサブセットを更新する	✅ MLV 実行定義を使用します	/mlvexecutiondefinitions を作成し、executionData.mlvExecutionDefinitionId を渡します
ビジュアル系譜グラフを取得する	❌ 公開グラフ API はありません	Fabric Lakehouse UI を使用します
データ品質メトリクスを確認する	❌ API が 404 を返します	Fabric Lakehouse UI を使用します
スキーマのサポートを確認する	❌ プロパティがありません	MLV が機能する場合、スキーマが有効になっているとみなします

現在利用できる機能（公開 MLV API の対応範囲（プレビュー））

• ✅ スケジュールの作成／一覧表示／更新／削除（5 個の API）
• ✅ 更新ジョブのトリガー／監視／キャンセル（4 個の API）
• ✅ MLV 実行定義の作成／一覧表示／取得／更新／削除（5 個の API）
• ✅ executionData.mlvExecutionDefinitionId による全系譜または選択した系譜の更新
• ✅ 更新ワークフローの完全な自動化
• ✅ 安全性を確保するための人間参加型の確認
• ✅ 反復的なエラー処理

今後の予定（REST API のリリース時）

• MLV の検出：レイクハウス内の MLV を自動で一覧表示します
• ビジュアル系譜トレース：依存関係グラフを表示します
• データ品質：DQ メトリクスをプログラムから取得します
• スキーマの検証：enableSchemas プロパティを確認します

エージェントの設計は将来の互換性を考慮しています：API が利用可能になった際は、スケジュールのロジックを変更せずに検出機能を追加できます。

結論

このスキルは、公開 REST API を使用して、MLV の更新スケジュール、実行定義、監視を検証済みの方法で自動化します。現時点では、MLV の検出とビジュアル系譜の確認には引き続き UI による回避策が必要ですが、スケジュール設定、選択した系譜の実行定義、ジョブの実行はドキュメントに記載されたとおりに機能します。

設計方針（Databricks Data Engineering Agent に着想を得ています）：

• 安全性のための人間参加型の確認
• 複雑なタスクに対する段階的な計画
• 役立つ提案を伴う反復的なエラー処理
• 制限事項を明示（推測に基づく回避策は提示しません）

次のステップ：このスキルを使用して、MLV 更新ワークフローを自動化します。検出 API がリリースされた際には、スキルを拡張して、レイクハウス ID とテーブル名の手動入力を不要にします。