取得訂閱附加元件獲取數

發行項
03/22/2024

在 Microsoft Store 分析 API 中使用此方法，在特定日期範圍期間和其他選擇性篩選條件取得附加元件訂用帳戶的彙總獲取資料。

必要條件

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

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

Request

要求語法

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

要求標頭

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

要求參數

參數	類型	描述	必要
applicationId	字串	您想要擷取訂用帳戶附加元件獲取資料之應用程式的 Store ID。	是
subscriptionProductId	字串	您想要擷取獲取資料之訂用帳戶附加元件的 Store ID。如果您未指定此值，這個方法會傳回指定應用程式之所有訂用帳戶附加元件的獲取資料。	否
startDate	date	要擷取訂用帳戶附加元件獲取資料之日期範圍的開始日期。預設值是目前的日期。	否
endDate	date	要擷取訂用帳戶附加元件獲取資料之日期範圍的結束日期。預設值是目前的日期。	否
熱門	int	要求中要傳回的資料列數。如果未指定，則最大值和預設值為 100。如果查詢中有更多資料列，回應本文會包含下一個連結，您可以用來要求下一頁的資料。	否
skip	int	要在查詢中忽略的列數。使用此參數逐頁瀏覽大型資料集。例如，top=100 和 skip=0 會擷取前 100 列資料，top=100 和 skip=100 會擷取接下來的 100 列資料，依此類推。	否
篩選器	字串	篩選回應本文的一或多個陳述式。每個陳述式都可以使用 eq 或 ne 運算子，而且可以使用 and 或 or 結合陳述式。您可以在篩選陳述式中指定下列字串 (這些對應至回應本文中的值)： date subscriptionProductName applicationName skuId market deviceType 以下是範例 filter 參數：filter=date eq '2017-07-08'。	否
aggregationLevel	字串	指定要擷取彙總資料的時間範圍。可以是下列其中一個字串：day、week 或 month。如果未指定，則預設值為 day。	否
orderby	字串	對每個訂用帳戶附加元件獲取的結果資料值進行排序的陳述式。語法為 orderby=field [order],field [order],...。field 參數可以是下列其中一個字串： date subscriptionProductName applicationName skuId market deviceType order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。預設為asc。以下是範例 orderby 字串：orderby=date,market	否
groupby	字串	僅將資料彙總套用至指定欄位的陳述式。您可以指定下列功能變數： date subscriptionProductName applicationName skuId market deviceType groupby 參數可以搭配 aggregationLevel 參數使用。例如：groupby=market&aggregationLevel=week	否

要求範例

下列範例示範如何取得訂用帳戶附加元件獲取資料。以您應用程式的適當 Store ID 取代 applicationId 值。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=2017-07-07&endDate=2017-07-08 HTTP/1.1
Authorization: Bearer <your access token>

回應

回應本文

值	類型	描述
值	陣列	物件的陣列，其中包含彙總訂用帳戶附加元件獲取資料。如需關於每個物件中的資料的詳細資訊，請參閱下方的訂用帳戶附加元件獲取值一節。
@nextLink	字串	如果有額外的資料頁面，此字串會包含可用來要求下一頁資料的 URI。例如，如果要求的 top 參數設定為 100，但訂用帳戶附加元件獲取資料超過 100 個資料列，則會傳回此值。
TotalCount	int	查詢的資料結果中的總列數。

訂用帳戶獲取值

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

