获取订阅加载项购置

项目
01/15/2024

使用 Microsoft Store 分析 API 中的此方法，可获取使用给定日期范围和其他可选筛选器时应用的加载项订阅聚合购置数据。

先决条件

若要使用此方法，首先需要执行以下操作：

完成 Microsoft Store 分析 API 的所有先决条件（如果尚未这样做）。
获取 Azure AD 访问令牌，以供在此方法的请求标头中使用。获取访问令牌后，在它到期前，你有 60 分钟的使用时间。该令牌到期后，可以获取新的令牌。

请求

请求语法

方法	请求 URI
GET	`https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions`

请求头

标头	类型	说明
授权	字符串	必需。 Azure AD 访问令牌的格式为 Bearertoken<>。

请求参数

参数	类型	描述	必需
applicationId	string	要为其检索订阅加载项购置数据的应用的 Store ID。	是
subscriptionProductId	string	要为其检索购置数据的订阅加载项的 Store ID。如果不指定此值，此方法将返回指定应用的所有订阅加载项的购置数据。	否
startDate	date	要检索的订阅加载项购置数据日期范围中的开始日期。默认是当前日期。	否
endDate	date	要检索的订阅加载项购置数据日期范围中的结束日期。默认是当前日期。	否
top	int	要在请求中返回的数据行数。如果未指定，最大值和默认值为 100。当查询中存在多行数据时，响应正文中包含的下一个链接可用于请求下一页数据。	否
skip	int	要在查询中跳过的行数。使用此参数可以浏览较大的数据集。例如，top=100 和 skip=0，将检索前 100 行数据；top=100 和 skip=100，将检索之后的 100 行数据，依此类推。	否
filter	string	一条或多条用来筛选响应正文的语句。每条语句可以使用 eq 或 ne 运算符，多条语句还可以使用 and 或 or 进行组合。你可以在筛选器语句中指定以下字符串（它们对应于响应正文中的值）： date subscriptionProductName applicationName skuId market deviceType 下面是一个 filter 参数的示例：filter=date eq '2017-07-08'。	否
aggregationLevel	string	指定用于检索聚合数据的时间范围。可以是以下字符串之一：day、week 或 month。如果未指定，默认值为 day。	否
orderby	string	对每个订阅加载项购置的结果数据值进行排序的语句。语法为 orderby=field [order],field [order],...，其中 field 参数可以是以下字符串之一： date subscriptionProductName applicationName skuId market deviceType order 参数是可选的，可以是 asc 或 desc，用于指定每个字段的升序或降序排列。默认值为 asc。下面是一个 orderby 字符串的示例：orderby=date,market	否
groupby	string	仅将数据聚合应用于指定字段的语句。可以指定以下字段： date subscriptionProductName applicationName skuId market deviceType groupby 参数可以与 aggregationLevel 参数结合使用。例如：groupby=market&aggregationLevel=week	否

请求示例

以下示例演示如何获取订阅加载项购置数据。将 applicationId 值替换为应用的相应 Store ID。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=2017-07-07&endDate=2017-07-08 HTTP/1.1
Authorization: Bearer <your access token>

响应

响应正文

值	类型	说明
Value	array	包含聚合订阅加载项购置数据的对象数组。有关每个对象中的数据的详细信息，请参阅下面的订阅购置值部分。
@nextLink	string	如果存在其他数据页，则此字符串包含一个你可用来请求下一页数据的 URI。例如，当请求的 top 参数设置为 100，但查询的订阅加载项购置数据超过 100 行时，就会返回此值。
TotalCount	int	查询的数据结果中的行总数。

订阅购置值

Value 数组中的元素包含以下值。

