パブリック API を使用して環境を管理します

2025-03-31

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

重要

新しいリリースには、新しい API、API の非推奨、API 応答/要求コントラクトの変更が含まれています。次のセクションの表は、すべての API の変更をまとめたものです。
非推奨となる API は、2025 年 6 月 30 日までサポートを継続します。応答/要求コントラクトの変更は、リリースが開始されると直ちに有効になります。

環境 API の概要

カテゴリ	API	説明	注
アイテム操作	環境を作成する	ワークスペースに新しい空の環境を作成します。	変更なし
アイテム操作	定義を使用して環境を作成する	定義を使用して新しい環境を作成します。	新しい API
アイテム操作	環境を削除する	既存の環境を削除する	変更なし
アイテム操作	環境を一覧表示する	ワークスペース内の環境のリストを取得します。	変更なし
アイテム操作	環境を取得する	環境のメタデータを取得します。応答には、環境の状態が含まれます。	応答コントラクトの更新
アイテム操作	環境定義の取得	環境の定義を取得します。	新しい API
アイテム操作	環境を更新する	名前や説明など、環境のメタデータを更新します。	変更なし
アイテム操作	環境定義を更新する	環境の定義を更新します。	新しい API
アイテム操作	環境を公開する	現在保留中の変更で環境の発行をトリガーします。	応答コントラクトの更新
アイテム操作	環境の公開を取り消す	環境の継続的な公開を取り消す	変更なし
ステージング	ステージングライブラリを一覧表示する	ステージングライブラリの完全な一覧を取得します。この一覧には、公開済みライブラリと保留中のライブラリが含まれます。	応答コントラクトの更新
ステージング	外部ライブラリをインポートする	外部ライブラリをenvironment.yml ファイルとして環境にアップロードします。これは、環境内の既存の外部ライブラリの一覧をオーバーライドします。	新しい API
ステージング	外部ライブラリをエクスポートする	完全な外部ライブラリをenvironment.yml ファイルとして取得します。	新しい API
ステージング	外部ライブラリを削除する	環境から外部ライブラリを削除します。この API は、一度に 1 つのライブラリを受け入れます	新しい API
ステージング	カスタムライブラリをアップロードする	環境でカスタムパッケージをアップロードします。この API を使用すると、一度に 1 つのファイルをアップロードできます。サポートされているファイル形式は、.jar、.py、.whl、および.tar.gzです。	新しい API
ステージング	カスタムライブラリを削除する	環境からカスタムパッケージを削除します。カスタムパッケージの完全な名前と拡張機能を API 要求に配置して削除します。	新しい API
ステージング	ステージングライブラリをアップロードする	環境内に 1 つのカスタムライブラリまたは 1 つまたは複数のパブリックライブラリを追加します。	廃止予定
ステージング	ステージングライブラリを削除する	1 つのステージングカスタムライブラリまたはすべてのパブリックライブラリを削除します。	廃止予定
ステージング	Spark のステージング設定を一覧にする	完全なステージングコンピューティング構成を取得します。ステージング構成には、公開済みのコンピューティング構成と保留中のコンピューティング構成が含まれます。	応答コントラクトの更新
ステージング	Spark の設定を更新する	環境のコンピューティング構成と Spark プロパティを更新する	要求/応答コントラクトの更新
公開済み	発行済みライブラリを一覧表示する	Spark セッションで発行され、有効なライブラリを取得します。	応答コントラクトの更新
公開済み	発行済みの Spark 設定を一覧表示する	Spark セッションで発行され、有効な Spark コンピューティング構成と Spark プロパティを取得します。	応答コントラクトの更新
公開済み	外部ライブラリをエクスポートする	発行された外部ライブラリをenvironment.yml ファイルとして取得します。	新しい API

既存の環境パブリック API の詳細については、「項目 API - 環境」にアクセスしてください。

環境パブリック API 更新プログラムの詳細

このセクションでは、既存の API の今後の更新プログラムについて説明します。

環境を取得する

Get Environment API の応答では、'startTime' は 'startDateTime' になり、'endTime' は 'endDateTime' になります。発行操作の開始時刻/終了時刻を表します。

注釈

'startTime' と 'endTime' は Date-Time 形式を使用していますが、'startDateTime' と 'endDateTime' は UTC 時間の YYYY-MM-DDTHH:mm:ssZ 形式を使用する String です。

