dx-app-analytics-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

App Analytics

When This Skill Owns the Task

此技能适用场景

Use

dx-app-analytics-query

when the work involves:

Creating
```
AppAnalyticsQueryRequest
```
records via the REST/sObject API
Configuring
```
AppAnalyticsSettings
```
via the Metadata API (simulation mode, opt-out)
Understanding the query lifecycle: New → Pending → Complete → Expired → Failed
Choosing between dataType values: PackageUsageSummary, PackageUsageLog, SubscriberSnapshot
File format and compression options for analytics downloads
Time-range filtering with startTime, endTime, availableSince
Troubleshooting failed or expired analytics queries

Delegate elsewhere when the user is:

Running standard CRM SOQL queries → platform-soql-query
Working with Data Cloud SQL or DMOs → data360-query
Building reports/dashboards on standard objects → reporting skills
Deploying or retrieving generic metadata XML → platform-metadata-deploy / retrieving-metadata

当工作涉及以下内容时，使用

dx-app-analytics-query

：

通过REST/sObject API创建
```
AppAnalyticsQueryRequest
```
记录
通过Metadata API配置
```
AppAnalyticsSettings
```
（模拟模式、退出选项）
了解查询生命周期：新建→待处理→完成→过期→失败
选择dataType取值：PackageUsageSummary、PackageUsageLog、SubscriberSnapshot
分析数据下载的文件格式与压缩选项
使用startTime、endTime、availableSince进行时间范围过滤
排查失败或过期的分析查询

当用户进行以下操作时，请转至其他技能：

运行标准CRM SOQL查询 → platform-soql-query
处理Data Cloud SQL或DMO → data360-query
基于标准对象构建报表/仪表板 → 报表技能
部署或检索通用元数据XML → platform-metadata-deploy / retrieving-metadata

Available Types

可用类型

AppAnalyticsQueryRequest (REST/sObject API)

AppAnalyticsQueryRequest（REST/sObject API）

An asynchronous query request that ISV partners use to retrieve usage analytics data for their managed packages from the ISV Intelligence Data Lake. Records are created via

POST /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest

and polled via

GET /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest/<id>

. The system processes the query and provides a presigned download URL upon completion.

Fields (14 properties):

Field	Type	Description
DataType	string (filterable)	Type of analytics data. Values: `PackageUsageSummary` , `PackageUsageLog` , `SubscriberSnapshot`
RequestState	string (filterable)	Processing status. Values: `New` , `Pending` , `Complete` , `Expired` , `Failed` , `NoData` , `Delivered`
StartTime	string	Start of time range for requested data
EndTime	string	End of time range. Should be set on an hour boundary
AvailableSince	string	Limits query to data indexed after this time (inclusive). Use for incremental retrieval
PackageIds	string	Comma-delimited list of managed package IDs (033-prefix)
OrganizationIds	string	Comma-delimited list of subscriber org IDs to filter results
DownloadUrl	string	Presigned URL for downloading results. Populated when RequestState is Complete
DownloadSize	long	Size in bytes of the result data file
DownloadExpirationTime	string	Time at which the download URL expires
FileType	string (filterable)	Output format. Values: `csv` , `parquet`
FileCompression	string (filterable)	Compression. Values: `none` , `gzip` , `snappy`
QuerySubmittedTime	string	Time the query was submitted to the Data Lake
ErrorMessage	string	Diagnostic message for failed queries

ISV合作伙伴用于从ISV智能数据湖检索其托管包使用分析数据的异步查询请求。通过

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	查询提交至数据湖的时间
ErrorMessage	string	失败查询的诊断信息

AppAnalyticsSettings (Metadata API)

AppAnalyticsSettings（Metadata API）

Configuration settings for ISV App Analytics that control simulation mode and opt-out behavior. Deployed via the Metadata API (

sf project deploy

) or Tooling API.

Fields (2 properties):

Field	Type	Description
enableSimulationMode	boolean (filterable)	When true, allows querying sample usage logs for integration testing without real subscriber data
enableAppAnalyticsOptOut	boolean (filterable)	When true, opts this subscriber org out of AppExchange App Analytics data collection

控制ISV App Analytics模拟模式和退出行为的配置设置。通过Metadata API（

sf project deploy

）或Tooling API部署。

字段（2个属性）：

字段	类型	描述
enableSimulationMode	boolean（可过滤）	设为true时，允许在集成测试中查询示例使用日志，无需真实订阅者数据
enableAppAnalyticsOptOut	boolean（可过滤）	设为true时，将此订阅者组织退出AppExchange App Analytics数据收集

Request Lifecycle

请求生命周期

text

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)

text

New → Pending → Complete → （在过期窗口内下载）
                         → Expired（下载URL不再有效）
                         → Delivered（确认已接收下载）
         → Failed（查看errorMessage）
         → NoData（无匹配查询条件的记录）

Common Patterns

常见模式

Query Package Usage Summary (last 7 days)

查询包使用汇总（最近7天）

Create a record via the REST API:

bash

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"
}

Poll the record via GET until

RequestState

reaches

Complete

, then download from

DownloadUrl

通过REST API创建记录：

bash

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

下载数据。

Incremental Data Retrieval

增量数据检索

Set

AvailableSince

to the timestamp of your last successful query completion to avoid re-downloading data you already have.

将

AvailableSince

设置为上次成功查询完成的时间戳，避免重新下载已获取的数据。

Enable Simulation Mode for Testing

启用模拟模式进行测试

Deploy

AppAnalyticsSettings

via Metadata API with

enableSimulationMode: true

to query sample data without real subscribers.

通过Metadata API部署

AppAnalyticsSettings

并设置

enableSimulationMode: true

，即可查询示例数据，无需真实订阅者。

High-Signal Gotchas

关键注意事项

AppAnalyticsQueryRequest is an sObject — create and poll records via the REST Data API (
```
/sobjects/AppAnalyticsQueryRequest
```
), NOT via Metadata API XML deployment.
AppAnalyticsQueryRequest does NOT have Apex triggers and does NOT flow through custom objects or Flows.
Download URLs expire — always check
```
DownloadExpirationTime
```
before attempting download.
```
EndTime
```
should be set on an hour boundary for consistent results.
```
AvailableSince
```
is inclusive — data indexed at exactly that timestamp will be included.
```
PackageIds
```
uses 033-prefix IDs, not 04t (package version) IDs.
Data is processed asynchronously by the ISV Intelligence Data Lake infrastructure. There is no synchronous query option.
```
FileType: parquet
```
with
```
FileCompression: snappy
```
gives optimal performance for large datasets.

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

Output Format

输出格式

text

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>

text

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>