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 は、作成、読み取り、更新、削除の略で、データに対して実行できる 4 つの基本操作です。 Fabric Data Factory では、CRUD 操作は、Data Factory 用 Fabric API を通じてサポートされます。これらの API を使用すると、ユーザーはパイプラインをプログラムで管理できます。 CRUD のサポートに関する重要なポイントをいくつか示します。

作成: API を使用して新しいパイプラインを作成します。これには、パイプライン構造の定義、データソース、変換、宛先の指定が含まれます。
読み取り: 既存のパイプラインに関する情報を取得します。これには、構成、状態、実行履歴に関する詳細が含まれます。
更新: 既存のパイプラインを更新します。これには、パイプライン構造の変更、データソースの変更、または変換ロジックの更新が含まれる場合があります。
削除: 不要になったパイプラインを削除します。これは、リソースの管理とクリーンアップに役立ちます。

Microsoft Fabric REST API の主なオンラインリファレンスドキュメントは、「Microsoft Fabric REST API ドキュメント」にあります。

パイプラインの REST API を使い始める

次の例は、Fabric Data Factory API を使用してパイプラインを作成、更新、管理する方法を示しています。

承認トークンを取得

他の REST API を使用する前に、ベアラートークンを取得する必要があります。

重要

次の例では、"Bearer" (スペース付き) という単語がアクセストークン自体の前にあることを確認します。 API クライアントを使用し、認証の種類として [Bearer Token] を選択すると、'Bearer' が自動的に挿入され、アクセストークンのみを指定する必要があります。

オプション 1: MSAL.Net の使用

MSAL 認可トークンを取得する方法の例については、Fabric API クイックスタートの「トークンの取得」セクションを参照してください。

MSAL.Net を使用して、スコープ Workspace.ReadWrite.All、Item.ReadWrite.All での Fabric サービスの Microsoft Entra ID トークンを取得します。 MSAL.Net を使用したトークン取得の詳細については、「トークンの取得 - .NET用 Microsoft 認証ライブラリ」を参照してください。

AccessToken プロパティからトークンをコピーし、次の例の <access-token> プレースホルダーをトークンに置き換えます。

オプション 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 定義を含むパイプラインを作成します。

要求のサンプル:

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": "<[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
}

パイプラインをスケジュールする

API を使用してプログラムでスケジュールを作成することもできます。 Scheduler 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
pipelineID	経路	正しい	String(guid)	パイプライン ID	aaaa0000-bb11-2222-33cc-444444ddddd
jobType	経路	正しい	String	ジョブの種類	DefaultJob
workspaceId	経路	正しい	String	ワークスペース ID	aaaaaa-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>Retry-after: 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) は、アプリケーションまたはサービスが特定のリソースにアクセスするために使用するセキュリティ ID 機能です。 Fabric Data Factory では、SPN のサポートは、データソースへのセキュリティで保護された自動アクセスを有効にするために不可欠です。 SPN のサポートに関するいくつかの重要なポイントを次に示します。

認証: SPN は、データソースにアクセスするときにアプリケーションまたはサービスを認証するために使用されます。これにより、承認されたエンティティのみがデータにアクセスできるようになります。
構成: SPN を使用するには、Azure でサービスプリンシパルを作成し、データソースにアクセスするために必要なアクセス許可を付与する必要があります。たとえば、データレイクを使用している場合、サービスプリンシパルにはストレージ BLOB データリーダーアクセスが必要です。
接続: Fabric Data Factoryでデータ接続を設定する際には、サービスプリンシパルを使用して認証することを選択できます。これには、サービスプリンシパルのテナント ID、クライアント ID、クライアントシークレットの指定が含まれます。
セキュリティ: SPN を使用すると、データフローでハードコーディングされた資格情報が使用されるのを回避して、セキュリティが強化されます。また、アクセス許可の管理とアクセスアクティビティの監査を向上させることもできます。

Fabric Data Factory で SPN を設定して使用する方法の詳細については、Data Factory における SPN サポートを参照してください。

現在の制限

ジョブの制限: 実行 API は呼び出し可能ですが、実際の実行は (UI からの実行/更新と同様に) 成功しません。
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) のサポート

現在の制限

関連するコンテンツ

ドキュメント

チュートリアル

フィードバック

その他のリソース

パイプラインの API ユースケース

オンデマンドでパイプラインジョブを実行する

パイプラインジョブインスタンスの取得

サービスプリンシパル名 (SPN) のサポート