REST API を使用して Microsoft Fabric のレイクハウスを管理する

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

Microsoft Fabric REST API は、Fabric 項目の CRUD 操作用のサービスエンドポイントを提供します。レイクハウスでは、次のアクションを使用できます。

アクション	説明
作成	ワークスペース内にレイクハウスを作成します。 SQL 分析エンドポイントも、レイクハウスと共にプロビジョニングされます。
更新プログラム	レイクハウスと SQL 分析エンドポイントの名前を更新します。
削除	レイクハウスと関連付けられている SQL 分析エンドポイントを削除します。
プロパティを取得する	レイクハウスと SQL 分析エンドポイントのプロパティを取得します。
テーブルを一覧表示する	レイクハウス内のテーブルを一覧表示します。
テーブルの読み込み	CSV ファイルと Parquet ファイル、およびフォルダーから Delta テーブルを作成します。
テーブルのメンテナンス	bin 圧縮、V オーダー、および参照されていないファイルと古いファイルの削除を適用します。

前提条件

Fabric REST API を使用するには、まず、Fabric サービス用の Microsoft Entra トークンを取得する必要があります。次に、API 呼び出しの Authorization ヘッダーでそのトークンを使用します。
Microsoft Fabric Rest API は、操作用の統合エンドポイントを定義します。エンドポイントが https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items です。プレースホルダー {workspaceId} と {lakehouseId} は、この記事で例示したコマンドを発行するときに適切な値に置き換える必要があります。

レイクハウス CRUD

ワークスペース内のレイクハウスの作成、変更、削除を実行するには、次の API を使用します。

レイクハウスを作成する

要求:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items 
{ 
    "displayName": "demo", 
    "type": "Lakehouse" 
}

応答:

{
    "id": "56c6dedf-2640-43cb-a412-84faad8ad648", 
    "type": "Lakehouse", 
    "displayName": "demo", 
    "description": "", 
    "workspaceId": "fc67689a-442e-4d14-b3f8-085076f2f92f" 
}

レイクハウスを更新する

説明を更新し、レイクハウスの名前を変更します。

要求:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/dc39f96a-47d7-4c2d-9358-740f50c0aa31 
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
}

応答:

{ 
    "id": "56c6dedf-2640-43cb-a412-84faad8ad648", 
    "type": "Lakehouse", 
    "displayName": "newname", 
    "description": "", 
    "workspaceId": "fc67689a-442e-4d14-b3f8-085076f2f92f" 
}

レイクハウスのプロパティを取得する

要求:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}

応答:

{ 
    "id": "daaa77c7-9ef4-41fc-ad3c-f192604424f5", 
    "type": "Lakehouse", 
    "displayName": "demo", 
    "description": "", 
    "workspaceId": "bee6c118-c2aa-4900-9311-51546433bbb8", 
    "properties": { 
        "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{lakehouseId}/Tables", 
        "oneLakeFilesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{lakehouseId}/Files", 
        "sqlEndpointProperties": { 
            "connectionString": "A1bC2dE3fH4iJ5kL6mN7oP8qR9-C2dE3fH4iJ5kL6mN7oP8qR9sT0uV-datawarehouse.pbidedicated.windows.net", 
            "id": "0dfbd45a-2c4b-4f91-920a-0bb367826479", 
            "provisioningStatus": "Success" 
        } 
    } 
}

レイクハウスを削除する

レイクハウスを削除すると、オブジェクトのメタデータとデータが削除されます。ショートカット参照は削除されますが、そのデータはターゲットに保持されます。

要求:

DELETE https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}

応答: 空白

レイクハウスのテーブルを一覧表示する

要求:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables

応答:

{ 
    "continuationToken": null, 
    "continuationUri": null, 
    "data": [ 
        { 
            "type": "Managed", 
            "name": "demo1", 
            "location": "abfss://c522396d-7ac8-435d-8d77-442c3ff21295@onelake.dfs.fabric.microsoft.com/{workspaceId}/Tables/demo1", 
            "format": "delta" 
        } 
    ] 
}

list tables API では、改ページ位置の設定がサポートされています。要求で、ページあたりの maxResults をパラメータとして指定すると、API は、結果の次のページを取得するために使用できる継続 URI を返します。

改ページ位置の自動修正の例

要求:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables?maxResults=1

応答:

{ 
    "continuationToken": "+RID:~HTsuAOseYicH-GcAAAAAAA==#RT:1#TRC:1#ISV:2#IEO:65567#QCF:8#FPC:AgKfAZ8BnwEEAAe8eoA=", 
    "continuationUri": "https://api.fabric.microsoft.com:443/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables?continuationToken=%2BRID%3A~HTsuAOseYicH-GcAAAAAAA%3D%3D%23RT%3A1%23TRC%3A1%23ISV%3A2%23IEO%3A65567%23QCF%3A8%23FPC%3AAgKfAZ8BnwEEAAe8eoA%3D", 
    "data": [ 
        { 
            "type": "Managed", 
            "name": "nyctaxismall", 
            "location": "abfss://bee6c118-c2aa-4900-9311-51546433bbb8@onelake.dfs.fabric.microsoft.com/daaa77c7-9ef4-41fc-ad3c-f192604424f5/Tables/nyctaxismall", 
            "format": "delta" 
        } 
    ] 
}

テーブルへの読み込み

この API は、テーブルへの読み込みレイクハウス機能を表面化します。この API を使用すると、CSV ファイルと Parquet ファイルをレイクハウス内の新規または既存の Delta Lake テーブルに読み込むことができます。

この API は非同期であるため、次の 3 つの手順が必要です。

