Power BI REST API による強化された更新

[アーティクル]
01/08/2024

REST 呼び出しをサポートするいずれかのプログラミング言語を使うと、Power BI Refresh Dataset REST API を使って、セマンティックモデル更新操作を行うことができます。

従来、パーティション分割された大規模で複雑なモデルの更新の最適化は、TOM (表形式オブジェクトモデル)、PowerShell コマンドレット、または TMSL (表形式モデルスクリプト言語) を使うプログラミング手法で呼び出されています。ただし、このような手法には、信頼性の低い長時間の HTTP 接続が必要です。

Power BI Refresh Dataset REST API はモデル更新操作を非同期で実行できるため、クライアントアプリケーションからの実行時間の長い HTTP 接続は必要ありません。標準の更新操作に比べて、REST API によって "強化された更新" には、大規模なモデルに役立つ多くのカスタマイズオプションと次の機能が用意されています。

コミットのバッチ処理
テーブルレベルとパーティションレベルの更新
増分更新ポリシーの適用
GET 更新の詳細
更新の取り消し

Note

強化された更新は、以前は "REST API を使った非同期更新" と呼ばれていました。ただし、Refresh Dataset REST API を使う標準の更新も、その本来の性質上、非同期で実行されます。
強化された Power BI REST API の更新操作では、タイルキャッシュは自動的に更新されません。タイルキャッシュは、ユーザーがレポートにアクセスしたときにのみ更新されます。

ベース URL

ベース URL は次の形式です。

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes

パラメーターに基づいて、ベース URL にリソースと操作を追加できます。次の図の Groups、Datasets、Refreshes は "コレクション" です。 Group、Dataset、Refresh は、"オブジェクト" です。

Diagram that shows asynchronous refresh flow.

必要条件

REST API を使うには、次の要件が必要です。

Power BI Premium、Premium Per User、または Power BI Embedded のセマンティックモデル。
要求 URL で使うグループ ID とデータセット ID。
Dataset.ReadWrite.All アクセス許可スコープ。

更新の数は、Pro と Premium のモデルに対する API ベースの更新に関する一般的な制限に従って制限されます。

認証

すべての呼び出しは、認可ヘッダーの有効な Microsoft Entra ID OAuth 2.0 トークンを使って認証する必要があります。トークンは、次の要件を満たす必要があります。

ユーザートークンまたはアプリケーションサービスプリンシパルのどちらかである必要があります。
対象ユーザーを正しく https://api.powerbi.com に設定する必要があります。
モデルに対して十分なアクセス許可を持っているユーザーまたはアプリケーションが使う必要があります。

Note

REST API の変更では、モデル更新に対して現在定義されているアクセス許可は変更されません。

POST /refreshes

更新を行うには、/refreshes コレクションに対して POST 動詞を使い、新しい refresh オブジェクトをコレクションに追加します。応答内の Location ヘッダーには、requestId が含まれます。操作は非同期であるため、クライアントアプリケーションは、後から必要に応じて接続を切断し、requestId を使って状態を確認することができます。

次のコードはサンプル要求を示しています。

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

要求本文は次の例のようになります。

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Note

このサービスは、モデルに対して一度に 1 つの更新操作のみを受け入れます。現在実行中の更新がある状態で別の要求が送信された場合は、400 Bad Request HTTP 状態コードが返されます。

パラメーター

強化された更新操作を行うには、要求本文に 1 つ以上のパラメーターを指定する必要があります。指定するパラメーターには、既定値または省略可能な値を指定できます。要求にパラメーターを指定した場合、他のすべてのパラメーターはその既定値が操作に適用されます。要求にパラメーターを指定しない場合、すべてのパラメーターにはその既定値が使われ、標準の更新操作が行われます。

