Compartilhar via

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