获取广告性能数据Get ad performance data

使用 Microsoft Store 分析 API 中的此方法,可获取给定日期范围和其他可选筛选器内你的应用程序的广告性能聚合数据。Use this method in the Microsoft Store analytics API to get aggregate ad performance data for your applications during a given date range and other optional filters. 此方法返回采用 JSON 格式的数据。This method returns the data in JSON format.

此方法返回由提供的相同数据广告性能报告在合作伙伴中心。This method returns the same data that is provided by the Advertising performance 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.

有关详细信息,请参阅使用 Microsoft Store 服务访问分析数据For more information, see Access analytics data using Microsoft Store services.

请求Request

请求语法Request syntax

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

请求头Request header

标头Header 在任务栏的搜索框中键入Type 描述Description
授权Authorization 字符串string 必需。Required. Azure AD 访问令牌的格式为 Bearer token<>。The Azure AD access token in the form Bearer <token>.

请求参数Request parameters

若要检索特定应用的广告性能数据,请使用 applicationId 参数。To retrieve ad performance data for a specific app, use the applicationId parameter. 若要检索与你的开发者帐户关联的所有应用的广告性能数据,请忽略 applicationId 参数。To retrieve ad performance data for all apps that are associated with your developer account, omit the applicationId parameter.

参数Parameter 在任务栏的搜索框中键入Type 描述Description 必需Required
applicationIdapplicationId 字符串string 要检索广告性能数据的应用的 Store IDThe Store ID of the app for which you want to retrieve ad performance data. No
startDatestartDate 日期date 要检索的广告性能数据日期范围中的开始日期,格式为 YYYY/MM/DD。The start date in the date range of ad performance data to retrieve, in the format YYYY/MM/DD. 默认值为当前日期减去 30 天。The default is the current date minus 30 days. No
endDateendDate 日期date 要检索的广告性能数据日期范围中的结束日期,格式为 YYYY/MM/DD。The end date in the date range of ad performance data to retrieve, in the format YYYY/MM/DD. 默认值为当前日期减去 1 天。The default is the current date minus one day. 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 字符串string 在响应中筛选行的一条或多条语句。One or more statements that filter the rows in the response. 有关详细信息,请参阅下面的筛选器字段部分。For more information, see the filter fields section below. No
aggregationLevelaggregationLevel 字符串string 指定用于检索聚合数据的时间范围。Specifies the time range for which to retrieve aggregate data. 可以是以下字符串之一:dayweekmonthCan be one of the following strings: day, week, or month. 如果未指定,默认值为 dayIf unspecified, the default is day. No
orderbyorderby 字符串string 对结果数据值进行排序的语句。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
  • marketmarket
  • deviceTypedeviceType
  • adUnitIdadUnitId

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 字符串string 仅将数据聚合应用于指定字段的语句。A statement that applies data aggregation only to the specified fields. 可以指定的字段如下所示:You can specify the following fields:

  • applicationIdapplicationId
  • 应用程序名称applicationName
  • datedate
  • accountCurrencyCodeaccountCurrencyCode
  • marketmarket
  • deviceTypedeviceType
  • adUnitNameadUnitName
  • adUnitIdadUnitId
  • pubCenterAppNamepubCenterAppName
  • adProvideradProvider

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

No

筛选器字段Filter fields

请求正文中的 filter 参数包含的一条或多条语句用于在响应中筛选行。The filter parameter of the request body contains one or more statements that filter the rows in the response. 每条语句包含的字段和值使用 eqne 运算符进行关联,并且语句可以使用 andor 进行组合。Each statement contains a field and value that are associated with the eq or ne operators, and statements can be combined using and or or. 下面是一个 filter 参数的示例:Here is an example filter parameter:

  • 筛选器 = 市场 eq 美国和 deviceType eq 电话filter=market eq 'US' and deviceType eq 'phone'

