API を使用して Fabric でノートブックを管理および実行する

Microsoft Fabric REST API は、Fabric 項目の作成、読み取り、更新、削除 (CRUD) 操作用のサービス エンドポイントを提供します。 この記事では、使用可能なノートブック REST API とそれらの使用方法について説明します。

データ エンジニアとデータ サイエンティストは、ノートブック API を使用して独自のパイプラインを自動化し、CI/CD を便利かつ効率的に確立できます。 また、ユーザーはこれらの API を使用して、Fabric ノートブック項目を簡単に管理および操作したり、ノートブックを他のツールやシステムと統合したりできます。 ノートブックは、これらの API を介して Fabric パイプラインと外部スケジューラから調整できるため、自動化されたワークフローとのシームレスな統合が可能になります。

ノートブックでは、次の項目管理アクションを使用できます。

アクション 説明
アイテムの作成 ワークスペース内でノートブックを作成する。
項目を更新する ノートブックのメタデータを更新する。
項目定義を更新する ノートブックの内容を更新する。
アイテムの削除 ノートブックを削除する。
項目を取得する ノートブックのメタデータを取得する。
項目定義を取得する ノートブックの内容を取得する。
リスト項目 ワークスペース内のすべての項目を一覧表示する。

詳細については、項目 - REST API に関するページを参照してください。

ノートブックでは、次のジョブ スケジューラ アクションを使用できます。

アクション 説明
オンデマンドでアイテムジョブを実行する パラメーター化、セッション構成 (Spark/コンピューティング設定など)、環境とランタイムの選択、およびターゲット Fabric Lakehouse の選択をサポートして、必要に応じてノートブックを実行します。
項目ジョブのインスタンスを取り消す ノートブック ジョブの実行をキャンセルします。
項目タスクのインスタンスを取得する ノートブックの実行状態を取得し、実行によって返される終了値を取得します。

詳細については、ジョブ スケジューラに関する記事を参照してください。

注意

サービス プリンシパル認証は、Items REST API (ノートブック CRUD 操作) とジョブ スケジューラ API (実行、監視、取り消し) の両方でサポートされています。 これにより、安全な無人自動化と CI/CD シナリオが可能になります。 ノートブックを管理および実行するための適切なロール (管理者、メンバー、または共同作成者) を持つサービス プリンシパルをワークスペースに追加します。

ノートブック実行の出力値

ジョブ スケジューラ API を使用して実行されるノートブックの実行は、条件付きオーケストレーションに使用できる終了値を返すことができます。 終了値は、exitValue 応答ペイロードの フィールドに表示されます。

ノートブックは、実行が完了する前に mssparkutils.notebook.exit("your-value") を呼び出すことによって、終了値を設定できます。 終了値は文字列であり、結果シグナル ( "success"、 "no_rows_processed"、JSON シリアル化された結果など) をエンコードできます。

外部オーケストレーター、ファブリック パイプライン、およびその他の自動化ツールは、実行が完了した後に Get Item Job Instance を 呼び出して終了値を読み取り、結果に分岐できます。 例えば次が挙げられます。

  1. パラメーターと実行設定を使用してオンデマンド実行するアイテムジョブを送信します。
  2. がstatus (またはCompleted) になるまで、Failedをポーリングします。
  3. 応答から exitValue 読み取り、ワークフローの次のステップを決定します。

このパターンにより、ノートブックの実行結果に基づく条件付きオーケストレーションとダウンストリームシグナル通知が可能になります。

エンド ツー エンドの例

次の例は、ノートブックの実行を送信し、その状態と終了値を取得する方法を示しています。 パラメーター、セッション構成、Lakehouse の選択フィールドなど、要求本文のスキーマ全体については、「 ジョブ スケジューラ - オンデマンド項目の実行ジョブ API リファレンス」を参照してください。

手順 1: 実行を送信する

オンデマンドアイテムジョブの実行エンドポイントを使用して、ノートブックの実行を開始します。

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

応答は、実行の監視に使用するジョブ インスタンスの URL を含む202 Accepted ヘッダーを含むLocationを返します。

手順 2: 実行状態と終了値を取得する

Location ヘッダーの URL を使用して状態を確認し、実行の完了後に終了値を読み取ります。

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances/{jobInstanceId}

応答の例 (省略形):

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

exitValueを読んで結果を判断し、それに応じて自動化ロジックを分岐させます。

  • Last updated on