この記事では、Spark リソースの使用状況情報を取得する方法について説明します。
権限
呼び出し元には、項目に対する "読み取り" アクセス許可が必要です。
必要な委任されたスコープ
Item.Read.All または Item.ReadWrite.All、または次の 3 つのグループのいずれか (Spark アプリケーションをトリガーした項目に応じて)
- Notebook.Read.All または Notebook.ReadWrite.All
- SparkJobDefinition.Read.All または SparkJobDefinition.ReadWrite.All
- Lakehouse.Read.All または Lakehouse.ReadWrite.All
Microsoft Entra でサポートされている ID
この API では、このセクションに記載されている Microsoft ID がサポートされています。
| アイデンティティ | 支援 |
|---|---|
| ユーザー | イエス |
| サービス プリンシパルとマネージド ID | イエス |
リソースの使用状況のタイムラインを取得する
すべてのリソース使用状況情報をタイムラインとして取得します。
インターフェイス
attemptId を使用する
GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks|sparkJobDefinitions|lakehouses/{itemId}/livySessions/{livyId}/applications/{appId}/{attemptId}/resourceUsage
attemptId を使用しない
GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks|sparkJobDefinitions|lakehouses/{itemId}/livySessions/{livyId}/applications/{appId}/resourceUsage
省略可能なパラメーターを使用します。
attemptId を使用する
GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks|sparkJobDefinitions|lakehouses/{itemId}/livySessions/{livyId}/applications/{appId}/{attemptId}/resourceUsage?jobGroup={jobGroup}&jobLimit={jobLimit}&executorLimit={executorLimit}&executorJobLimit={executorJobLimit}&start={start}&end={end}
attemptId を使用しない
GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks|sparkJobDefinitions|lakehouses/{itemId}/livySessions/{livyId}/applications/{appId}/resourceUsage?jobGroup={jobGroup}&jobLimit={jobLimit}&executorLimit={executorLimit}&executorJobLimit={executorJobLimit}&start={start}&end={end}
URI パラメーター
| 名前 | で | 必須 | タイプ | 説明 |
|---|---|---|---|---|
| ワークスペースID | 道 | 正しい | string uuid | ワークスペース ID。 |
| アイテムID | 道 | 正しい | string uuid | ノートブックまたは Spark ジョブ定義またはレイクハウスの項目 ID。 |
| livyId | 道 | 正しい | string uuid | Livy セッション ID。 |
| アプリID | 道 | 正しい | ひも | Spark アプリケーションの ID（例: application_1111111111111_0001）。 |
| attemptId | 道 | いいえ | 整数 (int) | そのアプリケーション ID の試行 ID。 指定しない場合は、最後の試行の ID が使用されます。 |
| ジョブグループ | 問い合わせ | いいえ | ひも | 指定された jobGroups 内のジョブのタイムラインのみを一覧表示します。 複数の jobGroup を次のように指定できます: ?jobGroup=1>jobGroup=2 |
| jobLimit | 問い合わせ | いいえ | 整数 (int) | タイム ポイントごとに一覧表示するジョブの最大数。 |
| 実行者の制限 | 問い合わせ | いいえ | 整数 (int) | タイム ポイントごとに一覧表示する Executor の最大数。 |
| エグゼキュータージョブの制限 | 問い合わせ | いいえ | 整数 (int) | 時間ポイントごとに一覧表示する Executor ジョブ情報の最大数。 |
| 開始/終了 | 問い合わせ | いいえ | 長い | 時間点の下限と上限をリスト化します。 |
リクエストの本文
無し
応答
| 名前 | タイプ | 説明 |
|---|---|---|
| 200 OK（正常に処理されました） | ResourceUsageInfo | 要求が正常に完了しました |
| 400 無効な要求 | パラメーターが無効です。 start が end より大きい | |
| 403 許可されていません | ユーザーが正しいアクセス許可を持っていない | |
| 404 見つかりません | - 項目 ID、アプリケーション ID、Livy ID が一致しません - リソース使用状況データを取得するには早すぎる |
例示
サンプルリクエスト
GET https://api.fabric.microsoft.com/v1/workspaces/aaaabbbb-0000-cccc-1111-dddd2222eeee/notebooks/11bb11bb-cc22-dd33-ee44-55ff55ff55ff/livySessions/0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c/applications/application_11111111111110001/1/resourceUsage?start=1745906291774&end=1745906293676
サンプル応答
状態コード:200
{
{
"resourceUsageApiVersion" : 2,
"duration" : 131903,
"capacityExceeded" : false,
"idleTime" : 120869,
"coreEfficiency" : 0.08070419171664026,
"data" : {
"timestamps" : [ 1745906291774, 1745906292471, 1745906292731],
"isPartials" : [ false, false, false ],
"allocatedCores" : [ 8.0, 8.0, 8.0 ],
"idleCores" : [ 0.0, 0.0, 1.0 ],
"runningCores" : [ 8.0, 8.0, 7.0 ],
"executors" : [ [ [ "1", 8.0, 12 ] ], [ [ "1", 8.0, 9 ] ], [ [ "1", 7.0, 7 ] ] ],
"jobs" : [ [ [ 9, 12 ] ], [ [ 9, 9 ] ], [ [ 9, 7 ] ] ],
"executorJobs" : [ [ [ "1", [ [ 9, 12 ] ] ] ], [ [ "1", [ [ 9, 9 ] ] ] ], [ [ "1", [ [ 9, 7 ] ] ] ] ]
}
}
}
定義
ResourceUsageInfo
オブジェクト
| 名前 | タイプ | 説明 |
|---|---|---|
| リソース使用APIバージョン | 整数 (int) | リソース使用状況 API のバージョン。 |
| 期間 | 長い | 指定された Spark アプリケーションの期間 (ミリ秒単位)。 |
| 容量超過 | ブール (bool) | True の場合は、10,000 個のタスクの制限を超えています。 true の場合、データ内のすべてのプロパティが空になります。 |
| idleTime | 長い | 指定された Spark アプリケーションがアイドル状態の時間 (ミリ秒単位)。 |
| コア効率 | ダブル | Executor コアの概要使用率。 |
| データ | ResourceUsageData |
ResourceUsageData
オブジェクト
| 名前 | タイプ | 説明 |
|---|---|---|
| タイムスタンプ | long の配列 | |
| isPartials | ブール値の配列 | 対応するタイムスタンプに制限があるために適用されるフィルター。 |
| 割り当て済み/アイドル/稼働中コア | double の配列 | 対応するタイムスタンプで状態が異なるコアの数。 |
| 執行者 | ResourceUsageExecutor の 2 次元配列 | 対応するタイムスタンプにおける、エグゼキュータごとのコアとタスクの情報。 |
| ジョブ | ResourceUsageJob の 2 次元配列 | ジョブごとのタスク情報 (対応するタイムスタンプ)。 |
| 実行タスク | ResourceUsageExecutorJob の 2 次元配列 | 各実行者のジョブ情報（対応するタイムスタンプで）。 |
ResourceUsageExecutor
オブジェクト
Executor ごとのコアとタスクの情報
| 名前 | タイプ | 説明 |
|---|---|---|
| エグゼキューターID | ひも | 実行者ID |
| コアカウント | 整数 (int) | Executor で実行中のコアの数 |
| タスク数 | 整数 (int) | Executor で実行中のタスクの数 |
ResourceUsageJob
オブジェクト
ジョブごとのタスク情報
| 名前 | タイプ | 説明 |
|---|---|---|
| jobId | 整数 (int) | 職務 ID |
| タスク数 | 整数 (int) | ジョブの実行中のタスクの数。 |
リソース使用量実行ジョブ
オブジェクト
Executor ごとのジョブ情報
| 名前 | タイプ | 説明 |
|---|---|---|
| 実行者ID | ひも | 実行者ID |
| リソース使用ジョブ | ResourceUsageJob の配列 | Executor でタスクが実行されているジョブの実行。 |
リソース使用量のスナップショットを取得する
特定のタイムスタンプに最も近い時点でリソース使用状況情報を取得します。
インターフェイス
attemptId を使用する
GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks|sparkJobDefinitions|lakehouses/{itemId}/livySessions/{livyId}/applications/{appId}/{attemptId}/resourceUsage/{timestamp}
attemptId を使用しない
GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks|sparkJobDefinitions|lakehouses/{itemId}/livySessions/{livyId}/applications/{appId}/resourceUsage/{timestamp}
省略可能なパラメーターを使用します。
attemptId を使用する
GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks|sparkJobDefinitions|lakehouses/{itemId}/livySessions/{livyId}/applications/{appId}/{attemptId}/resourceUsage/{timestamp}?jobGroup={jobGroup}&jobLimit={jobLimit}&executorLimit={executorLimit}
attemptId を使用しない
GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks|sparkJobDefinitions|lakehouses/{itemId}/livySessions/{livyId}/applications/{appId}/resourceUsage/{timestamp}?jobGroup={jobGroup}&jobLimit={jobLimit}&executorLimit={executorLimit}
URI パラメーター
| 名前 | で | 必須 | タイプ | 説明 |
|---|---|---|---|---|
| ワークスペースID | 道 | 正しい | 文字列 UUID | ワークスペース ID。 |
| アイテムID | 道 | 正しい | string uuid | ノートブックまたは Spark ジョブ定義またはレイクハウスの項目 ID。 |
| livyId | 道 | 正しい | string uuid | Livy セッション ID。 |
| アプリID | 道 | 正しい | ひも | 例として、application_1111111111111_0001 のようなSpark アプリケーション ID。 |
| attemptId | 道 | いいえ | 整数 (int) | そのアプリケーション ID の試行 ID。 指定しない場合は、最後の試行の ID が使用されます。 |
| タイムスタンプ（時刻印） | 道 | 正しい | 長い | クエリする特定のタイムスタンプ |
| 職務グループ | 問い合わせ | いいえ | ひも | 指定された jobGroups 内のジョブのタイムラインのみを一覧表示します。 複数の jobGroup を次のように指定できます: ?jobGroup=1>jobGroup=2 |
| jobLimit | 問い合わせ | いいえ | 整数 (int) | 一覧表示するジョブの最大数 |
| 実行者制限 | 問い合わせ | いいえ | 整数 (int) | 一覧表示する Executor の最大数 |
リクエストの本文
無し
応答
| 名前 | タイプ | 説明 |
|---|---|---|
| 200 OK（正常に処理されました） | リソース使用状況スナップショット | 要求が正常に完了しました |
| 403 許可されていません | ユーザーが正しいアクセス許可を持っていない | |
| 404 見つかりません | - 項目 ID、アプリケーション ID、Livy ID が一致しません - リソース使用状況データを取得するには早すぎる |
例示
サンプルリクエスト
GET https://api.fabric.microsoft.com/v1/workspaces/aaaabbbb-0000-cccc-1111-dddd2222eeee/notebooks/11bb11bb-cc22-dd33-ee44-55ff55ff55ff/livySessions/0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c/applications/application_1111111111111_0001/1/resourceUsage/1745906291774
サンプル応答
状態コード:200
{
"queryTime" : 1745906291774,
"data" : {
"timestamp" : 1745906291774,
"isPartial" : false,
"allocatedCores" : 8.0,
"idleCores" : 0.0,
"runningCores" : 8.0,
"executors" : [ [ "1", 8.0, 12 ] ],
"jobs" : [ [ 9, 12 ] ],
"executorJobs" : [ [ "1", [ [ 9, 12 ] ] ] ]
}
}
定義
リソース使用状況スナップショット
オブジェクト
| 名前 | タイプ | 説明 |
|---|---|---|
| queryTime | 長い | 要求で指定されたタイムスタンプ |
| データ | リソース使用状況スナップショットデータ |
リソース使用量スナップショットデータ (ResourceUsageSnapshotData)
オブジェクト
| 名前 | タイプ | 説明 |
|---|---|---|
| タイムスタンプ（時刻印） | 長い | 指定されたタイムスタンプに最も近いタイム ポイントのタイムスタンプ。 |
| isPartial | ブール (bool) | タイムスタンプの制限により適用されるフィルター。 |
| 割り当て済み/アイドル中/稼働中のコア | ダブル | タイムスタンプの状態が異なるコアの数。 |
| 実行者 | ResourceUsageExecutor の配列 | タイムスタンプにおける各Executorのコアとタスク情報。 |
| ジョブ | ResourceUsageJob の配列 | タイムスタンプ時点でのジョブごとのタスク情報。 |
| エグゼキュータージョブ | ResourceUsageExecutorJob の配列 | Executorごとのジョブ情報（タイムスタンプ付き） |