Partilhar via

Obter classificações de app

  • Artigo

Use esse método na API de análise da Microsoft Store para obter dados de classificações agregados em formato JSON para um determinado intervalo de datas e outros filtros opcionais. Essas informações também estão disponíveis no relatório de Revisões na Central de Parceiros.

Pré-requisitos

Para usar este método, primeiro você precisa fazer o seguinte:

  • Se você ainda não fez isso, conclua todos os pré-requisitos da API de análise da Microsoft Store.
  • Obtenha um token de acesso do Azure AD a ser usado no cabeçalho da solicitação para esse método. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá obter um novo.

Solicitar

Sintaxe da solicitação

Método URI da solicitação
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings

Cabeçalho da solicitação

Cabeçalho Tipo Descrição
Autorização string Obrigatório. O token de acesso do Azure AD no Token<de portador> do formulário.

Parâmetros da solicitação

Parâmetro Tipo Descrição Obrigatório
applicationId string A ID da Store do aplicativo cujos dados de classificações você deseja Recuperar. Sim
startDate date A data de início no intervalo de datas dos dados de classificações a serem recuperados. O padrão é a data atual. Não
endDate date A data de término no intervalo de datas dos dados de classificações a serem recuperados. O padrão é a data atual. Não
top int O número de linhas de dados a serem retornadas na solicitação. O valor máximo e padrão, se não for especificado, será 10.000. Se houver mais linhas na consulta, o corpo da resposta incluirá um proximo link que você poderá usar para solicitar a próxima página de dados. Não
skip int O número de linhas a serem ignoradas na consulta. Use esse parâmetro para percorrer grandes conjuntos de dados. Por exemplo, top=10000 e skip=0 recupera as primeiras 10.000 mil linhas de dados, top=10000 e skip=10000 recupera as próximas dez mil linhas de dados, e assim por diante. Não
filtro string Uma ou mais instruções que filtram as linhas na resposta. Para obter mais informações, consulte a seção sobre campos de filtro abaixo. Não
aggregationLevel string Especifica o intervalo de tempo cujos dados agregados serão recuperados. Pode ser uma das seguintes sequências: dia, semana ou mês. Se não for especificado, o padrão será dia. Não
orderby string Uma instrução que ordena os valores dos dados de resultado para cada classificação. A sintaxe é orderby=field [order],field [order],.... O parâmetro field pode ser uma das seguintes sequências:
  • date
  • osVersion
  • market
  • deviceType
  • isRevised

O parâmetro order é opcional e pode ser asc ou desc para especificar ordem ascendente ou descendente para cada campo. O padrão é asc.

Este é um exemplo de sequência orderby: orderby=date,market

 Não
groupby string Uma instrução que aplica agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos:
  • date
  • applicationName
  • market
  • osVersion
  • deviceType
  • isRevised

As linhas de dados retornadas conterão os campos especificados no parâmetro groupby, bem como:

  • date
  • applicationId
  • fiveStars
  • fourStars
  • threeStars
  • twoStars
  • oneStar

O parâmetro groupby pode ser usado com o parâmetro aggregationLevel. Por exemplo: &groupby=osVersion,market&aggregationLevel=week

 Não

 

Filtrar campos

O parâmetro filter da solicitação contém uma ou mais instruções que filtram as linhas na resposta. Cada instrução contém um campo e um valor associados aos operadores eq ou ne e as instruções podem ser combinadas usando and ou or.

Este é um exemplo de sequência filter: filter=market eq 'US' and deviceType eq 'phone' and isRevised eq true

Para obter uma lista dos campos com suporte, consulte a tabela a seguir. Os valores de sequência devem estar entre aspas simples no parâmetro filter.

Campos Descrição
market Uma sequência que contém o código de país ISO 3166 do mercado no qual o aplicativo foi classificado.
osVersion Uma das cadeias de caracteres a seguir:
  • Windows Phone 7.5
  • Windows Phone 8
  • Windows Phone 8.1
  • Windows Phone 10
  • Windows 8
  • Windows 8.1
  • Windows 10
  • Windows 11
  • Desconhecido
deviceType Uma das cadeias de caracteres a seguir:
  • Computador
  • Telefone
  • Console-Xbox One
  • Console-Xbox Series X
  • IoT
  • Holográfico
  • Desconhecido
isRevised Especifique true para filtrar as classificações que foram revisadas; caso contrário, selecione false.

Exemplo de solicitação

Os exemplos a seguir demonstram várias solicitações para obter dados de classificações. Substitua o valor applicationId pela ID da Store para seu aplicativo.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings?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/ratings?applicationId=9NBLGGGZ5QDR&startDate=8/1/2015&endDate=8/31/2015&skip=0&filter=market eq 'US' and deviceType eq 'phone' HTTP/1.1
Authorization: Bearer <your access token>

