Obter classificações de aplicativo

Use esse método na API de análise da Microsoft Store para obter dados de classificações agregadas 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 Revisões no Partner Center.

Pré-requisitos

Para usar esse 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. Depois de obter um token de acesso, você terá 60 minutos para usá-lo antes que ele expire. Depois que o token expirar, você poderá obter um novo.

Solicitação

Sintaxe da solicitação

Método URI de solicitação
OBTER 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
ID do aplicativo corda O ID da loja do aplicativo para a qual deseja obter dados de avaliações. Sim
Data de Início data A data de início no intervalo de datas dos dados de classificação a serem recuperados. O padrão é a data atual. Não
data de término data A data de término no intervalo de datas dos dados de classificação a serem recuperados. O padrão é a data atual. Não
Início int O número de linhas de dados a serem retornados na solicitação. O valor máximo e o valor padrão se não especificado for 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 esse 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 será dia. Não
pedido por corda Uma instrução que ordena os valores de 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
  • OSVersion
  • mercado
  • tipoDeDispositivo
  • foi revisado

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

Aqui está um exemplo de string orderby: 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
  • OSVersion
  • tipoDeDispositivo
  • foi revisado

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

  • data
  • ID do aplicativo
  • cincoEstrelas
  • quatroEstrelas
  • trêsEstrelas
  • 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 de filtro 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 que estão associados aos operadores eq ou ne, e as instruções podem ser combinadas usando e ou ou.

Veja um exemplo filtrar cadeia de caracteres: filter=market eq 'US' e deviceType eq 'phone' e isRevised eq true

Para obter uma lista dos campos com suporte, consulte a tabela a seguir. Os valores de cadeia de caracteres devem ser cercados por aspas simples no parâmetro de filtro .

Campos Descrição
mercado Uma cadeia de caracteres que contém o código de país ISO 3166 do mercado em que seu aplicativo foi classificado.
osVersion Uma das seguintes cadeias de caracteres:
  • Windows Phone 7.5
  • Telefone Windows 8
  • Windows Phone 8.1
  • Telefone Windows 10
  • janelas 8
  • Windows 8.1
  • Windows 10
  • Windows 11
  • Desconhecido
tipo de dispositivo Uma das seguintes cadeias de caracteres:
  • Computador
  • Telefone
  • Console-Xbox Um
  • SérieConsole-Xbox X
  • Muito
  • Holográfico
  • Desconhecido
éRevisado Especifique verdadeiro 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 do 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 Tipo Descrição
Valor conjunto Uma matriz de objetos que contêm dados de classificações agregadas. Para obter mais informações sobre os dados em cada objeto, consulte a seção 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 for definido como 10000, mas houver mais de 10.000 linhas de dados de classificação para a consulta.
ContagemTotal int O número total de linhas no resultado dos dados da consulta.

Valores de classificação

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

Valor Tipo Descrição
data corda A primeira data no intervalo de datas para os dados de avaliações. Se a solicitação tiver especificado um único dia, esse valor será essa data. Se a solicitação especificou uma semana, um mês ou outro intervalo de datas, este valor é a primeira data nesse intervalo.
ID do aplicativo corda A ID da Loja do aplicativo para o qual você está recuperando dados de classificações.
Nome do aplicativo corda O nome de exibição do aplicativo.
mercado corda O código do país ISO 3166 do mercado em que a classificação foi enviada.
osVersion corda A versão do sistema operacional na qual a classificação foi enviada. Para obter uma lista das strings com suporte, 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 strings com suporte, consulte a seção de campos de filtro acima.
éRevisado Booliano O valor verdadeiro indica que a classificação foi revisada; caso contrário , false.
oneStar número O número de avaliações de uma estrela.
duas estrelas 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 snippets de código a seguir demonstram alguns exemplos de solicitação e corpo de resposta JSON para essas 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
}
  • Last updated on