Fabric 数据工厂中管道的 REST API 功能

2025-08-28

Fabric 数据工厂提供了一组功能强大的 API，能够轻松实现管道自动化和管理。只需几行代码即可连接到不同的数据源和服务，并生成、更新或监视工作流。 API 涵盖从创建和编辑管道到计划和跟踪管道等所有内容，因此，无需麻烦即可使数据流顺利进行。

管道的 API 用例

Fabric 数据工厂中管道的 API 可用于各种场景：

自动部署：使用 CI/CD 做法自动跨不同环境（开发、测试、生产）部署管道。
监视和警报：设置自动监视和警报系统，以跟踪管道的状态，并在发生故障或性能问题时接收通知。
数据集成：将来自多个源（例如数据库、数据湖和云服务）的数据集成到统一管道中，以便进行处理和分析。
错误处理：实现自定义错误处理和重试机制，以确保管道顺利运行并从故障中恢复。

了解 API

若要有效地将 API 用于 Fabric 数据工厂中的管道，必须了解关键概念和组件：

终结点：API 终结点提供对各种管道操作（例如创建、更新和删除管道）的访问权限。
身份验证：使用 OAuth 或 API 密钥等身份验证机制保护对 API 的访问。
请求和响应：了解 API 请求和响应的结构，包括所需的参数和预期输出。
速率限制：注意对 API 使用施加的速率限制，以避免超过允许的请求数。

CRUD 支持

CRUD 代表“创建”、“读取”、“更新”和“删除”，这些是可对数据执行的四项基本操作。在 Fabric 数据工厂中，通过 Fabric API 支持 CRUD 操作。通过这些 API，用户能够以编程方式管理其管道。以下是有关 CRUD 支持的一些要点：

创建：使用 API 创建新管道。这涉及定义管道结构，指定数据源、转换和目标。
读取：检索有关现有管道的信息。这包括有关其配置、状态和执行历史记录的详细信息。
更新：更新现有管道。这可能涉及修改管道结构、更改数据源或更新转换逻辑。
删除：删除不再需要的管道。这有助于管理和清理资源。

可在 Microsoft Fabric REST API 文档中找到 Microsoft Fabric REST API 的主要联机参考文档。

开始使用用于管道的 REST API

以下示例演示如何使用 Fabric 数据工厂 API 创建、更新和管理管道。

获取授权令牌

在使用其他 REST API 之前，需要拥有持有者令牌。

重要

在以下示例中，确保“Bearer”（带空格）一词位于访问令牌本身之前。使用 API 客户端并选择“Bearer 令牌”作为身份验证类型时，会自动为您插入'Bearer '，您只需提供访问令牌即可。

选项 1：使用 MSAL.Net

有关如何获取 MSAL 授权令牌的示例，请参阅 Fabric API 快速入门的“获取令牌”部分。

使用 MSAL.Net 获取 Fabric 服务的 Microsoft Entra ID 令牌，其范围包括：Workspace.ReadWrite.All、Item.ReadWrite.All。有关使用 MSAL.Net 获取令牌的详细信息，请参阅令牌获取 - 适用于 .NET 的 Microsoft 身份验证库。

从 AccessToken 属性复制令牌，并将以下示例中的访问令牌<占位符替换为>令牌。

选项 2：使用 Fabric 门户

登录到要在其上测试的租户的 Fabric 门户，然后按 F12 进入浏览器的开发人员模式。在控制台中运行以下内容：

powerBIAccessToken

复制令牌，并将以下示例中的<访问令牌>占位符替换为令牌。

创建管道

在指定的工作区中创建管道。

示例请求：

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 定义创建管道。

示例请求：

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 支持以下作：

取消管道作业实例
创建管道计划
删除管道计划
获取管道实例
获取管道计划
列出管道作业实例
列出管道计划
运行按需管道作业
更新管道计划

例如，可以在 2025 年 5 月 27 日到 2025 年 5 月 31 日期间每隔 10 分钟设置一个管道，并且当前已启用：

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 
  } 
}

Name	In	必选	类型	Description	Example
pipelineID	路径	True	String（guid）	管道 ID	aaaa0000-bb11-2222-33cc-444444dd
jobType	路径	True	String	作业类型	DefaultJob
workspaceId	路径	True	String	工作区 ID	aaaaaaaa-0000-1111-2222-bbbbbbbbbb

响应：

状态代码：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"
}

注意

“作业 ID”是在作业调度器公共 API 中创建和使用的相同 ID

响应 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 支持的一些要点：

身份验证：在访问数据源时，SPN 用于验证应用程序或服务的身份。这可确保只有经过授权的实体才能访问数据。
配置：若要使用 SPN，需要在 Azure 中创建服务主体，并向其授予访问数据源所需的权限。例如，如果你使用数据湖，则服务主体需要拥有存储 Blob 数据读取者访问权限。
连接：在 Fabric 数据工厂中设置数据连接时，可以选择使用服务主体进行身份验证。这涉及到提供服务主体的租户 ID、客户端 ID 和客户端机密。
安全性：使用 SPN 可以避免在数据流中使用硬编码的凭据，从而增强安全性。它还允许更好地管理访问权限和审核访问活动。

要了解如何在数据工厂中设置和使用 SPN 的更多详细信息，请参阅数据工厂中的 SPN 支持。

当前限制

作业限制：运行 API 是可调用的，但实际运行永远不会成功（就像从 UI 运行/刷新一样）。
非 Power BI Fabric 项：工作区必须具有支持 Fabric 容量。
创建项：使用 creationPayload 或定义，但不能同时使用这两者。

有关 Fabric 数据工厂中管道的 REST API 的详细信息，请参阅以下内容：

文档

教程

反馈

此页面是否有帮助？

通过

Fabric 数据工厂中管道的 REST API 功能

管道的 API 用例

了解 API

CRUD 支持

开始使用用于管道的 REST API

获取授权令牌

选项 1：使用 MSAL.Net

选项 2：使用 Fabric 门户

创建管道

使用定义创建管道

获取管道

使用定义获取管道

更新管道

使用定义更新管道

删除管道

运行按需管道作业

获取管道作业实例

计划管道

取消管道作业实例

查询活动运行

服务主体名称 (SPN) 的支持

当前限制

相关内容

文档

教程

反馈

其他资源