Salesforce Reports and Dashboards API via Apex
Salesforce Reports and Dashboards REST API 通过 Apex 提供对报表数据的编程访问——集成到自定义对象、构建可视化仪表板、自动化报表任务。支持运行表格/摘要/矩阵报表（同步或异步）、动态过滤数据、查询报表数据和元数据。需要组织 API 已启用。
API 概览与能力
核心能力：运行报表同步或异步、过滤特定数据、查询报表元数据（报表类型/字段/过滤器）、获取 Fact Map（报表摘要和记录级数据）、列出报表异步运行实例（最多 2000 条）、解码不同报表格式的 Fact Map 键模式、仪表板刷新和数据查询。可以触发 Chatter 帖子展示季度业绩快照。
要求与限制
通用限制：不支持交叉过滤器/标准报表过滤器/按行数限制过滤。历史追踪仅矩阵报表支持——订阅不支持。最多 100 个字段选为列、最多 200 条最近查看报表、最多 20 个自定义字段过滤器。返回最多前 2,000 行——使用过滤器缩小结果。速率限制：500 同步报表运行/小时、最多 20 个同步请求同时处理、1,200 异步请求/小时、异步结果 24 小时内可用。200 仪表板刷新/小时、5,000 仪表板结果请求/小时。
Apex 特定限制与测试注意事项
Apex 特定限制：异步报表调用不允许在 Batch Apex 中、报表调用不允许在触发器中、无 Apex 方法列出最近运行的报表。同步报表运行处理的行数计入 SOQL 50,000 行 Governor Limit——异步报表不受此限制。自动流程用户从 Apex 测试类运行报表时仅返回必填自定义字段。
测试注意事项：Apex 测试中报表运行始终忽略 SeeAllData 注解——结果包含测试未创建的已有数据。无法禁用报表执行的 SeeAllData——使用过滤器限制结果。异步报表运行在 Test.stopTest() 之后才执行——在 stopTest 后验证结果。报表构建器中适用于报表的限制同样适用于 API。
运行报表
使用 Reports.ReportManager 类——同步运行（runReport(reportId, includeDetails)——快速报表推荐）和异步运行（runAsyncReport(reportId, includeDetails)——长时间报表推荐：更低超时风险）。报表可带或不带详细信息运行——返回值与 UI 中相同数量记录。
// 同步运行
Reports.ReportResults results = Reports.ReportManager.runReport(reportId, true);
// 异步运行——返回 instanceId
Reports.ReportInstance instance = Reports.ReportManager.runAsyncReport(reportId, true);
// 后续获取结果
Reports.ReportResults asyncResults = Reports.ReportManager.getAsyncReportResults(instance.getId());列出报表异步运行实例
使用 Reports.ReportManager.getAsyncReportInstances(reportId) 获取报表的异步运行实例列表——最多 2,000 条。每个实例包含状态（New/Processing/Completed/Error）、完成时间、所有者信息。用于监控长时间报表的运行历史和状态追踪。
获取报表元数据
Reports.ReportManager.describeReport(reportId) 返回 Reports.ReportDescribeResult——包含：报表名称/描述/类型（Tabular/Summary/Matrix）、ReportType（报表类型——主对象和关联对象信息）、字段信息（分组字段/汇总字段/过滤字段——含字段 API 名称和标签）、过滤器列表（已配置的报表级过滤器）、货币代码。用于动态构建报表 UI 或验证字段可用性。
获取报表数据（Fact Map）
Reports.ReportResults.getFactMap() 返回 Map<String, Reports.ReportFact>——报表摘要和记录级数据值。每个 Fact Map 条目含 getRows()（行数据——每行含 getDataCells() 列表——每个数据单元格有 label 和 value）和 getAggregates()（汇总值列表——对应列的 GROUP BY 聚合函数如 SUM/AVG/COUNT/MIN/MAX）。
Fact Map 键格式取决于报表类型：Tabular——T!T（Grand Total）/ 0!T（第一行+总计）。Summary——最外层分组：GroupingValue!T + 内层分组键 + 总计 T!T（如 Industry!Technology → 表示 Technology 行业分组）。Matrix——行分组键 + 列分组键（如 RowGroup!ColGroup——行列交叉点的值）。
过滤报表
通过设置报表运行时的元数据过滤器动态获取特定结果——使用 Reports.ReportMetadata + Reports.ReportFilter。最多添加 20 个自定义字段过滤器。过滤器属性：column（字段 API 名）、operator（equals/notEquals/lessThan/greaterThan/contains/notContain/startsWith）、value（过滤值）。支持日期范围过滤——设置 durationValue 和 startDate/endDate。过滤器在 runReport(reportId, metadata, includeDetails) 的 metadata 参数中传递。
Reports.ReportDescribeResult describe = Reports.ReportManager.describeReport(reportId);
Reports.ReportMetadata metadata = describe.getReportMetadata();
metadata.getReportFilters().add(
new Reports.ReportFilter('Industry', 'equals', 'Technology'));
Reports.ReportResults filtered = Reports.ReportManager.runReport(reportId, metadata, true);解码 Fact Map
三种报表格式的 Fact Map 键模式详解：Tabular——单层键 T!T 为总计行；0!T/1!T 等为行号+总计。遍历所有行键获取每行数据。Summary——多层嵌套键——最外层分组值（如 Industry=Technology → 键为 Technology!T）+ 内层分组（如 Technology 下的 Country=USA → Technology!USA）+ 总计 T!T。递归遍历键的层级结构。Matrix——行列交叉键——格式 RowGroupKey!ColGroupKey——每个交叉点含该行列组合的汇总数据。需要同时解析行键和列键维度。
测试报表代码
报表 API 代码需测试覆盖——测试中报表运行始终返回已有数据（SeeAllData 被忽略——无法禁用）。使用过滤器限制测试结果范围（如按特定记录名过滤可预测的结果集）。异步报表在 Test.stopTest() 后执行——在 stopTest 后调用 getAsyncReportResults(instanceId) 验证。准备可预测的测试数据——运行报表——验证 Fact Map 的汇总值和行数据与期望值匹配。
Salesforce Sites 与 URL 重写
Salesforce Sites 构建自定义页面和 Web 应用——继承平台功能（分析/工作流/审批/可编程逻辑）。URL Rewriting：实现 Site.UrlRewriter 接口类——mapRequestUrl(Site.UrlRewriter.Url) 映射传入 URL 到 Salesforce 页面——generateUrlFor(Site.UrlRewriter.Url[]) 生成用户友好 URL。在 Setup → Sites → URL Rewriter Class 配置类。规则：仅作用于站点上下文中的页面、不能重写到外部域、传入 URL 已解码。支持自定义错误页面和友好 URL 结构。
Support Classes
Business Hours：BusinessHours 类计算工作时间——add(businessHoursId, startDate, intervalMs) 添加毫秒到开始日期跳过非工作时间；diff(businessHoursId, startDate, endDate) 返回两个日期间工作毫秒差；isWithin(businessHoursId, targetDate) 检查日期是否在工作时间内。支持多组工作时间定义（不同时区/节假日）。Cases：使用 Case sObject 标准 CRUD——CaseComment（案例评论）/ EmailMessage + EmailMessageRelation（案例邮件）/ Case.Status + Case.Priority 管理流程。案例自动升级规则在 DML 操作时自动触发。
Territory Management 2.0
Support for Territory2 和 UserTerritory2Association 标准对象的触发器——自动化区域管理记录变化相关操作。典型用例：区域负责人变更时自动更新相关记录所有权、根据区域层级自动分配新记录、集成外部区域管理系统。在触发器中通过 Trigger.new/Trigger.old 访问 Territory2 和 UserTerritory2Association 记录——实现企业级销售区域自动化和治理。
Reports API 将数据洞察集成到应用中，Sites 和 URL 重写构建自定义 Web 体验，Support Classes 和 Territory Management 增强服务自动化和销售区域管理。