Возможности 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": "pipeline"
}

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

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

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

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

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

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": "pipeline",
  "definition": { 
    "parts": [ 
      { 
        "path": "pipeline-content.json", 
        "payload": "<Your Base64 encoded JSON payload>"
        "payloadType": "InlineBase64" 
      } 
    ] 
  }
}

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

{
    "id": "<Your artifactId>",
    "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 artifactId>",
    "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": "pipeline"
}

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

{
    "id": "<Your artifactId>",
    "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": "pipeline",
  "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": "<[email protected]>",
        "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
}

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

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

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

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".

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

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

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

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

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

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

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

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