Obtener adquisiciones de complementos de suscripciónGet subscription add-on acquisitions

Use este método en la API de Microsoft Store Analytics para obtener datos de adquisición agregados para las suscripciones de complementos de la aplicación durante un intervalo de fechas determinado y otros filtros opcionales.Use this method in the Microsoft Store analytics API to get aggregate acquisition data for add-on subscriptions for your app during a given date range and other optional filters.

Requisitos previosPrerequisites

Para usar este método, primero debes hacer lo siguiente:To use this method, you need to first do the following:

  • Si aún no lo ha hecho, complete todos los requisitos previos de la API de Microsoft Store Analytics.If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • Obtén un token de acceso de Azure AD para usarlo en el encabezado de la solicitud de este método.Obtain an Azure AD access token to use in the request header for this method. Una vez que haya obtenido un token de acceso, tiene 60 minutos para usarlo antes de que expire.After you obtain an access token, you have 60 minutes to use it before it expires. Si el token expira, puedes obtener uno nuevo.After the token expires, you can obtain a new one.

SolicitudRequest

Sintaxis de la solicitudRequest syntax

MétodoMethod URI de solicitudRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions

Encabezado de solicitudRequest header

EncabezadoHeader TipoType DescripciónDescription
AuthorizationAuthorization stringstring Necesario.Required. El token de acceso de Azure AD del formulario Bearer <token>.The Azure AD access token in the form Bearer <token>.

Parámetros de solicitudRequest parameters

ParámetroParameter TipoType DescripciónDescription RequeridoRequired
applicationIdapplicationId stringstring El identificador de la tienda de la aplicación para la que desea recuperar los datos de adquisición del complemento de suscripción.The Store ID of the app for which you want to retrieve subscription add-on acquisition data. Yes
subscriptionProductIdsubscriptionProductId stringstring El identificador de almacén del complemento de suscripción para el que desea recuperar los datos de adquisición.The Store ID of the subscription add-on for which you want to retrieve acquisition data. Si no especifica este valor, este método devuelve los datos de adquisición de todos los complementos de suscripción de la aplicación especificada.If you do not specify this value, this method returns acquisition data for all subscription add-ons for the specified app. NoNo
startDatestartDate datedate Fecha de inicio del intervalo de fechas de los datos de adquisición del complemento de suscripción que se va a recuperar.The start date in the date range of subscription add-on acquisition data to retrieve. La fecha predeterminada es la actual.The default is the current date. NoNo
endDateendDate datedate Fecha de finalización del intervalo de fechas de los datos de adquisición del complemento de suscripción que se va a recuperar.The end date in the date range of subscription add-on acquisition data to retrieve. La fecha predeterminada es la actual.The default is the current date. NoNo
toptop intint Número de filas de datos que se devuelven en la solicitud.The number of rows of data to return in the request. El valor máximo y el valor predeterminado si no se especifica es 100.The maximum value and the default value if not specified is 100. Si hay más filas en la consulta, el cuerpo de la respuesta incluye un vínculo que puedes usar para solicitar la siguiente página de datos.If there are more rows in the query, the response body includes a next link that you can use to request the next page of data. NoNo
skipskip intint Número de filas que se omiten en la consulta.The number of rows to skip in the query. Usa este parámetro para consultar grandes conjuntos de datos.Use this parameter to page through large data sets. Por ejemplo, los valores top=100 y skip=0 recuperan las primeras 100 filas de datos, los valores top=100 y skip=100 recuperan las siguientes 100 filas de datos, y así sucesivamente.For example, top=100 and skip=0 retrieves the first 100 rows of data, top=100 and skip=100 retrieves the next 100 rows of data, and so on. NoNo
filterfilter stringstring Una o más instrucciones que filtran el cuerpo de la respuesta.One or more statements that filter the response body. Cada instrucción puede utilizar los operadores eq o ne, y las instrucciones se pueden combinar mediante and u or.Each statement can use the eq or ne operators, and statements can be combined using and or or. Puede especificar las siguientes cadenas en las instrucciones de filtro (que se corresponden con los valores del cuerpo de respuesta):You can specify the following strings in the filter statements (these correspond to values in the response body):
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • datamarketmarket
  • TipoDeDispositivodeviceType

Este es un parámetro de filtro de ejemplo: Filter = date EQ ' 2017-07-08 '.Here is an example filter parameter: filter=date eq '2017-07-08'.

NoNo
aggregationLevelaggregationLevel stringstring Especifica el intervalo de tiempo necesario para el que quieres recuperar datos agregados.Specifies the time range for which to retrieve aggregate data. Puede ser una de las siguientes cadenas: día, semana o mes.Can be one of the following strings: day, week, or month. Si no se especifica, el valor predeterminado es día.If unspecified, the default is day. NoNo
orderbyorderby stringstring Una instrucción que ordena los valores de los datos de resultado de cada adquisición del complemento de suscripción.A statement that orders the result data values for each subscription add-on acquisition. La sintaxis es OrderBy = Field [order], Field [order],.... El parámetro de campo puede ser una de las cadenas siguientes:The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • datamarketmarket
  • TipoDeDispositivodeviceType

