dx-app-analytics-query

应用分析

此技能适用的任务

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

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

以下情况请转交其他技能：

• 运行标准 CRM SOQL 查询 → platform-soql-query
• 使用 Data Cloud SQL 或 DMO → retrieving-datacloud
• 基于标准对象构建报表/仪表板 → reporting skills
• 部署或检索通用元数据 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>