インターフェイス

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}

元のサンプル応答

{
  "displayName": "Environment_1",
  "description": "An Environment description",
  "type": "Environment",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715",
  "properties": {
    "publishDetails": {
      "state": "Success",
      "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
      "startTime": "2024-03-29T14:17:09.0697022Z",
      "endTime": "2024-03-29T14:48:09.0697022Z",
      "componentPublishInfo": {
        "sparkLibraries": {
          "state": "Success"
        },
        "sparkSettings": {
          "state": "Success"
        }
      }
    }
  }
}

新しいサンプル応答

{
  "displayName": "Environment_1",
  "description": "An Environment description",
  "type": "Environment",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715",
  "properties": {
    "publishDetails": {
      "state": "Success",
      "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
      "startDateTime": "2024-03-29T14:17:09Z",
      "endDateTime": "2024-03-29T14:48:09Z",
      "componentPublishInfo": {
        "sparkLibraries": {
          "state": "Success"
        },
        "sparkSettings": {
          "state": "Success"
        }
      }
    }
  }
}

環境を公開する

発行環境 API では、リリース以降の実行時間の長い操作がサポートされます。応答のコントラクトが変更されます。エンドポイントは、要求の送信でも同じままです。

インターフェイス

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/staging/publish

元のサンプル応答

{
  "publishDetails": {
    "state": "Running",
    "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
    "startTime": "2024-03-29T14:17:09.0697022Z",
    "componentPublishInfo": {
      "sparkLibraries": {
        "state": "Running"
      },
      "sparkSettings": {
        "state": "Running"
      }
    }
  }
}

新しいサンプル応答


Location: https://api.fabric.microsoft.com/v1/operations/abcdef00-9d7e-469a-abf1-fca847a0ea69
x-ms-operation-id: abcdef00-9d7e-469a-abf1-fca847a0ea69
Retry-After: 60

ステージングまたは発行済みライブラリを一覧表示する

これら 2 つの API は、環境のステージング/発行済みライブラリの完全な一覧を取得できます。エンドポイントは要求を送信しても変わりませんが、ライブラリは異なる構造で返されます。

インターフェイス

ステージングライブラリを取得する

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/staging/libraries

公開済みライブラリを取得する

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries

元のサンプル応答


{
  "customLibraries": {
    "wheelFiles": [
      "samplewheel-0.18.0-py2.py3-none-any.whl"
    ],
    "pyFiles": [
      "samplepython.py"
    ],
    "jarFiles": [
      "samplejar.jar"
    ],
    "rTarFiles": [
      "sampleR.tar.gz"
    ]
  },
  "environmentYml": "dependencies:\r\n- pip:\r\n  - matplotlib==3.4.3"
}

新しいサンプル応答

{
  "libraries": [
    {
      "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
      "libraryType": "Custom"
    },
    {
      "name": "samplepython.py",
      "libraryType": "Custom"
    },
    {
      "name": "samplejar.jar",
      "libraryType": "Custom"
    },
    {
      "name": "sampleR.tar.gz",
      "libraryType": "Custom"
    },
    {
      "name": "fuzzywuzzy",
      "libraryType": "External",
      "version": "0.0.1"
    },
    {
      "name": "matplotlib",
      "libraryType": "External",
      "version": "0.0.1"
    }
  ],
  "continuationToken": "null",
  "continuationUri": "null"
}

ステージング/発行済みのSpark設定を一覧として表示する

これら 2 つの API は、環境の Spark コンピューティング構成とプロパティを取得できます。エンドポイントは要求を送信しても変わりませんが、構成は異なる構造で返されます。 Spark プロパティがリストに変更されます。

インターフェイス

ステージング Spark の設定を取得する

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/staging/sparkcompute

発行済みの Spark 設定を取得する

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/sparkcompute

元のサンプル応答

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace",
    "id": "78942136-106c-4f3e-80fc-7ff4eae11603"
  },
  "driverCores": 4,
  "driverMemory": "56g",
  "executorCores": 4,
  "executorMemory": "56g",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": {
    "spark.acls.enable": "false"
  },
  "runtimeVersion": "1.2"
}

