Возможности REST API для конвейеров в Фабрике данных Fabric

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

Варианты использования API для конвейеров

API для конвейеров в Фабрике данных Fabric можно использовать в различных сценариях:

• Автоматическое развертывание: автоматизация развертывания конвейеров в разных средах (разработка, тестирование, производство) с помощью методик CI/CD.
• Мониторинг и оповещения. Настройка автоматизированных систем мониторинга и оповещений для отслеживания состояния конвейеров и получения уведомлений в случае сбоев или проблем с производительностью.
• Интеграция данных. Интеграция данных из нескольких источников, таких как базы данных, озера данных и облачные службы, в единый конвейер обработки и анализа.
• Обработка ошибок: Реализуйте пользовательские механизмы обработки ошибок и повторных попыток, чтобы конвейеры работали бесперебойно и восстанавливались после сбоев.

Общие сведения об API

Чтобы эффективно использовать API для конвейеров в Фабрике данных Fabric, важно понимать основные понятия и компоненты:

• Конечные точки: конечные точки API предоставляют доступ к различным операциям конвейера, таким как создание, обновление и удаление конвейеров.
• Проверка подлинности: безопасный доступ к API с помощью таких механизмов проверки подлинности, как OAuth или ключи API.
• Запросы и ответы. Понимание структуры запросов и ответов API, включая необходимые параметры и ожидаемые выходные данные.
• Ограничения скорости. Учитывайте ограничения скорости, введенные для использования API, чтобы избежать превышения допустимого количества запросов.

Поддержка CRUD

CRUD обозначает создание, чтение, обновление и удаление, которые являются четырьмя основными операциями, которые можно выполнять с данными. В Фабрике данных Fabric операции CRUD поддерживаются через API Fabric для фабрики данных. Эти API позволяют пользователям программно управлять конвейерами. Ниже приведены некоторые ключевые моменты поддержки CRUD:

• Создать: Создайте новые потоки данных с помощью API. Это включает определение структуры конвейера, указание источников данных, преобразований и назначений.
• Чтение: Получение сведений о существующих потоках данных. Сюда входят сведения о конфигурации, состоянии и журнале выполнения.
• Обновление: обновление существующих конвейеров. Это может включать изменение структуры конвейера, изменение источников данных или обновление логики преобразования.
• Удаление: удаление конвейеров, которые больше не нужны. Это помогает управлять ресурсами и очищать их.

Основную справочную документацию по REST API Microsoft Fabric можно найти в документации по REST API Microsoft Fabric.

Начало работы с REST API для конвейеров

В следующих примерах показано, как создавать, обновлять и управлять конвейерами с помощью API Фабрики данных Fabric.

Получение токена авторизации

Прежде чем использовать другие API REST, вам нужно получить токен доступа.

Вариант 1. Использование MSAL.Net

Обратитесь к разделу "Получение токена" в кратком руководстве API Fabric, чтобы ознакомиться с примером получения токена авторизации MSAL.

Используйте MSAL.Net для получения токена Microsoft Entra ID для службы Fabric с следующими допусками: Workspace.ReadWrite.All, Item.ReadWrite.All. Дополнительные сведения о получении токенов с помощью MSAL.Net см. в статье «Получение токенов» — библиотека аутентификации Microsoft для .NET.

Скопируйте токен из свойства AccessToken и замените <заполнитель токена доступа> в следующих примерах токеном.

Вариант 2. Использование портала Fabric

Войдите на портал Fabric для арендатора, которого вы хотите протестировать, и нажмите клавишу F12, чтобы перейти в режим разработчика браузера. В консоли выполните следующие действия:

powerBIAccessToken

Скопируйте токен и замените заполнитель <access-token> в следующих примерах токеном.

Создание конвейера

Создайте конвейер в указанной рабочей области.

Пример запроса:

URI: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items

Заголовки:

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

Наполнение:

{
  "displayName": "My pipeline",
  "description": "My pipeline description",
  "type": "DataPipeline"
}

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

{
    "id": "<itemId>",
    "type": "pipeline",
    "displayName": "My pipeline",
    "description": "My pipeline description",
    "workspaceId": "<workspaceId>"
}

Создание конвейера с определением

Создайте конвейер с определением base64 в указанной рабочей области.

Для полезных данных содержимое определения должно быть в кодировке Base64 в формате JSON, определяющем конвейер. Структура JSON должна соответствовать схеме определения конвейера, ожидаемой фабрикой данных Fabric.

Ниже приведен пример того, как может выглядеть описание конвейера JSON перед кодировкой:

{
  "name": "SamplePipeline",
  "properties": {
    "activities": [
      {
        "name": "Wait10Seconds",
        "type": "Wait",
        "typeProperties": {
          "waitTimeInSeconds": 10
        }
      }
    ]
  }
}

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

