Получение данных о приобретении надстроек для игр и приложений

  • Статья

Используйте этот метод в API аналитики Microsoft Store, чтобы получить статистические данные о приобретении надстроек в формате JSON для приложений UWP и игр Xbox One, которые были приема через портал разработчика Xbox (XDP) и доступны на панели мониторинга Центра партнеров XDP Analytics.

Необходимые компоненты

Чтобы использовать этот метод, сначала необходимо выполнить следующие действия:

  • Если это еще не сделано, выполните все предварительные требования для API аналитики Microsoft Store.
  • Получите маркер доступа Azure AD для использования в заголовке запроса для этого метода. После получения маркера доступа у вас будет 60 минут, чтобы использовать его до истечения срока действия. После истечения срока действия маркера можно получить новый.

Примечание.

Этот API не предоставляет ежедневные статистические данные до 1 октября 2016 г.

Запросить

Синтаксис запроса

Способ URI запроса
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

Заголовок запроса

Верхний колонтитул Тип Описание
Авторизация строка Обязательно. Маркер доступа Azure AD в форме носителя<token>.

Параметры запроса

Требуется параметр applicationId или addonProductId. Чтобы получить данные о приобретении для всех надстроек, зарегистрированных в приложении, укажите параметр applicationId . Чтобы получить данные о приобретении для одной надстройки, укажите параметр addonProductId . Если указать оба параметра, параметр applicationId игнорируется.

Параметр Тип Описание Обязательное поле
applicationId строка ProductId игры Xbox One, для которой вы извлеките данные о приобретении. Чтобы получить идентификатор продукта игры, перейдите к игре в программе XDP Analytics и получите productId из URL-адреса. Кроме того, при скачивании данных о приобретении из отчета аналитики Центра партнеров идентификатор продукта включен в TSV-файл. Да
addonProductId строка ProductId надстройки, для которой требуется получить данные о приобретении. Да
startDate Дата Дата начала в диапазоне дат получения данных получения надстроек. Значение по умолчанию — текущая дата. No
endDate Дата Дата окончания в диапазоне дат получения данных о приобретении надстройки. Значение по умолчанию — текущая дата. No
Фильтр строка Одна или несколько инструкций, которые фильтруют строки в ответе. Каждая инструкция содержит имя поля из текста ответа и значения, связанного с операторами eq или ne, и операторы могут быть объединены с помощью или или. Строковые значения должны быть окружены одними кавычками в параметре фильтра. Например, filter=market eq 'US' и gender eq 'm'.
В тексте ответа можно указать следующие поля:
  • acquisitionType
  • возраст
  • storeClient
  • пол
  • Рынке
  • osVersion
  • deviceType
  • sandboxId
 No
aggregationLevel строка Указывает диапазон времени, для которого требуется получить статистические данные. Может быть одной из следующих строк: день, неделя или месяц. Если не указано, значение по умолчанию равно дню. No
orderby строка Инструкция, которая упорядочивает значения результирующих данных для каждого приобретения надстройки. Синтаксис — orderby=field [order], field [order],... Параметр поля может быть одной из следующих строк:
  • date
  • acquisitionType
  • возраст
  • storeClient
  • пол
  • Рынке
  • osVersion
  • deviceType
  • orderName
Параметр order является необязательным и может быть asc или desc , чтобы указать возрастание или убывание для каждого поля. Значение по умолчанию — asc.
Ниже приведен пример строки заказа : orderby=date,market		 No
Groupby строка Инструкция, которая применяет агрегирование данных только к указанным полям. Можно указать следующие поля:
  • date
  • applicationName
  • addonProductName
  • acquisitionType
  • возраст
  • storeClient
  • пол
  • Рынке
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleIdHex
Возвращаемые строки данных будут содержать поля, указанные в параметре groupby , а также следующие:
  • date
  • applicationId
  • addonProductId
  • acquisitionQuantity
Параметр groupby можно использовать с параметром aggregationLevel . Например: &groupby=age,market&aggregationLevel=week		 No

Пример запроса

В следующих примерах показано несколько запросов на получение данных о приобретении надстроек. Замените значения addonProductId и applicationId соответствующим идентификатором Магазина для надстройки или приложения.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&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/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0&filter=market eq 'GB' and gender eq 'm' HTTP/1.1 

Authorization: Bearer <your access token>

Response

Текст ответа

Значение Тип Описание
Значение array Массив объектов, содержащих статистические данные о приобретении надстроек. Дополнительные сведения о данных в каждом объекте см . в разделе "Значения приобретения надстройки" ниже.
TotalCount INT Общее количество строк в результатах данных для запроса.

Значения приобретения надстроек

Элементы в массиве значений содержат следующие значения.

