Partilhar via

Obter compras de extensões de subscrição

Use esse método na API de análise da Microsoft Store para obter dados de aquisição agregados para assinaturas de complementos para seu aplicativo durante um determinado intervalo de datas e outros filtros opcionais.

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/subscriptions

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 A ID da Store do aplicativo para o qual você deseja recuperar dados de aquisição de complementos de assinatura. Sim
IdDoProdutoDeSubscrição corda O ID de loja do complemento de assinatura para o qual pretende obter dados de aquisição. Se você não especificar esse valor, esse método retornará dados de aquisição para todos os complementos de assinatura para o aplicativo especificado. Não
data de início data A data de início no intervalo de datas dos dados de aquisição de complementos de assinatura a serem recuperados. O padrão é a data atual. Não
data de término data A data final no intervalo de datas dos dados de aquisição de complementos de assinatura 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, é 100. 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=100 e skip=0 recupera as primeiras 100 linhas de dados, top=100 e skip=100 recupera as próximas 100 linhas de dados e assim por diante. Não
filtro corda Uma ou mais declarações que filtram o corpo da resposta. Cada afirmação pode usar os operadores eq ou ne, e as afirmações podem ser combinadas usando e ou ou. Você pode especificar as seguintes cadeias de caracteres nas instruções de filtro (elas correspondem a valores no corpo da resposta):
  • data
  • nomeDoProdutoDeAssinatura
  • nome_do_aplicativo
  • skuId
  • mercado
  • Tipo de dispositivo

Aqui está um exemplo filtro parâmetro: filtro=data igual a '2017-07-08'.

 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 resultantes para cada aquisição de adicional de subscrição. A sintaxe é orderby=field [order],field [order],.... O parâmetro field pode ser uma das seguintes strings:
  • data
  • nomeDoProdutoDeAssinatura
  • nome_do_aplicativo
  • skuId
  • mercado
  • Tipo de dispositivo

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
agrupados por corda Uma instrução que aplica a agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos:
  • data
  • nomeDoProdutoDeAssinatura
  • nome_do_aplicativo
  • skuId
  • mercado
  • Tipo de dispositivo

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

 Não

Exemplo de solicitação

Os exemplos a seguir demonstram como obter dados de aquisição de complementos de assinatura. Substitua o valor applicationId pelo ID da Loja apropriada para o seu aplicativo.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=2017-07-07&endDate=2017-07-08 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 agregados sobre a aquisição de complementos de assinatura. Para obter mais informações sobre os dados em cada objeto, consulte a seção valores de aquisição de assinatura 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, este valor é retornado se o parâmetro superior da solicitação estiver definido como 100, mas houver mais de 100 linhas de dados de aquisição de complemento de assinatura na consulta.
Contagem total Int O número total de linhas no resultado de dados para a consulta.

Valores de aquisição da subscrição

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

Valor Tipo Descrição
data corda A primeira data no intervalo de datas dos dados de aquisiçã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.
IdDoProdutoDeSubscrição corda A ID da Store do complemento de assinatura para o qual você está recuperando dados de aquisição.
assinaturaProductName corda Nome de exibição do complemento de subscrição.
applicationId corda A ID da Store do aplicativo para o qual você está recuperando dados de aquisição de complementos de assinatura.
Nome da Aplicação corda O nome de exibição da aplicação.
skuId corda A ID do SKU do complemento de assinatura para o qual você está recuperando dados de aquisição.
Tipo de dispositivo corda Uma das seguintes cadeias de caracteres que especifica o tipo de dispositivo que concluiu a aquisição:
  • Computador pessoal
  • Telefone
  • Console-Xbox Um
  • Console-Xbox Série X
  • Internet das coisas
  • Holográfico
  • Desconhecido
mercado corda O código de país ISO 3166 do mercado onde ocorreu a aquisição.
código da moeda corda O código de moeda no formato ISO 4217 para vendas brutas antes de impostos.
VendasBrutasAntesDeImpostos número inteiro As vendas brutas na moeda local especificadas pelo currencyCode valor.
totalActiveCount número inteiro O número total de assinaturas ativas durante o período de tempo especificado. Isso é equivalente à soma dos valores de goodStandingActiveCount, pendingGraceActiveCount, graceActiveCounte lockedActiveCount.
totalChurnCount número inteiro A contagem total de assinaturas que foram desativadas durante o período de tempo especificado. Isso é equivalente à soma dos valores de cancelamento de faturamento , cancelamento por não renovação , cancelamento por reembolso , cancelamento por estorno , cancelamento antecipado , e outros cancelamentos .
newCount número inteiro O número de novas aquisições de subscrição durante o período de tempo especificado, incluindo versões experimentais.
contadorDeRenovação número inteiro O número de renovações de assinatura durante o período de tempo especificado, incluindo renovações iniciadas pelo usuário e renovações automáticas.
contagemAtivaEmBomEstado número inteiro O número de assinaturas que estavam ativas durante o período de tempo especificado e onde a data de expiração é >= o valor endDate para a consulta.
pendenteGraceActiveCount número inteiro O número de assinaturas que estavam ativas durante o período de tempo especificado, mas que apresentaram uma falha de cobrança, e em que a data de expiração da assinatura corresponde a >, ou seja, o valor de endDate na consulta.
graceActiveCount número inteiro O número de assinaturas que estavam ativas durante o período de tempo especificado, mas tiveram uma falha de cobrança, e onde:
  • A data de expiração da subscrição é <, sendo o endDate o valor para a consulta.
  • O final do período de carência é >= o valor de data de término.
