Управление lakehouse в Microsoft Fabric с помощью REST API
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": "hkpobavgthae5kji5cuqxtivcu-dda6npvkyiaeteyrkfkgim53xa-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"
}
}
}
Заголовок ответа содержит URI для опроса состояния асинхронных операций. Универсальный код ресурса (URI) находится в переменной Location заголовка ответа.
Переменная 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 — задание выполняется
- Завершено — задание завершено
- Сбой — задание завершилось сбоем
- Отменено — задание отменено
- Дедупировано. Экземпляр того же типа задания уже запущен, и этот экземпляр задания пропускается
Связанный контент
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по