Resposta

Corpo da resposta

Valor Type Descrição
Valor matriz Uma matriz de objetos que contêm dados de classificações agregados. Para obter mais informações sobre os dados em cada objeto, consulte a seção valores de classificação abaixo.
@nextLink string Se houver páginas adicionais de dados, essa sequência conterá um URI que você poderá usar para solicitar a próxima página de dados. Por exemplo, esse valor será retornado se o parâmetro top da solicitação estiver definido como 10000, mas se existirem mais de 10000 linhas de dados de classificações para a consulta.
TotalCount int O número total de linhas no resultado de dados da consulta.

Valores de classificação

Os elementos na matriz Value contêm os valores a seguir.

Valor Type Descrição
date string A primeira data no intervalo de datas para os dados de classificações. Se a solicitação tiver especificado um único dia, esse valor será essa data. Se a solicitação tiver especificado uma semana, um mês ou outro intervalo de datas, esse valor será a primeira data nesse intervalo de datas.
applicationId string O ID da Store do aplicativo para o qual você está recuperando os dados de classificações.
applicationName string O nome de exibição do aplicativo.
market string O código de país ISO 3166 do mercado no qual a classificação foi enviada.
osVersion string A versão do SO na qual a classificação foi enviada. Para obter uma lista das sequências com suporte, consulte a seção campos de filtro acima.
deviceType string O tipo de dispositivo no qual a classificação foi enviada. Para obter uma lista das sequências com suporte, consulte a seção campos de filtro acima.
isRevised Booliano O valor true indica que a classificação foi revisada, caso contrário, o valor é false.
oneStar número O número de classificações de uma estrela.
twoStars número O número de classificações de duas estrelas.
threeStars número O número de classificações de três estrelas.
fourStars número O número de classificações de quatro estrelas.
fiveStars número O número de classificações de cinco estrelas.

Exemplo de solicitação e resposta

Os snippets de código a seguir demonstram alguns exemplos de solicitações e o corpo da resposta JSON para estas solicitações.

Solicitação de Exemplo

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

Resposta de exemplo


{
    "Value": [
        {
            "date": "2012-09-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "oneStar": 1,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 1,
            "fiveStars": 3
        },
        {
            "date": "2012-09-02",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "oneStar": 3,
            "twoStars": 0,
            "threeStars": 1,
            "fourStars": 2,
            "fiveStars": 17
        },
        {
            "date": "2012-09-03",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "oneStar": 1,
            "twoStars": 1,
            "threeStars": 1,
            "fourStars": 5,
            "fiveStars": 17
        },
  ],
    "TotalCount": 3
}

Solicitação de Exemplo

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

Resposta de exemplo

{
    "Value": [
        {
            "date": "2022-06-22",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "CL",
            "osVersion": "Windows 11",
            "deviceType": "PC",
            "isRevised": "false",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 0,
            "fiveStars": 1
        },
        {
            "date": "2022-06-22",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "TR",
            "osVersion": "Windows 11",
            "deviceType": "PC",
            "isRevised": "false",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 0,
            "fiveStars": 1
        },
        {
            "date": "2022-06-29",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "FR",
            "osVersion": "Windows 10",
            "deviceType": "PC",
            "isRevised": "false",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 1,
            "fiveStars": 0
        },
        {
            "date": "2022-07-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "BR",
            "osVersion": "Windows 10",
            "deviceType": "PC",
            "isRevised": "false",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 0,
            "fiveStars": 1
        },
        {
            "date": "2022-07-04",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "ES",
            "osVersion": "Windows 10",
            "deviceType": "PC",
            "isRevised": "false",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 0,
            "fiveStars": 1
        },
        {
            "date": "2022-07-06",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "ES",
            "osVersion": "Windows 10",
            "deviceType": "PC",
            "isRevised": "false",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 0,
            "fiveStars": 1
        },
        {
            "date": "2022-07-07",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "AE",
            "osVersion": "Windows 10",
            "deviceType": "PC",
            "isRevised": "true",
            "oneStar": 1,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 0,
            "fiveStars": 0
        },
        {
            "date": "2022-07-10",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "BR",
            "osVersion": "Windows 10",
            "deviceType": "PC",
            "isRevised": "true",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 0,
            "fiveStars": 1
        },
        {
            "date": "2022-07-13",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "EG",
            "osVersion": "Windows 10",
            "deviceType": "PC",
            "isRevised": "false",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 0,
            "fiveStars": 1
        },
        {
            "date": "2022-07-14",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "market": "BR",
            "osVersion": "Windows 10",
            "deviceType": "PC",
            "isRevised": "true",
            "oneStar": 0,
            "twoStars": 0,
            "threeStars": 0,
            "fourStars": 1,
            "fiveStars": 0
        }
    ],
    "TotalCount": 10
}