Power BI REST API を使用した強化された更新
POWER BI Refresh Dataset REST API を使用して、REST 呼び出しをサポートする任意のプログラミング言語を使用して、セマンティック モデルの更新操作を実行できます。
大規模で複雑なパーティション 分割モデルの最適化された更新は、従来、TOM (テーブル オブジェクト モデル)、PowerShell コマンドレット、または TMSL (表形式モデル スクリプト言語) を使用するプログラミング メソッドを使用して呼び出されます。 ただし、これらのメソッドには、信頼性の低い実行時間の長い HTTP 接続が必要です。
Power BI Refresh Dataset REST API は、モデル更新操作を非同期的に実行できるため、クライアント アプリケーションからの実行時間の長い HTTP 接続は必要ありません。 標準の更新操作と比較して、REST API を使用 強化された更新 には、より多くのカスタマイズ オプションと、大規模なモデルに役立つ次の機能が用意されています。
- バッチ処理でのコミット
- テーブルとパーティション レベルの更新
- 増分更新ポリシーの適用
GET
更新の詳細- 更新の取り消し
- タイムアウト構成
手記
- 以前は、拡張更新は「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 にリソースと操作を追加できます。 次の図では、
必要条件
REST API を使用するには、次の要件が必要です。
- Power BI Premium、ユーザーごとの Premium、または Power BI Embedded のセマンティック モデル。
- 要求 URL で使用するグループ ID とデータセット ID。
- Dataset.ReadWrite.All アクセス許可スコープ。
更新の数は、Pro および Premium モデルの API ベースの更新に関する一般的な制限に従って制限されます。
認証
すべての呼び出しは、Authorization ヘッダーの有効な Microsoft Entra ID OAuth 2 トークンで認証する必要があります。 トークンは、次の要件を満たしている必要があります。
- ユーザー トークンまたはアプリケーション サービス プリンシパルのいずれかです。
- 対象ユーザーを正しく
https://api.powerbi.com
に設定します。 - モデルに対する十分なアクセス許可を持つユーザーまたはアプリケーションによって使用されます。
手記
REST API の変更によって、モデルの更新に対して現在定義されているアクセス許可は変更されません。
POST /refreshes
更新を行うには、/refreshes コレクションで POST 動詞を使用して、新しい更新オブジェクトをコレクションに追加します。 応答の 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,
"timeout": "02:00:00",
"objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer"
},
{
"table": "DimDate"
}
]
}
手記
サービスは、モデルに対して一度に 1 つの更新操作のみを受け入れます。 現在実行中の更新があり、別の要求が送信されると、400 Bad Request
HTTP 状態コードが返されます。
パラメーター
拡張更新操作を実行するには、要求本文で 1 つ以上のパラメーターを指定する必要があります。 指定されたパラメーターでは、既定値または省略可能な値を指定できます。 要求でパラメーターを指定すると、その他のすべてのパラメーターが既定値で操作に適用されます。 要求でパラメーターが指定されていない場合、すべてのパラメーターで既定値が使用され、標準の更新操作が実行されます。
名前 | 種類 | 既定値 | 説明 |
---|---|---|---|
type |
列挙型 | automatic |
実行する処理の種類。 型は、TMSL 更新コマンドの種類 (full 、clearValues 、calculate 、dataOnly 、automatic 、および defragment ) と一致します。 add 型はサポートされていません。 |
commitMode |
列挙型 | transactional |
オブジェクトをバッチでコミットするか、完了したときにのみコミットするかを決定します。 モードは transactional と partialBatch です。 partialBatch を使用する場合、更新操作は 1 つのトランザクション内では発生しません。 各コマンドは個別にコミットされます。 エラーが発生した場合、モデルが空であるか、データのサブセットのみが含まれている可能性があります。 障害から保護し、操作が開始される前にモデルにあったデータを保持するには、commitMode = transactional を使用して操作を実行します。 |
maxParallelism |
整数 | 10 |
処理コマンドを並列で実行できるスレッドの最大数を決定します。 この値は、TMSL Sequence コマンドまたは他のメソッドを使用して設定できる MaxParallelism プロパティに合わせて調整されます。 |
retryCount |
整数 | 0 |
操作が再試行されてから失敗した回数。 |
objects |
配列 | モデル全体 | 処理するオブジェクトの配列。 各オブジェクトには、テーブル全体を処理するときの table 、またはパーティションの処理時に table と partition が含まれます。 オブジェクトが指定されていない場合は、モデル全体が更新されます。 |
applyRefreshPolicy |
ブーリアン | true |
増分更新ポリシーが定義されている場合は、ポリシーを適用するかどうかを決定します。 モードは true または false です。 ポリシーが適用されていない場合、完全なプロセスによってパーティション定義は変更されず、テーブル内のすべてのパーティションが完全に更新されます。 commitMode が transactional の場合、applyRefreshPolicy は true または false できます。 commitMode が partialBatch の場合、true の applyRefreshPolicy はサポートされず、applyRefreshPolicy を false に設定する必要があります。 |
effectiveDate |
日付 | 現在の日付 | 増分更新ポリシーが適用されている場合、effectiveDate パラメーターは現在の日付をオーバーライドします。 指定しない場合、現在の日付は、'Refresh'のタイム ゾーン構成を使用して決定されます。 |
timeout |
糸 | 05:00:00 (5 時間) | timeout が指定されている場合、セマンティック モデルでの各データ更新の試行は、そのタイムアウトに従います。 retryCount が指定されている場合、1 回の更新要求に複数の試行を含めることができます。これにより、合計更新期間が指定されたタイムアウトを超える可能性があります。 たとえば、timeout を 1 時間に設定し、retryCount を 2 に設定すると、合計更新時間が最大 3 時間になる可能性があります。 ユーザーは、timeout を調整して、障害検出を高速化するために更新期間を短縮したり、より複雑なデータ更新のために既定の 5 時間を超えて延長したりできます。 ただし、再試行を含む合計更新期間は 24 時間を超えることはできません。 |
応答
202 Accepted
応答には、作成されて受け入れられた更新操作を呼び出し元に示す Location
response-header フィールドも含まれています。 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",
"status": "Unknown"
}
{
"requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
"refreshType": "ViaEnhancedApi",
"startTime": "2020-12-07T01:05:54.157324Z",
"status": "Unknown",
"extendedStatus": "NotStarted"
}
]
手記
短期間に要求が多すぎると、Power BI によって要求が削除される可能性があります。 Power BI は更新を行い、次の要求をキューに入れ、他のすべての要求を削除します。 設計上、破棄された要求の状態を問い合わせることはできません。
応答プロパティ
名前 | 種類 | 説明 |
---|---|---|
requestId |
Guid | 更新要求の識別子。 個々の更新操作の状態を照会したり、進行中の更新操作を取り消したりするには、requestId が必要です。 |
refreshType |
糸 | OnDemand は、Power BI ポータルを介して対話形式で更新がトリガーされたことを示します。Scheduled は、モデルの更新スケジュールによって更新がトリガーされたことを示します。 ViaApi は、API 呼び出しによって更新がトリガーされたことを示します。 ViaEnhancedApi は、API 呼び出しによって強化された更新がトリガーされたことを示します。 |
startTime |
糸 | 更新の開始日時。 |
endTime |
糸 | 更新の終了日時。 |
status |
糸 | Completed は、更新操作が正常に完了したことを示します。 Failed は、更新操作が失敗したことを示します。 Unknown は、完了状態を判断できないことを示します。 この状態では、endTime は空です。 Disabled は、選択的更新によって更新が無効にされたことを示します。 Cancelled 更新が正常に取り消されたことを示します。 |
extendedStatus |
糸 | status プロパティを拡張して、詳細情報を提供します。 |
手記
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
を指定して、更新オブジェクトで 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
を指定して、更新オブジェクトで 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"
}
]
}
解決策は、更新操作を再実行することです。 動的メモリ管理とモデルの削除の詳細については、「モデルの削除
更新操作の時間制限
retryCount
が指定されている場合、更新操作には複数の試行が含まれる場合があります。 各試行の既定のタイムアウトは 5 時間で、timeout
パラメーターを使用して調整できます。 再試行を含む合計更新期間は、24 時間を超えてはなりません。
retryCount
が数値を指定した場合、新しい更新操作はタイムアウト制限で開始されます。 サービスは、成功するか、retryCount
制限に達するか、最初の試行から 24 時間の最大値に達するまで、この操作を再試行します。
timeout
を調整して、障害検出を高速化するために更新期間を短縮したり、より複雑なデータ更新のために既定の 5 時間を超えて延長することができます。
データセットの更新 REST API を使用してセマンティック モデルの更新を計画する場合は、時間制限と retryCount パラメーターを考慮してください。 最初の試行が失敗し、retryCount が 1 以上に設定されている場合、更新がタイムアウトを超える可能性があります。 "retryCount": 1 で更新を要求し、4 時間後に最初の試行が失敗した場合、2 回目の試行が開始されます。 これが 3 時間で成功した場合、更新の合計時間は 7 時間です。
更新操作が定期的に失敗する場合、タイムアウト時間の制限を超える場合、または必要な更新操作の成功時間を超える場合は、データ ソースから更新されるデータの量を減らすことを検討してください。 更新は、テーブルごとに要求など、複数の要求に分割できます。 commitMode パラメーターで partialBatch を指定することもできます。
コード サンプル
開始するための C# コード サンプルについては、GitHub の RestApiSample を参照してください。
コード サンプルを使用するには:
- リポジトリを複製またはダウンロードします。
- RestApiSample ソリューションを開きます。
client.BaseAddress = …
行を見つけて、ベース URLを指定します。
このコード サンプルでは、サービス プリンシパル認証を使用します。