El parámetro order, en cambio, es opcional y puede ser asc o desc para especificar el orden ascendente o descendente de cada campo.The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. El valor predeterminado es ASC.The default is asc.

Este es un ejemplo de cadena OrderBy : OrderBy = Date, MarketHere is an example orderby string: orderby=date,market

NoNo
groupbygroupby stringstring Una instrucción que aplica la agregación de datos únicamente a los campos especificados.A statement that applies data aggregation only to the specified fields. Puedes especificar los siguientes campos:You can specify the following fields:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • datamarketmarket
  • TipoDeDispositivodeviceType

Puedes usar el parámetro groupby con aggregationLevel.The groupby parameter can be used with the aggregationLevel parameter. Por ejemplo: GroupBy = Market & aggregationLevel = WeekFor example: groupby=market&aggregationLevel=week

NoNo

Ejemplo de solicitudRequest example

En los siguientes ejemplos se muestra cómo obtener los datos de adquisición del complemento de suscripción.The following examples demonstrates how to get subscription add-on acquisition data. Reemplace el valor de ApplicationID por el identificador de almacén adecuado para su aplicación.Replace the applicationId value with the appropriate Store ID for your app.

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>

ResponseResponse

Cuerpo de la respuestaResponse body

ValueValue TipoType DescripciónDescription
ValueValue arrayarray Matriz de objetos que contienen datos agregados de adquisición de complementos de suscripción.An array of objects that contain aggregate subscription add-on acquisition data. Para obtener más información sobre los datos de cada objeto, consulte la sección valores de adquisición de suscripción a continuación.For more information about the data in each object, see the subscription acquisition values section below.
@nextLink stringstring Si hay páginas adicionales de datos, esta cadena contiene un URI que puedes usar para solicitar la siguiente página de datos.If there are additional pages of data, this string contains a URI that you can use to request the next page of data. 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 del complemento de suscripción para la consulta.For example, this value is returned if the top parameter of the request is set to 100 but there are more than 100 rows of subscription add-on acquisition data for the query.
TotalCountTotalCount intint El número total de filas del resultado de datos de la consulta.The total number of rows in the data result for the query.

Valores de adquisición de suscripciónSubscription acquisition values

Los elementos de la matriz Value contienen los siguientes valores.Elements in the Value array contain the following values.

ValueValue TipoType DescripciónDescription
datedate stringstring Es la primera fecha del intervalo de fechas de los datos de compra.The first date in the date range for the acquisition data. Si la solicitud especifica un solo día, este valor será esa fecha.If the request specified a single day, this value is that date. Si, por el contrario, la solicitud especifica una semana, un mes u otro intervalo de fechas, este valor será la primera fecha de ese intervalo de fechas.If the request specified a week, month, or other date range, this value is the first date in that date range.
subscriptionProductIdsubscriptionProductId stringstring El identificador de almacén del complemento de suscripción para el que se recuperan los datos de adquisición.The Store ID of the subscription add-on for which you are retrieving acquisition data.
subscriptionProductNamesubscriptionProductName stringstring El nombre para mostrar del complemento de suscripción.The display name of the subscription add-on.
applicationIdapplicationId stringstring El identificador de la tienda de la aplicación para la que se recuperan los datos de adquisición del complemento de suscripción.The Store ID of the app for which you are retrieving subscription add-on acquisition data.
applicationNameapplicationName stringstring El nombre para mostrar de la aplicación.The display name of the app.
skuIdskuId stringstring IDENTIFICADOR de la SKU del complemento de suscripción para el que se recuperan los datos de adquisición.The ID of the SKU of the subscription add-on for which you are retrieving acquisition data.
deviceTypedeviceType stringstring Una de las siguientes cadenas que especifica el tipo de dispositivo que completó la adquisición:One of the following strings that specifies the type of device that completed the acquisition:
  • PCPC
  • NúmeroPhone
  • Consola: Xbox OneConsole-Xbox One
  • Consola: serie Xbox XConsole-Xbox Series X
  • IoTIoT
  • HolographicHolographic
  • UnknownUnknown
