取得廣告活動績效資料

在Microsoft市集分析 API 中使用此方法，取得指定日期範圍和其他選擇性篩選期間應用程式促銷廣告營銷活動績效數據的匯總摘要。這個方法會以 JSON 格式傳回數據。

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

若要建立、更新或擷取廣告營銷活動的詳細數據，您可以使用 Microsoft 市集促銷 API中的管理廣告營銷活動方法。

先決條件

若要使用此方法，您必須先執行下列動作：

如果您尚未執行此操作，請完成 Microsoft Store 分析 API 的所有必要條件。
取得 Azure AD 存取權杖以便用於此方法的要求標頭中。取得存取令牌之後，您必須在 60 分鐘内使用它，否則將會失效。令牌到期之後，您可以取得新的令牌。

請求

請求語法

方法	請求網址識別碼 (URI)
獲取	`https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion`

請求標頭

頁首	類型	說明
授權	字符串	必須的。 Azure AD 存取令牌的形式為 Bearer<token>。

要求參數

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

參數	類型	說明	為必填項目
應用程式ID	字符串	您想要檢索其廣告活動績效數據的 app 的商店 ID 。	否
開始日期	日期	要擷取的廣告營銷活動績效數據的日期範圍開始日期，格式為YYYY/MM/DD。預設值為目前日期減去 30 天。	否
結束日期	日期	要擷取的廣告營銷活動績效數據日期範圍的結束日期，格式為YYYY/MM/DD。預設值為目前日期減去一天。	否
返回頁首	整數 (int)	要求中要傳回的數據列數。如果未指定，則最大值和預設值為10000。如果查詢中有更多資料列，回應內容會包含下一個連結，您可以使用該連結來請求下一頁的資料。	否
略過	整數 (int)	查詢中要略過的行數目。使用此參數逐頁流覽大型數據集。例如，top=10000 和 skip=0 會擷取前 10000 個數據列、top=10000 和 skip=10000 會擷取接下來的 10000 個數據列等等。	否
篩選器	字符串	一或多個語句用於篩選回應中的數據列。唯一支援的篩選是 campaignId。每個語句都可以使用 eq 或 ne 運算符，而語句可以使用和或或結合。以下是範例篩選器參數：`filter=campaignId eq '100023'`。	否
聚合層級	字符串	指定要擷取匯總數據的時間範圍。可以是下列其中一個字串：day、week 或 month。如果未指定，則預設值為 day。	否
排序	字符串	用來排列廣告活動績效數據結果值的語句。語法為 orderby=field [order]，field [order],...。 field 參數可以是下列其中一個字符串：日期 campaignId order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。預設為asc。以下是範例 orderby 字串：orderby=date，campaignId	否
按群組分類	字符串	僅將資料彙總套用至指定欄位的陳述式。您可以指定下欄位： campaignId 應用程式ID 日期貨幣代碼 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 個，則會傳回此值。
總計數	整數 (int)	查詢的資料結果中的總列數。

行銷活動績效對象

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

價值觀	類型	說明
日期	字符串	廣告營銷活動績效數據日期範圍中的第一個日期。如果要求指定了單一天，這個值就是該日期。如果要求指定了一周、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。
應用程式ID	字符串	您正在擷取廣告營銷活動績效數據的 App 市集識別碼。
活動ID	字符串	廣告活動的ID。
lineId	字符串	產生此績效數據的廣告活動投放線的標識碼。
貨幣代碼	字符串	營銷活動預算的貨幣代碼。
花費	字符串	廣告營銷活動所花費的預算金額。
印象	長	營銷活動的廣告曝光數。
安裝	長	與營銷活動相關的應用程式安裝數目。
點擊數	長	營銷活動的廣告點擊次數。
iapInstalls	長	與行銷活動相關的加值項目安裝次數（也稱為應用程式內購買或 IAP）。
活躍用戶	長	點擊廣告的用戶數目，該廣告屬於營銷活動的一部分，並返回應用程式。

回應範例

下列範例顯示這個請求的 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
}

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-06-10