获取见解数据Get insights data

使用此方法在 Microsoft Store 分析 API 来获取见解数据中的在给定的日期范围和其他可选的筛选器与收购、 运行状况和使用情况指标的应用程序相关。Use this method in the Microsoft Store analytics API to get insights data related to acquisitions, health, and usage metrics for an app during a given date range and other optional filters. 此信息也位于Insights 报告在合作伙伴中心。This information is also available in the Insights 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/insights

请求头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 ID想检索 insights 数据的应用。The Store ID of the app for which you want to retrieve insights data. 如果不指定此参数,响应正文将包含已注册到你的帐户的所有应用的 insights 数据。If you do not specify this parameter, the response body will contain insights data for all apps registered to your account. No
startDatestartDate 日期date 开始 insights 数据的日期范围内要检索的日期。The start date in the date range of insights data to retrieve. 默认值为当前日期之前 30 天。The default is 30 days before the current date. No
endDateendDate 日期date 最终的 insights 数据的日期范围内要检索的日期。The end date in the date range of insights data to retrieve. 默认值为当前日期。The default is the current date. No
filterfilter 字符串string 在响应中筛选行的一条或多条语句。One or more statements that filter the rows in the response. 每条语句包含的响应正文中的字段名称和值使用 eqne 运算符进行关联,并且语句可以使用 andor 进行组合。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. 例如,筛选器 = 数据类型 eq 获取For example, filter=dataType eq 'acquisition'.

可以指定以下筛选器字段:You can specify the following filter fields:

  • 获取acquisition
  • 运行状况health
  • 使用情况usage
No

请求示例Request example

下面的示例演示了用于获取见解数据请求。The following example demonstrates a request for getting insights data. applicationId 值替换为你的应用的存储 ID。Replace the applicationId value with the Store ID for your app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/insights?applicationId=9NBLGGGZ5QDR&startDate=6/1/2018&endDate=6/15/2018&filter=dataType eq 'acquisition' or dataType eq 'health' HTTP/1.1
Authorization: Bearer <your access token>

响应Response

响应正文Response body

Value 在任务栏的搜索框中键入Type 描述Description
Value 数组array 包含应用程序的 insights 数据的对象的数组。An array of objects that contain insights data for the app. 有关每个对象中的数据的详细信息,请参阅见解值下面一节。For more information about the data in each object, see the Insight values section below.
TotalCountTotalCount intint 查询的数据结果中的行总数。The total number of rows in the data result for the query.

见解值Insight values

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

Value 在任务栏的搜索框中键入Type 描述Description
applicationIdapplicationId 字符串string 要为其检索 insights 数据的应用 Store ID。The Store ID of the app for which you are retrieving insights data.
insightDateinsightDate 字符串string 我们发现特定度量值中的更改的日期。The date on which we identified the change in a specific metric. 此日期表示在其中我们检测到大量增加的一周结束,或减小相比前的一周的指标。This date represents the end of the week in which we detected a significant increase or decrease in a metric compared to the week before that.
数据类型dataType 字符串string 指定此信息介绍的常规分析区域的以下字符串之一:One of the following strings that specifies the general analytics area that this insight describes:

  • 获取acquisition
  • 运行状况health
  • 使用情况usage
insightDetailinsightDetail 数组array 一个或多个InsightDetail 值表示以当前深入了解详细信息。One or more InsightDetail values that represent the details for current insight.

InsightDetail 值InsightDetail values

Value 在任务栏的搜索框中键入Type 描述Description
FactNameFactName 字符串string 以下值,该值指示当前的见解或当前维度所述,度量值的一个基于数据类型值。One of the following values that indicates the metric that the current insight or current dimension describes, based on the dataType value.
  • 有关运行状况,此值始终为点击次数For health, this value is always HitCount.
  • 有关采集,此值始终为AcquisitionQuantityFor acquisition, this value is always AcquisitionQuantity.
  • 有关使用情况,此值可以是下列字符串之一:For usage, this value can be one of the following strings:
    • dailyActiveUsersDailyActiveUsers
    • engagementDurationMinutesEngagementDurationMinutes
    • dailyActiveDevicesDailyActiveDevices
    • dailyNewUsersDailyNewUsers
    • dailySessionCountDailySessionCount
SubDimensionsSubDimensions 数组array 描述单个指标以深入了解的一个或多个对象。One or more objects that describe a single metric for the insight.
PercentChangePercentChange 字符串string 在您的整个客户群之间更改度量值所占百分比。The percentage that the metric changed across your entire customer base.
DimensionNameDimensionName 字符串string 当前维度中所述的指标的名称。The name of the metric described in the current dimension. 示例包括EventType市场DeviceTypePackageVersionAcquisitionTypeAgeGroup性别Examples include EventType, Market, DeviceType, PackageVersion, AcquisitionType, AgeGroup and Gender.
DimensionValueDimensionValue 字符串string 描述当前维度中的指标值。The value of the metric that is described in the current dimension. 例如,如果DimensionNameEventTypeDimensionValue可能崩溃挂起.For example, if DimensionName is EventType, DimensionValue might be crash or hang.
FactValueFactValue 字符串string 检测到见解的日期的跃点数的绝对值。The absolute value of the metric on the date the insight was detected.
方向Direction 字符串string 更改的方向 ()。The direction of the change (Positive or Negative).
日期Date 字符串string 我们发现与当前的见解或当前维度相关的更改的日期。The date on which we identified the change related to the current insight or the current dimension.

响应示例Response example

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

{
  "Value": [
    {
      "applicationId": "9NBLGGGZ5QDR",
      "insightDate": "2018-06-03T00:00:00",
      "dataType": "health",
      "insightDetail": [
        {
          "FactName": "HitCount",
          "SubDimensions": [
            {
              "FactName:": "HitCount",
              "PercentChange": "21",
              "DimensionValue:": "DE",
              "FactValue": "109",
              "Direction": "Positive",
              "Date": "6/3/2018 12:00:00 AM",
              "DimensionName": "Market"
            }
          ],
          "DimensionValue": "crash",
          "Date": "6/3/2018 12:00:00 AM",
          "DimensionName": "EventType"
        },
        {
          "FactName": "HitCount",
          "SubDimensions": [
            {
              "FactName:": "HitCount",
              "PercentChange": "71",
              "DimensionValue:": "JP",
              "FactValue": "112",
              "Direction": "Positive",
              "Date": "6/3/2018 12:00:00 AM",
              "DimensionName": "Market"
            }
          ],
          "DimensionValue": "hang",
          "Date": "6/3/2018 12:00:00 AM",
          "DimensionName": "EventType"
        },
      ],
      "insightId": "9CY0F3VBT1AS942AFQaeyO0k2zUKfyOhrOHc0036Iwc="
    }
  ],
  "@nextLink": null,
  "TotalCount": 2
}