值	類型	描述
date	字串	下載資料之日期範圍中的第一個日期。如果要求指定了單天，這個值就是該日期。如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。
subscriptionProductId	字串	您正在擷取獲取資料之附加元件的 Store ID。
subscriptionProductName	字串	訂用帳戶附加元件的顯示名稱。
applicationId	字串	您正在擷取訂用帳戶附加元件獲取資料之應用程式的 Store ID。
applicationName	字串	應用程式的顯示名稱。
skuId	字串	您正在擷取獲取資料之訂用帳戶附加元件的 SKU 識別碼。
deviceType	字串	下列其中一個字串，指定已完成獲取的裝置類型： PC 手機 Xbox One 主機 Xbox Series X 主機 IoT Holographic Unknown
market	字串	發生獲取之市場的 ISO 3166 國家/地區代碼。
currencyCode	字串	稅前總銷售額的 ISO 4217 格式貨幣代碼。
grossSalesBeforeTax	整數	currencyCode 值所指定之當地貨幣的總銷售額。
totalActiveCount	整數	在指定時段期間作用中的訂用帳戶總數。這相當於 goodStandingActiveCount、pendingGraceActiveCount、graceActiveCount 和 lockedActiveCount 值的總和。
totalChurnCount	整數	在指定時段期間停用的訂用帳戶總數。這相當於 billingChurnCount、nonRenewalChurnCount、refundChurnCount、chargebackChurnCount、earlyChurnCount 和 otherChurnCount 值的總和。
newCount	整數	在指定時段期間新的訂用帳戶獲取數，包括試用版。
renewCount	整數	在指定時段期間的訂用帳戶續約數目，包括使用者起始的續約和自動更新。
goodStandingActiveCount	整數	在指定時段期間處於作用中且到期日為 >= 查詢的 endDate 值的訂用帳戶數目。
pendingGraceActiveCount	整數	在指定時段期間處於作用中但發生計費失敗，且訂用帳戶到期日為 >= 查詢的 endDate 值的訂用帳戶數目。
graceActiveCount	整數	在指定時段期間處於作用中但發生計費失敗，且符合下列情況的訂用帳戶數目：訂用帳戶到期日是 < 查詢的 endDate 值。寬限期的結尾是 >= endDate 值。
lockedActiveCount	整數	在指定時段期間處於「催繳」狀態 (也就是訂用帳戶即將到期，而 Microsoft 正嘗試取得資金以自動更新訂用帳戶)，且符合下列情況的訂用帳戶數目：訂用帳戶到期日是 < 查詢的 endDate 值。寬限期的結尾是 <= endDate 值。
billingChurnCount	整數	在指定時段期間由於無法處理計費費用且訂用帳戶先前處於催繳狀態而停用的訂用帳戶數目。
nonRenewalChurnCount	整數	在指定時段期間因為未更新而停用的訂用帳戶數目。
refundChurnCount	整數	在指定時段期間因為已退款而停用的訂用帳戶數目。
chargebackChurnCount	整數	在指定時段期間因為拒付而停用的訂用帳戶數目。
earlyChurnCount	整數	在指定時段期間在維持良好信譽下停用的訂用帳戶數目。
otherChurnCount	整數	在指定時段期間基於其他原因而停用的訂用帳戶數目。

要求和回應範例

下列程式碼片段示範一些要求的範例要求和 JSON 回應本文。

範例要求

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

範例回應

{
    "Value": [
        {
            "date": "2022-04-18",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "grossSalesBeforeTax": 3460656.260391250,
            "totalActiveCount": 20211321,
            "totalChurnCount": 5605,
            "newCount": 3810366,
            "renewCount": 12102044,
            "goodStandingActiveCount": 17893664,
            "pendingGraceActiveCount": 2255792,
            "graceActiveCount": 61833,
            "lockedActiveCount": 32,
            "billingChurnCount": 4,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 2717,
            "otherChurnCount": 2884
        },
        {
            "date": "2022-04-18",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Unknown",
            "grossSalesBeforeTax": 2342.580615228,
            "totalActiveCount": 50550,
            "totalChurnCount": 7,
            "newCount": 8312,
            "renewCount": 31446,
            "goodStandingActiveCount": 44047,
            "pendingGraceActiveCount": 6503,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 5,
            "otherChurnCount": 2
        }
    ],
    "TotalCount": 2
}

範例要求

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=12/19/2021&endDate=04/20/2022&top=10&skip=0&orderby=date&groupby=date,subscriptionProductName,applicationName,skuId,market,deviceType&aggregationLevel=week
HTTP/1.1
Authorization: Bearer <your access token>

範例回應

{
    "Value": [
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "IT",
            "deviceType": "Console-Xbox One",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 0,
            "totalChurnCount": 0,
            "newCount": 2,
            "renewCount": 0,
            "goodStandingActiveCount": 0,
            "pendingGraceActiveCount": 0,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        },
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "NO",
            "deviceType": "Unknown",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 0,
            "totalChurnCount": 0,
            "newCount": 0,
            "renewCount": 13,
            "goodStandingActiveCount": 0,
            "pendingGraceActiveCount": 0,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        },
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.02",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "CA",
            "deviceType": "Unknown",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 152,
            "totalChurnCount": 0,
            "newCount": 0,
            "renewCount": 270,
            "goodStandingActiveCount": 133,
            "pendingGraceActiveCount": 19,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        }
    ],
    "TotalCount": 3
}

共用方式為

取得訂閱附加元件獲取數

必要條件

Request

要求語法

要求標頭

要求參數

要求範例

回應

回應本文

訂用帳戶獲取值

要求和回應範例

範例要求

範例回應

範例要求

範例回應

意見反應

其他資源

共用方式為

取得訂閱附加元件獲取數

必要條件

Request

要求語法

要求標頭

要求參數

要求範例

回應

回應本文

訂用帳戶獲取值

要求和回應範例

範例要求

範例回應

範例要求

範例回應

相關主題

意見反應

其他資源