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

Статья
09/05/2024

REST API Microsoft Fabric предоставляет конечную точку службы для операции CRUD элемента Fabric. Для Lakehouse доступны следующие действия:

Действие	Description
Создание	Создает lakehouse внутри рабочей области. Конечная точка аналитики SQL также подготавливается вместе с lakehouse.
Обновить	Обновляет имя lakehouse и конечную точку аналитики SQL.
Удаление	Удаляет lakehouse и связанную конечную точку аналитики SQL.
Получение свойств	Возвращает свойства lakehouse и конечной точки аналитики SQL.
Перечисление таблиц	Список таблиц в lakehouse.
Загрузка таблицы	Создает разностные таблицы из CSV-файлов и папок parquet.
Обслуживание таблиц	Применение bin-compaction, V-Order и удаление unreferenced и старых файлов.

Необходимые компоненты

Чтобы использовать REST API Fabric, сначала необходимо получить маркер Microsoft Entra для службы Fabric. Затем используйте этот маркер в заголовке авторизации вызова API.
REST API Microsoft Fabric определяет единую конечную точку для операций. Конечная точка имеет значение https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items. Заполнители и {lakehouseId} должны быть заменены {workspaceId} соответствующими значениями при выполнении команд, приведенных в этой статье.

Lakehouse CRUD

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

Запрос:

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 предоставляет возможности функции Load to Tables lakehouse. С помощью этого API можно загрузить CSV-файлы и файлы parquet в новые или существующие таблицы разностного озера в lakehouse.

Этот API является асинхронным, поэтому требуются три шага:

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

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

Загрузка запроса API таблиц

Параметр mode поддерживает overwrite и append операции. pathType параметр, указанный при загрузке отдельных файлов или всех файлов из указанной папки. Оба CSV и parquet поддерживаются в качестве параметра файла format .

Этот пример отправляет CSV-файл с именем demo.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 Идентификатор 32ad6d2a-82bb-420d-bb57-4620c8860373 операции — это идентификатор операции для запроса состояния выполнения загрузки в операции таблиц, как описано в следующем разделе.

Мониторинг операций загрузки в таблицы

После записи идентификатора операции из ответа на загрузку запроса API таблиц выполните следующий запрос:

Запрос:

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-Order к таблице, а также применяет Z-Order к tipAmount столбцу и выполняет 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"
        }
    }
}

Переменная Location содержит URI следующим образом: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b Идентификатор f2d65699-dd22-4889-980c-15226deb0e1b операции — это идентификатор операции для запроса состояния выполнения операций обслуживания таблицы, как описано в следующем разделе.

Мониторинг операций обслуживания таблиц

После записи operationId из ответа на загрузку запроса API таблиц выполните следующий запрос:

Запрос:

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 — задание выполняется
Завершено — задание завершено
Сбой — задание завершилось сбоем
Отменено — задание отменено
Дедупировано. Экземпляр того же типа задания уже запущен, и этот экземпляр задания пропускается

Поделиться через

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

Необходимые компоненты

Lakehouse CRUD

Создание озера данных

Обновление lakehouse

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

Удаление озера

Перечисление таблиц в Lakehouse

Загрузка в таблицы

Загрузка запроса API таблиц

Мониторинг операций загрузки в таблицы

Обслуживание таблиц

Запрос API обслуживания таблиц

Мониторинг операций обслуживания таблиц

Обратная связь

Дополнительные ресурсы

Поделиться через

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

Необходимые компоненты

Lakehouse CRUD

Создание озера данных

Обновление lakehouse

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

Удаление озера

Перечисление таблиц в Lakehouse

Пример разбиения на страницы

Загрузка в таблицы

Загрузка запроса API таблиц

Мониторинг операций загрузки в таблицы

Обслуживание таблиц

Запрос API обслуживания таблиц

Мониторинг операций обслуживания таблиц

Связанный контент

Обратная связь

Дополнительные ресурсы