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 complementos para o aplicativo durante um determinado intervalo de datas e outros filtros opcionais.
Pré-requisitos
Para usar este 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. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá obter um novo.
Solicitar
Sintaxe da solicitação
| Método | URI da solicitação |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions |
Cabeçalho da solicitação
| Cabeçalho | Tipo | Descrição |
|---|---|---|
| Autorização | string | Obrigatório. O token de acesso do Azure AD no Token<de portador> do formulário. |
Parâmetros da solicitação
| Parâmetro | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| applicationId | string | A ID da Store do aplicativo cujos dados de aquisição de complementos de assinatura você deseja recuperar. | Sim |
| subscriptionProductId | string | O 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 de todos os complementos de assinatura para o aplicativo especificado. | Não |
| startDate | date | 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 |
| endDate | date | A data de término no intervalo de datas dos dados de aquisição de complementos de assinatura a serem recuperados. O padrão é a data atual. | Não |
| top | int | O número de linhas de dados a serem retornadas na solicitação. O valor máximo e padrão, se não for especificado, será 100. Se houver mais linhas na consulta, o corpo da resposta incluirá um proximo link que você poderá usar para solicitar a próxima página de dados. | Não |
| skip | 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 cem linhas de dados, top=100 e skip=100 recupera as próximas cem linhas de dados, e assim por diante. | Não |
| filtro | string | Uma ou mais instruçõ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 and ou or. É possível especificar as seguintes sequências nas instruções de filtro (elas correspondem aos valores no corpo da resposta):
Este é um exemplo de parâmetro filter: filter=date eq ‘2017-07-08’. |
Não |
| aggregationLevel | string | Especifica o intervalo de tempo cujos dados agregados serão recuperados. Pode ser uma das seguintes sequências: dia, semana ou mês. Se não for especificado, o padrão será dia. | Não |
| orderby | string | Uma instrução que ordena os valores dos dados de resultado para cada aquisição de complementos de assinatura. A sintaxe é orderby=field [order],field [order],.... O parâmetro field pode ser uma das seguintes sequências:
O parâmetro order é opcional e pode ser asc ou desc para especificar ordem ascendente ou descendente para cada campo. O padrão é asc. Este é um exemplo de sequência orderby: orderby=date,market |
Não |
| groupby | string | Uma instrução que aplica agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos:
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 apresentados a seguir demonstram como obter dados de aquisição de complementos de assinatura. Substitua o valor applicationId pelo ID da Store mais apropriado 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 | Type | Descrição |
|---|---|---|
| Valor | matriz | 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 | string | Se houver páginas adicionais de dados, essa sequência conterá um URI que você poderá usar para solicitar a próxima página de dados. Por exemplo, esse valor será retornado se o parâmetro top da solicitação estiver definido como cem, mas houver mais de cem linhas de dados de aquisição de complementos de assinatura para a consulta. |
| TotalCount | int | O número total de linhas no resultado de dados da consulta. |
Valores de aquisição de assinatura
Os elementos na matriz Value contêm os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| date | string | A primeira data no intervalo de datas para os dados de aquisição. Se a solicitação tiver especificado um único dia, esse valor será essa data. Se a solicitação tiver especificado uma semana, um mês ou outro intervalo de datas, esse valor será a primeira data nesse intervalo de datas. |
| subscriptionProductId | string | O ID da Store do complemento de assinatura para o qual você está recuperando os dados de aquisição. |
| subscriptionProductName | string | O nome de exibição do complemento de assinatura. |
| applicationId | string | O ID da Store do aplicativo para o qual você está recuperando os dados de aquisição de complementos de assinatura. |
| applicationName | string | O nome de exibição do aplicativo. |
| skuId | string | O ID de SKU do complemento de assinatura para o qual você está recuperando os dados de aquisição. |
| deviceType | string | Uma das seguintes sequências que especifica o tipo de dispositivo que concluiu a aquisição:
|
| market | string | O código de país ISO 3166 do mercado no qual a aquisição ocorreu. |
| currencyCode | string | O código de moeda no formato ISO 4217 para vendas brutas antes de impostos. |
| grossSalesBeforeTax | Número inteiro | As vendas brutas na moeda local especificadas pelo valor currencyCode. |
| totalActiveCount | Número inteiro | O número total de assinaturas ativas durante o período especificado. Isso é equivalente à soma dos valores goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount e lockedActiveCount. |
| totalChurnCount | Número inteiro | A contagem total de assinaturas que foram desativadas durante o período especificado. Isso é equivalente à soma dos valores billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount e otherChurnCount. |
| newCount | Número inteiro | O número de novas aquisições de assinaturas durante o período especificado, incluindo as avaliações. |
| renewCount | Número inteiro | O número de renovações de assinaturas durante o período especificado, incluindo as renovações iniciadas pelo usuário e as renovações automáticas. |
| goodStandingActiveCount | Número inteiro | O número de assinaturas que estavam ativas durante o período especificado e em que a data do término é >= ao valor endDate da consulta. |
| pendingGraceActiveCount | Número inteiro | O número de assinaturas que estavam ativas durante o período especificado, mas que tiveram uma falha de cobrança e em que a data do término da assinatura é >= ao valor endDate da consulta. |
| graceActiveCount | Número inteiro | O número de assinaturas que estavam ativas durante o período especificado, mas que tiveram uma falha de cobrança e em que:
|
| lockedActiveCount | Número inteiro | O número de assinaturas que estavam em processo de cobrança (ou seja, a assinatura está próxima da expiração e a Microsoft está tentando adquirir fundos para renovar automaticamente a assinatura) durante o período especificado e em que:
|
| billingChurnCount | Número inteiro | O número de assinaturas que foram desativadas durante o período especificado devido a uma falha no processamento de uma cobrança e em que as assinaturas estavam anteriormente em processo de cobrança. |
| nonRenewalChurnCount | Número inteiro | O número de assinaturas que foram desativadas durante o período especificado porque não foram renovadas. |
| refundChurnCount | Número inteiro | O número de assinaturas que foram desativadas durante o período 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. |
| earlyChurnCount | Número inteiro | O número de assinaturas que foram desativadas durante o período especificado enquanto estavam em situação regular. |
| otherChurnCount | Número inteiro | O número de assinaturas que foram desativadas durante o período especificado por outros motivos. |
Exemplo de solicitação e resposta
Os snippets de código a seguir demonstram alguns exemplos de solicitações e o corpo da resposta JSON para estas 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
}
Tópicos relacionados
- Relatório de aquisições de complemento
- Acessar dados analíticos usando os serviços da Microsoft Store