Compartilhar via

Obter aquisições de complemento de assinatura

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

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/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
ID do aplicativo corda O ID da loja do aplicativo para o qual você deseja recuperar dados de aquisição do complemento da assinatura. Sim
IdProdutoAssinatura corda A ID da Store do complemento de assinatura para o qual você deseja recuperar 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 do complemento de assinatura 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 aquisição do complemento 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 retornados na solicitação. O valor máximo e o valor padrão se não especificado for 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 esse 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 instrução pode usar os operadores eq ou ne e as instruçõ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
  • applicationName
  • skuId (Identificador de SKU)
  • mercado
  • tipoDeDispositivo

Aqui está um exemplo de parâmetro do filtro : filter=date eq '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 será dia. Não
orderby corda Uma declaração que ordena os valores dos dados de resultado para cada aquisição de complemento de assinatura. A sintaxe é orderby=field [order],field [order],.... O parâmetro field pode ser uma das seguintes strings:
  • data
  • nomeDoProdutoDeAssinatura
  • applicationName
  • skuId (Identificador de SKU)
  • mercado
  • tipoDeDispositivo

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
  • nomeDoProdutoDeAssinatura
  • applicationName
  • skuId (Identificador de SKU)
  • mercado
  • tipoDeDispositivo

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 complemento de assinatura. Substitua o valor applicationId pela Store ID apropriada para 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 de 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, esse valor será retornado se o parâmetro superior da solicitação for definido como 100, mas existirem mais de 100 linhas de dados de aquisição de complementos de assinatura na consulta.
ContagemTotal int O número total de linhas no resultado dos dados da consulta.

Valores de aquisição de assinatura

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

Valor Tipo Descrição
data corda A primeira data no intervalo de datas dos dados de aquisição. 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.
IdProdutoAssinatura corda A ID da Store do complemento de assinatura para o qual você está recuperando dados de aquisição.
nomeDoProdutoDeAssinatura corda O nome para exibição do complemento da assinatura.
ID do aplicativo corda O ID da loja do aplicativo para o qual você está recuperando os dados de aquisição do complemento de assinatura.
Nome do aplicativo corda O nome de exibição do aplicativo.
skuId corda O ID do SKU do complemento de assinatura para o qual você está obtendo 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
  • Telefone
  • Console-Xbox Um
  • SérieConsole-Xbox X
  • Muito
  • Holográfico
  • Desconhecido
mercado corda O código de país ISO 3166 do mercado no qual a aquisição ocorreu.
código de moeda corda O código de moeda no formato ISO 4217 para vendas brutas antes dos impostos.
vendasBrutasAntesDeImpostos número inteiro O valor das vendas brutas na moeda local especificado pelo currencyCode.
totalActiveCount número inteiro O número total de assinaturas ativas durante o período de tempo especificado. Isso é equivalente à soma dos valores goodStandingActiveCount, pendingGraceActiveCount, graceActiveCounte lockedActiveCount.
ContagemTotalDeCancelamentos número inteiro A contagem total de assinaturas que foram desativadas durante o período de tempo especificado. Isso é equivalente à soma do billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCounte outros valores de ChurnCount.
newCount número inteiro O número de novas aquisições de assinatura durante o período de tempo especificado, incluindo testes.
renewCount 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.
contagemAtivosEmBomEstado número inteiro O número de assinaturas que estavam ativas durante o período de tempo especificado e em que a data de expiração é >= o valor de endDate para a consulta.
pendingGraceActiveCount número inteiro O número de assinaturas que estavam ativas durante o período de tempo especificado mas que tiveram uma falha de cobrança, e para as quais a data de validade da assinatura é >, igual ao valor endDate para a 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 validade da assinatura é < o valor endDate para a consulta.
  • O final do período de carência é >= o valor endDate.
lockedActiveCount número inteiro O número de assinaturas que estavam em (ou seja, a assinatura está se aproximando da expiração e a Microsoft está tentando adquirir fundos para renovar automaticamente a assinatura) durante o período de tempo especificado e onde:
  • A data de validade da assinatura é < o valor endDate para a consulta.
  • O final do período de carência é <= o valor endDate.
billingChurnCount número inteiro O número de assinaturas que foram desativadas durante o período de tempo especificado devido a uma falha no processamento de uma cobrança e que estavam anteriormente em processo de cobrança.
ContagemDeCancelamentoPorNãoRenovação número inteiro O número de assinaturas que foram desativadas durante o período de tempo especificado porque não foram renovadas.
refundChurnCount número inteiro O número de assinaturas 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 especificado devido a um estorno (chargeback).
earlyChurnCount número inteiro O número de assinaturas que foram desativadas durante o período de tempo especificado enquanto estavam em situação regular.
otherChurnCount 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 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/subscriptions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

Resposta de exemplo

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

Solicitação de exemplo

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>

Resposta de exemplo

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