共用方式為

取得遊戲和應用程式的附加內容購買資料

在 Microsoft Store 分析 API 中使用此方法，以取得透過 Xbox 開發人員入口網站 (XDP) 已匯入的 UWP 應用程式和 Xbox One 遊戲的匯總附加元件取得數據，該數據為 JSON 格式。此外，這些資料可在 XDP Analytics 合作夥伴中心儀表板中查看。

必要條件

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

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

註記

此 API 不會在 2016 年 10 月 1 日前提供每日匯總資料。

要求

請求語法

方法 要求 URI
獲取 https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

要求標頭

標題 類型 描述
授權 字串 必要。 Azure AD 存取令牌的格式為Bearer<token>。

要求參數

需要 applicationId 或 addonProductId 參數。 若要擷取向應用程式註冊之所有附加元件的下載資料，請指定 applicationId 參數。 若要擷取單一附加元件的下載資料，請指定 addonProductId 參數。 如果您同時指定這兩個參數，則會忽略 applicationId 參數。

參數 類型 描述 必須的
應用程式ID 字串 您要擷取下載資料之 Xbox One 遊戲的 productId。 若要取得遊戲的 productId ，請瀏覽至 XDP Analytics 計畫中的遊戲，並從 URL 擷取 productId。 或者，如果您從合作夥伴中心分析報告下載您的購買資料，productId 會包含在 .tsv 檔案中。 是的
附加產品ID (addonProductId) 字串 您想要擷取取得資料之附加元件的 productId。 是的
開始日期 日期 要擷取附加元件下載資料之日期範圍的開始日期。 預設值是目前的日期。 否
結束日期 日期 要擷取附加元件下載資料之日期範圍的結束日期。 預設值是目前的日期。 否
篩選器 字串 篩選回應中的資料列的一個或多個語句。 每個字句都包含回應正文中的欄位名稱以及與 eq 或 ne 運算子相關聯的值，並且可以使用 and 或 or 來結合這些字句。 字串值必須以篩選參數中的單引號括住。 例如，filter=market 等於 'US' 並且 gender 等於 'm'。
您可以從回應主體中指定下列欄位：
  • 取得類型
  • 年齡
  • storeClient
  • 性別
  • 市場
  • 作業系統版本
  • 裝置類型
  • sandboxId
 否
聚合層級 字串 指定要擷取彙總資料的時間範圍。 可以是下列其中一個字串：day、week 或 month。 如果未指定，則預設值為 day。 否
排序 字串 對每個附加元件下載的結果資料值進行排序的陳述式。 語法為 orderby=field [order],field [order],...。field 參數可以是下列其中一個字串：
  • 日期
  • 取得類型
  • 年齡
  • storeClient
  • 性別
  • 市場
  • 作業系統版本
  • 裝置類型
  • 訂單名稱
order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。 預設為asc。
以下是範例 orderby 字串：orderby = date, market		 否
按群組分類 字串 僅將資料彙總套用至指定欄位的陳述式。 您可以指定下列欄位：
  • 日期
  • 應用程式名稱
  • addonProductName
  • 取得類型
  • 年齡
  • storeClient
  • 性別
  • 市場
  • 作業系統版本
  • 裝置類型
  • 支付工具類型
  • sandboxId
  • xboxTitleIdHex
傳回的資料列將包含 groupby 參數中指定的欄位，以及下列項目：
  • 日期
  • 應用程式ID
  • addonProductId
  • acquisitionQuantity
groupby 參數可以搭配 aggregationLevel 參數使用。 例如：&groupby=age,market&aggregationLevel=week		 否

要求範例

下列範例示範數個用於取得附加元件獲取資料的請求。 將 addonProductId 和 applicationId 值取代為附加元件或應用程式的適當 Store 識別碼。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&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/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0&filter=market eq 'GB' and gender eq 'm' HTTP/1.1 

Authorization: Bearer <your access token>

回應

回應內容

值 類型 描述
值 陣列 包含聚合附加元件獲取資料的物件陣列。 如需關於每個物件中的資料的詳細資訊，請參閱下方的「附加元件下載值」一節。
總計數 整數 查詢的資料結果中的總列數。

附加元件取得價值

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

值 類型 描述
日期 字串 下載資料之日期範圍中的第一個日期。 如果要求指定了單天，這個值就是該日期。 如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。
附加產品ID (addonProductId) 字串 您正在擷取取得資料的附加元件的 productId。
附加產品名稱 字串 附加元件的顯示名稱。 除非您在 groupby 參數中指定 addonProductName 欄位，否則只有在 aggregationLevel 參數設定為 day 時，此值才會出現在回應資料中。
應用程式ID 字串 您想要取得附加元件下載資料的應用程式的 productId。
應用程式名稱 字串 遊戲的顯示名稱
裝置類型 字串 以下其中一個字串，指定完成購買的裝置類型：
  • 「電腦」
  • 「手機」
  • 「Xbox One 主機」
  • 「Xbox Series X 主機」
  • 「IoT」
  • 「伺服器」
  • 「平板電腦」
  • 全息
  • 「未知」
