合作伙伴可以使用此查询规范轻松地构建自定义查询，以便从分析表中提取数据。 查询可用于仅选择符合特定条件的所需列和指标。 语言规范的核心是可在其基础上编写自定义查询的数据集定义。
数据集
自定义查询可以针对具有列和指标的数据集而运行，其方式与针对某个具有表和列的数据库运行某些查询的方式相同。 可通过数据集 API 获取可用于构建查询的数据集的完整列表。
下面是显示为 JSON 的数据集的示例。
{
"datasetName": "Acquisitions",
"selectableColumns": [
"TitleId",
"ProductId",
"XboxProductId",
"ProductTypeName",
"TitleName",
"CatalogId",
"SandboxId",
"SkuId",
"SkuTypeName",
"SkuDisplayName",
"AvailabilityId",
"RegionName",
"CountryName",
"Market",
"PaymentType",
"StoreClientName",
"StoreClientCategory",
"ParentProductName",
"ParentProductId",
"XboxParentProductId",
"AcquisitionType",
"PurchaseTaxType",
"LocalCurrencyCode",
"SupportedPlatform",
"Age",
"Gender",
"OsVersion",
"DeviceType",
"DateStamp"
],
"availableMetrics": [
"PurchaseQuantity",
"PurchasePriceUSDAmount",
"PurchaseTaxUSDAmount",
"PurchasePriceLocalAmount",
"PurchaseTaxLocalAmount"
],
"availableDateRanges": [
"LAST_72_HOURS",
"LAST_30_DAYS",
"LAST_3_MONTHS",
"LAST_6_MONTHS",
"LAST_12_MONTHS",
"LAST_2_YEARS",
"LAST_3_YEARS",
"LAST_4_YEARS"
],
"columnFilters": {},
"aggregationToDateRangeMapping": {
"Hourly": "LAST_72_HOURS",
"Daily": "LAST_30_DAYS,LAST_3_MONTHS",
"Weekly": "LAST_6_MONTHS,LAST_12_MONTHS",
"Monthly": "LAST_2_YEARS,LAST_3_YEARS,LAST_4_YEARS"
},
}
数据集的各个部分
数据集名称类似于数据库表名称。 例如 Acquisitions。 数据集包含可选择的列列表，例如 AcquisitionType。
数据集还包含指标，指标类似于数据库中的聚合函数。 例如 PurchaseQuantity。
存在可以导出其范围内数据的固定时间跨度。
在数据集上构建查询
下面是演示如何提取各种类型的数据的示例查询。
| 查询 | 说明 |
|---|---|
从Acquisitions时间跨度中选择 AcquisitionType, ProductId LAST_3_MONTHS |
此查询获取过去三个月中的每个 AcquisitionType 及其对应的 ProductId。 |
按限制从 Acquisitions 订单中选择 ProductId, PurchaseQuantity PurchaseQuantity 10 |
此查询按“购买数量”的降序获取前 10 个产品。 |
查询规范
此部分介绍查询定义和结构。
语法参考
下表介绍了查询中使用的符号。
| 符号 | 含义 |
|---|---|
| ? | 可选 |
| * | 零个或更多 |
| + | 一个或更多 |
| | | 或/列表之一 |
查询定义
查询语句具有以下子句：SelectClause、、FromClause、WhereClause?OrderClause?、LimitClause?和TimeSpan?。
- SelectClause： SELECT
ColumOrMetricName (, ColumOrMetricName)*- ColumOrMetricName：在数据集中定义的列和指标
- FromClause： FROM
DatasetName- DatasetName：在数据集中定义的数据集名称
- WhereClause： WHERE
FilterCondition (**AND** FilterCondition)*- FilterCondition：
ColumOrMetricName Operator Value- 运算符：
= | > | < | >= | <= | != | LIKE | NOT LIKE | IN | NOT IN - 值：
Number | StringLiteral | MultiNumberList | MultiStringList- 数字：
-? [0-9]+ (. [0-9] [0-9]*)? - StringLiteral：
' [a-zA-Z0-9_]*' - MultiNumberList：
(Number (,Number)*) - MultiStringList：
(StringLiteral (,StringLiteral)*)
- 数字：
- 运算符：
- FilterCondition：
- OrderClause： ORDER BY
OrderCondition (,OrderCondition)*- OrderCondition：
ColumOrMetricName (**ASC** | **DESC**)*
- OrderCondition：
- LimitClause： LIMIT
[0-9]+ - TimeSpan： TIMESPAN
( TODAY | YESTERDAY | LAST_7_DAYS | LAST_14_DAYS | LAST_30_DAYS | LAST_90_DAYS | LAST_180_DAYS | LAST_365_DAYS | LAST_MONTH | LAST_3_MONTHS | LAST_6_MONTHS | LAST_1_YEAR)
查询结构
报表查询由多个部分组成：
- SELECT
- FROM
- WHERE
- ORDER BY
- LIMIT
- TIMESPAN
每个部分如下所述：
SELECT
查询的这一部分指定导出的列。 可以选择的列是数据集的 selectableColumns 和 availableMetrics 部分列出的字段。 如果所选字段列表中包含一个指标列，则会针对非对称列的每个非重复组合计算指标。
示例：
- 选择
ProductId, PurchaseQuantity
DISTINCT
在 SELECT 之后添加 DISTINCT 关键字可确保最终导出的数据没有任何重复行。 DISTINCT 关键字的工作原理与是否选择了指标列无关。
示例：
- SELECT DISTINCT
ProductId, PurchaseQuantity
FROM
查询的此部分指示需要从中导出数据的数据集。 此处提供的数据集名称需要是数据集 API 返回的有效数据集名称。
示例：
- 从
Acquisition - 从
Usage
WHERE
查询的此部分用于指定数据集上的筛选条件。 只有匹配此子句中列出的所有条件的行才会出现在最终导出的文件中。 筛选条件可以位于 selectableColumns 和 availableMetrics 中列出的任意列上。 仅当运算符为 IN 或 NOT IN 时，筛选条件中指定的值才能是数字列表或字符串列表。 这些值始终可以作为文本字符串提供，它们将转换为本机类型的列。 需要使用 AND 运算将多个筛选条件分开。
示例：
- 哪里
ProductId = '8da-86836-3c12dc7e62957d-4959-899260' - WHERE
TitleNameLIKE'%Grand%' - WHERE
CountryNameNOT IN(3243, 321, 2123) - 哪里
PurchaseQuantity =100 - 哪里
PurchaseQuantity ='100' - WHERE
ProductId ='7b487ac0-ce12-b732-dcd6-91a1e4e74a50'ANDCountryName =' Canada'
ORDER BY
查询的此部分指定已导出行的排序条件。 可以在其上定义排序的列需要来自数据集的 selectableColumns 和 availableMetrics。 如果没有指定的排序方向，则默认为 DESC 该列。 可以通过使用逗号来分隔条件，在多个列上定义排序。
示例：
- ORDER BY
PurchaseQuantityASC、TitleName (CC)DESC - ORDER BY
TitleNameASC，PurchaseQuantity
LIMIT
查询的这一部分指定导出的行数。 指定的数字必须是非零正整数。
TIMESPAN
查询的此部分指定一个持续时间，该时间范围内的数据需要导出。 可能的值应来自数据集定义中的 availableDateRanges 字段。
查询规范中的区分大小写
规范完全不区分大小写。 可以使用大写或小写指定预定义关键字、列名和值。
自定义查询示例
curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \
--header 'Authorization: \
--header 'Content-Type: application/json' \
--data '{
"Description": "Testing sample report",
"QueryId": "<id of the query>",
"ReportName": "Test Reports",
"executeNow": true,
"QueryStartTime": "2024-06-01",
"QueryEndTime": "2024-06-13"
}'
提供的日期范围必须遵循数据集的日期到聚合映射。 例如，如果将“last_30_days”映射到每日聚合，并且使用每日聚合指定超过 30 天的自定义日期范围，则会引发错误，指示此日期范围不支持每日聚合。 同样，如果“last_3_months”映射到每周聚合，则对于日期范围差异为 31 到 90 天，则必须使用每周聚合。