取得廣告績效資料

  • 發行項

在 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 存取權杖。

要求參數

若要擷取特定應用程式的廣告績效資料，請使用 applicationId 參數。 若要擷取與您開發人員帳戶相關聯之所有應用程式的廣告績效資料，請省略 applicationId 參數。

參數 類型 描述 必要
applicationId 字串 您想要擷取廣告績效資料的應用程式 Store ID。 否
startDate date 要擷取廣告績效資料之日期範圍的開始日期，格式為 YYYY/MM/DD。 預設值為目前日期減去 30 天。 否
endDate date 要擷取廣告績效資料之日期範圍的結束日期，格式為 YYYY/MM/DD。 預設值為目前日期減去一天。 否
熱門 int 要求中要傳回的資料列數。 如果未指定，則最大值和預設值為 10000。 如果查詢中有更多資料列，回應本文會包含下一個連結，您可以用來要求下一頁的資料。 否
skip int 要在查詢中忽略的列數。 使用此參數逐頁瀏覽大型資料集。 例如，top=10000 和 skip=0 會擷取前 10000 列資料，top=10000 和 skip=10000 會擷取接下來的 10000 列資料，依此類推。 否
篩選器 字串 篩選回應中的資料列的一或多個陳述式。 如需詳細資訊，請參閱下面的篩選功能變數一節。 否
aggregationLevel 字串 指定要擷取彙總資料的時間範圍。 可以是下列其中一個字串：day、week 或 month。 如果未指定，則預設值為 day。 否
orderby 字串 排序結果資料值的陳述式。 語法為 orderby=field [order],field [order],...。field 參數可以是下列其中一個字串：
  • date
  • market
  • deviceType
  • adUnitId

order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。 預設為asc。

以下是範例 orderby 字串：orderby=date,market

 否
groupby 字串 僅將資料彙總套用至指定欄位的陳述式。 您可以指定下列功能變數：

  • 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 字串，指定要套用至篩選條件的廣告單元識別碼。
pubCenterAppName 字串，指定要套用至篩選條件之目前應用程式的 pubCenter 名稱。
adProvider 字串，指定要套用至篩選條件的提供者名稱。
date 字串，指定要以 YYYY/MM/DD 格式套用至篩選條件的日期。

要求範例

下列範例示範數個取得廣告績效資料的要求。 以您應用程式的 Store ID 取代 applicationId 值。

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>

回應

回應本文

值 類型 描述
值 陣列 物件的陣列，其中包含彙總廣告績效資料。 如需關於每個物件中的資料的詳細資訊，請參閱下面的廣告績效值一節。
@nextLink 字串 如果有額外的資料頁面，此字串會包含可用來要求下一頁資料的 URI。 例如，如果要求的 top 參數設定為 5，但查詢的資料超過 5 個項目，則會傳回此值。
TotalCount int 查詢的資料結果中的總列數。

廣告績效值

Value 陣列中的元素包含下列值。

值 類型 描述
date 字串 廣告績效資料日期範圍中的第一個日期。 如果要求指定了單天，這個值就是該日期。 如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。
applicationId 字串 您正在擷取廣告績效資料的應用程式 Store ID。
applicationName 字串 應用程式的顯示名稱。
adUnitId 字串 廣告單元的識別碼。
adUnitName 字串 開發人員在合作夥伴中心所指定的廣告單元名稱。
adProvider 字串 廣告提供者的名稱。
deviceType 字串 提供廣告的裝置類型。 如需支援的字串清單，請參閱上面的篩選功能變數一節。
market 字串 提供廣告之市場的 ISO 3166 國家/地區代碼。
accountCurrencyCode 字串 帳戶的貨幣代碼。
pubCenterAppName 字串 與合作夥伴中心內的應用程式相關聯的 pubCenter 應用程式名稱。
adProviderRequests int 指定廣告提供者的廣告要求數目。
impressions int 廣告曝光數。
clicks int 廣告點閱數。
revenueInAccountCurrency 值 以帳戶的國家/地區貨幣為單位的收入。
requests 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
}