共用方式為

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

  • 發行項

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

注意

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

必要條件

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

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

要求

要求語法

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

要求標頭

標題 類型 描述
授權 string 必要。 持有人<token>權杖形式的 Azure AD 存取權杖。

要求參數

參數 類型 描述 必要
applicationId string 您要擷取下載資料之 Xbox One 遊戲的產品識別碼。 若要取得遊戲的產品識別碼 ，請瀏覽至 XDP Analytics 計畫中的遊戲，並從 URL 擷取產品識別碼。 或者，如果您從合作夥伴中心分析報告下載您的下載數資料，產品識別碼會包含在 .tsv 檔案中。 Yes
startDate date 要擷取下載資料之日期範圍的開始日期。 預設值是目前的日期。 No
endDate date 要擷取下載資料之日期範圍的結束日期。 預設值是目前的日期。 No
篩選器 string 篩選回應中的資料列的一或多個陳述式。 每個陳述式都包含回應本文的功能變數名稱，以及與 eq 或 ne 運算子相關聯的值，而且可以使用 and 或 or 結合陳述式。 字串值必須以篩選參數中的單引號括住。 例如，filter=market eq 'US' and gender eq 'm'。
您可以從回應本文指定下列功能變數：
  • acquisitionType
  • 年齡
  • storeClient
  • 性別
  • market
  • osVersion
  • deviceType
  • sandboxId
 No
aggregationLevel string 指定要擷取彙總資料的時間範圍。 可以是下列其中一個字串：day、week 或 month。 如果未指定，則預設值為 day。 No
orderby string 對每個下載的結果資料值進行排序的陳述式。 語法為 orderby=field [order],field [order],...。field 參數可以是下列其中一個字串：
  • date
  • acquisitionType
  • 年齡
  • storeClient
  • 性別
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。 預設為asc。 以下是範例 orderby 字串：orderby=date,market		 No
groupby string 僅將資料彙總套用至指定欄位的陳述式。 您可以指定下列欄位：
  • 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 string 下載資料之日期範圍中的第一個日期。 如果要求指定了單天，這個值就是該日期。 如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。
applicationId string 您要擷取下載資料之 Xbox One 遊戲的產品識別碼。
applicationName string 遊戲的顯示名稱
acquisitionType string 下列其中一個字串，指出下載的類型：
  • 免費
  • 試用版
  • 付費
  • 促銷碼
  • 應用程式內購買
  • 訂閱內購買
  • 私人物件
  • 預購
  • Xbox Game Pass (或 Game Pass，若在 2018 年 3 月 23 日之前查詢)
  • 磁碟
  • 預付碼
  • 收費預購
  • 已取消預購
  • 預購失敗
年齡 string 以下其中一個字串，表示進行下載的使用者的年齡群組：
  • 小於 13 歲
  • 13-17 歲
  • 18-24 歲
  • 25-34 歲
  • 35-44 歲
  • 44-55 歲
  • 大於 55 歲
  • 未知
deviceType string 以下其中一個字串，指定完成購買的裝置類型：
  • 電腦
  • 手機
  • Xbox One 主機
  • Xbox Series X 主機
  • IoT
  • 伺服器
  • 平板電腦
  • 全像攝影裝置
  • 未知
性別 string 下列其中一個字串，指定進行下載的使用者性別：
  • m
  • f
  • 未知
market string 發生獲取之市場的 ISO 3166 國家/地區代碼。
osVersion string 發生獲取的 OS 版本。 針對此方法，此值一律為 Windows 10 或 Windows 11。
paymentInstrumentType string 下列其中一個字串，指出用於下載的付款指示：
  • 信用卡
  • 直接轉帳卡
  • 推斷購買
  • MS 餘額
  • 行動電信業者
  • 網路銀行轉帳
  • PayPal
  • 分割交易
  • 權杖兌換
  • 零支付金額
  • eWallet
  • 未知
sandboxId string 為遊戲建立的沙箱識別碼。 這可以是 RETAIL 值或私人沙盒識別碼。
storeClient string 以下其中一個字串，表示下載應用程式的 Store 版本：
  • Windows Phone Store (用戶端)
  • Microsoft Store (用戶端) (或 Windows Store (用戶端)，若是在 2018 年 3 月 23 日之前查詢資料)
  • Microsoft Store (網頁) (或 Windows Store (網頁)，若是在 2018 年 3 月 23 日之前查詢資料)
  • 組織大量採購
  • 其他
xboxTitleId string 適用於 Xbox Live 遊戲的 Xbox 開發人員入口網站 (XDP) 指派的 Xbox Live 標題識別碼 (以十六進位值表示)。
acquisitionQuantity 數值 指定彙總層級期間發生的獲取次數。
purchasePriceUSDAmount 數值 客戶針對下載所支付的金額，使用每月匯率轉換為美元。
purchaseTaxUSDAmount 數值 適用於下載的稅額，轉換成美元。
localCurrencyCode string 根據合作夥伴中心帳戶所在國家/地區的當地貨幣代碼。
xboxProductId string 如果適用的話，來自 XDP 的產品 Xbox 產品識別碼。
availabilityId string 如果適用的話，來自 XDP 的產品可用識別碼。
skuId string 如果適用，則為 XDP 產品 SKU 識別碼。
skuDisplayName string 如果適用，從 XDP 取得的產品 SKU 顯示名稱。
xboxParentProductId string 如果適用的話，來自 XDP 的產品 Xbox 上層產品識別碼。
parentProductName string 如果適用的話，來自 XDP 的產品上層產品名稱。
productTypeName string 如果適用的話，來自 XDP 產品的產品類型名稱。
purchaseTaxType string 如果適用，來自 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 
}