dx-app-analytics-use

应用分析

此技能负责处理的任务

当工作涉及以下内容时，请使用 dx-app-analytics-use：

• 通过 REST/sObject API 创建 AppAnalyticsQueryRequest 记录
• 通过 Metadata API 配置 AppAnalyticsSettings（模拟模式、选择退出）
• 了解查询生命周期：New → Pending → Complete → Expired → Failed
• 在 dataType 值之间进行选择：PackageUsageSummary、PackageUsageLog、SubscriberSnapshot
• 分析数据下载的文件格式和压缩选项
• 使用 startTime、endTime、availableSince 进行时间范围筛选
• 排查失败或过期的分析查询

以下情况请委派给其他技能：

• 运行标准 CRM SOQL 查询 → querying-soql
• 使用 Data Cloud SQL 或 DMO → retrieving-datacloud
• 基于标准对象构建报表/仪表板 → reporting skills
• 部署或检索通用 Metadata XML → deploying-metadata / retrieving-metadata

---

可用类型

AppAnalyticsQueryRequest（REST/sObject API）

异步查询请求，ISV 合作伙伴使用它从 ISV Intelligence Data Lake 检索其托管包的使用情况分析数据。通过 POST /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest 创建记录，并通过 GET /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest/<id> 轮询。系统会处理查询，并在完成后提供预签名下载 URL。

字段（14 个属性）：

字段	类型	说明
DataType	string（可筛选）	分析数据的类型。值：PackageUsageSummary、PackageUsageLog、SubscriberSnapshot
RequestState	string（可筛选）	处理状态。值：New、Pending、Complete、Expired、Failed、NoData、Delivered
StartTime	string	请求数据的时间范围起点
EndTime	string	时间范围终点。应设置为整点
AvailableSince	string	将查询限制为此时间之后（含此时间）编入索引的数据。用于增量检索
PackageIds	string	以逗号分隔的托管包 ID 列表（前缀为 033）
OrganizationIds	string	用于筛选结果的订阅方组织 ID 列表，以逗号分隔
DownloadUrl	string	用于下载结果的预签名 URL。RequestState 为 Complete 时填充
DownloadSize	long	结果数据文件的大小（字节）
DownloadExpirationTime	string	下载 URL 的过期时间
FileType	string（可筛选）	输出格式。值：csv、parquet
FileCompression	string（可筛选）	压缩方式。值：none、gzip、snappy
QuerySubmittedTime	string	查询提交到 Data Lake 的时间
ErrorMessage	string	查询失败时的诊断消息

AppAnalyticsSettings（Metadata API）

用于控制模拟模式和选择退出行为的 ISV App Analytics 配置设置。通过 Metadata API（sf project deploy）或 Tooling API 部署。

字段（2 个属性）：

字段	类型	说明
enableSimulationMode	boolean（可筛选）	为 true 时，可查询示例使用日志以进行集成测试，无需真实订阅方数据
enableAppAnalyticsOptOut	boolean（可筛选）	为 true 时，此订阅方组织将退出 AppExchange App Analytics 数据收集

---

请求生命周期

New → Pending → Complete → (download within expiration window)
                         → Expired (download URL no longer valid)
                         → Delivered (download confirmed received)
         → Failed (check errorMessage)
         → NoData (no matching records for the criteria)

---

常见模式

查询软件包使用情况摘要（最近 7 天）

通过 REST API 创建记录：

POST /services/data/v60.0/sobjects/AppAnalyticsQueryRequest
Content-Type: application/json

{
  "DataType": "PackageUsageSummary",
  "StartTime": "<7-days-ago>T00:00:00Z",
  "EndTime": "<today-on-hour-boundary>T00:00:00Z",
  "PackageIds": "033XXXXXXXXXXXX",
  "FileType": "csv",
  "FileCompression": "gzip"
}

通过 GET 轮询记录，直到 RequestState 达到 Complete，然后从 DownloadUrl 下载。

增量数据检索

将 AvailableSince 设为上次成功查询完成的时间戳，以避免重新下载已有数据。

启用模拟模式进行测试

通过 Metadata API 部署 AppAnalyticsSettings，并将 enableSimulationMode 设为 true，以查询示例数据，无需真实订阅方。

---

高信号注意事项

• AppAnalyticsQueryRequest 是一个 sObject — 通过 REST Data API（/sobjects/AppAnalyticsQueryRequest）创建和轮询记录，而不是通过 Metadata API XML 部署。
• AppAnalyticsQueryRequest 没有 Apex 触发器，也不会流经自定义对象或 Flows。
• 下载 URL 会过期 — 尝试下载前务必检查 DownloadExpirationTime。
• 为确保结果一致，EndTime 应设置为整点。
• AvailableSince 是包含边界的 — 恰好在该时间戳编入索引的数据也会包含在内。
• PackageIds 使用 033 前缀的 ID，而不是 04t（包版本）ID。
• 数据由 ISV Intelligence Data Lake 基础设施异步处理。没有同步查询选项。
• 对于大型数据集，使用 FileType: parquet 和 FileCompression: snappy 可获得最佳性能。

---

输出格式

Analytics task: <query / configure / troubleshoot>
Data type: <PackageUsageSummary / PackageUsageLog / SubscriberSnapshot>
Package IDs: <033-prefixed IDs>
Time range: <startTime> to <endTime>
File format: <csv|parquet> / <none|gzip|snappy>
Request state: <current state>
Next step: <poll for completion / download / investigate failure>