名前	Type	Default	説明
`type`	列挙型	`automatic`	実行する処理の種類です。型は、TMSL 更新コマンドの型 (`full`, `clearValues`、`calculate`、`dataOnly`、`automatic`、`defragment`) に合わせて調整されます。 `add` 型はサポートされていません。
`commitMode`	列挙型	`transactional`	オブジェクトをバッチでコミットするか、完了時にのみコミットするかを決定します。モードは `transactional` と `partialBatch` です。 `partialBatch` を使用する場合、更新操作は 1 つのトランザクション内では発生しません。各コマンドは個別にコミットされます。失敗が発生した場合、モデルは空となるか、データのサブセットのみを含んでいる可能性があります。失敗に対して備え、操作の開始前にモデル内にあったデータを保持するには、`commitMode = transactional` で操作を実行します。
`maxParallelism`	int	`10`	処理コマンドを並列実行できるスレッドの最大数を決定します。この値は、TMSL `Sequence` コマンド、または他のメソッドを使って設定できる `MaxParallelism` プロパティに合わせて調整されます。
`retryCount`	int	`0`	操作を失敗にするまでの再試行回数。
`objects`	Array	モデル全体	処理するオブジェクトの配列。各オブジェクトには、テーブル全体を処理する場合は `table` が、パーティションを処理する場合には `table` と `partition` が含まれます。オブジェクトが指定されていない場合は、モデル全体が更新されます。
`applyRefreshPolicy`	ブール型	`true`	増分更新ポリシーが定義されている場合は、そのポリシーを適用するかどうかを決定します。モードは `true` または `false` です。このポリシーが適用されない場合、完全処理によってパーティション定義は変更されず、テーブル内のすべてのパーティションが完全に更新されます。 `commitMode` が `transactional` の場合、`applyRefreshPolicy` は `true` または `false` になる可能性があります。 `commitMode` が `partialBatch` の場合、`true` の `applyRefreshPolicy` はサポートされておらず、`applyRefreshPolicy` を `false` に設定する必要があります。
`effectiveDate`	Date	現在の日付	増分更新ポリシーが適用されている場合、`effectiveDate` パラメーターが現在の日付よりも優先されます。指定しない場合は、現在の日付を判断するのに UTC が使用されます。

回答

202 Accepted

応答には、作成し、受け入れた更新操作を呼び出し元に指す Location 応答ヘッダーフィールドも含まれています。 Location は、要求が作成した新しいリソースの場所であり、一部の強化されたされた更新操作が要求する requestId が含まれています。たとえば、次の応答では、requestId は応答 87f31ef7-1e3a-4006-9b0b-191693e79e9e 内の最後の識別子です。

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

GET /refreshes

/refreshes コレクションに対して GET 動詞を使用して、履歴、最新、および保留中の更新操作を一覧表示します。

応答本文は、次の例のようになります。

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Note

短時間にあまりにも多くの要求があった場合、Power BI は要求をドロップすることがあります。 Power BI は更新を行い、次の要求をキューに格納し、他のすべての要求をドロップします。設計上、ドロップされた要求の状態に対してクエリを実行することはできません。

応答プロパティ

名前	タイプ	Description
`requestId`	Guid	更新要求の識別子。個々の更新操作の状態に対してクエリを実行する場合、または進行中の更新操作を取り消す場合は、`requestId` が必要です。
`refreshType`	String	`OnDemand` は、更新が Power BI ポータルを介して対話形式でトリガーされたことを示します。 `Scheduled` は、モデルの更新スケジュールによって更新がトリガーされたことを示します。 `ViaApi` は、API 呼び出しによって更新がトリガーされたことを示します。 `ViaEnhancedApi` は、API 呼び出しによって強化された更新がトリガーされたことを示します。
`startTime`	String	更新の開始日時。
`endTime`	String	更新の終了日時。
`status`	String	`Completed` は、更新操作が正常に完了したことを示します。 `Failed` は、更新操作が失敗したことを示します。 `Unknown` は、完了状態を判断できないことを示します。この状態の場合、`endTime` は空です。 `Disabled` は、更新が選択的更新によって無効にされたことを示します。 `Cancelled` は、更新が正常に取り消されたことを示します。
`extendedStatus`	String	より多くの情報を提供するには、`status` プロパティを拡張します。

Note

Azure Analysis Services の場合、完了した status の結果は succeeded です。 Azure Analysis Services ソリューションを Power BI に移行する場合は、ソリューションの変更が必要になることがあります。

返される更新操作の数を制限する

