资源使用 API

本文介绍如何获取 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 支持的标识

此 API 支持本节中列出的Microsoft 标识。

身份	支持
用户	是的
服务主体和托管标识	是的

获取资源使用时间线

以时间线的形式获取所有资源使用情况信息。

接口

具有 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 参数

名称	在	必选	类型	DESCRIPTION
工作区ID	路径	真 实	字符串 uuid	工作区 ID。
项目编号	路径	真 实	字符串 uuid	笔记本、Spark 作业定义或湖屋的项 ID。
livyId	路径	真 实	字符串 uuid	Livy 会话 ID。
应用程序ID	路径	真 实	字符串	Spark 应用程序 ID，如 application_1111111111111_0001。
attemptId	路径	假	整数 (int)	该应用程序 ID 对应的尝试 ID。 如果未指定，则使用上一次尝试的 ID。
工作组	查询	假	字符串	仅列出指定作业组中作业的时间线。 可以将多个 jobGroup 指定为：？jobGroup=1&jobGroup=2
任务限制	查询	假	整数 (int)	每个时间点要列出的最大作业数。
执行器限制	查询	假	整数 (int)	每个时间点要列出的最大执行器数。
执行者作业限制	查询	假	整数 (int)	要列出每个时间点的执行器作业信息的最大数量。
开始 / 结束	查询	假	长整型	要列出的时间点的下限和上限。

请求主体

没有

反应

名称	类型	DESCRIPTION
200 正常	ResourceUsageInfo	请求成功完成
400 错误的请求		参数无效。 开始大于结束
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

物体

名称	类型	DESCRIPTION
resourceUsageApiVersion	整数 (int)	资源使用情况 API 的版本。
持续时间	长整型	给定 Spark 应用程序的持续时间（以毫秒为单位）。
容量超出	布尔	当任务超过1万个的限制时，条件为真。 如果为 true，则数据中的所有属性均为空。
空闲时间	长整型	给定的 Spark 应用程序处于空闲状态（以毫秒为单位）的持续时间。
核心效率	翻倍	执行程序核心的概述使用率。
数据	ResourceUsageData

ResourceUsageData

物体

名称	类型	DESCRIPTION
时间戳	长数组
isPartials	布尔数组	由于时间戳限制而应用的任何筛选器。
分配的/空闲的/运行中的内核	双精度数组	具有不同状态的相应时间戳的核心计数。
执行程序	ResourceUsageExecutor 的二维数组	针对每个执行器的核心和任务信息在相应的时间戳。
工作	ResourceUsageJob 的二维数组	每个作业的任务信息及其对应的时间戳。
执行器任务	ResourceUsageExecutorJob 的二维数组	每个执行程序在相应时间戳的作业信息。

ResourceUsageExecutor

物体

每个执行器的核心和任务信息

名称	类型	DESCRIPTION
执行者ID	字符串	执行者 ID
核心计数	整数 (int)	执行器上正在运行的核心数量
taskCount	整数 (int)	执行者上运行的任务数

ResourceUsageJob

物体

每个作业任务信息

名称	类型	DESCRIPTION
jobId	整数 (int)	职位编号
taskCount	整数 (int)	作业中正在运行的任务数量。

ResourceUsageExecutorJob

物体

每个执行器的任务信息

名称	类型	DESCRIPTION
执行者ID	字符串	执行者 ID
资源使用作业	ResourceUsageJob 数组	运行在执行程序上运行任务的作业。

获取资源使用情况快照

获取最接近给定时间戳的时间点的资源使用情况信息。

接口

具有 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 参数

名称	在	必选	类型	DESCRIPTION
工作区ID	路径	真 实	字符串 uuid	工作区 ID。
项目编号	路径	真 实	字符串 uuid	笔记本、Spark 作业定义或湖屋的项 ID。
livyId	路径	真 实	字符串 uuid	Livy 会话 ID。
应用程序ID	路径	真 实	字符串	Spark 应用程序ID，如 application_1111111111111_0001。
attemptId	路径	假	整数 (int)	该应用程序 ID 对应的尝试 ID。 如果未指定，则使用上一次尝试的 ID。
时间戳	路径	真 实	长整型	要查询的特定时间戳
工作组	查询	假	字符串	仅列出在给定 jobGroups 中的作业时间线。 可以将多个 jobGroup 指定为：？jobGroup=1&jobGroup=2
任务限制	查询	假	整数 (int)	要列出的最大作业数
执行者上限	查询	假	整数 (int)	要列出的最大执行程序数

请求主体

没有

反应

名称	类型	DESCRIPTION
200 正常	资源使用快照	请求成功完成
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 ] ] ] ] 
   }
}  

定义

资源使用快照

物体

名称	类型	DESCRIPTION
queryTime	长整型	请求中指定的时间戳
数据	资源使用快照数据

ResourceUsageSnapshotData

物体

名称	类型	DESCRIPTION
时间戳	长整型	距离给定时间戳最近的时间点的时间戳。
是部分的	布尔	由于时间戳限制而应用的任何筛选器。
分配/空闲/运行核心	翻倍	时间戳中具有不同状态的核心计数。
执行程序	ResourceUsageExecutor 数组	每个执行器在时间戳上的核心和任务信息。
职位	ResourceUsageJob 数组	时间戳上的每作业任务信息。
执行器作业	ResourceUsageExecutorJob 的数组	基于每个执行器的作业信息在特定时间点。