获取广告活动效果数据

2025-06-10

在 Microsoft 商店分析 API 中使用此方法，以获取您的应用程序在给定日期范围和其他可选筛选器期间的促销广告活动性能数据的聚合摘要。此方法以 JSON 格式返回数据。

此方法返回与合作伙伴中心中广告活动报告提供的数据相同的数据。有关广告活动的详细信息，请参阅为应用创建广告活动。

若要创建、更新或检索广告市场活动的详细信息，可以使用 Microsoft 应用商店促销 API中的管理广告市场活动方法。

先决条件

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

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

请求

请求语法

方法	请求 URI
获取	`https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion`

请求标头

标题	类型	DESCRIPTION
授权	字符串	必填。 Azure AD 访问令牌，形式为Bearer<token>。

请求参数

若要检索特定应用的广告市场活动性能数据，请使用 applicationId 参数。若要检索与开发人员帐户关联的所有应用的广告性能数据，请省略 applicationId 参数。

参数	类型	DESCRIPTION	必选
应用ID	字符串	您希望检索广告活动性能数据的应用在应用商店的 ID 为。	否
开始日期	日期	要检索的广告活动性能数据日期范围中的开始日期，格式为 YYYY/MM/DD。默认值为当前日期减去 30 天。	否
结束日期	日期	要检索的广告活动表现数据的日期范围的结束日期，格式为 YYYY/MM/DD。默认值为当前日期减去一天。	否
顶部	整数 (int)	请求中要返回的数据行数。如果未指定，则最大值和默认值为 10000。如果查询中有更多行，响应正文将包含下一个链接，可用于请求下一页的数据。	否
跳过	整数 (int)	查询中要跳过的行数。使用此参数可分页浏览大型数据集。例如，top=10000 和 skip=0 检索前 10000 行数据，top=10000 和 skip=10000 检索接下来的 10000 行数据，依此等。	否
过滤器	字符串	一个或多个用于筛选响应中行的语句。唯一受支持的筛选器是 campaignId。每个语句都可以使用eq或ne运算符，并且可以使用and或or来组合语句。下面是筛选器参数的示例：`filter=campaignId eq '100023'`。	否
聚合级别	字符串	指定要检索聚合数据的时间范围。可以是以下字符串之一：day、week 或 month。如果未指定，默认值为 day。	否
排序	字符串	用于对广告活动表现数据的结果数据值进行排序的命令语句。语法为 orderby=field [order]，field [order]，...。字段参数可以是以下字符串之一：日期 campaignId 顺序参数是可选的，可以是 asc 或 desc 来指定每个字段的升序或降序。默认值为 asc。下面是 orderby 字符串示例：orderby=date，campaignId	否
按组分类	字符串	仅对指定字段应用数据聚合的语句。可以指定以下字段： campaignId 应用程序 ID 日期货币代码 groupby 参数可与 aggregationLevel 参数一起使用。例如：&groupby=applicationId&aggregationLevel=week	否

请求示例

以下示例演示了获取广告市场活动性能数据的多个请求。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion?aggregationLevel=week&groupby=applicationId,campaignId,date  HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion?applicationId=9NBLGGH0XK8Z&startDate=2015/1/20&endDate=2016/8/31&skip=0&filter=campaignId eq '31007388' HTTP/1.1
Authorization: Bearer <your access token>

响应

响应体

价值	类型	DESCRIPTION
价值	数组	包含聚合广告活动性能数据的对象数组。有关每个对象中的数据的详细信息，请参阅下面的市场活动性能对象部分。
@nextLink	字符串	如果有其他数据页，此字符串包含可用于请求下一页数据的 URI。例如，如果请求的顶部参数设置为 5，但查询的数据超过 5 项，则返回此值。
总计数	整数 (int)	查询的数据结果中的行总数。

活动绩效对象

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

价值	类型	DESCRIPTION
日期	字符串	广告活动表现数据日期范围内的起始日期。如果请求指定了某一天，此值就是该日期。如果请求指定了一周、月或其他日期范围，则此值是该日期范围内的第一个日期。
应用ID	字符串	要为其检索广告活动性能数据的应用的商店 ID。
活动编号	字符串	广告活动的ID。
线路ID	字符串	生成此性能数据的广告活动 ID 投放线。
货币代码	字符串	市场活动预算的货币代码。
花费	字符串	广告活动已花费的预算金额。
印象	长整型	市场活动的广告展示次数。
安装	长整型	与活动相关的应用安装数。
点击次数	长整型	市场活动的广告点击次数。
iapInstalls	长整型	与广告活动相关的加载项（也称为应用内购买或 IAP）安装的数量。
活跃用户	长整型	点击了活动中的广告并返回应用程序的用户数量。

响应示例

以下示例演示此请求的示例 JSON 响应正文。

{
  "Value": [
    {
      "date": "2015-04-12",
      "applicationId": "9WZDNCRFJ31Q",
      "campaignId": "4568",
      "lineId": "0001",
      "currencyCode": "USD",
      "spend": 700.6,
      "impressions": 200,
      "installs": 30,
      "clicks": 8,
      "iapInstalls": 0,
      "activeUsers": 0
    },
    {
      "date": "2015-05-12",
      "applicationId": "9WZDNCRFJ31Q",
      "campaignId": "1234",
      "lineId": "0002",
      "currencyCode": "USD",
      "spend": 325.3,
      "impressions": 20,
      "installs": 2,
      "clicks": 5,
      "iapInstalls": 0,
      "activeUsers": 0
    }
  ],
  "@nextLink": "promotion?applicationId=9NBLGGGZ5QDR&aggregationLevel=day&startDate=2015/1/20&endDate=2016/8/31&top=2&skip=2",
  "TotalCount": 1917
}

通过