新しいサンプル応答

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace",
    "id": "78942136-106c-4f3e-80fc-7ff4eae11603"
  },
  "driverCores": "4",
      "driverMemory": "56G",
  "executorCores": "4",
  "executorMemory": "56G",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": [
    {
      "key": "spark.acls.enable",
      "value": "false"
    }
  ],
  "runtimeVersion": "1.2"
}

Spark の設定を更新する

この API は、環境の Spark コンピューティングとプロパティを更新するためのものであり、要求と応答の Spark プロパティのコントラクトは、リリースが到着すると更新されます。

元のサンプル要求

PATCH https://api.fabric.microsoft.com/v1/workspaces/f089354e-8366-4e18-aea3-4cb4a3a50b48/environments/707cfd07-cbf1-41da-aad7-dd157ddb8c11/staging/sparkcompute

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace"
  },
  "driverCores": 4,
  "driverMemory": "56g",
  "executorCores": 4,
  "executorMemory": "56g",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": {
    "spark.acls.enable": "false",
    "spark.admin.acls": null
  },
  "runtimeVersion": "1.2"
}

新しいサンプル要求

PATCH https://api.fabric.microsoft.com/v1/workspaces/f089354e-8366-4e18-aea3-4cb4a3a50b48/environments/707cfd07-cbf1-41da-aad7-dd157ddb8c11/staging/sparkcompute

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace"
  },
  "driverCores": "4",
  "driverMemory": "56G",
  "executorCores": "4",
  "executorMemory": "56G",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": [
    {
      "key": "spark.acls.enable",
      "value": "false"
    },
    {
      "key": "spark.admin.acls",
      "value": null
    }
  ],
  "runtimeVersion": "1.2"
}

元のサンプル応答

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace",
    "id": "78942136-106c-4f3e-80fc-7ff4eae11603"
  },
  "driverCores": 4,
  "driverMemory": "56g",
  "executorCores": 4,
  "executorMemory": "56g",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": {
    "spark.acls.enable": "false"
  },
  "runtimeVersion": "1.2"
}

新しいサンプル応答

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace",
    "id": "78942136-106c-4f3e-80fc-7ff4eae11603"
  },
  "driverCores": "4",
  "driverMemory": "56G",
  "executorCores": "4",
  "executorMemory": "56G",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": [
    {
      "key": "spark.acls.enable",
      "value": "false"
    }
  ],
  "runtimeVersion": "1.2"
}

環境パブリック API のユースケース

重要

このセクションでは、新しい API とコントラクトの変更は含まれません。

このセクションでは、現在使用可能な API を使用して特定の目標を達成する方法について説明します。次の例の {WORKSPACE_ID} と {ARTIFACT_ID} を適切な値に置き換えることができます。

新規環境の作成

次の API を使用して、新しい空の環境を作成できます。

サンプルリクエスト

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

{
    "displayName": "Environment_1",
    "description": "An environment description"
}

ステージングライブラリを管理する

アップロード/削除ステージングライブラリ API を使用して、環境内のライブラリセクションを管理できます

環境の公開済みライブラリを確認する

ライブラリを追加または削除する前に、公開済みライブラリ取得 API を使用して、現在有効なライブラリをチェックできます。

サンプルの依頼

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/libraries

サンプル応答

{
    "customLibraries": {
        "wheelFiles": [
            "samplewheel-0.18.0-py2.py3-none-any.whl"
        ],
        "pyFiles": [
            "samplepython.py"
        ],
        "jarFiles": [
            "samplejar.jar"
        ],
        "rTarFiles": [
            "sampleR.tar.gz"
        ]
    },
    "environmentYml": "dependencies:\r\n- pip:\r\n  - matplotlib==3.4.3"
}

ライブラリのアップロード

ステージングライブラリをアップロードするための API では、一度に 1 つのファイルを受け入れます。サポートされているファイルの種類は、パブリックライブラリの場合は .whl、.jar、.tar.gz、.py、environment.yml です。 multipart/form-data content-type を使用してファイルを指定できます。

注

パブリックライブラリをより効率的に操作するには、PyPI と conda から必要なすべてのライブラリを environment.yml ファイルに作成することを強くお勧めします。
アップロード API では、1 回の要求で最大 200 MB のファイルを使用できます。このサイズ制限を超えるライブラリは、現在、パブリック API ではサポートされていません。

サンプルの要求

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries

ライブラリの削除

