Управление и выполнение записных книжек в Fabric с помощью API

REST API Microsoft Fabric предоставляет конечную точку службы для операций создания, чтения, обновления и удаления (CRUD) элемента Fabric. В этой статье описываются доступные интерфейсы REST API для блокнота и их использование.

С помощью API записных книжек инженеры и специалисты по обработке и анализу данных могут автоматизировать собственные конвейеры и удобно и эффективно устанавливать CI/CD. Эти API также позволяют пользователям легко управлять элементами записных книжек Fabric и интегрировать записные книжки с другими инструментами и системами. Блокноты можно координировать с помощью конвейеров Fabric и внешних планировщиков через эти API, это позволяет легко интегрироваться с автоматизированными рабочими процессами.

Эти действия по управлению элементами доступны для записных книжек:

Действие Описание
Создать элемент Создает блокнот в рабочей области.
Обновление элемента Обновляет метаданные записной книжки.
Обновление определения элемента Обновляет содержимое записной книжки.
Удаление элемента Удаляет записную книжку.
Get item (Получение элемента) Возвращает метаданные записной книжки.
Получение определения элемента Возвращает содержимое записной книжки.
Элемент списка Перечисление всех предметов в рабочем пространстве.

Дополнительные сведения см. в разделе "Элементы — REST API".

Для записных книжек доступны следующие действия планировщика заданий:

Действие Описание
Выполнение задания элемента по запросу Запустите ноутбук по запросу с поддержкой параметризации, конфигурации сеанса (например, параметров Spark или вычислений), выбора окружения и времени выполнения, а также выбора целевого хранилища Fabric Lakehouse.
Отмена задания экземпляра элемента Отменить выполнение задания для записной книжки.
Получение экземпляра задания элемента Узнайте состояние выполнения ноутбука и получите код завершения, возвращаемый выполнением.

Дополнительные сведения см. в разделе "Планировщик заданий".

Примечание.

Проверка подлинности субъекта-службы поддерживается как для REST API элементов (операции CRUD записной книжки), так и ДЛЯ API планировщика заданий (выполнение, мониторинг и отмена). Это обеспечивает безопасную автоматизацию без надзора и сценарии CI/CD. Добавьте сервисного принципала в рабочую область с соответствующей ролью (администратор, участник или член) для управления и выполнения блокнотов.

Выход из значений из записной книжки выполняется

Ноутбук запускается через API планировщика заданий и может возвращать код завершения, который можно использовать для условного управления процессами. Значение выхода отображается в exitValue поле полезных данных ответа " Получить экземпляр задания элемента ".

Блокнот может установить значение своего завершения, вызвав mssparkutils.notebook.exit("your-value") до завершения выполнения. Значение выхода представляет собой строку и может кодировать любой сигнал результата, например, "success""no_rows_processed"или результат, сериализованный в формате JSON.

Внешние оркестраторы, конвейеры Fabric и другие средства автоматизации могут вызывать Get Item Job Instance после завершения выполнения, чтобы считывать значение выхода и разветвиться в зависимости от результатов. Рассмотрим пример.

  1. Отправьте задание на выполнение элемента по запросу с параметрами и настройками выполнения.
  2. Опросите Экземпляр задания получения элемента до тех пор, пока status не станет равным Completed (или Failed).
  3. Прочитайте ответ exitValue, чтобы определить следующий шаг в рабочем процессе.

Этот шаблон позволяет выполнять условные оркестрации и сигналы для последующих этапов на основе результатов выполнения блокнота.

Полный пример

В следующем примере показано, как отправить выполнение записной книжки и получить его статус и код завершения. Полную схему тела запроса, включая параметры, конфигурацию сеанса и поля выбора Lakehouse, см. в справочнике API Планировщика заданий - Запуск задания по запросу.

** Шаг 1. Запустите выполнение

Используйте конечную точку задания 'Выполнить по требованию' для элемента, чтобы запустить блокнот:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

Ответ возвращается 202 Accepted с заголовком Location , содержащим URL-адрес экземпляра задания, используемого для мониторинга выполнения.

Шаг 2. Получение статуса выполнения и значения завершения

Используйте URL-адрес из заголовка Location, чтобы проверить состояние и прочитать значение завершения по завершении выполнения.

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

Пример ответа (сокращено):

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

Прочитайте exitValue, чтобы определить результат и соответствующим образом изменить логику автоматизации.

  • Last updated on