获取广告性能数据

  • 项目

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

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

必备条件

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

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

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

请求

请求语法

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

请求头

标头 类型 说明
授权 字符串 必需。 Azure AD 访问令牌的格式为 Bearertoken<>。

请求参数

若要检索特定应用的广告性能数据，请使用 applicationId 参数。 若要检索与你的开发者帐户关联的所有应用的广告性能数据，请忽略 applicationId 参数。

参数 类型 描述 必需
applicationId 字符串 要检索广告性能数据的应用的 Store ID。 否
startDate 日期 要检索的广告性能数据日期范围中的开始日期，格式为 YYYY/MM/DD。 默认值为当前日期减去 30 天。 否
endDate 日期 要检索的广告性能数据日期范围中的结束日期，格式为 YYYY/MM/DD。 默认值为当前日期减去 1 天。 否
top int 要在请求中返回的数据行数。 如果未指定，最大值和默认值为 10000。 当查询中存在多行数据时，响应正文中包含的下一个链接可用于请求下一页数据。 否
skip int 要在查询中跳过的行数。 使用此参数可以浏览较大的数据集。 例如，top=10000 和 skip=0，将检索前 10000 行数据；top=10000 和 skip=10000，将检索之后的 10000 行数据，依此类推。 否
filter string 在响应中筛选行的一条或多条语句。 有关详细信息，请参阅下面的筛选器字段部分。 否
aggregationLevel string 指定用于检索聚合数据的时间范围。 可以是以下字符串之一：day、week 或 month。 如果未指定，默认值为 day。 否
orderby string 对结果数据值进行排序的语句。 语法为 orderby=field [order],field [order],...，其中 field 参数可以是以下字符串之一：
  • date
  • market
  • deviceType
  • adUnitId

order 参数是可选的，可以是 asc 或 desc，用于指定每个字段的升序或降序排列。 默认值为 asc。

下面是一个 orderby 字符串的示例：orderby=date,market

 否
groupby string 仅将数据聚合应用于指定字段的语句。 可以指定的字段如下所示：

  • applicationId
  • applicationName
  • date
  • accountCurrencyCode
  • market
  • deviceType
  • adUnitName
  • adUnitId
  • pubCenterAppName
  • adProvider

groupby 参数可以与 aggregationLevel 参数结合使用。 例如：&groupby=applicationId&aggregationLevel=week

 否

筛选器字段

请求正文中的 filter 参数包含的一条或多条语句用于在响应中筛选行。 每条语句包含的字段和值使用 eq 或 ne 运算符进行关联，并且语句可以使用 and 或 or 进行组合。 下面是一个 filter 参数的示例：

  • filter=market eq 'US' and deviceType eq 'phone'

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

字段 说明
market 包含广告投放所在地市场的 ISO 3166 国家/地区代码的字符串。
deviceType 以下字符串之一：PC/Tablet 或 Phone。
adUnitId 指定要应用到筛选器的广告单元 ID 的字符串。
pubCenterAppName 指定要应用到筛选器的当前应用的 pubCenter 名称的字符串。
adProvider 指定要应用到筛选器的广告提供商名称的字符串。
date 指定要应用到筛选器的日期（格式为 YYYY/MM/DD）的字符串。

请求示例

以下示例演示用于获取广告性能数据的多个请求。 将 applicationId 值替换为你的应用的 Store 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>

响应

响应正文

值 类型 说明
Value array 包含广告性能聚合数据的对象数组。 有关每个对象中的数据的详细信息，请参阅以下广告性能值部分。
@nextLink string 如果存在其他数据页，则此字符串包含一个你可用来请求下一页数据的 URI。 例如，当请求的 top 参数设置为 5，但查询的数据超过 5 项时，就会返回此值。
TotalCount int 查询的数据结果中的行总数。

广告性能值

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

Value 类型 说明
date string 广告性能数据的日期范围内的第一个日期。 如果请求指定了某一天，此值就是该日期。 如果请求指定了一周、月或其他日期范围，此值是该日期范围内的第一个日期。
applicationId 字符串 要检索广告性能数据的应用的应用商店 ID。
applicationName string 应用的显示名称。
adUnitId string 广告单元的 ID。
adUnitName string 由开发人员在合作伙伴中心中指定的广告单元的名称。
adProvider string 广告提供商的名称
deviceType string 广告投放所在设备的类型。 有关支持的字符串列表，请参阅上述筛选器字段部分。
market string 广告投放所在地市场的 ISO 3166 国家/地区代码。
accountCurrencyCode string 帐户的货币代码。
pubCenterAppName string 与合作伙伴中心中的应用关联的 pubCenter 应用的名称。
adProviderRequests int 指定广告提供商的广告请求数。
impressions int 广告曝光数。
clicks int 广告点击数。
revenueInAccountCurrency 数值 以帐户所在国家/地区的货币为单位的收入。
请求 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
}