使用 REST API 管理 Microsoft Fabric 中的湖屋

Microsoft Fabric Rest API 为 Fabric 项的 CRUD 操作提供服务终结点。 以下操作可用于 Lakehouse：

操作	说明
创建​​	在工作区中创建湖屋。 SQL 分析终结点也随湖屋一起预配。
更新	更新湖屋和 SQL 分析终结点的名称。
删除	删除湖屋和关联的 SQL 分析终结点。
获取属性	获取湖屋和 SQL 分析终结点的属性。
列出表	列出湖屋中的表。
表加载	通过 CSV 和 parquet 文件和文件夹创建 delta 表。
表维护	应用 bin-compaction、V-Order 和未引用旧文件移除操作。

先决条件

• 若要使用 Fabric REST API，首先需要 获取 Fabric 服务的 Microsoft Entra 令牌。 然后在 API 调用的授权标头中使用令牌。

• Microsoft Fabric Rest API 定义了用于操作的统一终结点。 终结点为 https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items。 发出本文中所示的命令时，占位符 {workspaceId} 和 {lakehouseId} 应替换为相应的值。

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

创建湖屋

更新说明并重命名 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" 
} 

获取湖屋属性

请求：

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}

响应： 空

列出 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 提供“加载到表”湖屋功能。 使用此 API 时，可以将 CSV 和 parquet 文件加载到湖屋中新的或现有的 delta lake 表。

此 API 是异步的，因此需要三个步骤：

1. 使用 OneLake API 将文件和文件夹上传到 Lakehouse 的“文件”部分。
2. 将负载提交到表 API 请求。
3. 跟踪操作的状态，直到完成。

以下部分假定文件已上传。

加载到表 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 是用于查询运行加载到表操作的状态的操作 ID，如下一部分中所述。

监视加载到表操作

从加载到表 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 是异步的，因此需要执行两个步骤：

1. 提交表维护 API 请求。
2. 跟踪操作的状态，直到完成。

表维护 API 请求

此示例执行了一个表维护作业，它将 V-Order 应用于一个表，同时将 Z-Order 应用于 tipAmount 列，并执行保留期为 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 变量包含一个 URI，如下所示：https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b。 guid f2d65699-dd22-4889-980c-15226deb0e1b 是用于查询运行表维护操作的状态的操作 ID，如下一部分中所述。

监视表维护操作

从加载到表 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 - 作业正在进行
• Completed - 作业已完成
• Failed - 作业失败
• Canceled - 作业已取消
• Deduped - 同一作业类型的实例已在运行，此作业实例被跳过

相关内容

• 加载到表 Lakehouse 功能。
• 使用表维护功能管理 Fabric 中的 delta 表。
• Delta Lake 表优化和 V-Order。