Fabric Data Factory のデータパイプラインの REST API 機能

2025-04-16

Fabric Data Factory には、ユーザーがデータパイプラインを効率的に自動化および管理できる堅牢な API のセットが用意されています。これらの API を使用すると、さまざまなデータソースやサービスとシームレスに統合できるため、ユーザーはデータワークフローをプログラムで作成、更新、監視できるようになります。 API は、パイプライン CRUD (作成、読み取り、更新、削除)、スケジュール設定、監視など、さまざまな操作をサポートしています。これにより、ユーザーはデータ統合プロセスを管理しやすくなります。

データパイプラインの 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

Headers:

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

Headers:

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

Headers:

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

Headers:

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

Headers:

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

Headers:

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

Headers:

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

応答の例:

200 OK

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

オンデマンドパイプラインジョブインスタンスを実行します。

要求のサンプル:

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

Headers:

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

Headers:

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

応答の例:

{
  "id": "<id>",
  "itemId": "<itemId>",
  "jobType": "Refresh",
  "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

Headers:

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

注

"job id" は、Job Scheduler パブリック 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 のサポートに関するいくつかの重要なポイントを次に示します。

#B0 認証 #A1: SPN は、データソースにアクセスするときにアプリケーションまたはサービスを認証するために使用されます。これにより、承認されたエンティティのみがデータにアクセスできるようになります。
#B0 構成 #A1: SPN を使用するには、Azure でサービスプリンシパルを作成し、データソースにアクセスするために必要なアクセス許可を付与する必要があります。たとえば、データレイクを使用している場合、サービスプリンシパルにはストレージ BLOB データリーダーアクセスが必要です。
接続: Fabric Data Factoryでデータ接続を設定する際には、サービスプリンシパルを使用して認証することを選択できます。これには、サービスプリンシパルのテナント ID、クライアント ID、クライアントシークレットの指定が含まれます。
#B0 セキュリティ #A1: 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) のサポート

現在の制限

関連するコンテンツ

ドキュメント

チュートリアル

フィードバック

その他のリソース

Fabric Data Factory のデータパイプラインの REST API 機能

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

データパイプライン用 REST API を使い始める

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

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

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