取得附加元件獲取數
在 Microsoft Store 分析 API 中使用此方法，在特定日期範圍期間和其他選擇性篩選條件取得應用程式附加元件的 JSON 格式彙總獲取資料。 此資訊也可在合作夥伴中心的附加元件獲取報告中取得。
必要條件
要使用此方法，您需要先執行以下操作：
- 如果您尚未執行此操作，請完成 Microsoft Store 分析 API 的所有必要條件。
- 取得 Azure AD 存取權杖以便用於此方法的要求標頭中。 取得存取權杖之後，您在其到期之前有 60 分鐘的時間可以使用。 權杖到期之後，您可以取得新的權杖。
Request
要求語法
| 方法 | 要求 URI |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions |
要求標頭
| 標題 | 類型 | 描述 |
|---|---|---|
| 授權 | 字串 | 必要。 持有人<權杖>形式的 Azure AD 存取權杖。 |
要求參數
需要 applicationId 或 inAppProductId 參數。 若要擷取向應用程式註冊之所有附加元件的獲取資料，請指定 applicationId 參數。 若要擷取單一附加元件的獲取資料，請指定 inAppProductId 參數。 如果您同時指定這兩個參數，則會忽略 applicationId 參數。
| 參數 | 類型 | 描述 | 必要 |
|---|---|---|---|
| applicationId | 字串 | 您想要擷取附加元件獲取資料之應用程式的 Store ID。 | 是 |
| inAppProductId | 字串 | 您想要擷取獲取資料之附加元件的 Store ID。 | 是 |
| startDate | date | 要擷取附加元件下載資料之日期範圍的開始日期。 預設值是目前的日期。 | 否 |
| endDate | date | 要擷取附加元件下載資料之日期範圍的結束日期。 預設值是目前的日期。 | 否 |
| 熱門 | int | 要求中要傳回的資料列數。 如果未指定，則最大值和預設值為 10000。 如果查詢中有更多資料列，回應本文會包含下一個連結，您可以用來要求下一頁的資料。 | 否 |
| skip | int | 要在查詢中忽略的列數。 使用此參數逐頁瀏覽大型資料集。 例如，top=10000 和 skip=0 會擷取前 10000 列資料，top=10000 和 skip=10000 會擷取接下來的 10000 列資料，依此類推。 | 否 |
| 篩選器 | 字串 | 篩選回應中的資料列的一或多個陳述式。 如需詳細資訊，請參閱下面的篩選功能變數一節。 | 否 |
| aggregationLevel | 字串 | 指定要擷取彙總資料的時間範圍。 可以是下列其中一個字串：day、week 或 month。 如果未指定，則預設值為 day。 | 否 |
| orderby | 字串 | 對每個附加元件獲取的結果資料值進行排序的陳述式。 語法為 orderby=field [order],field [order],...。field 參數可以是下列其中一個字串：
order 參數是選擇性的，而且可以是 asc 或 desc，以指定每個欄位的遞增或遞減順序。 預設為asc。 以下是範例 orderby 字串：orderby=date,market |
否 |
| groupby | 字串 | 僅將資料彙總套用至指定欄位的陳述式。 您可以指定下列功能變數：
傳回的資料列將包含 groupby 參數中指定的欄位，以及下列項目：
groupby 參數可以搭配 aggregationLevel 參數使用。 例如：&groupby=ageGroup,market&aggregationLevel=week |
否 |
篩選功能變數
要求的 filter 參數包含一或多個陳述式，可篩選回應中的資料列。 每個陳述式都包含與 eq 或 ne 運算子相關聯的功能變數和值，而且可以使用 and 或 or 來結合陳述式。 以下是一些範例 filter 參數：
- filter=market eq 'US' and gender eq 'm'
- filter=(market ne 'US') and (gender ne 'Unknown') and (gender ne 'm') and (market ne 'NO') and (ageGroup ne 'greater than 55' or ageGroup ne ‘less than 13’)
如需支援的功能變數清單，請參閱下表。 字串值必須以 filter 參數中的單引號括住。
| 功能變數 | 描述 |
|---|---|
| acquisitionType | 下列其中一個字串：
|
| ageGroup | 下列其中一個字串：
|
| storeClient | 下列其中一個字串：
|
| 性別 | 下列其中一個字串：
|
| market | 字串，其中包含發生獲取之市場的 ISO 3166 國家/地區代碼。 |
| osVersion | 下列其中一個字串：
|
| deviceType | 下列其中一個字串：
|
| orderName | 字串，指定用來取得附加元件之促銷碼的訂單名稱 (這只適用於使用者藉由兌換促銷碼來取得附加元件的情況)。 |
要求範例
下列範例示範數個取得附加元件獲取資料的要求。 將 inAppProductId 和 applicationId 值取代為附加元件或應用程式的適當 Store ID。
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&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/inappacquisitions?applicationId=9NBLGGGZ5QDR&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/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=7/3/2015&top=100&skip=0&filter=market ne 'US' and gender ne 'Unknown' and gender ne 'm' and market ne 'NO' and ageGroup ne '>55' HTTP/1.1
Authorization: Bearer <your access token>
回應
回應本文
| 值 | 類型 | 描述 |
|---|---|---|
| 值 | 陣列 | 物件的陣列，其中包含彙總附加元件下載資料。 如需關於每個物件中的資料的詳細資訊，請參閱下方的附加元件獲取值一節。 |
| @nextLink | 字串 | 如果有額外的資料頁面，此字串會包含可用來要求下一頁資料的 URI。 例如，如果要求的 top 參數設定為 10000，但附加元件獲取資料超過 10000 個資料列，則會傳回此值。 |
| TotalCount | int | 查詢的資料結果中的總列數。 |
附加元件下載值
Value 陣列中的元素包含下列值。
| 值 | 類型 | 描述 |
|---|---|---|
| date | 字串 | 下載資料之日期範圍中的第一個日期。 如果要求指定了單天，這個值就是該日期。 如果要求指定了一週、月或其他日期範圍，這個值就是該日期範圍中的第一個日期。 |
| inAppProductId | 字串 | 您正在擷取獲取資料之附加元件的 Store ID。 |
| inAppProductName | 字串 | 附加元件的顯示名稱。 除非您在 groupby 參數中指定 inAppProductName 功能變數，否則只有在 aggregationLevel 參數設定為 day 時，此值才會出現在回應資料中。 |
| applicationId | 字串 | 您想要擷取附加元件獲取資料之應用程式的 Store ID。 |
| applicationName | 字串 | 應用程式的顯示名稱。 |
| deviceType | 字串 | 已完成獲取的裝置類型。 如需支援的字串清單，請參閱上面的篩選功能變數一節。 |
| orderName | 字串 | 順序的名稱。 |
| storeClient | 字串 | 發生獲取的市集版本。 如需支援的字串清單，請參閱上面的篩選功能變數一節。 |
| osVersion | 字串 | 發生獲取的 OS 版本。 如需支援的字串清單，請參閱上面的篩選功能變數一節。 |
| market | 字串 | 發生獲取之市場的 ISO 3166 國家/地區代碼。 |
| 性別 | 字串 | 進行獲取的使用者性別。 如需支援的字串清單，請參閱上面的篩選功能變數一節。 |
| ageGroup | 字串 | 進行獲取的使用者年齡群組。 如需支援的字串清單，請參閱上面的篩選功能變數一節。 |
| acquisitionType | 字串 | 獲取的類型 (免費、付費等)。 如需支援的字串清單，請參閱上面的篩選功能變數一節。 |
| acquisitionQuantity | 整數 | 發生的獲取次數。 |
要求和回應範例
下列程式碼片段示範這些要求的範例要求和 JSON 回應本文。
範例要求
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>
範例回應
{
"Value": [
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Deluxe Collector's Edition",
"addonProductId": "9NBLGGAAGZDQ",
"date": "2022-07-29",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 18.12,
"purchasePriceLocalAmount": 18.12,
"purchaseTaxUSDAmount": 1.13,
"purchaseTaxLocalAmount": 1.13
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Episode 4",
"addonProductId": "9NAAAAAAAAAQ",
"date": "2017-01-07",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 4.147206,
"purchasePriceLocalAmount": 3.99,
"purchaseTaxUSDAmount": 0.686004,
"purchaseTaxLocalAmount": 0.66
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Deluxe Collector's Edition",
"addonProductId": "9NALGGGZ5QDQ",
"date": "2018-04-01",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 1.99,
"purchasePriceLocalAmount": 1.99,
"purchaseTaxUSDAmount": 0.0,
"purchaseTaxLocalAmount": 0.0
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Strategy Guide Episode 4",
"addonProductId": "9NBLGGGZ5QDQ",
"date": "2021-11-25",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 1.31902922876179,
"purchasePriceLocalAmount": 150.0,
"purchaseTaxUSDAmount": 0.114315866492689,
"purchaseTaxLocalAmount": 13.0
},
],
"TotalCount": 4,
"DataFreshnessTimestamp": "2022-07-29T05:54:00"
}
相關主題