Fabric Data Factory 中管線的 REST API 功能

Fabric Data Factory 提供一組功能強大的 API，可讓您輕鬆地自動化及管理管線。您可以連線到不同的數據源和服務，並使用幾行程式代碼來建置、更新或監視您的工作流程。 API 涵蓋從建立和編輯管線到排程和追蹤管線等所有專案，因此您可以順暢地讓數據流順暢地流動，而不需要麻煩。

管線的 API 使用案例

Fabric Data Factory 中管線的 API 可用於各種案例：

自動化部署：使用 CI/CD 實踐在不同環境（開發、測試、生產）之間自動部署管道。
監控和警報：設定自動監控和警報系統來追蹤管道的狀態，並在發生故障或效能問題時接收通知。
資料整合：將資料庫、資料湖、雲端服務等多個來源的資料整合到統一的管道中進行處理和分析。
錯誤處理：實作自訂錯誤處理和重試機制，確保管道順利運作並從故障中復原。

瞭解 API

若要有效地使用 Fabric Data Factory 中管線的 API，請務必瞭解重要概念和元件：

端點：API 端點提供各種管線作業的存取權，例如建立、更新和刪除管線。
驗證：使用 OAuth 或 API 金鑰等驗證機制保護對 API 的存取。
要求和回應：瞭解 API 要求和響應的結構，包括必要的參數和預期的輸出。
速率限制：請注意 API 使用量所施加的速率限制，以避免超過允許的要求數目。

CRUD 支援

CRUD 代表 Create、Read、Update 和 Delete，這是可在數據上執行的四項基本作業。在網狀架構 Data Factory 中，CRUD 作業可透過適用於 Data Factory 的網狀架構 API 來支援。這些 API 可讓使用者以程式設計方式管理其管線。以下是 CRUD 支援的一些重點：

建立：使用 API 建立新的管線。這包括定義管線結構、指定數據源、轉換和目的地。
讀取：擷取現有管線的相關信息。這包括其設定、狀態和執行歷程記錄的詳細數據。
更新：更新現有的管線。這可能涉及修改管線結構、變更數據源或更新轉換邏輯。
刪除：刪除不再需要的管線。這有助於管理和清除資源。

Microsoft網狀架構 REST API 的主要在線參考文件位於 Microsoft 網狀架構 REST API 檔中。

開始使用管線的 REST API

下列範例示範如何使用 Fabric Data Factory API 來建立、更新及管理管線。

取得授權代幣

使用其他 REST API 之前，您需要有持有人令牌。

這很重要

在下列範例中，請確定『Bearer』一詞在存取令牌本身前面加上空格。使用 API 用戶端並選取 [持有人令牌] 作為驗證類型時，系統會自動為您插入 'Bearer'，而且只需要提供存取令牌。

選項 1：使用 MSAL.Net

請參閱網狀架構 API 快速入門的取得令牌一節，以取得 MSAL 授權令牌的範例。

使用 MSAL.Net 來為 Fabric 服務取得具有以下範圍的 Microsoft Entra ID 令牌：Workspace.ReadWrite.All、Item.ReadWrite.All。如需有關使用 MSAL.Net 獲取令牌的更多資訊，請參閱 Token Acquisition - Microsoft Authentication Library for .NET。

從 AccessToken 屬性複製令牌，並以令牌取代下列範例中的 <access-token> 佔位符。

選擇 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 日至 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 
  } 
}

名稱	In	為必填項目	類型	Description	Example
管道識別碼	路徑	對	字串（guid）	管線識別碼	aaaa0000-bb11-2222-33cc-444444dddddd
jobType	路徑	對	繩子	工作類型	預設工作
workspaceId	路徑	對	繩子	工作區標識碼	aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb

回應：

狀態碼：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" 
  } 
}

如需可用作業及其使用的詳細資訊，請參閱 Job Scheduler 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"
}

注意

「作業標識碼」與在作業排程器公用 API 中建立及使用的識別碼相同

回應 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 Data Factory 中，SPN 支援對於實現數據來源的安全和自動化存取至關重要。以下是SPN支援的一些重點：

驗證：SPN 可用來在存取資料來源時驗證應用程式或服務。這可確保只有授權的實體可以存取數據。
設定：若要使用 SPNs，您必須在 Azure 中建立服務主體，並授與存取資料來源的必要許可權。舉例來說，如果您正在使用資料湖，您的服務主體需要存取儲存Blob資料的讀取權限。
連線：在 Fabric Data Factory 中設定資料連線時，您可以選擇使用服務主體進行身份驗證。這牽涉到提供服務主體的租用戶標識碼、用戶端標識碼和客戶端密碼。
安全性：使用 SPN 可避免在資料流中使用硬编码凭证，以增強安全性。它也允許更妥善地管理訪問許可權和稽核存取活動。

如需更詳細的資訊來了解如何在 Fabric Data Factory 中設定和使用 SPN，請參閱資料工廠中的 SPN 支援。

目前的限制

工作限制：運行 API 可被調用，但實際運行從未成功（就像從用戶界面進行運行/刷新）。
非 Power BI Fabric 專案：工作區必須位於支援 Fabric 容量的環境中。
建立項目：使用 creationPayload 或定義，但不要同時使用兩者。

如需 Fabric Data Factory 中管線 REST API 的詳細資訊，請參閱下列內容：

共用方式為

Fabric Data Factory 中管線的 REST API 功能

管線的 API 使用案例

瞭解 API

CRUD 支援

開始使用管線的 REST API

取得授權代幣

選項 1：使用 MSAL.Net

選擇 2：使用 Fabric 平台入口網站

建立管線

建立具有定義的管線

取得管道

取得具有定義的管道

更新工作流程

更新管線並使用定義

刪除管線

按需求執行管線任務

取得管道作業實例

排程管線

取消流程任務實例

執行查詢活動

服務主體名稱 （SPN） 支援

目前的限制

相關內容

文件

教學課程

意見反應

其他資源

服務主體名稱（SPN）支援