Background Jobs - Run On Demand Table Maintenance

Служба:: Lakehouse

Версия API:: v1

Запустите экземпляр задания обслуживания таблицы по запросу.

Note

Этот API является частью предварительного выпуска и предоставляется только для оценки и разработки. Он может измениться на основе отзывов и не рекомендуется для использования в рабочей среде. URL-адрес этого API был обновлен, чтобы включить тип задания в рамках пути, заменив предыдущее использование параметра запроса. Для обратной совместимости вызовы с помощью параметра запроса по-прежнему поддерживаются.

Обязательные делегированные области

Lakehouse.Execute.All или Item.Execute.All

поддерживаемые удостоверения Microsoft Entra

Этот API поддерживает Microsoft identities, перечисленных в этом разделе.

Identity	Support
User	Yes
Представитель службы и управляемые удостоверения	Yes

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/tableMaintenance/instances

Параметры URI

Имя	В	Обязательно	Тип	Описание
lakehouseId	path	True	string (uuid)	Идентификатор элемента Lakehouse.
workspaceId	path	True	string (uuid)	Идентификатор рабочей области.

Текст запроса

Имя	Обязательно	Тип	Описание
executionData	True	TableMaintenanceExecutionData	Данные выполнения для настройки задания обслуживания таблицы .

Ответы

Имя Тип Описание

202 Accepted

Имя	Тип	Описание
202 Accepted		Запрос принят, выполнение задания выполняется. Заголовки: Расположение`string` — URL-адрес ресурса экземпляра задания. Повторная попытка после`integer` — Количество секунд, которые клиент должен ждать, прежде чем опрашивание состояния задания в первый раз. Клиенты должны использовать это значение, чтобы определить, когда проверять состояние задания и ждать по крайней мере это много секунд до первого опроса состояния.
429 Too Many Requests	ErrorResponse	Превышено ограничение скорости обслуживания. Сервер возвращает заголовок, указывающий `Retry-After` в секундах, сколько времени клиент должен ждать перед отправкой дополнительных запросов. Заголовки Retry-After: integer
Other Status Codes	ErrorResponse	Распространенные коды ошибок: MissingMinimalPermissions — вызывающий объект не имеет достаточных разрешений для запуска экземпляра задания. InvalidJobType — запрошенный тип задания недопустим. TooManyRequestsForJobs - вызывающий объект спам по большому числу выполняемых запросов заданий по запросу. ItemNotFound — запрошенный идентификатор элемента не найден.

Запрос принят, выполнение задания выполняется.

Заголовки:

Расположениеstring — URL-адрес ресурса экземпляра задания.

Повторная попытка послеinteger — Количество секунд, которые клиент должен ждать, прежде чем опрашивание состояния задания в первый раз. Клиенты должны использовать это значение, чтобы определить, когда проверять состояние задания и ждать по крайней мере это много секунд до первого опроса состояния.

429 Too Many Requests

ErrorResponse

Превышено ограничение скорости обслуживания. Сервер возвращает заголовок, указывающий Retry-After в секундах, сколько времени клиент должен ждать перед отправкой дополнительных запросов.

Заголовки

Retry-After: integer

Other Status Codes

ErrorResponse

Распространенные коды ошибок:

MissingMinimalPermissions — вызывающий объект не имеет достаточных разрешений для запуска экземпляра задания.
InvalidJobType — запрошенный тип задания недопустим.
TooManyRequestsForJobs - вызывающий объект спам по большому числу выполняемых запросов заданий по запросу.
ItemNotFound — запрошенный идентификатор элемента не найден.

Примеры

Run table maintenance with deletion vector purge enabled.

Run table maintenance with optimize enabled and vacuum disabled.

Run table maintenance with optimize Z-Order and vacuum enabled for schema enabled lakehouse.

Run table maintenance with optimize Z-Order and vacuum enabled.

Run table maintenance with deletion vector purge enabled.

Образец запроса

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/lakehouses/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/tableMaintenance/instances

{
  "executionData": {
    "tableName": "table1",
    "purgeDeletionVectors": true
  }
}

Пример ответа

Код состояния:: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

Run table maintenance with optimize enabled and vacuum disabled.

Образец запроса

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/lakehouses/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/tableMaintenance/instances

{
  "executionData": {
    "tableName": "table1",
    "optimizeSettings": {}
  }
}

Пример ответа

Код состояния:: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

Run table maintenance with optimize Z-Order and vacuum enabled for schema enabled lakehouse.

Образец запроса

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/lakehouses/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/tableMaintenance/instances

{
  "executionData": {
    "tableName": "table1",
    "schemaName": "dbo",
    "optimizeSettings": {
      "vOrder": true,
      "zOrderBy": [
        "tipAmount"
      ]
    },
    "vacuumSettings": {
      "retentionPeriod": "7:01:00:00"
    }
  }
}

Пример ответа

Код состояния:: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

Run table maintenance with optimize Z-Order and vacuum enabled.

