取得廣告行銷活動績效資料

  • 發行項

在 Microsoft Store 分析 API 中使用此方法，在特定日期範圍期間和其他選擇性篩選條件取得應用程式宣傳廣告行銷活動績效資料的彙總摘要。 這個方法會以 JSON 格式傳回資料。

此方法會傳回合作夥伴中心內廣告行銷活動報告所提供的相同資料。 如需廣告行銷活動的詳細資訊，請參閱為您的應用程式建立廣告行銷活動。

若要建立、更新或擷取廣告行銷活動的詳細資料，您可以使用 Microsoft Store 促銷 API 中的管理廣告行銷活動方法。

必要條件

要使用此方法，您需要先執行以下操作：

  • 如果您尚未執行此操作，請完成 Microsoft Store 分析 API 的所有必要條件。
  • 取得 Azure AD 存取權杖以便用於此方法的要求標頭中。 取得存取權杖之後，您在其到期之前有 60 分鐘的時間可以使用。 權杖到期之後，您可以取得新的權杖。

要求

要求語法

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

要求標頭

標題 類型 描述
授權 字串 必要。 持有人<權杖>形式的 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 列資料，依此類推。 否
篩選器 字串 篩選回應中的資料列的一或多個陳述式。 唯一支援的篩選條件是 campaignId。 每個陳述式都可以使用 eq 或 ne 運算子，而且可以使用 and 或 or 結合陳述式。 下面是一個範例 filter 參數：filter=campaignId eq '100023'。 否
aggregationLevel 字串 指定要擷取彙總資料的時間範圍。 可以是下列其中一個字串：day、week 或 month。 如果未指定，則預設值為 day。 否
orderby 字串

對廣告行銷活動績效資料的結果資料值進行排序的陳述式。 語法為 orderby=field [order],field [order],...。field 參數可以是下列其中一個字串：

  • date
  • campaignId

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

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

 否
groupby 字串

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

  • campaignId
  • applicationId
  • date
  • currencyCode

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>

回應

回應本文

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

行銷活動績效物件

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

值 類型 描述
date 字串 廣告行銷活動績效資料日期範圍中的第一個日期。 如果要求指定了單天，這個值就是該日期。 如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。
applicationId 字串 您正在擷取廣告行銷活動績效資料的應用程式 Store ID。
campaignId 字串 廣告行銷活動的識別碼。
lineId 字串 產生此績效資料之廣告行銷活動 投放資料行的識別碼。
currencyCode 字串 行銷活動預算的貨幣代碼。
spend 字串 廣告行銷活動所花費的預算金額。
impressions long 行銷活動的廣告曝光數。
安裝 long 與行銷活動相關的應用程式安裝數目。
clicks long 行銷活動的廣告點閱數。
iapInstalls long 與行銷活動相關的附加元件數目 (也稱為應用程式內購買或 IAP)。
activeUsers long 點擊屬於行銷活動一部分之廣告並返回應用程式的使用者數目。

回應範例

下列範例示範此要求的範例 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
}