获取订阅加载项购置Get subscription add-on acquisitions

使用 Microsoft Store analytics API 中的此方法获取给定日期范围内的应用程序外接程序订阅的聚合获取数据,以及其他可选筛选器。Use this method in the Microsoft Store analytics API to get aggregate acquisition data for add-on subscriptions for your app during a given date range and other optional filters.

必备条件Prerequisites

若要使用此方法,首先需要执行以下操作:To use this method, you need to first do the following:

  • 完成 Microsoft Store 分析 API 的所有先决条件(如果尚未这样做)。If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • 获取 Azure AD 访问令牌,以供在此方法的请求标头中使用。Obtain an Azure AD access token to use in the request header for this method. 获取访问令牌后,在它到期前,你有 60 分钟的使用时间。After you obtain an access token, you have 60 minutes to use it before it expires. 该令牌到期后,可以获取新的令牌。After the token expires, you can obtain a new one.

请求Request

请求语法Request syntax

方法Method 请求 URIRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions

请求头Request header

标头Header 类型Type 描述Description
授权Authorization 字符串string 必需。Required. Azure AD 访问令牌的格式为 Bearer <token> 。The Azure AD access token in the form Bearer <token>.

请求参数Request parameters

参数Parameter 类型Type 说明Description 必需Required
applicationIdapplicationId 字符串string 要为其检索订阅外接程序获取数据的应用的存储 IDThe Store ID of the app for which you want to retrieve subscription add-on acquisition data. Yes
subscriptionProductIdsubscriptionProductId stringstring 要检索其获取数据的订阅外接程序的存储 IDThe Store ID of the subscription add-on for which you want to retrieve acquisition data. 如果未指定此值,则此方法将返回指定应用的所有订阅外接程序的获取数据。If you do not specify this value, this method returns acquisition data for all subscription add-ons for the specified app. No
startDatestartDate datedate 要检索的订阅外接程序购买数据的日期范围的开始日期。The start date in the date range of subscription add-on acquisition data to retrieve. 默认值为当前日期。The default is the current date. No
endDateendDate 日期date 要检索的订阅外接程序购买数据的日期范围的结束日期。The end date in the date range of subscription add-on acquisition data to retrieve. 默认值为当前日期。The default is the current date. No
toptop intint 要在请求中返回的数据行数。The number of rows of data to return in the request. 如果未指定,最大值和默认值为 100。The maximum value and the default value if not specified is 100. 当查询中存在多行数据时,响应正文中包含的下一个链接可用于请求下一页数据。If there are more rows in the query, the response body includes a next link that you can use to request the next page of data. No
skipskip intint 要在查询中跳过的行数。The number of rows to skip in the query. 使用此参数可以浏览较大的数据集。Use this parameter to page through large data sets. 例如,top=100 和 skip=0,将检索前 100 行数据;top=100 和 skip=100,将检索之后的 100 行数据,依此类推。For example, top=100 and skip=0 retrieves the first 100 rows of data, top=100 and skip=100 retrieves the next 100 rows of data, and so on. No
filterfilter stringstring 筛选响应正文的一条或多条语句。One or more statements that filter the response body. 每条语句可以使用 eqne 运算符,多条语句还可以使用 andor 进行组合。Each statement can use the eq or ne operators, and statements can be combined using and or or. 您可以在筛选语句中指定以下字符串(这些字符串对应于响应正文中的值):You can specify the following strings in the filter statements (these correspond to values in the response body):
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • marketmarket
  • deviceTypedeviceType

下面是一个示例筛选器参数: filter = date eq ' 2017-07-08 'Here is an example filter parameter: filter=date eq '2017-07-08'.

No
aggregationLevelaggregationLevel stringstring 指定用于检索聚合数据的时间范围。Specifies the time range for which to retrieve aggregate data. 可以是以下字符串之一:dayweekmonthCan be one of the following strings: day, week, or month. 如果未指定,默认值为 dayIf unspecified, the default is day. No
orderbyorderby stringstring 对每个订阅外接程序购买的结果数据值进行排序的语句。A statement that orders the result data values for each subscription add-on acquisition. 语法为 orderby=field [order],field [order],...,其中 field 参数可以是以下字符串之一:The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • marketmarket
  • deviceTypedeviceType

