Obtener adquisiciones de complementos de suscripción

Artículo
01/19/2024

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	string	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
superior	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): date subscriptionProductName applicationName skuId market deviceType 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: date subscriptionProductName applicationName skuId market deviceType 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: date subscriptionProductName applicationName skuId market deviceType 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

Cuerpo de la respuesta

Valor	Tipo	Descripción
Valor	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: PC Teléfono Consola-Xbox One Consola-Xbox Series X IoT Holográfico Unknown
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: La fecha de expiración de la suscripción es < el valor endDate de la consulta. El final del período de gracia es >= el valor endDate.
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: La fecha de expiración de la suscripción es < el valor endDate de la consulta. El final del período de gracia es <= el valor endDate.
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
}

Compartir a través de

Obtener adquisiciones de complementos de suscripción

Requisitos previos

Solicitar

Sintaxis de la solicitud

Encabezado de solicitud

Parámetros de solicitud

Ejemplo de solicitud

Respuesta

Cuerpo de la respuesta

Valores de adquisición de suscripciones

Ejemplo de solicitud y respuesta

Solicitud de muestra

Respuesta de ejemplo

Solicitud de muestra

Respuesta de ejemplo

Comentarios

Recursos adicionales

Compartir a través de

Obtener adquisiciones de complementos de suscripción

Requisitos previos

Solicitar

Sintaxis de la solicitud

Encabezado de solicitud

Parámetros de solicitud

Ejemplo de solicitud

Respuesta

Cuerpo de la respuesta

Valores de adquisición de suscripciones

Ejemplo de solicitud y respuesta

Solicitud de muestra

Respuesta de ejemplo

Solicitud de muestra

Respuesta de ejemplo

Temas relacionados

Comentarios

Recursos adicionales