Obter dados de uso simultâneo do Xbox LiveGet Xbox Live concurrent usage data

Use este método na API de análise da Microsoft Store para obter dados de uso quase em tempo real (com latência de 5 a 15 minutos) sobre o número médio de clientes jogando seu jogo habilitado para Xbox Live a cada minuto, hora ou dia durante um intervalo de tempo especificado.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. Essas informações também estão disponíveis no relatório do Xbox Analytics no Partner Center.This information is also available in the Xbox analytics report in Partner Center.

Importante

Esse método oferece suporte somente a jogos para Xbox ou que usam os serviços do Xbox Live.This method only supports games for Xbox or games that use Xbox Live services. Esses jogos devem passar pelo processo de aprovação de conceito, que inclui jogos publicados por parceiros da Microsoft e jogos enviados por meio do programa ID@Xbox.These games must go through the concept approval process, which includes games published by Microsoft partners and games submitted via the ID@Xbox program. Esse método não oferece suporte no momento para jogos publicados pelo Programa de Criadores do Xbox Live.This method does not currently support games published via the Xbox Live Creators Program.

Pré-requisitosPrerequisites

Para usar este método, primeiro você precisa do seguinte:To use this method, you need to first do the following:

  • Se você não tiver feito isso, conclua todos os pré-requisitos para a API de análise da Microsoft Store.If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • Obtenha um token de acesso do Azure AD a ser usado no cabeçalho da solicitação para este método.Obtain an Azure AD access token to use in the request header for this method. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar.After you obtain an access token, you have 60 minutes to use it before it expires. Depois que o token expirar, você poderá obter um novo.After the token expires, you can obtain a new one.

SolicitaçãoRequest

Sintaxe da solicitaçãoRequest syntax

MétodoMethod URI da solicitaçãoRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/gameanalytics

Cabeçalho da solicitaçãoRequest header

CabeçalhoHeader TipoType DescriçãoDescription
AutorizaçãoAuthorization stringstring Obrigatórios.Required. O token de acesso do Azure AD no formulário Bearer <token>.The Azure AD access token in the form Bearer <token>.

Parâmetros da solicitaçãoRequest parameters

ParâmetroParameter TipoType DescriçãoDescription ObrigatórioRequired
applicationIdapplicationId stringstring A ID da Store do jogo para o qual você deseja recuperar os dados de uso simultâneo do Xbox Live.The Store ID of the game for which you want to retrieve Xbox Live concurrent usage data. SimYes
metricTypemetricType stringstring Uma sequência que especifica o tipo de dados de análise do Xbox Live para recuperar.A string that specifies the type of Xbox Live analytics data to retrieve. Para este método, especifique o valor concurrency.For this method, specify the value concurrency. SimYes
startDatestartDate datedate A data de início no intervalo de datas dos dados de uso simultâneo a serem recuperados.The start date in the date range of concurrent usage data to retrieve. Consulte a descrição de aggregationLevel para o comportamento padrão.See the aggregationLevel description for default behavior. NãoNo
endDateendDate datedate A data de término no intervalo de datas dos dados de uso simultâneo a serem recuperados.The end date in the date range of concurrent usage data to retrieve. Consulte a descrição de aggregationLevel para o comportamento padrão.See the aggregationLevel description for default behavior. NãoNo
aggregationLevelaggregationLevel stringstring Especifica o intervalo de tempo para o qual recuperar dados agregados.Specifies the time range for which to retrieve aggregate data. Pode ser uma das seguintes sequências: minute, hour ou day.Can be one of the following strings: minute, hour, or day. Se não for especificado, o padrão será day.If unspecified, the default is day.

Se você não especificar startDate ou endDate, o corpo da resposta assume como padrão o seguinte:If you do not specify startDate or endDate, the response body defaults to the following:

  • minute: os últimos 60 registros de dados disponíveis.minute: The last 60 records of available data.
  • hour: os últimos 24 registros de dados disponíveis.hour: The last 24 records of available data.
  • day: os últimos 7 registros de dados disponíveis.day: The last 7 records of available data.

Os seguintes níveis de agregação têm limites de tamanho no número de registros que podem ser retornado.The following aggregation levels have size limits on the number of records that can be returned. Os registros serão truncados se o período de tempo solicitado for muito grande.The records will be truncated if the requested time span is too large.

  • minute: até 1440 registros (24 horas de dados).minute: Up to 1440 records (24 hours of data).
  • hour: até 720 registros (30 dias de dados).hour: Up to 720 records (30 days of data).
  • day: até 60 registros (60 dias de dados).day: Up to 60 records (60 days of data).
NãoNo

Exemplo de solicitaçãoRequest example

O exemplo a seguir demonstra uma solicitação de obtenção de dados de uso simultâneo para o seu jogo habilitado para Xbox Live.The following example demonstrates a request for getting concurrent usage data for your Xbox Live-enabled game. Essa solicitação recupera os dados para cada minuto entre 1º de fevereiro de 2018 e 2 de fevereiro de 2018.This request retrieves data for every minute between February 1 2018 and February 2 2018. Substitua o valor de applicationId pela ID da Store do seu jogo.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>

RespostaResponse

O corpo da resposta contém uma matriz de objetos, cada um com um conjunto de dados de uso simultâneo de um minuto, hora ou dia especificado.The response body contains an array of objects that each contain one set of concurrent usage data for a specified minute, hour, or day. Cada objeto que contém os valores a seguir.Each object contains the following values.

ValorValue TipoType DescriçãoDescription
ContagemCount númeronumber O número médio de clientes jogando seu jogo habilitado para Xbox Live pelo minuto, hora ou dia especificado.The average number of customers playing your Xbox Live-enabled for the specified minute, hour, or day.

Note   Observação   Um valor de 0 indica que não havia usuários simultâneos durante o intervalo especificado ou que houve uma falha ao coletar dados de usuário simultâneos para o jogo durante o intervalo especificado.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.

DataDate stringstring A data e hora que especifica o minuto, hora ou dia durante o qual os dados de uso simultâneo ocorreram.The date and time that specifies the minute, hour or day during which the concurrent usage data occurred.
SeriesNameSeriesName stringstring Isso sempre tem o valor UserConcurrency.This always has the value UserConcurrency.

Exemplo de respostaResponse example

O código a seguir demonstra um exemplo de corpo de resposta JSON para essa solicitação com agregação de dados por minuto.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"
    }
]