取得遊戲和應用程式的其他銷售資料

發行項
07/04/2024

在 Microsoft Store 分析 API 中使用此方法，針對透過 Xbox 開發人員入口網站 (XDP) 內嵌的 UWP 應用程式和 Xbox One 遊戲取得 JSON 格式的匯總附加元件下載資料，並在 XDP Analytics 的合作夥伴中心儀表板中取得。

必要條件

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

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

注意

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

Request

要求語法

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

要求標頭

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

要求參數

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

參數	類型	描述	必要
applicationId	字串	您要擷取下載資料之 Xbox One 遊戲的 productId。若要取得遊戲的 productId ，請瀏覽至 XDP Analytics 計畫中的遊戲，並從 URL 擷取 productId。或者，如果您從合作夥伴中心分析報告下載您的下載數資料，productId 會包含在 .tsv 檔案中。	Yes
addonProductId	字串	您想要擷取下載資料之附加元件的 productId。	Yes
startDate	date	要擷取附加元件下載資料之日期範圍的開始日期。預設值是目前的日期。	否
endDate	date	要擷取附加元件下載資料之日期範圍的結束日期。預設值是目前的日期。	否
篩選器	字串	篩選回應中的資料列的一或多個陳述式。每個陳述式都包含回應本文的功能變數名稱，以及與 eq 或 ne 運算子相關聯的值，而且可以使用 and 或 or 結合陳述式。字串值必須以篩選參數中的單引號括住。例如，filter=market eq 'US' and gender eq 'm'。您可以從回應本文指定下列功能變數： acquisitionType 年齡 storeClient 性別 market osVersion deviceType sandboxId	No
aggregationLevel	字串	指定要擷取彙總資料的時間範圍。可以是下列其中一個字串：day、week 或 month。如果未指定，則預設值為 day。	否
orderby	字串	對每個附加元件下載的結果資料值進行排序的陳述式。語法為 orderby=field [order],field [order],...。field 參數可以是下列其中一個字串： date acquisitionType 年齡 storeClient 性別 market osVersion deviceType orderName order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。預設為asc。以下是範例 orderby 字串：orderby=date,market	否
groupby	字串	僅將資料彙總套用至指定欄位的陳述式。您可以指定下列欄位： date applicationName addonProductName acquisitionType 年齡 storeClient 性別 market osVersion deviceType paymentInstrumentType sandboxId xboxTitleIdHex 傳回的資料列將包含 groupby 參數中指定的欄位，以及下列項目： date applicationId addonProductId acquisitionQuantity groupby 參數可以搭配 aggregationLevel 參數使用。例如：&groupby=age,market&aggregationLevel=week	No

要求範例

下列範例示範數個取得附加元件下載資料的要求。將 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>

回應

回應本文

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

附加元件下載值

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

值	類型	描述
date	字串	下載資料之日期範圍中的第一個日期。如果要求指定了單天，這個值就是該日期。如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。
addonProductId	字串	您正在擷取下載資料之附加元件的 productId。
addonProductName	字串	附加元件的顯示名稱。除非您在 groupby 參數中指定 addonProductName 欄位，否則只有在 aggregationLevel 參數設定為 day 時，此值才會出現在回應資料中。
applicationId	字串	您想要擷取附加元件下載資料的應用程式的 productId。
applicationName	字串	遊戲的顯示名稱
deviceType	字串	以下其中一個字串，指定完成購買的裝置類型：「電腦」「手機」「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 日之前查詢資料) 「組織大量採購」「其他」
osVersion	字串	發生獲取的 OS 版本。針對此方法，此值一律為 Windows 10 或 Windows 11。
market	字串	發生獲取之市場的 ISO 3166 國家/地區代碼。
性別	字串	下列其中一個字串，指定進行下載的使用者性別： "m" "f" 「未知」
年齡	字串	以下其中一個字串，表示進行下載的使用者的年齡群組：「小於 13 歲」「13-17 歲」「18-24 歲」「25-34 歲」「35-44 歲」「44-55 歲」「大於 55 歲」「未知」
acquisitionType	字串	下列其中一個字串，指出下載的類型：「免費」「試用版」「付費」「促銷碼」「應用程式內購買」「訂閱內購買」「私人物件」「預購」「Xbox Game Pass」(或「Game Pass」，若在 2018 年 3 月 23 日之前查詢) 「磁碟」「預付碼」「收費預購」「已取消預購」「預購失敗」
acquisitionQuantity	整數	發生的下載數。
inAppProductId	字串	這個附加元件所使用的產品的產品識別碼。
inAppProductName	字串	這個附加元件所使用的產品的產品名稱。
paymentInstrumentType	字串	用於下載的付款工具類型。
sandboxId	字串	為遊戲建立的沙箱識別碼。這可以是 RETAIL 值或私人沙盒識別碼。
xboxTitleId	字串	如果適用的話，來自 XDP 的產品 Xbox 標題識別碼。
localCurrencyCode	字串	根據合作夥伴中心帳戶所在國家/地區的當地貨幣代碼。
xboxProductId	字串	如果適用的話，來自 XDP 的產品 Xbox 產品識別碼。
availabilityId	字串	如果適用的話，來自 XDP 的產品可用識別碼。
skuId	字串	如果適用，則為 XDP 產品 SKU 識別碼。
skuDisplayName	字串	如果適用，從 XDP 取得的產品 SKU 顯示名稱。
xboxParentProductId	字串	如果適用的話，來自 XDP 的產品 Xbox 上層產品識別碼。
parentProductName	字串	如果適用的話，來自 XDP 的產品上層產品名稱。
productTypeName	字串	如果適用的話，來自 XDP 產品的產品類型名稱。
purchaseTaxType	字串	如果適用，來自 XDP 產品的購物稅類型。
purchasePriceUSDAmount	數值	客戶為附加元件支付的金額，轉換為美元。
purchasePriceLocalAmount	數值	客戶以區域貨幣支付附加元件所支付的金額。
purchaseTaxUSDAmount	數值	附加元件適用的稅額，轉換成美元。
purchaseTaxLocalAmount	數值	如果適用，來自 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 
}

共用方式為