order 参数是可选的,可以是 ascdesc,用于指定每个字段的升序或降序排列。The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. 默认值为ascThe default is asc.

下面是一个 orderby 字符串的示例:orderby=date,marketHere is an example orderby string: orderby=date,market

No
groupbygroupby stringstring 仅将数据聚合应用于指定字段的语句。A statement that applies data aggregation only to the specified fields. 可以指定的字段如下所示:You can specify the following fields:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • marketmarket
  • deviceTypedeviceType

groupby 参数可以与 aggregationLevel 参数结合使用。The groupby parameter can be used with the aggregationLevel parameter. 例如: groupby = marketplace & aggregationLevel = weekFor example: groupby=market&aggregationLevel=week

No

请求示例Request example

下面的示例演示如何获取订阅外接程序获取数据。The following examples demonstrates how to get subscription add-on acquisition data. 用应用程序的相应存储区 ID 替换applicationId值。Replace the applicationId value with the appropriate Store ID for your app.

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>

响应Response

响应正文Response body

Value 类型Type 说明Description
ValueValue arrayarray 对象的数组,其中包含聚合订阅附加获取数据。An array of objects that contain aggregate subscription add-on acquisition data. 有关每个对象中的数据的详细信息,请参阅下面的 "订阅获取值" 一节。For more information about the data in each object, see the subscription acquisition values section below.
@nextLink stringstring 如果存在其他数据页,则此字符串包含一个你可用来请求下一页数据的 URI。If there are additional pages of data, this string contains a URI that you can use to request the next page of data. 例如,如果请求的top参数设置为100,但查询的订阅外接程序获取数据超过了100行,则会返回此值。For example, this value is returned if the top parameter of the request is set to 100 but there are more than 100 rows of subscription add-on acquisition data for the query.
TotalCountTotalCount intint 查询的数据结果中的行总数。The total number of rows in the data result for the query.

订阅获取值Subscription acquisition values

Value 数组中的元素包含以下值。Elements in the Value array contain the following values.

Value 类型Type 说明Description
datedate stringstring 购置数据的日期范围内的第一个日期。The first date in the date range for the acquisition data. 如果请求指定了某一天,此值就是该日期。If the request specified a single day, this value is that date. 如果请求指定了一周、月或其他日期范围,此值是该日期范围内的第一个日期。If the request specified a week, month, or other date range, this value is the first date in that date range.
subscriptionProductIdsubscriptionProductId stringstring 要为其检索获取数据的订阅外接程序的存储 IDThe Store ID of the subscription add-on for which you are retrieving acquisition data.
subscriptionProductNamesubscriptionProductName stringstring 订阅外接程序的显示名称。The display name of the subscription add-on.
applicationIdapplicationId 字符串string 要为其检索订阅外接程序获取数据的应用的存储 IDThe Store ID of the app for which you are retrieving subscription add-on acquisition data.
applicationNameapplicationName stringstring 应用的显示名称。The display name of the app.
skuIdskuId stringstring 要为其检索获取数据的订阅外接程序的SKU ID。The ID of the SKU of the subscription add-on for which you are retrieving acquisition data.
deviceTypedeviceType stringstring 用于指定完成购置的设备类型的以下字符串之一:One of the following strings that specifies the type of device that completed the acquisition:
  • PCPC
  • 移动Phone
  • 控制台-Xbox OneConsole-Xbox One
  • 控制台-Xbox 系列 XConsole-Xbox Series X
  • IoTIoT
  • HolographicHolographic
  • UnknownUnknown