storeClient 字串 以下其中一個字串，表示下載應用程式的 Store 版本：
  • 「Windows Phone Store (用戶端)」
  • 「Microsoft Store (用戶端)」(或「Windows Store (用戶端)」，若是在 2018 年 3 月 23 日之前查詢資料)
  • 「Microsoft Store (網頁)」(或「Windows Store (網頁)」，若是在 2018 年 3 月 23 日之前查詢資料)
  • 「組織大量採購」
  • 「其他」
作業系統版本 字串 執行獲取作業的作業系統版本。 針對此方法，此值一律為 Windows 10 或 Windows 11。
市場 字串 發生獲取之市場的 ISO 3166 國家/地區代碼。
性別 字串 下列其中一個字串，指定進行下載的使用者性別：
  • “m”
  • “f”
  • 「未知」
年齡 字串 以下其中一個字串，表示進行下載的使用者的年齡群組：
  • 「小於 13 歲」
  • 「13-17 歲」
  • 「18-24 歲」
  • 「25-34 歲」
  • 「35-44 歲」
  • 「44-55 歲」
  • 「大於 55 歲」
  • 「未知」
收購類型 字串 下列其中一個字串，指出取得的類型：
  • 「免費」
  • 「試用版」
  • 「付費」
  • 「促銷碼」
  • 「應用程式內購買」
  • 「訂閱內購買」
  • 私人會見
  • 「預購」
  • 「Xbox Game Pass」(或「Game Pass」，若在 2018 年 3 月 23 日之前查詢)
  • 「磁碟」
  • 「預付碼」
  • 「收費預購」
  • 「已取消預購」
  • 「預購失敗」
取得數量 整數 發生的收購數。
應用程式內產品ID 字串 這個附加元件所使用的產品的產品識別碼。
應用程式內產品名稱 字串 這個附加元件所使用的產品的產品名稱。
付款工具類型 字串 用於取得的付款工具類型。
sandboxId 字串 為遊戲建立的沙箱識別碼。 這可以是 RETAIL 值或私人沙盒識別碼。
xboxTitleId 字串 如果適用的話，來自 XDP 的產品 Xbox 標題識別碼。
本地貨幣代碼 字串 以合作夥伴中心帳戶國家/地區為基礎的當地貨幣代碼。
xboxProductId（Xbox產品ID） 字串 如果適用的話，來自 XDP 的產品 Xbox 產品識別碼。
availabilityId（可用性識別碼） 字串 如果適用的話，來自 XDP 的產品可用識別碼。
skuId 的 字串 如果適用，則為 XDP 產品 SKU 識別碼。
skuDisplayName 字串 若適用，產品來自 XDP 的 SKU 顯示名稱。
xboxParentProductId 字串 如果適用的話，來自 XDP 的產品 Xbox 上層產品識別碼。
父產品名稱 字串 如果適用的話，來自 XDP 的產品上層產品名稱。
產品類型名稱 字串 如果適用的話，來自 XDP 產品的產品類型名稱。
購買稅類型 字串 源自 XDP 產品的購買稅類型（如果適用）。
購買價格美元金額 數字 客戶為附加元件支付的金額，轉換為美元。
購買價格本地金額 數字 客戶以區域貨幣支付的附加項目金額。
美金購買稅額 數字 附加項目適用的稅額，換算成美元。
購買稅本地金額 數字 如果適用，XDP 產品的當地購物稅金額。

回應範例

此示範顯示此要求的 JSON 回應本文範例。

{ 
  "Value": [ 
    { 
            "inAppProductId": "9NBLGGH1864K", 
            "inAppProductName": "866879", 
            "addonProductId": "9NBLGGH1864K", 
            "addonProductName": "866879", 
            "date": "2017-11-05", 
            "applicationId": "9WZDNCRFJ314", 
            "applicationName": "Tetris Blitz", 
            "acquisitionType": "Iap", 
            "age": "35-49", 
            "deviceType": "Phone", 
            "gender": "m", 
            "market": "US", 
            "osVersion": "Windows Phone 8.1", 
            "paymentInstrumentType": "Credit Card", 
            "sandboxId": "RETAIL", 
            "storeClient": "Windows Phone Store (client)", 
            "xboxTitleId": "", 
            "localCurrencyCode": "USD", 
            "xboxProductId": "00000000-0000-0000-0000-000000000000", 
            "availabilityId": "", 
            "skuId": "", 
            "skuDisplayName": "Full", 
            "xboxParentProductId": "", 
            "parentProductName": "Tetris Blitz", 
            "productTypeName": "Add-On", 
            "purchaseTaxType": "", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 1.08, 
            "purchasePriceLocalAmount": 0.09, 
            "purchaseTaxUSDAmount": 1.08, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null, 
    
    "TotalCount": 7601 
}
  • Last updated on