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

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

前提条件

• 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 を使用します。 詳細な API パラメーターと要求の例については、 Lakehouse REST 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/aaaabbbb-0000-cccc-1111-dddd2222eeee 
{ 
    "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 つの手順が必要です。

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

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

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/bbbbcccc-1111-dddd-2222-eeee3333ffffのような URI が含まれています。 guid bbbbcccc-1111-dddd-2222-eeee3333ffff は、次のセクションで説明するように、テーブルへの読み込み操作の実行中の状態を照会する操作 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-compaction、V-Order、および参照されていない古いファイルのクリーンアップ (バキューム) を適用できます。

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

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

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}",
        "schemaName": "{schema_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/ccccdddd-2222-eeee-3333-ffff4444aaaaのような URI が含まれています。 guid ccccdddd-2222-eeee-3333-ffff4444aaaa は、次のセクションで説明するように、実行中のテーブル メンテナンス操作の状態を照会する操作 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 オーダー。