使用 REST API 管理 Microsoft Fabric 中的 Lakehouse

發行項
10/15/2024

Microsoft Fabric Rest API 提供 Fabric 項目 CRUD 作業的服務端點。 Lakehouse 可執行的動作如下：

動作	描述
建立	在工作區內建立 Lakehouse。 SQL 分析端點也會隨著 Lakehouse 一起布建。
更新	更新 Lakehouse 和 SQL 分析端點的名稱。
刪除	刪除 Lakehouse 和相關聯的 SQL 分析端點。
取得屬性	取得 Lakehouse 和 SQL 分析端點的屬性。
列出資料表	列出 Lakehouse 中的資料表。
資料表載入	從 CSV 和 parquet 檔案和資料夾建立差異資料表。
資料表維修	套用 bin-compaction、V-Order 和移除未參考和舊檔案。

必要條件

若要使用網狀架構 REST API，您必須先取得 Fabric 服務的 Microsoft Entra 令牌。然後在 API 呼叫的授權標頭中使用該權杖。
Microsoft Fabric Rest API 會定義作業的統一端點。端點為 https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items。發出本文所示的命令時，佔位符 {workspaceId} 和 {lakehouseId} 應取代為適當的值。

Lakehouse CRUD

使用下列 API 在工作區內執行 lakehouse 的建立、修改和移除。

建立 Lakehouse

要求：

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" 
}

更新 Lakehouse

更新描述並重新命名 Lakehouse。

要求：

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" 
}

取得 Lakehouse 屬性

要求：

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" 
        } 
    } 
}

刪除 Lakehouse

當您刪除 Lakehouse 時，會刪除物件中繼資料和資料。會刪除捷徑參考，但資料會保留在目標端。

要求：

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

回應空白

列出 Lakehouse 中的資料表

要求：

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" 
        } 
    ] 
}

清單資料表 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 會顯示載入至資料表 Lakehouse 功能的功能。使用此 API 時，可以將 CSV 和 parquet 檔案載入 Lakehouse 中新的或現有的 Delta Lake 資料表。

此 API 是異步的，因此需要三個步驟：

使用 OneLake API 將檔案和資料夾上傳至 Lakehouse 的檔案區段。
將載入提交至資料表 API 要求。
追蹤作業的狀態，直到完成為止。

下列各節假設檔案已上傳。

載入資料表 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 變數包含 URI，如下所示：https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373。 guid 32ad6d2a-82bb-420d-bb57-4620c8860373 是用來查詢執行中載入資料表作業狀態的作業標識碼，如下一節所述。

監視資料表作業的負載

從載入至資料表 API 要求的回應擷取 operationId 之後，請執行下列要求：

要求：

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

回應：

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

載入資料表的可能作業狀態：

1 - 尚未啟動作業。
2 - 執行中
3 - 成功
4 - 失敗

資料表維修

此 API 會顯示 Lakehouse 資料表維護功能的功能。使用此 API 時，可以套用 bin-compaction、V-Order 和未參考的舊檔案清除。

此 API 是異步的，因此需要兩個步驟：

提交資料表維護 API 要求。
追蹤作業的狀態，直到完成為止。

資料表維護 API 要求

此範例會執行資料表維護作業，將 V 順序套用至資料表，同時將 Z-Order 套用至 tipAmount 資料行，並執行 VACUUM 保留期為 7 天和 1 小時的作業。

要求：

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 變數包含 URI，如下所示：https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b。 guid f2d65699-dd22-4889-980c-15226deb0e1b 是用來查詢執行中資料表維護作業狀態的作業標識符，如下一節所述。

監視資料表維護作業

從載入至資料表 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
            }
        }
    }
}

資料表維護的可能作業狀態：

NotStarted - 作業未啟動
InProgress - 作業正在進行中
已完成 - 作業已完成。
失敗 - 作業失敗
已取消 - 作業已取消
重複資料刪除 - 相同作業類型的執行個體已在執行中，並略過此工作執行個體

共用方式為

使用 REST API 管理 Microsoft Fabric 中的 Lakehouse

必要條件

Lakehouse CRUD

建立 Lakehouse

更新 Lakehouse

取得 Lakehouse 屬性

刪除 Lakehouse

列出 Lakehouse 中的資料表

載入至資料表

載入資料表 API 要求

監視資料表作業的負載

資料表維修

資料表維護 API 要求

監視資料表維護作業

意見反應

其他資源

共用方式為

使用 REST API 管理 Microsoft Fabric 中的 Lakehouse

必要條件

Lakehouse CRUD

建立 Lakehouse

更新 Lakehouse

取得 Lakehouse 屬性

刪除 Lakehouse

列出 Lakehouse 中的資料表

分頁範例

載入至資料表

載入資料表 API 要求

監視資料表作業的負載

資料表維修

資料表維護 API 要求

監視資料表維護作業

相關內容

意見反應

其他資源