Значение Тип Описание
Дата строка Первая дата в диапазоне дат для данных приобретения. Если запрос указал один день, это значение равно дате. Если запрос указал неделю, месяц или другой диапазон дат, это значение является первой датой в этом диапазоне дат.
addonProductId строка ProductId надстройки, для которой извлекаются данные о приобретении.
addonProductName строка Отображаемое имя надстройки. Это значение отображается только в данных ответа, если параметр aggregationLevel имеет значение day, если в параметре groupby не указано поле addonProductName.
applicationId строка ProductId приложения, для которого требуется получить данные о приобретении надстроек.
applicationName строка Отображаемое имя игры.
deviceType строка Одна из следующих строк, указывающая тип устройства, завершив приобретение:
  • "PC"
  • "Телефон"
  • "Console-Xbox One"
  • "Консольная серия Xbox X"
  • "IoT"
  • "Сервер"
  • "Планшет"
  • "Holographic"
  • "Неизвестно"
storeClient строка Одна из следующих строк, указывающая версию Магазина, в которой произошло приобретение:
  • "Магазин Windows Телефон (клиент)"
  • "Microsoft Store (клиент)" (или "Магазин Windows (клиент)", если запрашивать данные до 23 марта 2018 г.)
  • Microsoft Store (web)" (или "Магазин Windows (web)", если запрашивать данные до 23 марта 2018 г.)
  • "Приобретение томов организациями"
  • "Другое"
osVersion строка Версия ОС, в которой произошло приобретение. Для этого метода это значение всегда равно Windows 10 или Windows 11.
на рынок строка Код страны ISO 3166 рынка, на котором произошло приобретение.
пол строка Одна из следующих строк, указывающая пол пользователя, который сделал приобретение:
  • "m"
  • "f"
  • "Неизвестно"
возраст строка Одна из следующих строк, указывающая возрастную группу пользователя, который сделал приобретение:
  • "менее 13"
  • "13-17"
  • "18-24"
  • "25-34"
  • "35-44"
  • "44-55"
  • "больше 55"
  • "Неизвестно"
acquisitionType строка Одна из следующих строк, указывающих тип приобретения:
  • "Бесплатный"
  • "Пробная версия"
  • "Платный"
  • "Рекламный код"
  • "Iap"
  • "Подписка Iap"
  • "Частная аудитория"
  • "Предварительный заказ"
  • "Xbox Game Pass" (или "Game Pass", если запрашивать данные до 23 марта 2018 г.)
  • "Диск"
  • "Предоплаченный код"
  • "Платный предварительный заказ"
  • "Отмененный предварительный заказ"
  • "Сбой предварительного заказа"
acquisitionQuantity integer Количество приобретений, которые произошли.
inAppProductId строка Идентификатор продукта, в котором используется эта надстройка.
inAppProductName строка Имя продукта, в котором используется эта надстройка.
paymentInstrumentType строка Тип инструмента оплаты, используемый для приобретения.
sandboxId строка Идентификатор песочницы, созданный для игры. Это может быть значение RETAIL или частный идентификатор песочницы.
xboxTitleId строка Идентификатор названия Xbox продукта из XDP, если это применимо.
localCurrencyCode строка Код локальной валюты на основе страны учетной записи Центра партнеров.
xboxProductId строка Идентификатор продукта Xbox из XDP, если это применимо.
availabilityId строка Идентификатор доступности продукта из XDP, если применимо.
skuId строка Идентификатор SKU продукта из XDP, если это применимо.
skuDisplayName строка Отображаемое имя SKU продукта из XDP, если применимо.
xboxParentProductId строка Идентификатор родительского продукта Xbox из XDP, если это применимо.
parentProductName строка Имя родительского продукта из XDP, если применимо.
productTypeName строка Имя типа продукта из XDP, если применимо.
purchaseTaxType строка При необходимости приобрести налоговый тип продукта из XDP.
purchasePriceUSDAmount number Сумма, выплачиваемая клиентом за надстройку, преобразованная в USD.
purchasePriceLocalAmount number Сумма, выплачиваемая клиентом для надстройки, в валюте региона.
purchaseTaxUSDAmount number Сумма налога, примененная к надстройке, преобразованной в USD.
purchaseTaxLocalAmount number При необходимости приобрести налог на локальную сумму продукта из XDP.

Пример ответа

В следующем примере показан пример текста ответа JSON для этого запроса.

{ 
  "Value": [ 
    { 
            "inAppProductId": "9NBLGGH1864K", 
            "inAppProductName": "866879", 
            "addonProductId": "9NBLGGH1864K", 
            "addonProductName": "866879", 
            "date": "2017-11-05", 
            "applicationId": "9WZDNCRFJ314", 
            "applicationName": "Tetris Blitz", 
            "acquisitionType": "Iap", 
            "age": "35-49", 
            "deviceType": "Phone", 
            "gender": "m", 
            "market": "US", 
            "osVersion": "Windows Phone 8.1", 
            "paymentInstrumentType": "Credit Card", 
            "sandboxId": "RETAIL", 
            "storeClient": "Windows Phone Store (client)", 
            "xboxTitleId": "", 
            "localCurrencyCode": "USD", 
            "xboxProductId": "00000000-0000-0000-0000-000000000000", 
            "availabilityId": "", 
            "skuId": "", 
            "skuDisplayName": "Full", 
            "xboxParentProductId": "", 
            "parentProductName": "Tetris Blitz", 
            "productTypeName": "Add-On", 
            "purchaseTaxType": "", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 1.08, 
            "purchasePriceLocalAmount": 0.09, 
            "purchaseTaxUSDAmount": 1.08, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

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