タイプサフィックスを持つ完全なライブラリファイル名を指定することで、一度に 1 つのライブラリを削除できます。

注

削除するファイルとして environment.yml を指定すると、すべてのパブリックライブラリが削除されます。
既存のパブリックライブラリのサブセットを削除する場合は、代わりにアップロードライブラリを使用し、必要なライブラリのみを含む environment.yml をアップロードしてください。アップロードされた environment.yml は、既存のパブリックライブラリセクションを完全に置き換えます。

サンプルの要求

DELETE https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries?libraryToDelete=fuzzywuzzy-0.18.0-py2.py3-none-any.whl

Sparkコンピュートのステージングを管理する

更新ステージング Spark コンピューティングを使用して、Spark コンピューティングを管理できます。

発行された Spark コンピューティングの環境を確認する

環境の構成を変更する前に、発行済みの Spark コンピューティング API を使用して、現在有効な Spark コンピューティング構成をチェックできます。

サンプルリクエスト

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/sparkcompute

サンプル応答

{
    "instancePool": {
        "name": "Starter Pool",
        "type": "Workspace"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
        "enabled": false,
        "minExecutors": 1,
        "maxExecutors": 1
    },
    "sparkProperties": {
        "spark.acls.enable": "false"
    },
    "runtimeVersion": "1.2"
}

コンピューティング構成を更新する

この API の要求本文を編集することで、Spark ランタイムの更新、別のプールへの切り替え、コンピューティング構成の調整、Spark プロパティの追加/削除を行うことができます。

プール名とプールを指定することで、接続されているプールを切り替えることができます。プールを既定の設定に切り替えるには、プール名を Starter Pool として指定します。 REST API によるワークスペースの使用可能なカスタムプールの全リストを取得するには、「カスタムプール - ワークスペースカスタムプールのリスト」を参照してください。

既存の Spark プロパティを削除する場合は、次の例に示すように、削除するキーと同様に null として値を指定する必要があります。

要求のサンプル

PATCH https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/sparkcompute

{
    "instancePool": {
        "name": "Starter Pool",
        "type": "Workspace"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
        "enabled": false,
        "minExecutors": 1,
        "maxExecutors": 1
    },
    "sparkProperties": {
        "spark.acls.enable": null
    },
    "runtimeVersion": "1.2"
}

変更を有効にする

次の API セットを使用して変更を発行します。

公開を準備する

環境では、一度に 1 つの公開を受け入れます。環境を公開する前に、環境の状態を検証し、ステージングの変更の最終レビューを行うことができます。環境が正常に公開されると、ステージング状態のすべての構成が有効になります。

手順 1: 環境のメタデータを取得する
```
GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/
```
応答本文では、環境の状態を明確に示すことができます。次の手順に進む前に、進行中の発行がないことを確認してください。

手順 2: ステージングライブラリ/Spark コンピューティングを取得して最終的なレビューを行う

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/sparkcompute

環境の公開をトリガーする

ステージングライブラリと Spark コンピューティングに対して行った変更はキャッシュされますが、公開を有効にするには必要です。次の例に従って公開をトリガーします。

サンプルリクエスト

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/publish

サンプル応答

{
    "publishDetails":
    {
        "state": "Running",
        "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
        "startTime": "2024-03-29T14:17:09.0697022Z",
        "componentPublishInfo": {
            "sparkLibraries": {
                "state": "Running"
            },
            "sparkSettings": {
                "state": "Running"
            }
        }
    }
}

発行中に、次の API を呼び出して取り消すこともできます。

サンプル要求

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/cancelPublish

次の方法で共有

パブリック API を使用して環境を管理します

環境 API の概要

環境パブリック API 更新プログラムの詳細

環境を取得する

環境を公開する

ステージングまたは発行済みライブラリを一覧表示する

ステージング/発行済みのSpark設定を一覧として表示する

Spark の設定を更新する

環境パブリック API のユース ケース

新規環境の作成

ステージング ライブラリを管理する

環境の公開済みライブラリを確認する

ライブラリのアップロード

ライブラリの削除

Sparkコンピュートのステージングを管理する

発行された Spark コンピューティングの環境を確認する

コンピューティング構成を更新する

変更を有効にする

公開を準備する

環境の公開をトリガーする

関連するコンテンツ

フィードバック

その他のリソース

環境パブリック API のユースケース

ステージングライブラリを管理する