获取每日应用使用情况Get daily app usage

在给定的日期范围(仅限最近90天)和其他可选筛选器中,使用 Microsoft Store analytics API 中的此方法以 JSON 格式获取应用程序的聚合使用情况数据(不包括 Xbox 多人参与数据)。Use this method in the Microsoft Store analytics API to get aggregate usage data (not including Xbox multiplayer) in JSON format for an application during a given date range (last 90 days only) and other optional filters. 合作伙伴中心的使用情况报告中也提供了此信息。This information is also available in the Usage report in Partner Center.

必备条件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/usagedaily

请求头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 要检索评价数据的应用的 Store IDThe Store ID of the app for which you want to retrieve review data. Yes
startDatestartDate datedate 要检索的评价数据日期范围中的开始日期。The start date in the date range of review data to retrieve. 默认值为当前日期。The default is the current date. No
endDateendDate 日期date 要检索的评价数据日期范围中的结束日期。The end date in the date range of review data to retrieve. 默认值为当前日期。The default is the current date. No
toptop intint 要在请求中返回的数据行数。The number of rows of data to return in the request. 如果未指定,最大值和默认值为 10000。The maximum value and the default value if not specified is 10000. 当查询中存在多行数据时,响应正文中包含的下一个链接可用于请求下一页数据。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=10000 和 skip=0,将检索前 10000 行数据;top=10000 和 skip=10000,将检索之后的 10000 行数据,依此类推。For example, top=10000 and skip=0 retrieves the first 10000 rows of data, top=10000 and skip=10000 retrieves the next 10000 rows of data, and so on. No
filterfilter stringstring 在响应中筛选行的一条或多条语句。One or more statements that filter the rows in the response. 每条语句包含的响应正文中的字段名称和值使用 eq 或 ne 运算符进行关联,并且语句可以使用 and 或 or 进行组合。Each statement contains a field name from the response body and value that are associated with the eq or ne operators, and statements can be combined using and or or. filter 参数中的字符串值必须使用单引号引起来。String values must be surrounded by single quotes in the filter parameter. 可以指定响应正文中的以下字段:You can specify the following fields from the response body:
  • marketmarket
  • deviceTypedeviceType
  • packageVersionpackageVersion
No
orderbyorderby stringstring 对结果数据值进行排序的语句。A statement that orders the result data values. 语法为 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
  • applicationIdapplicationId
  • applicationNameapplicationName
  • marketmarket
  • packageVersionpackageVersion
  • deviceTypedeviceType
  • subscriptionNamesubscriptionName
  • dailySessionCountdailySessionCount
  • engagementDurationMinutesengagementDurationMinutes
  • dailyActiveUsersdailyActiveUsers
  • dailyActiveDevicesdailyActiveDevices
  • dailyNewUsersdailyNewUsers
  • monthlyActiveUsersmonthlyActiveUsers
  • monthlyActiveDevicesmonthlyActiveDevices
  • monthlyNewUsersmonthlyNewUsers

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 from the response body:
  • applicationNameapplicationName
  • subscriptionNamesubscriptionName
  • deviceTypedeviceType
  • packageVersionpackageVersion
  • marketmarket
  • datedate

返回的数据行会包含 groupby 参数中指定的字段,以及以下字段:The returned data rows will contain the fields specified in the groupby parameter as well as the following:

  • applicationIdapplicationId
  • subscriptionNamesubscriptionName
  • dailySessionCountdailySessionCount
  • engagementDurationMinutesengagementDurationMinutes
  • dailyActiveUsersdailyActiveUsers
  • dailyActiveDevicesdailyActiveDevices
  • dailyNewUsersdailyNewUsers
  • monthlyActiveUsersmonthlyActiveUsers
  • monthlyActiveDevicesmonthlyActiveDevices
  • monthlyNewUsersmonthlyNewUsers

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

No

请求示例Request example

下面的示例演示了获取每日应用使用数据的请求。The following example demonstrates a request for getting daily app usage data. applicationId 值替换为你的应用的 Store ID。Replace the applicationId value with the Store ID for your app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagedaily?applicationId=XXXXXXXXXXXX&startDate=2018-08-10&endDate=2018-08-14 HTTP/1.1
Authorization: Bearer <your access token>

响应Response

响应正文Response body

Value 类型Type 说明Description
ValueValue arrayarray 包含聚合使用情况数据的对象的数组。An array of objects that contain aggregate usage data. 有关每个对象中的数据的详细信息,请参阅下表。For more information about the data in each object, see the following table.
@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 参数设置为 10000,但查询的评价数据超过 10000 行时,就会返回此值。For example, this value is returned if the top parameter of the request is set to 10000 but there are more than 10000 rows of reviews data for the query.
TotalCountTotalCount intint 查询的数据结果中的行总数。The total number of rows in the data result for the query.

 