Пример запроса:

URI: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items

Заголовки:

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

Наполнение:

{
  "displayName": " My pipeline",
  "description": "My pipeline description",

  "type": "DataPipeline",
  "definition": { 
    "parts": [ 
      { 
        "path": "pipeline-content.json", 
        "payload": "<Your Base64 encoded JSON payload>"
        "payloadType": "InlineBase64" 
      } 
    ] 
  }
}

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

{
    "id": "<Your itemId>",
    "type": "pipeline",
    "displayName": "My pipeline",
    "description": "My pipeline description",
    "workspaceId": "<Your workspaceId>"
}

Получить конвейер

Возвращает свойства указанного конвейера.

Пример запроса:

URI: GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}

Заголовки:

{
  "Authorization": "Bearer <access-token>"
}

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

{
    "id": "<Your itemId>",
    "type": "pipeline",
    "displayName": "My pipeline",
    "description": "My pipeline description",
    "workspaceId": "<Your workspaceId>"
}

Получить поток с определением

Возвращает определение элемента конвейера.

Пример запроса:

URI: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/getDefinition

Заголовки:

{
  "Authorization": "Bearer <access-token>"
}

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

{
    "definition": {
        "parts": [
            {
                "path": "pipeline-content.json",
                "payload": "<Base64 encoded payload>"
                "payloadType": "InlineBase64"
            },
            {
                "path": ".platform",
                "payload": "<Base64 encoded payload>",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

Обновление конвейера

Обновляет свойства конвейера.

Пример запроса:

URI: PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}

Заголовки:

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

Наполнение:

{
  "displayName": "My pipeline updated",
  "description": "My pipeline description updated",
  "type": "DataPipeline"
}

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

{
    "id": "<Your itemId>",
    "type": "pipeline",
    "displayName": "My pipeline updated",
    "description": "My pipeline description updated",
    "workspaceId": "<Your workspaceId>"
}

Обновление определения конвейера

Обновляет определение элемента конвейера.

Пример запроса:

URI: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/updateDefinition

Заголовки:

{
  "Authorization": "Bearer <access-token>",
  "Content-Type": "application/json"
}

Наполнение:

{
  "displayName": " My pipeline ",
  "type": "DataPipeline",
  "definition": {
    "parts": [ 
      { 
        "path": "pipeline-content.json", 
        "payload": "<Your Base64 encoded payload>", 
        "payloadType": "InlineBase64" 
      }
    ]
  }
}

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

200 OK

Удаление конвейера

Удаляет указанный конвейер.

Пример запроса:

URI: DELETE https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}

Заголовки:

{
  "Authorization": "Bearer <access-token>"
}

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

200 OK

Выполнение задания в конвейере по требованию

Выполняет экземпляр конвейерного задания по требованию.

Пример запроса:

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

Заголовки:

{
  "Authorization": "Bearer <access-token>"
}

Наполнение:

{
    "executionData": {
        "pipelineName": "pipeline",
        "OwnerUserPrincipalName": "<user@domain.com>",
        "OwnerUserObjectId": "<Your ObjectId>"
    }
}

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

202 Accepted

Получить экземпляр задачи конвейера

Возвращает экземпляр задания сингулярным конвейером.

Пример запроса:

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

Заголовки:

{
  "Authorization": "Bearer <access-token>"
}

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

{
  "id": "<id>",
  "itemId": "<itemId>",
  "jobType": "Pipeline",
  "invokeType": "Manual",
  "status": "Completed",
  "rootActivityId": "<rootActivityId>",
  "startTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "endTimeUtc": "YYYY-MM-DDTHH:mm:ss.xxxxxxx",
  "failureReason": null
}

Планирование конвейера

Вы также можете создавать расписания программным способом с помощью API. API планировщика поддерживает следующие операции:

• Отмена экземпляра задания потока данных
• Создание расписания конвейера
• Удаление расписания конвейера
• Получение экземпляра конвейера
• Получение расписания конвейера
• Список экземпляров заданий конвейера
• Список расписаний потока
• Выполнение задания конвейера по запросу
• Обновление расписания конвейера

Например, можно настроить конвейер, который выполняется каждые 10 минут в период с 27 мая по 31 мая 2025 г. в центральном стандартном времени и в настоящее время включен:

POST https://api.fabric.microsoft.com/v1/workspaces/<workspaceId>/items/<pipelineId>/jobs/<jobType>/schedules 

{ 
  "enabled": true, 
  "configuration": { 
    "startDateTime": "2025-05-27T00:00:00", 
    "endDateTime": "2025-05-31T23:59:00", 
    "localTimeZoneId": " Central Standard Time", 
    "type": "Cron", 
    "interval": 10 
  } 
} 

Ответ.

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

{ 
  "id": " eeeeeeee-4444-5555-6666-ffffffffffff", 
  "enabled": true, 
  "createdDateTime": "2025-05-27T05:35:20.5366667", 
  "configuration": { 
    "startDateTime": "2025-05-27T00:00:00", 
    "endDateTime": "2025-05-31T23:59:00", 
    "localTimeZoneId": "Central Standard Time", 
    "type": "Cron", 
    "interval": 10 
  }, 
  "owner": { 
    "id": " aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e", 
    "type": "User" 
  } 
} 

Дополнительные сведения о доступных операциях и их использовании см. в документации по API планировщика заданий.

Отменить экземпляр конвейерного задания

Отменить выполнение задачи конвейера.

Пример запроса:

URI: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/jobs/instances/{jobInstanceId}/cancel

Заголовки:

{
  "Authorization": "Bearer <access-token>"
}

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

* Расположение: https://api.fabric.microsoft.com/v1/workspaces/<worksapceId>/items/<itemId>/jobs/instances/<jobInstanceId>повторная попытка:60

Запуск активности запроса

Пример:

POST https://api.fabric.microsoft.com/v1/workspaces/<your WS Id>/datapipelines/pipelineruns/<job id>/queryactivityruns

Тело:

{
  "filters":[],
  "orderBy":[{"orderBy":"ActivityRunStart","order":"DESC"}],
  "lastUpdatedAfter":"2024-05-22T14:02:04.1423888Z",
  "lastUpdatedBefore":"2024-05-24T13:21:27.738Z"
}

Ответ 200:

[
    {
        "pipelineName": "ca91f97e-5bdd-4fe1-b39a-1f134f26a701",
        "pipelineRunId": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
        "activityName": "Wait1",
        "activityType": "Wait",
        "activityRunId": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
        "linkedServiceName": "",
        "status": "Succeeded",
        "activityRunStart": "2024-05-23T13:43:03.6397566Z",
        "activityRunEnd": "2024-05-23T13:43:31.3906179Z",
        "durationInMs": 27750,
        "input": {
            "waitTimeInSeconds": 27
        },
        "output": {},
        "error": {
            "errorCode": "",
            "message": "",
            "failureType": "",
            "target": "Wait1",
            "details": ""
        },
        "retryAttempt": null,
        "iterationHash": "",
        "userProperties": {},
        "recoveryStatus": "None",
        "integrationRuntimeNames": null,
        "executionDetails": null,
        "id": "/SUBSCRIPTIONS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/RESOURCEGROUPS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/PROVIDERS/MICROSOFT.TRIDENT/WORKSPACES/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/pipelineruns/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f/activityruns/cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a"
    }
]

Поддержка имени служебного принципала (SPN)

Имя субъекта-службы (SPN) — это функция идентификации безопасности, используемая приложениями или службами для доступа к определенным ресурсам. В Фабрике данных Fabric поддержка учетной записи службы критически важна для обеспечения безопасного и автоматического доступа к источникам данных. Ниже приведены некоторые ключевые моменты поддержки SPN:

• Аутентификация: SPN используются для проверки подлинности приложений или служб при доступе к источникам данных. Это гарантирует, что только авторизованные сущности могут получить доступ к данным.
• Конфигурация: Чтобы использовать SPNs, необходимо создать учетную запись службы в Azure и предоставить ей необходимые разрешения для доступа к источнику данных. Например, если вы используете хранилище данных, служебному принципалу необходим доступ на чтение данных из BLOB-объектов в хранилище.
• Подключение: При настройке подключения к данным в Fabric Data Factory можно выбрать аутентификацию через сервисный принципал. Это включает в себя предоставление идентификатора арендатора, идентификатора клиента и секрета клиента служебного принципала.
• Безопасность: Использование SPN повышает безопасность, избегая использования жестко закодированных учетных данных в процессе передачи данных. Кроме того, он обеспечивает более эффективное управление разрешениями доступа и аудит действий доступа.

Дополнительные сведения о настройке и использовании SPN в Fabric Data Factory см. в разделе "Поддержка SPN в Data Factory".

Текущие ограничения

• Ограничение JOB: можно вызывать API-интерфейсы запуска, но фактический запуск никогда не завершается успешно (так же, как запуск и обновление из пользовательского интерфейса).
• Элементы, отличные от Power BI Fabric: рабочая область должна размещаться в поддерживаемой емкости Fabric.
• Создание элемента: используйте creationPayload или определение, но не используйте оба одновременно.

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

Дополнительные сведения о REST API для конвейеров в Фабрике данных Fabric см. в следующем содержимом:

Документация

• Общедоступный REST API конвейера данных Fabric
• Microsoft Fabric REST API
• API CRUD для элементов в Fabric

Обучающие материалы

• API планировщика заданий в Fabric
• Вариант использования ИИ — преобразование изображения для API-потоков