共用方式為

取得每月應用程式使用量

在 Microsoft Store 分析 API 中使用此方法，在特定日期範圍期間 (僅限過去 90 天) 和其他選擇性篩選條件取得應用程式的 JSON 格式彙總使用量資料 (不包括 Xbox 多人遊戲)。 此資訊也可在合作夥伴中心的 使用量報告中 取得。

以 Anaheim 為基礎的 PWA 應用程式的遙測會在裝置層級收集。 因此，與使用者相關的計量不適用於這類產品。 如需功能變數有效性的詳細資訊，請參閱下列「使用量值」一節。

必要條件

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

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

請求

要求語法

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

要求標頭

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

要求參數

參數 類型 描述 必要
應用程式ID 字串 您想要擷取評論數據的應用程式的商店 ID。 是
開始日期 日期 要擷取評論資料之日期範圍的開始日期。 預設值是目前的日期。 否
結束日期 日期 要擷取評論資料之日期範圍的結束日期。 預設值是目前的日期。 否
熱門 整數 (int) 要求中要傳回的資料列數。 如果未指定，則最大值和預設值為 10000。 如果查詢中有更多資料列，回應本文會包含下一個連結，您可以用來要求下一頁的資料。 否
略過 整數 (int) 要在查詢中忽略的列數。 使用此參數逐頁瀏覽大型資料集。 例如，top=10000 和 skip=0 會擷取前 10000 列資料，top=10000 和 skip=10000 會擷取接下來的 10000 列資料，依此類推。 否
篩選器 字串 篩選回應中的資料列的一或多個陳述式。 每個陳述式都包含回應本文的功能變數名稱，以及與 eq 或 ne 運算子相關聯的值，而且可以使用 and 或 or 結合陳述式。 字串值必須以 filter 參數中的單引號括住。 您可以從回應本文指定下列功能變數：
  • 市場
  • 設備類型
  • 封包版本
 否
排序 字串 排序結果資料值的陳述式。 語法為 orderby=field [order],field [order],...。field 參數可以是下列其中一個字串：
  • 日期
  • 應用程式ID
  • 應用程式名稱
  • 市場
  • 封包版本
  • 設備類型
  • 訂閱名稱
  • 每月會話數量
  • 參與時長分鐘數（engagementDurationMinutes）
  • monthlyActiveUsers
  • 每月活躍設備
  • 每月新增用戶
  • 平均每日活躍使用者
  • 平均每日活躍設備
  • 每月新增設備

order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。 預設值為 asc。

以下是範例 orderby 字串：orderby=date,market

 否
按群組分類 字串 僅將資料彙總套用至指定欄位的陳述式。 您可以從回應本文指定下列功能變數：
  • 應用程式名稱
  • 訂閱名稱
  • 設備類型
  • 封包版本
  • 市場
  • 日期

傳回的數據列將包含 groupby 參數中指定的欄位以及以下內容：

  • 應用程式ID
  • 訂閱名稱
  • 每月會話數量
  • 參與時長分鐘數（engagementDurationMinutes）
  • monthlyActiveUsers
  • 每月活躍設備
  • 每月新增用戶
  • 平均每日活躍使用者
  • 平均每日活躍設備
  • 每月新增設備

groupby 參數可以搭配 aggregationLevel 參數使用。 例如：&groupby=ageGroup,market&aggregationLevel=week

 否

要求範例

下列範例示範取得每月應用程式使用量資料的要求。 以您應用程式的 Store ID 取代 applicationId 值。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=XXXXXXXXXXXX&startDate=2018-06-01&endDate=2018-07-01 HTTP/1.1  
Authorization: Bearer <your access token>

回應

回應本文

值 類型 描述
值 陣列 包含彙總使用量資料的物件陣列。 如需每個物件中資料的詳細資訊，請參閱下表。
@nextLink 字串 如果有額外的資料頁面，此字串會包含可用來要求下一頁資料的 URI。 例如，如果要求的 top 參數設定為 10000，但查詢的評論數據列超過 10000 個數據列，則會傳回此值。
總計數 整數 (int) 查詢的資料結果中的總列數。

 

使用量值

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

