获取广告性能数据

2025-06-20

在 Microsoft Store 分析 API 中使用此方法，以便在给定日期范围和其他可选筛选器内获取您应用程序的聚合广告性能数据。此方法以 JSON 格式返回数据。

此方法返回在合作伙伴中心广告性能报告中提供的相同数据。

先决条件

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

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

有关详细信息，请参阅使用 Microsoft 应用商店服务访问分析数据。

请求

请求语法

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

请求标头

标题	类型	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 行数据，依此等。	否
过滤器	字符串	一个或多个用于筛选响应中行的语句。有关详细信息，请参阅下面的筛选器字段部分。	否
聚合级别	字符串	指定要检索聚合数据的时间范围。可以是以下字符串之一：day、week 或 month。如果未指定，默认值为 day。	否
排序	字符串	对结果数据值进行排序的语句。语法为 orderby=field [order]，field [order]，...。字段参数可以是以下字符串之一：日期市场设备类型广告单元ID 顺序参数是可选的，可以是 asc 或 desc 来指定每个字段的升序或降序。默认值为 asc。下面是一个 orderby 字符串的示例：orderby=date,market	否
按组分类	字符串	仅对指定字段应用数据聚合的语句。可以指定以下字段：应用程序 ID 应用程序名称日期账户货币代码市场设备类型广告单元名称广告单元ID pubCenterApp名称广告提供商 groupby 参数可与 aggregationLevel 参数一起使用。例如：&groupby=applicationId&aggregationLevel=week	否

筛选字段

请求正文的 筛选器 参数包含一个或多个语句，用于筛选响应中的行。每个语句都包含一个字段和值，这些字段和值与 eq 或 ne 运算符相关联，可以使用和或或组合语句。下面是一个 示例筛选器 参数：

filter=market eq 'US' 和 deviceType eq 'phone'

有关支持字段的列表，请参阅下表。字符串值必须用 筛选器 参数中的单引号括起来。

领域	DESCRIPTION
市场	包含广告投放市场 ISO 3166 国家/地区代码的字符串。
设备类型	以下字符串之一： PC/平板电脑或手机。
广告单元ID	一个指定要应用于筛选器的广告单元ID的字符串。
pubCenterApp名称	一个字符串，指定要应用于筛选器的当前应用的 pubCenter 名称。
广告提供商	一个字符串，指定要应用于筛选器的广告提供商名称。
日期	一个指定日期的字符串，其格式为 YYYY/MM/DD，以应用于筛选器。

请求示例

以下示例演示了获取广告性能数据的多个请求。将 applicationId 值替换为应用的应用商店 ID。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance?applicationId=9NBLGGH4R315&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0  HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance?applicationId=9NBLGGH4R315&startDate=8/1/2015&endDate=8/31/2015&skip=0&$filter=market eq 'US' and deviceType eq 'phone’ eq 'US'; and gender eq 'm'  HTTP/1.1
Authorization: Bearer <your access token>

响应

响应体

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

广告性能值

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

价值	类型	DESCRIPTION
日期	字符串	广告性能数据的日期范围中的第一个日期。如果请求指定了某一天，此值就是该日期。如果请求指定了一周、月或其他日期范围，则此值是该日期范围内的第一个日期。
应用ID	字符串	要为其检索广告性能数据的应用的应用商店 ID。
应用程序名称	字符串	应用的显示名称。
广告单元ID	字符串	广告单元的 ID。
广告单元名称	字符串	合作伙伴中心开发人员指定的广告单元的名称。
广告提供商	字符串	广告提供商的名称
设备类型	字符串	提供广告的设备类型。有关支持的字符串列表，请参阅上面的筛选器字段部分。
市场	字符串	提供广告的市场 ISO 3166 国家/地区代码。
账户货币代码	字符串	帐户的货币代码。
pubCenterApp名称	字符串	与合作伙伴中心中的应用关联的 pubCenter 应用名称。
广告提供商请求	整数 (int)	来自指定广告提供商的广告请求数量。
印象	整数 (int)	广告展示次数。
点击次数	整数 (int)	广告点击次数。
账户货币收入	数字	收入，以帐户国家/地区的货币为单位。
请求	整数 (int)	广告请求数。

响应示例

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

{
  "Value": [
    {
      "date": "2015-03-09",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso Demo",
      "market": "US",
      "deviceType": "phone",
      "adUnitId":"10765920",
      "adUnitName":"TestAdUnit",
      "revenueInAccountCurrency": 10.0,
      "impressions": 1000,
      "requests": 10000,
      "clicks": 1,
      "accountCurrencyCode":"USD"
    },
    {
      "date": "2015-03-09",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso Demo",
      "market": "US",
      "deviceType": "phone",
      "adUnitId":"10795110",
      "adUnitName":"TestAdUnit2",
      "revenueInAccountCurrency": 20.0,
      "impressions": 2000,
      "requests": 20000,
      "clicks": 3,
      "accountCurrencyCode":"USD"
    },
  ],
  "@nextLink": "adsperformance?applicationId=9NBLGGH4R315&aggregationLevel=week&startDate=2015/03/01&endDate=2016/02/01&top=2&skip=2",
  "TotalCount": 191753
}

广告性能报告
通过 Microsoft 应用商店服务获取分析数据

通过