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

發行項
07/04/2024

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

注意

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

必要條件

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

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

Request

要求語法

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

要求標頭

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

要求參數

參數	類型	描述	必要
applicationId	字串	您要擷取下載資料之 Xbox One 遊戲的產品識別碼。若要取得遊戲的產品識別碼，請瀏覽至 XDP Analytics 計畫中的遊戲，並從 URL 擷取產品識別碼。或者，如果您從合作夥伴中心分析報告下載您的下載數資料，產品識別碼會包含在 .tsv 檔案中。	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 paymentInstrumentType sandboxId xboxTitleId order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。預設為asc。以下是範例 orderby 字串：orderby=date,market	否
groupby	字串	僅將資料彙總套用至指定欄位的陳述式。您可以指定下列欄位： date applicationName acquisitionType 年齡 storeClient 性別 market osVersion deviceType paymentInstrumentType sandboxId xboxTitleId 傳回的資料列將包含 groupby 參數中指定的欄位，以及下列項目： date applicationId acquisitionQuantity groupby 參數可以搭配 aggregationLevel 參數使用。例如：&groupby=age,market&aggregationLevel=week	No

要求範例

下列範例示範數個取得 Xbox One 應用程式下載資料的要求。以遊戲的產品識別碼取代 applicationId 值。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&top=10&skip=0 HTTP/1.1 
Authorization: Bearer <your access token> 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&skip=0&filter=market eq 'US' and gender eq 'm' HTTP/1.1 
Authorization: Bearer <your access token>

回應

回應本文

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

下載值

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

值	類型	描述
date	字串	下載資料之日期範圍中的第一個日期。如果要求指定了單天，這個值就是該日期。如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。
applicationId	字串	您要擷取下載資料之 Xbox One 遊戲的產品識別碼。
applicationName	字串	遊戲的顯示名稱
acquisitionType	字串	下列其中一個字串，指出下載的類型：免費試用版付費促銷碼應用程式內購買訂閱內購買私人物件預購 Xbox Game Pass (或 Game Pass，若在 2018 年 3 月 23 日之前查詢) 磁碟預付碼收費預購已取消預購預購失敗
年齡	字串	以下其中一個字串，表示進行下載的使用者的年齡群組：小於 13 歲 13-17 歲 18-24 歲 25-34 歲 35-44 歲 44-55 歲大於 55 歲未知
deviceType	字串	以下其中一個字串，指定完成購買的裝置類型：電腦手機 Xbox One 主機 Xbox Series X 主機 IoT 伺服器平板電腦全像攝影裝置未知
性別	字串	下列其中一個字串，指定進行下載的使用者性別： m f 未知
market	字串	發生獲取之市場的 ISO 3166 國家/地區代碼。
osVersion	字串	發生獲取的 OS 版本。針對此方法，此值一律為 Windows 10 或 Windows 11。
paymentInstrumentType	字串	下列其中一個字串，指出用於下載的付款指示：信用卡直接轉帳卡推斷購買 MS 餘額行動電信業者網路銀行轉帳 PayPal 分割交易權杖兌換零支付金額 eWallet 未知
sandboxId	字串	為遊戲建立的沙箱識別碼。這可以是 RETAIL 值或私人沙盒識別碼。
storeClient	字串	以下其中一個字串，表示下載應用程式的 Store 版本： Windows Phone Store (用戶端) Microsoft Store (用戶端) (或 Windows Store (用戶端)，若是在 2018 年 3 月 23 日之前查詢資料) Microsoft Store (網頁) (或 Windows Store (網頁)，若是在 2018 年 3 月 23 日之前查詢資料) 組織大量採購其他
xboxTitleId	字串	適用於 Xbox Live 遊戲的 Xbox 開發人員入口網站 (XDP) 指派的 Xbox Live 標題識別碼 (以十六進位值表示)。
acquisitionQuantity	值	指定彙總層級期間發生的獲取次數。
purchasePriceUSDAmount	數值	客戶針對下載所支付的金額，使用每月匯率轉換為美元。
purchaseTaxUSDAmount	數值	適用於下載的稅額，轉換成美元。
localCurrencyCode	字串	根據合作夥伴中心帳戶所在國家/地區的當地貨幣代碼。
xboxProductId	字串	如果適用的話，來自 XDP 的產品 Xbox 產品識別碼。
availabilityId	字串	如果適用的話，來自 XDP 的產品可用識別碼。
skuId	字串	如果適用，則為 XDP 產品 SKU 識別碼。
skuDisplayName	字串	如果適用，從 XDP 取得的產品 SKU 顯示名稱。
xboxParentProductId	字串	如果適用的話，來自 XDP 的產品 Xbox 上層產品識別碼。
parentProductName	字串	如果適用的話，來自 XDP 的產品上層產品名稱。
productTypeName	字串	如果適用的話，來自 XDP 產品的產品類型名稱。
purchaseTaxType	字串	如果適用，來自 XDP 產品的購物稅類型。
purchasePriceLocalAmount	數值	如果適用，來自 XDP 產品的購買價格當地金額。
purchaseTaxLocalAmount	數值	如果適用，來自 XDP 產品的購物稅當地金額。

回應範例

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

{ 
    "Value": [ 
        { 
            "date": "2019-01-15T01:00:00.0000000Z", 
            "applicationId": "9WZDNCRFHXHT", 
            "applicationName": null, 
            "acquisitionType": "Paid", 
            "age": null, 
            "deviceType": "Phone", 
            "gender": null, 
            "market": "US", 
            "osVersion": "Windows 11", 
            "paymentInstrumentType": null, 
            "sandboxId": "RETAIL", 
            "storeClient": "Microsoft Store (client)", 
            "xboxTitleId": null, 
            "localCurrencyCode": "USD", 
            "xboxProductId": null, 
            "availabilityId": "B42LRTSZ2MCJ", 
            "skuId": "0010", 
            "skuDisplayName": null, 
            "xboxParentProductId": null, 
            "parentProductName": null, 
            "productTypeName": "Game", 
            "purchaseTaxType": "TaxesNotIncluded", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 3.08, 
            "purchasePriceLocalAmount": 3.08, 
            "purchaseTaxUSDAmount": 0.09, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null,
    
    "TotalCount": 12221 
}

共用方式為