值 類型 描述 UWP 可用性 以 Anaheim 為基礎的 PWA 可用性 Xbox 可用性
日期 字串 使用量資料之日期範圍中的第一個日期。 如果要求指定了單天，這個值就是該日期。 如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。 是 是 是
應用程式ID 字串 您正在擷取使用量資料之應用程式的 Store ID。 是 是 是
應用程式名稱 字串 應用程式的顯示名稱。 是 是 是
市場 字串 客戶使用您的應用程式之市場的 ISO 3166 國家/地區代碼。 是 是 是
封包版本 字串 發生使用量的套件版本。 是 是 否
裝置類型 字串 下列其中一個字串，指定發生使用量的裝置類型：
  • 個人電腦
  • 電話
  • Console-Xbox One
  • Console-Xbox 系列 X
  • 平板
  • 物聯網
  • 伺服器
  • 全息
  • 未知
 是 是 是
訂閱名稱 字串 指出使用量是否透過 Xbox Game Pass。 是 否 否
每月會話計數 長 當月期間的使用者工作階段數目。 是 是 是
互動時長（分鐘） 雙倍 依不同時間週期測量使用者主動使用應用程式的分鐘數，從應用程式啟動時開始 (處理序開始) 和終止 (處理序結束) 或一段閒置期間之後結束。 是 是 是
每月活躍用戶 長 當月使用應用程式的客戶數目。 是 否 是
每月活躍裝置 長 不同時段內執行您的應用程式的裝置數目，從應用程式啟動時 (處理序開始) 開始，並在終止 (處理序結束) 或一段閒置期間之後結束。 是 是 是
每月新增用戶 長 當月第一次使用您的應用程式的客戶數目。 是 否 是
每日平均活躍用戶數 雙倍 每天使用應用程式的平均客戶數目。 是 否 是
平均每日活躍設備 雙倍 所有使用者每天用來與您的應用程式互動的平均裝置數目。 是 是 是
每月新裝置 長 當月內第一次使用應用程式的裝置數目。 否 是 否

注意

如果功能變數對特定產品無效，則回應中會將這些欄位的值傳送為 0 或 Null。 新使用者和新裝置的計算是使用 3 年的滾動視窗完成，也就是如果使用者/裝置未使用應用程式 3 年以上，則會在 3 年後被視為新的使用者/裝置。

要求和回應範例

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

範例要求

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

範例回應

{
    "Value": [
        {
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "deviceType": "All",
            "packageVersion": "All",
            "market": "All",
            "engagementDurationMinutes": 2828568.3,
            "monthlyActiveUsers": 165249,
            "monthlyActiveDevices": 165753,
            "monthlyNewUsers": 95787,
            "monthlySessionCount": 314263,
            "averageDailyActiveUsers": 192.506111111111,
            "averageDailyActiveDevices": 191.199722222222,
            "monthlyNewDevices": 0
        }
    ],
    "TotalCount": 1
}

範例要求

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=9NBLGGGZ5QDR&startDate=2022-06-01&endDate=2022-07-01&groupby=applicationName,subscriptionName,deviceType,packageVersion,market,date&top=10&skip=0
HTTP/1.1
Authorization: Bearer <your access token>

範例回應

{
    "Value": [
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "JP",
            "engagementDurationMinutes": 0.3,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "MX",
            "engagementDurationMinutes": 2.7,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "Unknown",
            "engagementDurationMinutes": 0.1,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "US",
            "engagementDurationMinutes": 0.2,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AE",
            "engagementDurationMinutes": 3.2,
            "monthlyActiveUsers": 2,
            "monthlyActiveDevices": 2,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 3,
            "averageDailyActiveUsers": 0.07,
            "averageDailyActiveDevices": 0.07,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AO",
            "engagementDurationMinutes": 1.2,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AR",
            "engagementDurationMinutes": 574.7,
            "monthlyActiveUsers": 39,
            "monthlyActiveDevices": 39,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 53,
            "averageDailyActiveUsers": 1.43,
            "averageDailyActiveDevices": 1.43,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AT",
            "engagementDurationMinutes": 5.3,
            "monthlyActiveUsers": 4,
            "monthlyActiveDevices": 4,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 9,
            "averageDailyActiveUsers": 0.17,
            "averageDailyActiveDevices": 0.17,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AU",
            "engagementDurationMinutes": 434.7,
            "monthlyActiveUsers": 22,
            "monthlyActiveDevices": 22,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 36,
            "averageDailyActiveUsers": 0.9,
            "averageDailyActiveDevices": 0.9,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AZ",
            "engagementDurationMinutes": 13.5,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        }
    ],
    "TotalCount": 10
}
  • Last updated on