Образец запроса

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/lakehouses/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/tableMaintenance/instances

{
  "executionData": {
    "tableName": "table1",
    "optimizeSettings": {
      "vOrder": true,
      "zOrderBy": [
        "tipAmount"
      ]
    },
    "vacuumSettings": {
      "retentionPeriod": "7:01:00:00"
    }
  }
}

Пример ответа

Код состояния:: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

Определения

Имя	Описание
ErrorRelatedResource	Объект сведений об ошибках, связанных с ресурсом.
ErrorResponse	Ответ на ошибку.
ErrorResponseDetails	Сведения об ответе на ошибку.
OptimizeSettings	Параметры оптимизации обслуживания таблиц.
RunOnDemandTableMaintenanceRequest	Запуск полезных данных для экземпляра обслуживания таблиц lakehouse по запросу
TableMaintenanceExecutionData	Запуск полезных данных для экземпляра обслуживания таблиц lakehouse по запросу
VacuumSettings	Параметры вакуума обслуживания таблиц.

ErrorRelatedResource

Объект

Объект сведений об ошибках, связанных с ресурсом.

Имя	Тип	Описание
resourceId	string	Идентификатор ресурса, участвующий в ошибке.
resourceType	string	Тип ресурса, который участвует в ошибке.

ErrorResponse

Объект

Ответ на ошибку.

Имя	Тип	Описание
errorCode	string	Определенный идентификатор, предоставляющий сведения об условии ошибки, что позволяет стандартизировать обмен данными между службой и ее пользователями.
isRetriable	boolean	Если задано значение true, запрос можно получить. `Retry-After` Используйте заголовок ответа, чтобы определить задержку, если она доступна.
message	string	Удобочитаемое представление ошибки.
moreDetails	ErrorResponseDetails[]	Список дополнительных сведений об ошибке.
relatedResource	ErrorRelatedResource	Сведения об ошибках, связанных с ресурсом.
requestId	string (uuid)	Идентификатор запроса, связанного с ошибкой.

ErrorResponseDetails

Объект

Сведения об ответе на ошибку.

Имя	Тип	Описание
errorCode	string	Определенный идентификатор, предоставляющий сведения об условии ошибки, что позволяет стандартизировать обмен данными между службой и ее пользователями.
message	string	Удобочитаемое представление ошибки.
relatedResource	ErrorRelatedResource	Сведения об ошибках, связанных с ресурсом.

OptimizeSettings

Объект

Параметры оптимизации обслуживания таблиц.

Имя	Тип	Описание
vOrder	boolean	Параметры V-Order . True — включено, false — отключено.
zOrderBy	string[]	Список имен столбцов в Z-Order по данным. Если это не указано, Z-Ordering не применяется.

RunOnDemandTableMaintenanceRequest

Объект

Запуск полезных данных для экземпляра обслуживания таблиц lakehouse по запросу

Имя	Тип	Описание
executionData	TableMaintenanceExecutionData	Данные выполнения для настройки задания обслуживания таблицы .

TableMaintenanceExecutionData

Объект

Запуск полезных данных для экземпляра обслуживания таблиц lakehouse по запросу

Имя	Тип	Описание
optimizeSettings	OptimizeSettings	Настраивает параметры оптимизации задания обслуживания. Чтобы пропустить оптимизацию таблицы, оставьте этот параметр пустым.
purgeDeletionVectors	boolean	Если значение true, выполняет REORG TABLE APPLY (PURGE) для перезаписи файлов с векторами удаления, физически удаляя удаленные строки.
schemaName	string pattern: ^(?=[0-9]*[a-zA-Z_])[a-zA-Z0-9_]{1,128}$	Имя схемы, в которой создается таблица. Это свойство применимо только для схемы, включенной Lakehouse. Максимальная длина буквенно-цифровой строки длиной 128 символов с символами подчеркивания.
tableName	string pattern: ^(?=[0-9]*[a-zA-Z_])[a-zA-Z0-9_]{1,256}$	Имя таблицы для запуска обслуживания. Максимальная длина буквенно-цифровой строки длиной 256 символов с символами подчеркивания.
vacuumSettings	VacuumSettings	Настраивает параметры вакуума задания обслуживания. Чтобы пропустить вакуум таблицы, оставьте этот параметр пустым.

VacuumSettings

Объект

Параметры вакуума обслуживания таблиц.

Имя	Тип	Описание
retentionPeriod	string pattern: ^(\d+:)?\d{1,2}:\d{1,2}:\d{1,2}$	Переопределяет период хранения по умолчанию. Неуправляемые файлы или файлы данных, связанные с версиями разностных таблиц старше указанного периода хранения, удаляются. Это значение должно соответствовать шаблону `d:hh:mm:ss` , где d — число дней, чх — это количество часов в диапазоне от 00 до 23, мм — это количество минут в диапазоне от 00 до 59, а число секунд от 00 до 59.