marketmarket stringstring 发生购置行为的市场的 ISO 3166 国家/地区代码。The ISO 3166 country code of the market where the acquisition occurred.
currencyCodecurrencyCode stringstring 税前总销售额的 ISO 4217 格式的货币代码。The currency code in ISO 4217 format for gross sales before taxes.
grossSalesBeforeTaxgrossSalesBeforeTax integerinteger currencyCode值指定的本地货币的总销售额。The gross sales in the local currency specified by the currencyCode value.
totalActiveCounttotalActiveCount integerinteger 指定时间段内活动订阅总数。The number of total active subscriptions during the specified time period. 这等效于goodStandingActiveCountpendingGraceActiveCountgraceActiveCountlockedActiveCount值的总和。This is equivalent to the sum of the goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount, and lockedActiveCount values.
totalChurnCounttotalChurnCount integerinteger 在指定的时间段内停用的订阅的总计数。The total count of subscriptions that were deactivated during the specified time period. 这等效于billingChurnCountnonRenewalChurnCountrefundChurnCountchargebackChurnCountearlyChurnCountotherChurnCount值的总和。This is equivalent to the sum of the billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount, and otherChurnCount values.
newCountnewCount integerinteger 指定时间段内新的订阅收购数量,包括试验。The number of new subscription acquisitions during the specified time period, including trials.
renewCountrenewCount integerinteger 指定时间段内的订阅续订数,包括用户启动的续订和自动续订。The number of subscription renewals during the specified time period, including user-initiated renewals and automatic renewals.
goodStandingActiveCountgoodStandingActiveCount integerinteger 指定时间段内处于活动状态的订阅的数目,以及到期日期 >为查询的结束值。The number of subscriptions that were active during the specified time period and where the expiration date is >= the endDate value for the query.
pendingGraceActiveCountpendingGraceActiveCount integerinteger 在指定的时间段内处于活动状态但有计费失败的订阅数,以及订阅到期日期 >= 查询的终止值。The number of subscriptions that were active during the specified time period but had a billing failure, and where the subscription expiration date is >= the endDate value for the query.
graceActiveCountgraceActiveCount integerinteger 在指定的时间段内处于活动状态但有计费失败的订阅数,以及:The number of subscriptions that were active during the specified time period but had a billing failure, and where:
  • 订阅到期日期为查询 <终止日期值。The subscription expiration date is < the endDate value for the query.
  • 宽限期的结束时间为 >=终止点值。The end of the grace period is >= the endDate value.
lockedActiveCountlockedActiveCount integerinteger 在指定的时间段内,纠缠中的订阅数(即,订阅即将过期,Microsoft 尝试获取资金以自动续订订阅)和位置:The number of subscriptions that were in dunning (that is, the subscription is nearing expiration and Microsoft is trying to acquire funds to automatically renew the subscription) during the specified time period, and where:
  • 订阅到期日期为查询 <终止日期值。The subscription expiration date is < the endDate value for the query.
  • 宽限期的结束时间为 <=终止点值。The end of the grace period is <= the endDate value.
billingChurnCountbillingChurnCount integerinteger 在指定的时间段内因处理计费费用失败,以及订阅之前在纠缠中停用的订阅数。The number of subscriptions that were deactivated during the specified time period because of a failure to process a billing charge and where the subscriptions were previously in dunning.
nonRenewalChurnCountnonRenewalChurnCount integerinteger 在指定的时间段内因未续订而停用的订阅数。The number of subscriptions that were deactivated during the specified time period because they were not renewed.
refundChurnCountrefundChurnCount integerinteger 在指定的时间段内因被退回而停用的订阅数。The number of subscriptions that were deactivated during the specified time period because they were refunded.
chargebackChurnCountchargebackChurnCount integerinteger 由于计费而在指定时间段内停用的订阅数。The number of subscriptions that were deactivated during the specified time period because of a chargeback.
earlyChurnCountearlyChurnCount integerinteger 处于良好状态的指定时间段内停用的订阅数。The number of subscriptions that were deactivated during the specified time period while they were in good standing.
otherChurnCountotherChurnCount integerinteger 出于其他原因在指定的时间段内停用的订阅数。The number of subscriptions that were deactivated during the specified time period for other reasons.

响应示例Response example

以下示例举例说明此请求的 JSON 响应正文。The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9KDLGHH6R365",
      "subscriptionProductName": "Contoso App Subscription with One Month Free Trial",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "Unknown",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    },
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9JJFDHG4R478",
      "subscriptionProductName": "Contoso App Monthly Subscription",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "US",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    }
  ],
  "@nextLink": null,
  "TotalCount": 2
}