marketmarket stringstring Código de país ISO 3166 del mercado donde se realizó la compra.The ISO 3166 country code of the market where the acquisition occurred.
currencyCodecurrencyCode stringstring El código de moneda en formato ISO 4217 para ventas brutas antes de los impuestos.The currency code in ISO 4217 format for gross sales before taxes.
grossSalesBeforeTaxgrossSalesBeforeTax integerinteger Ventas brutas en la moneda local especificada por el valor de currencyCode .The gross sales in the local currency specified by the currencyCode value.
totalActiveCounttotalActiveCount integerinteger Número total de suscripciones activas durante el período de tiempo especificado.The number of total active subscriptions during the specified time period. Esto es equivalente a la suma de los valores goodStandingActiveCount, pendingGraceActiveCount, graceActiveCounty lockedActiveCount .This is equivalent to the sum of the goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount, and lockedActiveCount values.
totalChurnCounttotalChurnCount integerinteger Número total de suscripciones que se han desactivado durante el período de tiempo especificado.The total count of subscriptions that were deactivated during the specified time period. Esto es equivalente a la suma de los valores billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCounty otherChurnCount .This is equivalent to the sum of the billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount, and otherChurnCount values.
newCountnewCount integerinteger El número de nuevas adquisiciones de suscripciones durante el período de tiempo especificado, incluidas las pruebas.The number of new subscription acquisitions during the specified time period, including trials.
renewCountrenewCount integerinteger El número de renovaciones de suscripción durante el período de tiempo especificado, incluidas las renovaciones iniciadas por el usuario y las renovaciones automáticas.The number of subscription renewals during the specified time period, including user-initiated renewals and automatic renewals.
goodStandingActiveCountgoodStandingActiveCount integerinteger El número de suscripciones que estaban activas durante el período de tiempo especificado y donde la fecha de expiración es >= el valor de EndDate de la consulta.The number of subscriptions that were active during the specified time period and where the expiration date is >= the endDate value for the query.
pendingGraceActiveCountpendingGraceActiveCount integerinteger El número de suscripciones que estaban activas durante el período de tiempo especificado pero tuvieron un error de facturación y donde la fecha de expiración de la suscripción es >= el valor de EndDate de la consulta.The number of subscriptions that were active during the specified time period but had a billing failure, and where the subscription expiration date is >= the endDate value for the query.
graceActiveCountgraceActiveCount integerinteger El número de suscripciones que estaban activas durante el período de tiempo especificado pero tuvieron un error de facturación y donde:The number of subscriptions that were active during the specified time period but had a billing failure, and where:
  • La fecha de expiración de la suscripción es < el valor de EndDate de la consulta.The subscription expiration date is < the endDate value for the query.
  • El final del período de gracia es >= el valor de EndDate .The end of the grace period is >= the endDate value.
lockedActiveCountlockedActiveCount integerinteger El número de suscripciones que estaban en las demás (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:The number of subscriptions that were in dunning (that is, the subscription is nearing expiration and Microsoft is trying to acquire funds to automatically renew the subscription) during the specified time period, and where:
  • La fecha de expiración de la suscripción es < el valor de EndDate de la consulta.The subscription expiration date is < the endDate value for the query.
  • El final del período de gracia es <= el valor de EndDate .The end of the grace period is <= the endDate value.
billingChurnCountbillingChurnCount integerinteger El número de suscripciones que se han desactivado durante el período de tiempo especificado debido a un error en el procesamiento de un cargo de facturación y en el que las suscripciones estaban anteriormente en las demás.The number of subscriptions that were deactivated during the specified time period because of a failure to process a billing charge and where the subscriptions were previously in dunning.
nonRenewalChurnCountnonRenewalChurnCount integerinteger Número de suscripciones que se han desactivado durante el período de tiempo especificado porque no se han renovado.The number of subscriptions that were deactivated during the specified time period because they were not renewed.
refundChurnCountrefundChurnCount integerinteger Número de suscripciones que se han desactivado durante el período de tiempo especificado porque se volvieron a reembolsar.The number of subscriptions that were deactivated during the specified time period because they were refunded.
chargebackChurnCountchargebackChurnCount integerinteger Número de suscripciones que se han desactivado durante el período de tiempo especificado debido a un recargo.The number of subscriptions that were deactivated during the specified time period because of a chargeback.
earlyChurnCountearlyChurnCount integerinteger Número de suscripciones que se han desactivado durante el período de tiempo especificado mientras estaban en buen estado.The number of subscriptions that were deactivated during the specified time period while they were in good standing.
otherChurnCountotherChurnCount integerinteger Número de suscripciones que se han desactivado durante el período de tiempo especificado por otros motivos.The number of subscriptions that were deactivated during the specified time period for other reasons.

Ejemplo de respuestaResponse example

En el ejemplo siguiente se muestra el cuerpo de una respuesta JSON de ejemplo realizada para esta solicitud.The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9KDLGHH6R365",
      "subscriptionProductName": "Contoso App Subscription with One Month Free Trial",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "Unknown",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    },
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9JJFDHG4R478",
      "subscriptionProductName": "Contoso App Monthly Subscription",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "US",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    }
  ],
  "@nextLink": null,
  "TotalCount": 2
}