OneLake API を使用して、ファイルとフォルダーをレイクハウスの [ファイル] セクションにアップロードします。
load to tables API 要求を送信します。
完了するまで操作の状態を追跡します。

次のセクションでは、ファイルが既にアップロードされていることを前提としています。

load to tables API 要求

mode パラメータは、overwrite と append の操作をサポートします。 pathType パラメータは、個々のファイルを読み込むのか、指定したフォルダーからまたはすべてのファイルを読み込むのかを指定します。 CSV と parquet の両方とも、ファイル format のパラメータとしてサポートされています。

次の使用例は、demo.csv という名前の付いたCSV ファイルを demo という名前の既存のテーブルにアップロードします。

要求:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables/demo/load 
{ 
    "relativePath": "Files/demo.csv", 
    "pathType": "File", 
    "mode": "overwrite", 
    "formatOptions": 
    { 
        "header": true, 
        "delimiter": ",", 
        "format": "CSV" 
    } 
}

応答ヘッダーには、非同期操作の状態をポーリングする URI が含まれています。 URI は、応答ヘッダーの Location 変数にあります。

Location 変数には、https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373のような URI が含まれています。 guid 32ad6d2a-82bb-420d-bb57-4620c8860373 は、次のセクションで説明するように、テーブルへの読み込み操作の実行中の状態を照会する操作 ID です。

テーブルへの読み込み操作の監視

load to tables API 要求への読み込みの応答から operationId をキャプチャした後、次の要求を実行します。

要求:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/{operationId}

応答:

{ 
    "Status": 3, 
    "CreatedTimeUtc": "", 
    "LastUpdatedTimeUtc": "", 
    "PercentComplete": 100, 
    "Error": null 
}

load to tables で使用できる操作の状態は次の通りです。

1 - 操作が開始されていません
2 - 実行中
3 - 成功
4 - 失敗

テーブルのメンテナンス

この API は、レイクハウスのテーブルのメンテナンス機能を表面化させます。この API を使用すると、bin 圧縮、V オーダー、および参照されていない古いファイルのクリーンアップを適用できます。

この API は非同期であるため、次の 2 つの手順が必要です。

table maintenance API 要求を送信します。
完了するまで操作の状態を追跡します。

table maintenance API 要求

次の使用例は、テーブルに V オーダーを適用するテーブルメンテナンスジョブを実行します。一方、tipAmount 列に Z オーダーを適用し、7 日 1 時間のリテンション期間で VACUUM 操作を実行します。

要求:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances?jobType=TableMaintenance
{
    "executionData": {
        "tableName": "{table_name}",
        "optimizeSettings": {
            "vOrder": true,
            "zOrderBy": [
                "tipAmount"
            ]
        },
        "vacuumSettings": {
            "retentionPeriod": "7.01:00:00"
        }
    }
}

応答ヘッダーには、非同期操作の状態をポーリングする URI が含まれています。 URI は、応答ヘッダーの Location 変数にあります。

Location 変数には、https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1bのような URI が含まれています。 guid f2d65699-dd22-4889-980c-15226deb0e1b は、次のセクションで説明するように、実行中のテーブルメンテナンス操作の状態を照会する操作 ID です。

テーブルのメンテナンス操作の監視

table maintenance API 要求への読み込みの応答から operationId をキャプチャした後、次の要求を実行します。

要求:

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

応答:

{
    "parameters": {
        "workspaceId": "{workspaceId}",
        "itemId": "{lakehouseId}",
        "jobInstanceId": "{operationId}"
    },
    "responses": {
        "200": {
            "body": {
                "id": "{operationId}",
                "itemId": "431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7",
                "jobType": "DefaultJob",
                "invokeType": "Manual",
                "status": "Completed",
                "rootActivityId": "8c2ee553-53a4-7edb-1042-0d8189a9e0ca",
                "startTimeUtc": "2023-04-22T06:35:00.7812154",
                "endTimeUtc": "2023-04-22T06:35:00.8033333",
                "failureReason": null
            }
        }
    }
}

table maintenance で使用できる操作の状態は次の通りです。

NotStarted - ジョブが開始されていません
InProgress - ジョブが進行中です
table maintenance - ジョブの完了
Failed - ジョブは失敗しました
Canceled - ジョブが取り消されました
Deduped - 同じジョブの種類のインスタンスが既に実行されており、このジョブインスタンスはスキップされます

テーブルへの読み込みレイクハウス機能。
テーブルメンテナンス機能を使用して、Fabric で Delta テーブルを管理する。
Delta Lake テーブルの最適化と V オーダー。

次の方法で共有

REST API を使用して Microsoft Fabric のレイクハウスを管理する

前提条件

レイクハウス CRUD

レイクハウスを作成する

レイクハウスを更新する

レイクハウスのプロパティを取得する

レイクハウスを削除する

レイクハウスのテーブルを一覧表示する

テーブルへの読み込み

load to tables API 要求

テーブルへの読み込み操作の監視

テーブルのメンテナンス

table maintenance API 要求

テーブルのメンテナンス操作の監視

フィードバック

その他のリソース

次の方法で共有

REST API を使用して Microsoft Fabric のレイクハウスを管理する

前提条件

レイクハウス CRUD

レイクハウスを作成する

レイクハウスを更新する

レイクハウスのプロパティを取得する

レイクハウスを削除する

レイクハウスのテーブルを一覧表示する

改ページ位置の自動修正の例

テーブルへの読み込み

load to tables API 要求

テーブルへの読み込み操作の監視

テーブルのメンテナンス

table maintenance API 要求

テーブルのメンテナンス操作の監視

関連するコンテンツ

フィードバック

その他のリソース