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

  • [アーティクル]

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

重要

この機能はプレビュー段階にあります。

Note

Notebook CURD API では、サービス プリンシパル認証 を使用できます。 現時点では、ノートブック API の実行はサポートされていません。

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

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

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

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

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

アクション 説明
オンデマンドの項目ジョブを実行する パラメーター化を使用してノートブックを実行する。
項目ジョブのインスタンスを取り消す ノートブック ジョブの実行を取り消す。
項目ジョブのインスタンスを取得する ノートブックの実行状態を取得する。

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

ノートブック REST API の使用例

次の手順を使用して、特定のノートブックのパブリック API の使用例をテストし、結果を確認します。

Note

これらのシナリオでは、ノートブック固有の使用例のみを取り上げます。 Fabric 項目の一般的な API の例は、ここでは取り上げません。

前提条件

Fabric REST API では、操作用の統合エンドポイントを定義します。 この記事の例に従う際は、プレースホルダーの {WORKSPACE_ID} と {ARTIFACT_ID} を適切な値に置き換えます。

定義を含むノートブックを作成する

既存の .ipynb ファイルを使用してノートブック項目を作成します。

Request

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items

{
    "displayName":"Notebook1",
    "type":"Notebook",
    "definition" : {
        "format": "ipynb",
        "parts": [
            {
                "path": "artifact.content.ipynb",
                "payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

要求のペイロードは、次のサンプル ノートブックから変換された base64 文字列です。

{
    "nbformat": 4,
    "nbformat_minor": 5,
    "cells": [
        {
            "cell_type": "code",
            "source": [
                "# Welcome to your new notebook\n# Type here in the cell editor to add code!\n"
            ],
            "execution_count": null,
            "outputs": [],
            "metadata": {}
        }
    ],
    "metadata": {
        "language_info": {
            "name": "python"
        },
        "dependencies": {
            "environment": {
                "environmentId": "6524967a-18dc-44ae-86d1-0ec903e7ca05",
                "workspaceId": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
            },
            "lakehouse": {
                "default_lakehouse": "5b7cb89a-81fa-4d8f-87c9-3c5b30083bee",
                "default_lakehouse_name": "lakehouse_name",
                "default_lakehouse_workspace_id": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
            }
        }
    }
}

Note

ノートブックのコンテンツ metadata.trident.lakehouse または metadata.trident.environment を変更すると、ノートブックの既定のレイクハウスまたはアタッチされた環境を変更できます。

定義を含むノートブックを取得する

ノートブックのコンテンツを取得するには、次の API を使用します。 Fabric では、クエリ文字列の形式を .ipynb として設定して、.ipynb ノートブックを取得できます。

Request

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items/{{ARTIFACT_ID}}/GetDefinition?format=ipynb

回答

状態コード:200

{
    "definition": {
        "parts": [
            {
                "path": "notebook-content.ipynb",
                "payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

ノートブックをオンデマンドで実行する

次の API を使用してノートブックの実行のスケジュールを設定します。 要求が成功すると、Spark ジョブの実行が開始されます。

Fabric では、要求本文の parameters を渡して、ノートブックの実行をパラメーター化できます。 これらの値は、ノートブック パラメーター セルで使用されます。

configuration を使用して、ノートブックの実行の Spark セッションをカスタマイズすることもできます。 configuration では、Spark セッションの構成マジック コマンドと同じコントラクトを共有します。

Request

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

{
    "executionData": {
        "parameters": {
            "parameterName": {
                "value": "new value",
                "type": "string"
            }
        },
        "configuration": {
            "conf": {
                "spark.conf1": "value"
            },
            "environment": {
                "id": "<environment_id>",
                "name": "<environment_name>"
            },
            "defaultLakehouse": {
                "name": "<lakehouse-name>",
                "id": "<lakehouse-id>",
                "workspaceId": "<(optional) workspace-id-that-contains-the-lakehouse>"
            },
            "useStarterPool": false,
            "useWorkspacePool": "<workspace-pool-name>"
        }
    }
}

回答

状態コード: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

location を使用すると、「項目ジョブのインスタンスを取得する」を使用してジョブの状態を表示したり、「項目ジョブのインスタンスを取り消す」を使用して現在のノートブックの実行を取り消したりできます。

関連するコンテンツ