用法值Usage 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 usage 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.
applicationIdapplicationId 字符串string 要为其检索使用情况数据的应用的存储 ID。The Store ID of the app for which you are retrieving usage data.
applicationNameapplicationName stringstring 应用的显示名称。The display name of the app.
deviceTypedeviceType stringstring 以下字符串之一,指定发生使用的设备类型:One of the following strings that specifies the type of device where usage occurred:
  • PCPC
  • 移动Phone
  • 控制台-Xbox OneConsole-Xbox One
  • 控制台-Xbox 系列 XConsole-Xbox Series X
  • 平板电脑Tablet
  • IoTIoT
  • ServerServer
  • HolographicHolographic
  • UnknownUnknown
packageVersionpackageVersion stringstring 发生使用的包版本。The version of the package where usage occurred.
marketmarket stringstring 客户使用应用的市场的 ISO 3166 国家/地区代码。The ISO 3166 country code of the market where the customer used your app.
subscriptionNamesubscriptionName stringstring 指示使用情况是否通过 Xbox 游戏 Pass。Indicates if usage was through Xbox Game Pass.
dailySessionCountdailySessionCount longlong 当天的用户会话数。The number of user sessions on that day.
engagementDurationMinutesengagementDurationMinutes Doubledouble 用户主动使用您的应用程序的分钟数,在应用程序启动时(进程开始)和终止(进程结束)或处于不活动状态一段时间后开始。The minutes where users are actively using your app measured by a distinct period of time, starting when the app launches (process start) and ending when it terminates (process end) or after a period of inactivity.
dailyActiveUsersdailyActiveUsers longlong 使用该应用的客户数。The number of customers using the app that day.
dailyActiveDevicesdailyActiveDevices longlong 所有用户与应用程序进行交互时使用的每日设备数。The number of daily devices used to interact with your app by all users.
dailyNewUsersdailyNewUsers longlong 在当天首次使用应用的客户数。The number of customers who used your app for the first time that day.
monthlyActiveUsersmonthlyActiveUsers longlong 使用当月的应用的客户数。The number of customers using the app that month.
monthlyActiveDevicesmonthlyActiveDevices longlong 在不同的时间段内运行你的应用程序的设备的数量,在应用程序启动时(进程开始)和结束(进程结束)或处于不活动状态一段时间后开始。The number of devices running your app for a distinct period of time, starting when the app launches (process start) and ending when it terminates (process end) or after a period of inactivity.
monthlyNewUsersmonthlyNewUsers longlong 此月份第一次使用应用的客户数。The number of customers who used your app for the first time that month.

响应示例Response example

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

{
  "Value": [
    {
      "date": "2018-08-10",
      "applicationId": "XXXXXXXXXXXX",
      "applicationName": "My App",
      "market": "All",
      "packageVersion": "All",
      "deviceType": "All",
      "subscriptionName": "All",
      "dailySessionCount": 17718,
      "engagementDurationMinutes": 582540.2,
      "dailyActiveUsers": 7078,
      "dailyActiveDevices": 6964,
      "dailyNewUsers": 1727,
      "monthlyActiveUsers": 123609,
      "monthlyActiveDevices": 116723,
      "monthlyNewUsers": 72271
    },
    {
      "date": "2018-08-11",
      "applicationId": "XXXXXXXXXXXX",
      "applicationName": "My App",
      "market": "All",
      "packageVersion": "All",
      "deviceType": "All",
      "subscriptionName": "All",
      "dailySessionCount": 19899,
      "engagementDurationMinutes": 655379.7,
      "dailyActiveUsers": 7877,
      "dailyActiveDevices": 7789,
      "dailyNewUsers": 2062,
      "monthlyActiveUsers": 123666,
      "monthlyActiveDevices": 116770,
      "monthlyNewUsers": 72276
    },
    {
      "date": "2018-08-12",
      "applicationId": "XXXXXXXXXXXX",
      "applicationName": "My App",
      "market": "All",
      "packageVersion": "All",
      "deviceType": "All",
      "subscriptionName": "All",
      "dailySessionCount": 21349,
      "engagementDurationMinutes": 735640.5,
      "dailyActiveUsers": 8456,
      "dailyActiveDevices": 8309,
      "dailyNewUsers": 2433,
      "monthlyActiveUsers": 124241,
      "monthlyActiveDevices": 117289,
      "monthlyNewUsers": 72732
    }
  ],
  "@nextLink": null,
  "TotalCount": 3
}