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

[アーティクル]
05/22/2024

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

重要

この機能はプレビュー中です。

利用可能な環境 API の概要

API	説明	カテゴリ
環境の作成	ワークスペースで新しい環境を作成します。	全般
環境を取得する	環境のメタデータを取得します。応答には、環境の状態が含まれます。	全般
環境を更新する	名前や説明など、環境のメタデータを更新します。	全般
環境を削除する	既存の環境を削除する	全般
ワークスペース内の環境をリストします。	ワークスペース内の環境のリストを取得します。	全般
環境を公開する	現在保留中の変更で環境の発行をトリガーします。	全般
公開を取り消す	環境の継続的な公開を取り消す	全般
公開済みの Spark コンピューティングを取得する	有効な Spark コンピューティング構成を取得します。	Spark コンピューティング
ステージング Spark コンピューティングを取得する	完全なステージングコンピューティング構成を取得します。ステージング構成には、公開済みのコンピューティング構成と保留中のコンピューティング構成が含まれます。	Spark コンピューティング
公開済みライブラリを取得する	有効なライブラリリストを取得します。	ライブラリ
ステージングライブラリを取得する	ステージングライブラリの完全な一覧を取得します。この一覧には、公開済みライブラリと保留中のライブラリが含まれます。	ライブラリ
ステージングライブラリをアップロードする	環境内に 1 つのカスタムライブラリまたは 1 つまたは複数のパブリックライブラリを追加します。	ライブラリ
ステージングライブラリを削除する	1 つのステージングカスタムライブラリまたはすべてのパブリックライブラリを削除します。	ライブラリ

Item 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 を使用してファイルを指定できます。

Note

パブリックライブラリをより効率的に操作するには、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 つのライブラリを削除できます。

Note

削除するファイルとして 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 を使用して環境を管理します

利用可能な環境 API の概要

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

新しい環境の作成

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

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

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

ライブラリの削除

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

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

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

変更を有効にする

公開を準備する

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

関連するコンテンツ

フィードバック

その他のリソース

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

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