Power BI REST API は、省略可能な $top パラメーターを使用して、更新履歴に要求されたエントリ数を制限することをサポートしています。指定しない場合、既定ですべての使用可能なエントリが表示されます。

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}

GET /refreshes/<requestId>

更新操作の状態を確認するには、requestId を指定して refresh オブジェクトで GET 動詞を使用します。操作が進行中の場合は、次の応答本文例のように、status は InProgress を返します。

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

DELETE /refreshes/<requestId>

進行中の強化された更新操作を取り消すには、requestId を指定して refresh オブジェクトで DELETE 動詞を使います。

たとえば、次のように入力します。

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

考慮事項と制限事項

更新操作には、次の考慮事項と制限があります。

標準の更新操作

DELETE /refreshes/<requestId> を使って、スケジュールされた、またはオンデマンドの手動モデル更新を取り消すことはできません。
スケジュールされた、またオンデマンドの手動モデル更新は、GET /refreshes/<requestId> を使った更新操作の詳細の取得をサポートしていません。
詳細の取得と取り消しは、強化された更新専用の新しい操作です。標準の更新は、これらの操作をサポートしていません。

Power BI Embedded

Power BI ポータルまたは PowerShell を使って手動で容量を一時停止した場合、またはシステム停止が発生した場合、進行中の強化された更新操作の状態は最長 6 時間 InProgress のままになります。 6 時間以内に容量が再開された場合、更新操作は自動的に再開されます。 6 時間を超えてから容量が再開された場合、更新操作はタイムアウトエラーを返すことがあります。その場合は、更新操作を再び開始する必要があります。

セマンティックモデルの削除

Power BI は動的メモリ管理を使用して容量のメモリを最適化します。更新操作中にモデルがメモリから削除されると、次のエラーが返されることがあります。

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

解決策は、更新操作を再実行することです。動的メモリ管理とモデルの削除の詳細については、「モデルの削除」を参照してください。

更新操作の時間制限

"1 回の更新操作" の最大時間は 5 時間です。更新操作が 5 時間の上限以内に正常に完了しないとき、retryCount が指定されていないか、0 が要求本文に指定されている場合 (既定値)、タイムアウトエラーが返されます。

retryCount に 1 または他の数値を指定した場合、5 時間の上限で新しい更新操作が開始されます。この再試行操作に失敗した場合、retryCount に指定した最大再試行回数、または最初の更新要求の開始から 24 時間という強化された更新プロセス時間の上限まで、サービスは更新操作を再試行し続けます。

Refresh Dataset REST API を使って強化されたモデル更新ソリューションを計画する場合、これらの時間制限と retryCount パラメーターを考慮することが重要です。最初の更新操作に失敗し、retryCount に 1 以上を指定した場合、更新が正常に完了するまでに 5 時間を超えることがあります。

たとえば、"retryCount": 1 で更新操作を要求したとき、開始時刻から 4 時間で最初の再試行操作に失敗した場合、その要求の 2 回目の更新操作が始まります。その 2 回目の更新操作が 3 時間で成功した場合、更新要求の正常実行にかかった合計時間は 7 時間です。

更新操作が定期的に失敗する場合、5 時間の上限時間を超える場合、または更新操作の成功の目標時間を超える場合、データソースから更新対象のデータ量を減らすことを検討してください。更新を複数回の要求に分けることができます (たとえば、テーブルごとに 1 つの要求)。また、commitMode パラメーターで partialBatch を指定することもできます。

コードサンプル

基本的な C# コードサンプルについては、GitHub の RestApiSample を参照してください。

コードサンプルを使うには:

リポジトリを複製またはダウンロードします。
RestApiSample ソリューションを開きます。
行 client.BaseAddress = … を見つけて、ベース URL を指定します。

このコード例では、サービスプリンシパルの認証を使用しています。

Power BI REST API による強化された更新

ベース URL

必要条件

認証

POST /refreshes

パラメーター

回答

GET /refreshes

応答プロパティ

返される更新操作の数を制限する

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

考慮事項と制限事項

標準の更新操作

Power BI Embedded

セマンティック モデルの削除

更新操作の時間制限

コード サンプル

関連するコンテンツ

その他のリソース

セマンティックモデルの削除

コードサンプル