有关支持的字段列表,请参阅下表。For a list of the supported fields, see the following table. filter 参数中的字符串值必须使用单引号括起来。String values must be surrounded by single quotes in the filter parameter.

字段Field 描述Description
marketmarket 包含广告投放所在地市场的 ISO 3166 国家/地区代码的字符串。A string that contains the ISO 3166 country code of the market where the ads were served.
deviceTypedeviceType 以下字符串之一:PC/平板电脑PhoneOne of the following strings: PC/Tablet or Phone.
adUnitIdadUnitId 指定要应用到筛选器的广告单元 ID 的字符串。A string that specifies an ad unit ID to apply to the filter.
pubCenterAppNamepubCenterAppName 指定要应用到筛选器的当前应用的 pubCenter 名称的字符串。A string that specifies the pubCenter name for the current app to apply to the filter.
adProvideradProvider 指定要应用到筛选器的广告提供商名称的字符串。A string that specifies an ad provider name to apply to the filter.
日期date 指定要应用到筛选器的日期(格式为 YYYY/MM/DD)的字符串。A string that specifies a date in YYYY/MM/DD format to apply to the filter.

请求示例Request example

以下示例演示用于获取广告性能数据的多个请求。The following example demonstrates several requests for getting ad performance data. applicationId 值替换为你的应用的存储 ID。Replace the applicationId value with the Store ID for your app.

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>

响应Response

响应正文Response body

Value 在任务栏的搜索框中键入Type 描述Description
Value 数组array 包含广告性能聚合数据的对象数组。An array of objects that contain aggregate ad performance data. 有关每个对象中的数据的详细信息,请参阅以下广告性能值部分。For more information about the data in each object, see the ad performance values section below.
@nextLink 字符串string 如果存在数据的其他页,此字符串中包含的 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 参数设置为 5,但查询的数据超过 5 项时,就会返回此值。For example, this value is returned if the top parameter of the request is set to 5 but there are more than 5 items of data for the query.
TotalCountTotalCount intint 查询的数据结果中的行总数。The total number of rows in the data result for the query.

广告性能值Ad performance values

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

Value 在任务栏的搜索框中键入Type 描述Description
日期date 字符串string 广告性能数据的日期范围内的第一个日期。The first date in the date range for the ad performance 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 ad performance data.
applicationNameapplicationName 字符串string 应用的显示名称。The display name of the app.
adUnitIdadUnitId 字符串string 广告单元的 ID。The ID of the ad unit.
adUnitNameadUnitName 字符串string Ad 整体,而是由开发人员在合作伙伴中心中指定的名称。The name of the ad unit, as specified by the developer in Partner Center.
adProvideradProvider 字符串string 广告提供商的名称The name of the ad provider
deviceTypedeviceType 字符串string 广告投放所在设备的类型。The type of device on which the ads were served. 有关支持的字符串列表,请参阅上述筛选器字段部分。For a list of the supported strings, see the filter fields section above.
marketmarket 字符串string 广告投放所在地市场的 ISO 3166 国家/地区代码。The ISO 3166 country code of the market where the ads were served.
accountCurrencyCodeaccountCurrencyCode 字符串string 帐户的货币代码。The currency code for the account.
pubCenterAppNamepubCenterAppName 字符串string 与合作伙伴中心中的应用程序相关联的 pubCenter 应用的名称。The name of the pubCenter app that is associated with the app in Partner Center.
adProviderRequestsadProviderRequests intint 指定广告提供商的广告请求数。The number of ad requests for the specified ad provider.
impressionsimpressions intint 广告曝光数。The number of ad impressions.
clicksclicks intint 广告点击数。The number of ad clicks.
revenueInAccountCurrencyrevenueInAccountCurrency 数字number 以帐户所在国家/地区的货币为单位的收入。The revenue, in the currency for the country/region of the account.
requestsrequests intint 广告请求数。The number of ad requests.

响应示例Response example

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

{
  "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
}