Управление lakehouse с помощью REST API

В этой статье рассматриваются типичные сценарии программного управления lakehouse с помощью REST API Microsoft Fabric. В каждом разделе показано HTTP-запрос и ответ для конкретной задачи, чтобы можно было адаптировать шаблон к скриптам автоматизации или приложениям.

Полные спецификации, включая все параметры, необходимые разрешения, схемы запросов и коды ошибок, см. в справочнике по REST API Lakehouse.

Предварительные требования

• Получите маркер Microsoft Entra для службы Fabric и включите его в Authorization заголовок каждого запроса.
• Замените {workspaceId} и {lakehouseId} в приведенных ниже примерах собственными значениями.

Создание, обновление и удаление озерохранилища

В следующих примерах показано, как создать новый lakehouse, переименовать его, получить его свойства (включая автоматически подготовленную конечную точку аналитики SQL) и удалить его. Полный список параметров и дополнительные примеры (например, создание озера с поддержкой схемы или создание с помощью определения) см. в справочнике по API Lakehouse Items.

Создание озера-хранилища

Чтобы создать lakehouse в рабочей области, отправьте запрос POST с отображаемым именем. Структура автоматически подготавливает конечную точку аналитики SQL вместе с lakehouse.

запрос

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses
{ 
    "displayName": "demo"
} 

Ответ

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

Обновите Lakehouse

Чтобы переименовать lakehouse или обновить его описание, отправьте запрос PATCH с новыми значениями.

запрос

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
} 

Ответ

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

Получение свойств Lakehouse

Извлеките метаданные Lakehouse, включая пути OneLake и строку подключения к конечной точке аналитики SQL.

запрос

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 удаляются как метаданные, так и данные. Ярлыки удаляются, но данные в целевом объекте ярлыка сохраняются.

запрос

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

Ответ

Текст ответа пуст.

Перечислите таблицы в "lakehouse"

Чтобы получить все таблицы Delta на lakehouse — например, для создания каталога данных или проверки развертывания — используйте конечную точку List Tables. Полный список параметров см. в справочнике по API таблиц.

запрос

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 в качестве параметра запроса для управления размером страницы. Ответ включает continuationUri, который можно вызвать для получения следующей страницы.

Постраничная навигация по большому списку данных в таблице

запрос

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

Загрузка файла в таблицу Delta

Чтобы преобразовать CSV-файлы или Parquet в разностные таблицы без написания кода Spark, используйте API загрузки таблиц. Это программный эквивалент функции load to Tables на домашней странице Lakehouse. Полный список параметров см. в справочнике по API загрузки таблиц.

Операция является асинхронной. Выполните следующие действия:

1. Отправьте файлы в раздел "Файлы lakehouse" с помощью API OneLake.
2. Отправьте запрос на загрузку.
3. Продолжайте опрашивать состояние операции до её завершения.

В следующих примерах предполагается, что файлы уже загружены.

Отправка запроса на загрузку

Этот пример загружает CSV-файл с именем demo.csv в таблицу с именем demo, перезаписав все существующие данные. Установите mode, чтобы Append добавления строк вместо этого. Установите pathType в Folder, чтобы загрузить все файлы из папки.

запрос

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

Ответ не включает тело. Вместо этого заголовок Location содержит универсальный код ресурса (URI), используемый для опроса состояния операции. Универсальный код ресурса (URI) следует этому шаблону:

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

Проверка состояния операции загрузки

Используйте operationId из заголовка Location, чтобы проверить прогресс:

запрос

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 — сбой

Запуск обслуживания таблицы в таблице Delta

Чтобы оптимизировать таблицы Delta — применяя bin-compaction, V-Order, Z-Order или VACUUM без использования Lakehouse Explorer, используйте API для обслуживания таблиц. Это программный эквивалент функции обслуживания таблиц. Полный список параметров см. в справочнике по API обслуживания таблиц.

Операция является асинхронной. Выполните следующие действия:

1. Отправьте запрос на обслуживание таблицы.
2. Продолжайте опрашивать состояние операции до её завершения.

Отправка запроса на обслуживание таблицы

В этом примере применяется оптимизация V-Order и Z-Order в столбце tipAmount, а также запускается VACUUM с периодом хранения данных в семь дней и один час.

запрос

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/TableMaintenance/instances
{
    "executionData": {
        "tableName": "{table_name}",
        "schemaName": "{schema_name}",
        "optimizeSettings": {
            "vOrder": true,
            "zOrderBy": [
                "tipAmount"
            ]
        },
        "vacuumSettings": {
            "retentionPeriod": "7:01:00:00"
        }
    }
}

Ответ не включает тело. Заголовок Location содержит URI, используемый для опроса состояния операции:

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

Конечная точка запуска ограничена рамками lakehouse, но для опроса экземпляра задания используется универсальная конечная точка задания (/items/{itemId}/jobs/instances/{jobInstanceId}) по замыслу.

Опрос состояния обслуживания таблицы

Используйте operationId из заголовка Location для проверки статуса работы.

запрос

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

Этот маршрут опроса намеренно использует items , а не lakehouses.

Ответ

{
    "id": "{operationId}",
    "itemId": "431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7",
    "jobType": "TableMaintenance",
    "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 Lakehouse
• Загрузка в таблицы
• Использование функции обслуживания таблиц для управления разностными таблицами в Fabric
• Оптимизация таблицы Delta Lake и V-Order
• Краткое руководство по REST API Fabric