Value	类型	说明
date	string	购置数据的日期范围内的第一个日期。如果请求指定了某一天，此值就是该日期。如果请求指定了一周、月或其他日期范围，此值是该日期范围内的第一个日期。
subscriptionProductId	string	要为其检索购置数据的订阅加载项的 Store ID。
subscriptionProductName	string	订阅加载项的显示名称。
applicationId	string	要为其检索订阅加载项购置数据的应用的 Store ID。
applicationName	string	应用的显示名称。
skuId	string	要为其检索购置数据的订阅加载项的 SKU ID。
deviceType	string	以下字符串之一，指定完成购置的设备类型：电脑 Phone Console-Xbox One Console-Xbox 系列 X IoT Holographic Unknown
market	string	发生购置的市场的 ISO 3166 国家/地区代码。
currencyCode	string	税前总销售额的 ISO 4217 格式的货币代码。
grossSalesBeforeTax	integer	按 currencyCode 值指定的本地货币总销售额。
totalActiveCount	integer	指定时间段内使用中的订阅总数。它等效于 goodStandingActiveCount、pendingGraceActiveCount、graceActiveCount 和 lockedActiveCount 值的总和。
totalChurnCount	integer	指定时间段内停用的订阅的总计数。它等效于 billingChurnCount、nonRenewalChurnCount、refundChurnCount、chargebackChurnCount、earlyChurnCount 和 otherChurnCount 值的总和。
newCount	integer	指定时间段内的新订阅购置的数量，包括试用。
renewCount	integer	指定时间段内的订阅续订数，包括用户启动的续订和自动续订。
goodStandingActiveCount	integer	指定时间段内处于使用中状态且到期日期 >= 查询的 endDate 值的订阅数。
pendingGraceActiveCount	integer	指定时间段内处于使用中状态，但存在计费故障，且订阅到期日期 >= 查询的 endDate 值的订阅数。
graceActiveCount	integer	指定时间段内处于使用中状态，但存在计费故障，且符合以下条件的订阅数：订阅到期日期 < 查询的 endDate 值。宽限期结束时间 >= endDate 值。
lockedActiveCount	integer	指定时间段内处于“催缴”状态（即，订阅即将过期，且 Microsoft 正尝试获取自动续订此订阅所需的款项）且符合以下条件的订阅数：订阅到期日期 < 查询的 endDate 值。宽限期结束时间 <= endDate 值。
billingChurnCount	integer	指定时间段内因无法处理计费而停用且以前处于催缴状态的订阅数。
nonRenewalChurnCount	integer	指定时间段内因未续订而停用的订阅数。
refundChurnCount	integer	指定时间段内因已退款而停用的订阅数。
chargebackChurnCount	integer	指定时间段内因退单拒付而停用的订阅数。
earlyChurnCount	integer	指定时间段内虽停用但状态仍良好的订阅数。
otherChurnCount	integer	指定时间段内因其他原因而停用的订阅数。

请求和响应示例

如下代码片段展示了这些请求的一些示例请求和 JSON 响应正文。

示例请求

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

示例响应

{
    "Value": [
        {
            "date": "2022-04-18",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "grossSalesBeforeTax": 3460656.260391250,
            "totalActiveCount": 20211321,
            "totalChurnCount": 5605,
            "newCount": 3810366,
            "renewCount": 12102044,
            "goodStandingActiveCount": 17893664,
            "pendingGraceActiveCount": 2255792,
            "graceActiveCount": 61833,
            "lockedActiveCount": 32,
            "billingChurnCount": 4,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 2717,
            "otherChurnCount": 2884
        },
        {
            "date": "2022-04-18",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Unknown",
            "grossSalesBeforeTax": 2342.580615228,
            "totalActiveCount": 50550,
            "totalChurnCount": 7,
            "newCount": 8312,
            "renewCount": 31446,
            "goodStandingActiveCount": 44047,
            "pendingGraceActiveCount": 6503,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 5,
            "otherChurnCount": 2
        }
    ],
    "TotalCount": 2
}

示例请求

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=12/19/2021&endDate=04/20/2022&top=10&skip=0&orderby=date&groupby=date,subscriptionProductName,applicationName,skuId,market,deviceType&aggregationLevel=week
HTTP/1.1
Authorization: Bearer <your access token>

示例响应

{
    "Value": [
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "IT",
            "deviceType": "Console-Xbox One",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 0,
            "totalChurnCount": 0,
            "newCount": 2,
            "renewCount": 0,
            "goodStandingActiveCount": 0,
            "pendingGraceActiveCount": 0,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        },
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "NO",
            "deviceType": "Unknown",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 0,
            "totalChurnCount": 0,
            "newCount": 0,
            "renewCount": 13,
            "goodStandingActiveCount": 0,
            "pendingGraceActiveCount": 0,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        },
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.02",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "CA",
            "deviceType": "Unknown",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 152,
            "totalChurnCount": 0,
            "newCount": 0,
            "renewCount": 270,
            "goodStandingActiveCount": 133,
            "pendingGraceActiveCount": 19,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        }
    ],
    "TotalCount": 3
}

通过

获取订阅加载项购置

先决条件

请求

请求语法

请求头

请求参数

请求示例

响应

响应正文

订阅购置值

请求和响应示例

示例请求

示例响应

示例请求

示例响应

反馈

其他资源

通过

获取订阅加载项购置

先决条件

请求

请求语法

请求头

请求参数

请求示例

响应

响应正文

订阅购置值

请求和响应示例

示例请求

示例响应

示例请求

示例响应

相关主题

反馈

其他资源