Obter classificações de aplicações

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

Pré-requisitos

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

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

Pedido

Sintaxe da solicitação

Método Solicitar URI
Obtém https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings

Cabeçalho da solicitação

Cabeçalho Tipo Descrição
Autorização corda Obrigatório O token de acesso do Azure AD no formato Bearer<token>.

Parâmetros de solicitação

Parâmetro Tipo Descrição Obrigatório
applicationId corda O ID da Store do aplicativo para o qual você deseja recuperar dados de classificações. Sim
data de início data A data de início no intervalo de datas dos dados de classificações a recuperar. O padrão é a data atual. Não
data de término data A data final do intervalo de datas dos dados de avaliação a serem recuperados. O padrão é a data atual. Não
Início Int O número de linhas de dados a serem retornadas na solicitação. O valor máximo e o valor padrão, se não especificado, é 10000. Se houver mais linhas na consulta, o corpo da resposta incluirá um próximo link que você pode usar para solicitar a próxima página de dados. Não
pular Int O número de linhas a serem ignoradas na consulta. Use este parâmetro para percorrer grandes conjuntos de dados. Por exemplo, top=10000 e skip=0 recupera as primeiras 10000 linhas de dados, top=10000 e skip=10000 recupera as próximas 10000 linhas de dados e assim por diante. Não
filtro corda Uma ou mais declarações que filtram as linhas da resposta. Para obter mais informações, consulte a seção de campos de filtro abaixo. Não
Nível de Agregação corda Especifica o intervalo de tempo para o qual recuperar dados agregados. Pode ser uma das seguintes cadeias de caracteres: dia, semana ou mês. Se não for especificado, o padrão é dia. Não
ordenar por corda 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 strings:
  • data
  • osVersão
  • mercado
  • Tipo de dispositivo
  • estáRevisado

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

Aqui está um exemplo orderby string: orderby=date,market

 Não
"groupby" corda Uma instrução que aplica a agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos:
  • data
  • nome_do_aplicativo
  • mercado
  • osVersão
  • Tipo de dispositivo
  • estáRevisado

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

  • data
  • applicationId
  • cinco estrelas
  • quatro estrelas
  • três estrelas
  • duas estrelas
  • umaEstrela

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 do filtro da solicitação contém uma ou mais declarações que filtram as linhas na resposta. Cada instrução contém um campo e um valor que estão associados aos operadores eq ou ne , e as instruções podem ser combinadas usando e ou ou.

Aqui está um exemplo filtro string: filter=market eq 'US' e deviceType eq 'phone' e isRevised eq true

Para obter uma lista dos campos suportados, consulte a tabela a seguir. Os valores de cadeia de caracteres devem estar entre aspas simples no parâmetro do filtro .

Campos Descrição
mercado Uma cadeia de caracteres que contém o código de país ISO 3166 do mercado onde seu aplicativo foi classificado.
osVersão Uma das seguintes cadeias de caracteres:
  • Telefone Windows 7.5
  • Windows Phone 8
  • Windows Phone 8.1
  • Telefone Windows 10
  • Janelas 8
  • Windows 8.1
  • Janelas 10
  • Janelas 11
  • Desconhecido
Tipo de dispositivo Uma das seguintes cadeias de caracteres:
  • Computador pessoal
  • Telefone
  • Console-Xbox Um
  • Console-Xbox Série X
  • Internet das coisas
  • Holográfico
  • Desconhecido
está revisado Especifique true para filtrar as classificações que foram revisadas; caso contrário , falso.

Exemplo de solicitação

Os exemplos a seguir demonstram várias solicitações para obter dados de classificação. Substitua o valor applicationId pelo Store ID da sua aplicação.

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 Tipo Descrição
Valor conjunto 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 de valores de classificação abaixo.
@nextLink corda Se houver páginas adicionais de dados, essa cadeia de caracteres conterá um URI que você pode usar para solicitar a próxima página de dados. Por exemplo, esse valor será retornado se o parâmetro superior da solicitação estiver definido como 10000, mas houver mais de 10000 linhas de dados de classificação para a consulta.
Contagem total Int O número total de linhas no resultado de dados para a consulta.

Valores de classificação

Os elementos na matriz Value contêm os seguintes valores.

Valor Tipo Descrição
data corda A primeira data no intervalo de datas para os dados de classificação. Se a solicitação especificou um único dia, esse valor será essa data. Se a solicitação especificou uma semana, mês ou outro intervalo de datas, esse valor será a primeira data nesse intervalo de datas.
applicationId corda O identificador da loja da aplicação da qual está a recuperar dados de classificações.
Nome da Aplicação corda O nome de exibição da aplicação.
mercado corda O código de país ISO 3166 do mercado onde a classificação foi apresentada.
osVersão corda A versão do SO na qual a classificação foi submetida. Para obter uma lista das cadeias de caracteres suportadas, consulte a seção de campos de filtro acima.
Tipo de dispositivo corda O tipo de dispositivo no qual a classificação foi enviada. Para obter uma lista das cadeias de caracteres suportadas, consulte a seção de campos de filtro acima.
está revisado Booleano O valor true indica que a classificação foi revista; caso contrário , falso.
oneStar número O número de classificações de uma estrela.
TwoStars número O número de classificações de duas estrelas.
três estrelas número O número de classificações de três estrelas.
quatro estrelas número O número de classificações de quatro estrelas.
cinco estrelas número O número de classificações de cinco estrelas.

Exemplo de solicitação e resposta

Os trechos de código a seguir demonstram alguns exemplos de solicitação e corpo de resposta JSON para essas solicitações.

Pedido de amostra

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

Exemplo de resposta


{
    "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
}

Pedido de amostra

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>

Exemplo de resposta

{
    "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
}
  • Last updated on