Contagem de Ativos Bloqueados número inteiro O número de subscrições que estavam em situação de cobrança (ou seja, a subscrição está prestes a expirar e a Microsoft está a tentar obter fundos para renovar automaticamente a subscrição) durante o período de tempo especificado e onde:
  • A data de expiração da subscrição é <, sendo o endDate o valor para a consulta.
  • O final do período de carência é <= o valor de data de término.
faturamentoChurnCount número inteiro O número de subscrições que foram desativadas durante o período de tempo especificado devido a uma falha no processamento de uma cobrança de faturação e onde as subscrições estavam anteriormente em fase de cobrança.
nãoRenovaçãoChurnCount número inteiro O número de assinaturas que foram desativadas durante o período de tempo especificado porque não foram renovadas.
reembolsChurnCount número inteiro O número de subscrições que foram desativadas durante o período de tempo especificado porque foram reembolsadas.
chargebackChurnCount número inteiro O número de assinaturas que foram desativadas durante o período de tempo especificado devido a um estorno.
cedoChurnCount número inteiro O número de subscrições que foram desativadas durante o período de tempo especificado enquanto estavam em situação regular.
outroChurnCount número inteiro O número de assinaturas que foram desativadas durante o período de tempo especificado por outros motivos.

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/subscriptions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

Exemplo de resposta

{
    "Value": [
        {
            "date": "2022-04-18",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "grossSalesBeforeTax": 3460656.260391250,
            "totalActiveCount": 20211321,
            "totalChurnCount": 5605,
            "newCount": 3810366,
            "renewCount": 12102044,
            "goodStandingActiveCount": 17893664,
            "pendingGraceActiveCount": 2255792,
            "graceActiveCount": 61833,
            "lockedActiveCount": 32,
            "billingChurnCount": 4,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 2717,
            "otherChurnCount": 2884
        },
        {
            "date": "2022-04-18",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Unknown",
            "grossSalesBeforeTax": 2342.580615228,
            "totalActiveCount": 50550,
            "totalChurnCount": 7,
            "newCount": 8312,
            "renewCount": 31446,
            "goodStandingActiveCount": 44047,
            "pendingGraceActiveCount": 6503,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 5,
            "otherChurnCount": 2
        }
    ],
    "TotalCount": 2
}

Pedido de amostra

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=12/19/2021&endDate=04/20/2022&top=10&skip=0&orderby=date&groupby=date,subscriptionProductName,applicationName,skuId,market,deviceType&aggregationLevel=week
HTTP/1.1
Authorization: Bearer <your access token>

Exemplo de resposta

{
    "Value": [
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "IT",
            "deviceType": "Console-Xbox One",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 0,
            "totalChurnCount": 0,
            "newCount": 2,
            "renewCount": 0,
            "goodStandingActiveCount": 0,
            "pendingGraceActiveCount": 0,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        },
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "NO",
            "deviceType": "Unknown",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 0,
            "totalChurnCount": 0,
            "newCount": 0,
            "renewCount": 13,
            "goodStandingActiveCount": 0,
            "pendingGraceActiveCount": 0,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        },
        {
            "date": "2022-04-18",
            "subscriptionProductName": "realms.subscription.monthly.10player.02",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Windows and Doors",
            "skuId": "0100",
            "market": "CA",
            "deviceType": "Unknown",
            "grossSalesBeforeTax": 0.0,
            "totalActiveCount": 152,
            "totalChurnCount": 0,
            "newCount": 0,
            "renewCount": 270,
            "goodStandingActiveCount": 133,
            "pendingGraceActiveCount": 19,
            "graceActiveCount": 0,
            "lockedActiveCount": 0,
            "billingChurnCount": 0,
            "nonRenewalChurnCount": 0,
            "refundChurnCount": 0,
            "chargebackChurnCount": 0,
            "earlyChurnCount": 0,
            "otherChurnCount": 0
        }
    ],
    "TotalCount": 3
}

 

 

  • Last updated on