Obtener adquisiciones de complementos de suscripción
Usa este método en la API de análisis de Microsoft Store para obtener datos de adquisición agregados para suscripciones de complementos para tu aplicación durante un intervalo de fechas determinado y otros filtros opcionales.
Requisitos previos
Para usar este método, primero debes hacer lo siguiente:
- Si aún no lo has hecho, completa todos los requisitos previos de la API de análisis de Microsoft Store.
- Consigue un token de acceso a Azure AD para utilizarlo en el encabezado de solicitud de este método. Una vez que haya obtenido un token de acceso, tiene 60 minutos para usarlo antes de que expire. Una vez que expire el token, puede obtener uno nuevo.
Solicitar
Sintaxis de la solicitud
| Método | URI de solicitud |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions |
Encabezado de solicitud
| Encabezado | Tipo | Descripción |
|---|---|---|
| Autorización | cadena | Necesario. Token de acceso de Azure AD con el formato Token<de portador>. |
Parámetros de solicitud
| Parámetro | Tipo | Descripción | Obligatorio |
|---|---|---|---|
| applicationId | string | El Id. de Store de la aplicación para la que quieres recuperar los datos de adquisición de suscripciones de complementos. | Sí |
| subscriptionProductId | string | El Id. de Store del complemento de suscripción para el que se quieren recuperar los datos de adquisición. Si no se especifica este valor, este método devuelve los datos de adquisición de todos los complementos de suscripción para la aplicación especificada. | No |
| startDate | date | Fecha de inicio del intervalo de fechas de los datos de adquisición del complemento de suscripción que se van a recuperar. La fecha actual es el valor predeterminado. | No |
| endDate | date | Fecha de finalización del intervalo de fechas de los datos de adquisición del complemento de suscripción que se van a recuperar. La fecha actual es el valor predeterminado. | No |
| top | int | Número de filas de datos que se van a devolver en la solicitud. Si no se especifica, el valor predeterminado y el valor máximo es 100. Si hay más filas en la consulta, el cuerpo de la respuesta incluye un vínculo “Siguiente” que puedes usar para solicitar la siguiente página de datos. | No |
| skip | int | Número de filas que se omiten en la consulta. Usa este parámetro para pasar de página en conjuntos de datos grandes. Por ejemplo, top=100 y skip=0 recupera las primeras 100 filas de datos, top=100 y skip=100 recupera las siguientes 100 filas de datos, etc. | No |
| filter | string | Una o varias instrucciones que filtran el cuerpo de la respuesta. Cada instrucción puede usar los operadores eq o ne, y las instrucciones se pueden combinar mediante y u o. Puedes especificar las siguientes cadenas en las instrucciones de filtro (estas corresponden a valores en el cuerpo de la respuesta):
Este es un ejemplo de parámetro de filtro: filter=date eq '2017-07-08'. |
No |
| aggregationLevel | string | Especifica el intervalo de tiempo para el que se van a recuperar los datos agregados. Puede ser una de las siguientes cadenas: día, semana o mes. Si no se especifica nada, el valor predeterminado es día. | No |
| orderby | string | Instrucción que ordena los valores de datos de resultados para cada adquisición de un complemento de suscripción. La sintaxis es orderby=field [order],field [order],.... El parámetro field puede estar formado por una de las siguientes cadenas:
El parámetro order es opcional y puede ser asc o desc para especificar el orden ascendente o descendente de cada campo. El valor predeterminado es asc. Este es un ejemplo de cadena orderby: orderby=date,market |
No |
| groupby | string | Instrucción que aplica la agregación de datos solo a los campos especificados. Puedes especificar los siguientes campos:
El parámetro groupby se puede usar con el parámetro aggregationLevel. Por ejemplo: groupby=market&aggregationLevel=week |
No |
Ejemplo de solicitud
En los ejemplos siguientes se muestra cómo obtener datos de adquisición de complementos de suscripción. Reemplaza el valor applicationId por el Id. de Store adecuado de la aplicación.
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>
Respuesta
Response body
| Valor | Tipo | Descripción |
|---|---|---|
| Value | array | Matriz de objetos que contienen datos de adquisición de complementos de suscripción agregados. Para obtener más información sobre los datos de cada objeto, consulta la sección valores de adquisición de suscripciones a continuación. |
| @nextLink | string | Si hay páginas adicionales de datos, esta cadena contiene un URI que se puede usar para solicitar la siguiente página de datos. Por ejemplo, este valor se devuelve si el parámetro top de la solicitud se establece en 100, pero hay más de 100 filas de datos de adquisición de complementos de suscripción para la consulta. |
| TotalCount | int | Número total de filas que figura en el resultado de datos de la consulta. |
Valores de adquisición de suscripciones
Los elementos de la matriz Value contienen los valores siguientes.
| Valor | Tipo | Descripción |
|---|---|---|
| date | string | La primera fecha del intervalo de fechas de los datos de adquisición. Si la solicitud especificaba un solo día, este valor es esa fecha. Si la solicitud especificaba una semana, un mes u otro intervalo de fechas, este valor es la primera fecha de ese intervalo de fechas. |
| subscriptionProductId | string | Id. de Store del complemento de suscripción para el que se recuperan los datos de adquisición. |
| subscriptionProductName | string | Nombre para mostrar del complemento de suscripción. |
| applicationId | string | Id. de Store de la aplicación para la que se recuperan los datos de adquisición del complemento de suscripción. |
| applicationName | string | Nombre para mostrar de la aplicación. |
| skuId | string | El identificador del SKU del complemento de suscripción para el que van a recuperar los datos de adquisición. |
| deviceType | string | Una de las siguientes cadenas que especifica el tipo de dispositivo que completó la adquisición:
|
| market | string | El código de país ISO 3166 del mercado en el que se produjo la adquisición. |
| currencyCode | string | El código de moneda en formato ISO 4217 para las ventas brutas antes de impuestos. |
| grossSalesBeforeTax | integer | Ventas brutas en la moneda local especificada por el valor currencyCode. |
| totalActiveCount | integer | Número de suscripciones activas totales durante el período de tiempo especificado. Esto equivale a la suma de los valores goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount y lockedActiveCount. |
| totalChurnCount | integer | Recuento total de suscripciones desactivadas durante el período de tiempo especificado. Esto equivale a la suma de los valores billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount y otherChurnCount. |
| newCount | integer | Número de nuevas adquisiciones de suscripciones durante el período de tiempo especificado, incluidas las pruebas. |
| renewCount | integer | Número de renovaciones de suscripciones durante el período de tiempo especificado, incluidas las renovaciones iniciadas por el usuario y las renovaciones automáticas. |
| goodStandingActiveCount | integer | Número de suscripciones que estaban activas durante el período de tiempo especificado y donde la fecha de expiración es >= el valor endDate de la consulta. |
| pendingGraceActiveCount | integer | El número de suscripciones que estaban activas durante el período de tiempo especificado, pero con un error de facturación, y donde la fecha de expiración de la suscripción es >= el valor endDate de la consulta. |
| graceActiveCount | integer | Número de suscripciones activas durante el período de tiempo especificado, pero con un error de facturación y dónde:
|
| lockedActiveCount | integer | El número de suscripciones en dunning (es decir, la suscripción está a punto de expirar y Microsoft está intentando adquirir fondos para renovar automáticamente la suscripción) durante el período de tiempo especificado y dónde:
|
| billingChurnCount | integer | El número de suscripciones que se desactivaron durante el período de tiempo especificado debido a un error al procesar un cargo de facturación y dónde las suscripciones estaban anteriormente en dunning. |
| nonRenewalChurnCount | integer | Número de suscripciones que se desactivaron durante el período de tiempo especificado porque no se renovaron. |
| refundChurnCount | integer | Número de suscripciones que se desactivaron durante el período de tiempo especificado porque se hizo un reembolso. |
| chargebackChurnCount | integer | Número de suscripciones que se desactivaron durante el período de tiempo especificado debido a una contracargo. |
| earlyChurnCount | integer | Número de suscripciones que se desactivaron durante el período de tiempo especificado mientras estaban dentro del período de suscripción. |
| otherChurnCount | integer | Número de suscripciones que se desactivaron durante el período de tiempo especificado por otros motivos. |
Ejemplo de solicitud y respuesta
En los fragmentos de código siguientes se muestran algunos ejemplos de solicitud y del cuerpo de la respuesta en formato JSON de esa solicitud.
Solicitud de muestra
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>
Respuesta de ejemplo
{
"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
}
Solicitud de muestra
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>
Respuesta de ejemplo
{
"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
}
Temas relacionados
- Informe de adquisiciones de complementos
- Acceso a datos analíticos mediante los servicios de Microsoft Store
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de