Получение данных параллельного использования Xbox LiveGet Xbox Live concurrent usage data

Используйте этот метод в API аналитики для Microsoft Store, чтобы получить данные в режиме близости к реальному времени (с задержкой в 5-15 минут) о среднем числе пользователей, играющих в вашу игру с поддержкой Xbox Live в каждую минуту, час или день в течение заданного интервала времени.Use this method in the Microsoft Store analytics API to get near real-time usage data (with 5-15 minutes latency) about the average number of customers playing your Xbox Live-enabled game every minute, hour, or day during a specified time range. Эти сведения также доступны в отчете Xbox Analytics в центре партнеров.This information is also available in the Xbox analytics report in Partner Center.

Важно!

Этот метод поддерживает только игры для Xbox или игры, использующие службы Xbox Live.This method only supports games for Xbox or games that use Xbox Live services. Эти игры, в том числе игры, опубликованные партнерами Майкрософт, и отправленные в рамках программы [ID@Xbox, должны пройти процесс утверждения концепции](/gaming/xbox-live/developer-program-overview.md#id).These games must go through the concept approval process, which includes games published by Microsoft partners and games submitted via the ID@Xbox program. В настоящее время этот метод не поддерживает игры, опубликованные в рамках программы Xbox Live Creators Program.This method does not currently support games published via the Xbox Live Creators Program.

Предварительные требованияPrerequisites

Для использования этого метода сначала необходимо сделать следующее:To use this method, you need to first do the following:

  • Если вы еще не сделали этого, выполните все необходимые условия для API аналитики для Microsoft Store.If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • Получите маркер доступа Azure AD, который будет использоваться в заголовке запроса этого метода.Obtain an Azure AD access token to use in the request header for this method. После получения маркера доступа у вас будет 60 минут, чтобы использовать его до истечения срока действия.After you obtain an access token, you have 60 minutes to use it before it expires. После истечения срока действия маркера можно получить новый маркер.After the token expires, you can obtain a new one.

ЗапросRequest

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

МетодMethod Универсальный код ресурса (URI) запросаRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/gameanalytics

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

ЗаголовокHeader ТипType ОписаниеDescription
АвторизацияAuthorization строкаstring Обязательный.Required. Маркер доступа Azure AD в формате Bearer <token>.The Azure AD access token in the form Bearer <token>.

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

ПараметрParameter ТипType ОписаниеDescription ОбязательноRequired
applicationIdapplicationId строкаstring Код продукта в Store для игры, по которой требуется получить данные одновременного использования Xbox Live.The Store ID of the game for which you want to retrieve Xbox Live concurrent usage data. ДаYes
metricTypemetricType строкаstring Строка, определяющая тип аналитических данных Xbox Live, которые необходимо получить.A string that specifies the type of Xbox Live analytics data to retrieve. Для этого метода укажите значение concurrency.For this method, specify the value concurrency. ДаYes
startDatestartDate Датаdate Начальная дата диапазона дат, для которого требуется получить данные одновременного использования.The start date in the date range of concurrent usage data to retrieve. См. описание aggregationLevel, чтобы узнать поведение по умолчанию.See the aggregationLevel description for default behavior. НетNo
endDateendDate Датаdate Конечная дата диапазона дат, для которого требуется получить данные одновременного использования.The end date in the date range of concurrent usage data to retrieve. См. описание aggregationLevel, чтобы узнать поведение по умолчанию.See the aggregationLevel description for default behavior. НетNo
aggregationLevelaggregationLevel строкаstring Определяет диапазон времени, для которого требуется получить сводные данные.Specifies the time range for which to retrieve aggregate data. Можно использовать следующие строки: minute, hour или day.Can be one of the following strings: minute, hour, or day. Если параметр не задан, значение по умолчанию — day.If unspecified, the default is day.

Если вы не укажете startDate или endDate, по умолчанию в теле ответа содержится следующее:If you do not specify startDate or endDate, the response body defaults to the following:

  • minute: последние 60 записей из доступных данных.minute: The last 60 records of available data.
  • hour: последние 24 записи из доступных данных.hour: The last 24 records of available data.
  • day: последние 7 записей из доступных данных.day: The last 7 records of available data.

Следующие уровни агрегирования имеют ограничения размера по количеству записей, которые могут быть возвращены.The following aggregation levels have size limits on the number of records that can be returned. Если диапазон запрошенного времени слишком велик, записи будут усечены.The records will be truncated if the requested time span is too large.

  • minute: до 1440 записей (данные за 24 часа).minute: Up to 1440 records (24 hours of data).
  • hour: до 720 записей (данные за 30 дней).hour: Up to 720 records (30 days of data).
  • day: до 60 записей (данные за 60 дней).day: Up to 60 records (60 days of data).
НетNo

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

Ниже приведен пример запроса на получение данных одновременного использования для вашей игры с поддержкой Xbox Live.The following example demonstrates a request for getting concurrent usage data for your Xbox Live-enabled game. Этот запрос извлекает данные по каждой минуте от 1 февраля 2018 г. до 2 февраля 2018 г.This request retrieves data for every minute between February 1 2018 and February 2 2018. Замените значение applicationId кодом продукта в Store для вашей игры.Replace the applicationId value with the Store ID for your game.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/gameanalytics?applicationId=9NBLGGGZ5QDR&metrictype=concurrency&aggregationLevel=hour&startDate=2018-02-01&endData=2018-02-02 HTTP/1.1
Authorization: Bearer <your access token>

ОтветResponse

Тело ответа содержит массив объектов, каждый из которых содержит один набор данных одновременного использования для заданной минуты, часа или дня.The response body contains an array of objects that each contain one set of concurrent usage data for a specified minute, hour, or day. Каждый объект содержит следующие значения.Each object contains the following values.

ЗначениеValue ТипType ОписаниеDescription
СчетчикCount numbernumber Среднее количество пользователей, игравших в вашу игру с поддержкой Xbox Live в заданную минуту, час или день.The average number of customers playing your Xbox Live-enabled for the specified minute, hour, or day.

Примечание.     Значение 0 указывает, что в течение указанного интервала не было одновременно работающих пользователей или произошла ошибка при сборе одновременных данных пользователя для игры в течение заданного интервала.Note  A value of 0 indicates either that there were no concurrent users during the specified interval, or that there was a failure while collecting concurrent user data for the game during the specified interval.

ДатаDate строкаstring Дата и время указывает минуту, час или день, к которым относятся данные одновременного использования.The date and time that specifies the minute, hour or day during which the concurrent usage data occurred.
SeriesNameSeriesName строкаstring Всегда имеет значение **UserConcurrency **.This always has the value UserConcurrency.

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

В следующем примере демонстрируется пример текста ответа JSON на данный запрос с поминутным агрегированием данных.The following example demonstrates an example JSON response body for this request with data aggregation by minute.

[   {
        "Count": 418.0,
        "Date": "2018-02-02T04:42:13.65Z",
        "SeriesName": "UserConcurrency"
    }, {
        "Count": 418.0,
        "Date": "2018-02-02T04:43:13.65Z",
        "SeriesName": "UserConcurrency"
    }, {
        "Count": 415.0,
        "Date": "2018-02-02T04:44:13.65Z",
        "SeriesName": "UserConcurrency"
    }, {
        "Count": 412.0,
        "Date": "2018-02-02T04:45:13.65Z",
        "SeriesName": "UserConcurrency"
    }, {
        "Count": 414.0,
        "Date": "2018-02-02T04:46:13.65Z",
        "SeriesName": "UserConcurrency"
    }
]