Obtener los datos de las adquisiciones de complementosGet add-on acquisitions

Use este método en la API de Microsoft Store Analytics para obtener datos de adquisición agregados para los complementos de la aplicación en formato JSON 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-ons for your app in JSON format during a given date range and other optional filters. Esta información también está disponible en el Informe de adquisiciones de complementos del centro de Partners.This information is also available in the Add-on acquisitions report in Partner Center.

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/inappacquisitions

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

El parámetro applicationId o inAppProductId es obligatorio.The applicationId or inAppProductId parameter is required. Para recuperar los datos de compra de todos los complementos registrados en la aplicación, especifica el parámetro applicationId.To retrieve acquisition data for all add-ons registered to the app, specify the applicationId parameter. Para recuperar los datos de compra de un solo complemento, especifica el parámetro inAppProductId.To retrieve acquisition data for a single add-on, specify the inAppProductId parameter. Si especificas ambos, el parámetro applicationId se ignorará.If you specify both, the applicationId parameter is ignored.

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.The Store ID of the app for which you want to retrieve add-on acquisition data. Yes
inAppProductIdinAppProductId stringstring El identificador de almacén del complemento para el que desea recuperar los datos de adquisición.The Store ID of the add-on for which you want to retrieve acquisition data. Yes
startDatestartDate datedate La fecha de inicio del intervalo de fechas de los datos de compra del complemento que se recuperarán.The start date in the date range of add-on acquisition data to retrieve. La fecha predeterminada es la actual.The default is the current date. NoNo
endDateendDate datedate La fecha de finalización del intervalo de fechas de los datos de compra del complemento que recuperarán.The end date in the date range of 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 especifican, es 10 000.The maximum value and the default value if not specified is 10000. 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=10000 y skip=0 recuperan las primeras 10 000 filas de datos, los valores top=10000 y skip=10000 recuperan las siguientes 10 000 filas de datos, y así sucesivamente.For example, top=10000 and skip=0 retrieves the first 10000 rows of data, top=10000 and skip=10000 retrieves the next 10000 rows of data, and so on. NoNo
filterfilter stringstring Una o más instrucciones que filtran las filas de la respuesta.One or more statements that filter the rows in the response. Para obtener más información, consulta la sección filtrar campos a continuación.For more information, see the filter fields section below. 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 Instrucción que ordena los valores de datos resultantes de cada compra de complemento.A statement that orders the result data values for each 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
  • acquisitionTypeacquisitionType
  • ageGroupageGroup
  • storeClientstoreClient
  • sexogender
  • datamarketmarket
  • osVersionosVersion
  • TipoDeDispositivodeviceType
  • orderNameorderName

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
  • applicationNameapplicationName
  • inAppProductNameinAppProductName
  • acquisitionTypeacquisitionType
  • ageGroupageGroup
  • storeClientstoreClient
  • sexogender
  • datamarketmarket
  • osVersionosVersion
  • TipoDeDispositivodeviceType
  • orderNameorderName

Las filas de datos que se devuelvan contendrán los campos especificados en el parámetro groupby y en los siguientes:The returned data rows will contain the fields specified in the groupby parameter as well as the following:

  • datedate
  • applicationIdapplicationId
  • inAppProductIdinAppProductId
  • acquisitionQuantityacquisitionQuantity

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

NoNo

Campos de filtroFilter fields

El parámetro filter de la solicitud contiene una o más instrucciones que filtran las filas de la respuesta.The filter parameter of the request contains one or more statements that filter the rows in the response. Cada instrucción contiene un campo y un valor asociados a los operadores eq o ne; asimismo, puedes combinar las instrucciones mediante and u or.Each statement contains a field and value that are associated with the eq or ne operators, and statements can be combined using and or or. Estos son algunos ejemplos de parámetros filter:Here are some example filter parameters:

  • filter=market eq 'US' and gender eq 'm'filter=market eq 'US' and gender eq 'm'
  • filter=(market ne 'US') and (gender ne 'Desconocido') and (gender ne 'm') and (market ne 'NO') and (ageGroup ne 'mayor que 55' or ageGroup ne ‘menor que 13’)filter=(market ne 'US') and (gender ne 'Unknown') and (gender ne 'm') and (market ne 'NO') and (ageGroup ne 'greater than 55' or ageGroup ne ‘less than 13’)

Para obtener una lista de los campos compatibles, consulta la tabla siguiente.For a list of the supported fields, see the following table. Ten en cuenta que en el parámetro filter los valores de la cadena deben estar entre comillas simples.String values must be surrounded by single quotes in the filter parameter.

CamposFields DescripciónDescription
acquisitionTypeacquisitionType Una de las cadenas siguientes:One of the following strings:
  • ningúnfree
  • periodotrial
  • abonenpaid
  • código promocionalpromotional code
  • IAPiap
ageGroupageGroup Una de las cadenas siguientes:One of the following strings:
  • menor que 13less than 13
  • 13-1713-17
  • 18-2418-24
  • 25-3425-34
  • 35-4435-44
  • 44-5544-55
  • mayor que 55greater than 55
  • UnknownUnknown
storeClientstoreClient Una de las cadenas siguientes:One of the following strings:
  • Tienda de Windows Phone (cliente)Windows Phone Store (client)
  • Microsoft Store (cliente)Microsoft Store (client)
  • Microsoft Store (Web)Microsoft Store (web)
  • Compras por volumen de empresasVolume purchase by organizations
  • OtrosOther
gendergender Una de las cadenas siguientes:One of the following strings:
  • mm
  • ff
  • UnknownUnknown
marketmarket Es una cadena que contiene el código de país ISO 3166 del mercado donde se realizó la compra.A string that contains the ISO 3166 country code of the market where the acquisition occurred.
osVersionosVersion Una de las cadenas siguientes:One of the following strings:
  • Windows Phone 7.5Windows Phone 7.5
  • Windows Phone 8Windows Phone 8
  • Windows Phone 8.1Windows Phone 8.1
  • Windows Phone 10Windows Phone 10
  • Windows 8Windows 8
  • Windows 8.1Windows 8.1
  • Windows 10Windows 10
  • UnknownUnknown
deviceTypedeviceType Una de las cadenas siguientes:One of the following strings:
  • PCPC
  • NúmeroPhone
  • Consola: Xbox OneConsole-Xbox One
  • Consola: serie Xbox XConsole-Xbox Series X
  • IoTIoT
  • HolographicHolographic
  • UnknownUnknown
orderNameorderName Una cadena que especifica el nombre del pedido del código promocional que se usó para comprar el complemento (esto solo es aplicable si el usuario adquirió el complemento canjeando un código promocional).A string that specifies the name of the order for the promotional code that was used to acquire the add-on (this only applies if the user acquired the add-on by redeeming a promotional code).

Ejemplo de solicitudRequest example

En los ejemplos siguientes se muestran varias solicitudes para obtener datos de compra de complementos.The following examples demonstrates several requests for getting add-on acquisition data. Reemplaza los valores de inAppProductId y applicationId con los Id. de la Tienda correspondientes al complemento o aplicación.Replace the inAppProductId and applicationId values with the appropriate Store ID for your add-on or app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=7/3/2015&top=100&skip=0&filter=market ne 'US' and gender ne 'Unknown' and gender ne 'm' and market ne 'NO' and ageGroup ne '>55' 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 los datos de compra agregados del complemento.An array of objects that contain aggregate add-on acquisition data. Para obtener más información sobre los datos de cada objeto, consulta la sección valores de compra del complemento que encontrarás a continuación.For more information about the data in each object, see the add-on 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, se devuelve este valor si el parámetro top de la solicitud está establecido en 10000, pero hay más de 10000 filas de datos de compra de complementos para la solicitud.For example, this value is returned if the top parameter of the request is set to 10000 but there are more than 10000 rows of 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 compra del complementoAdd-on 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.
inAppProductIdinAppProductId stringstring El identificador de la Tienda del complemento para el que quieres recuperar datos de compra.The Store ID of the add-on for which you are retrieving acquisition data.
inAppProductNameinAppProductName stringstring Nombre del complemento que quieres que se muestre.The display name of the add-on. Este valor solo aparece en los datos de respuesta si el parámetro aggregationLevel se establece en day, a menos que especifiques el campo inAppProductName en el parámetro groupby.This value only appears in the response data if the aggregationLevel parameter is set to day, unless you specify the inAppProductName field in the groupby parameter.
applicationIdapplicationId stringstring El identificador de la Tienda de la aplicación para la que quieres recuperar los datos de compra de complementos.The Store ID of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring El nombre para mostrar de la aplicación.The display name of the app.
deviceTypedeviceType stringstring Tipo de dispositivo que completó la compra.The type of device that completed the acquisition. Para obtener una lista de las cadenas admitidas, consulta la sección previa Campos de filtro.For a list of the supported strings, see the filter fields section above.
orderNameorderName stringstring Nombre del pedido.The name of the order.
storeClientstoreClient stringstring Versión de la Tienda donde se realizó la compra.The version of the Store where the acquisition occurred. Para obtener una lista de las cadenas admitidas, consulta la sección previa Campos de filtro.For a list of the supported strings, see the filter fields section above.
osVersionosVersion stringstring Versión del sistema operativo en el que se realizó la compra.The OS version on which the acquisition occurred. Para obtener una lista de las cadenas admitidas, consulta la sección previa Campos de filtro.For a list of the supported strings, see the filter fields section above.
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.
gendergender stringstring Género del usuario que realizó la compra.The gender of the user who made the acquisition. Para obtener una lista de las cadenas admitidas, consulta la sección previa Campos de filtro.For a list of the supported strings, see the filter fields section above.
ageGroupageGroup stringstring Grupo de edad del usuario que realizó la compra.The age group of the user who made the acquisition. Para obtener una lista de las cadenas admitidas, consulta la sección previa Campos de filtro.For a list of the supported strings, see the filter fields section above.
acquisitionTypeacquisitionType stringstring Tipo de compra (gratuita, de pago, etc.).The type of acquisition (free, paid, and so on). Para obtener una lista de las cadenas admitidas, consulta la sección previa Campos de filtro.For a list of the supported strings, see the filter fields section above.
acquisitionQuantityacquisitionQuantity integerinteger Número de compras que se realizaron.The number of acquisitions that occurred.

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": "2015-01-02",
      "inAppProductId": "9NBLGGH3LHKL",
      "inAppProductName": "Contoso add-on 7",
      "applicationId": "9NBLGGGZ5QDR",
      "applicationName": "Contoso Demo",
      "deviceType": "Phone",
      "orderName": "",
      "storeClient": "Windows Phone Store (client)",
      "osVersion": "Windows Phone 8.1",
      "market": "GB",
      "gender": "m",
      "ageGroup": "50orover",
      "acquisitionType": "iap",
      "acquisitionQuantity": 1
    }
  ],
  "@nextLink": "inappacquisitions?applicationId=9NBLGGGZ5QDR&inAppProductId=&aggregationLevel=day&startDate=2015/01/01&endDate=2016/02/01&top=1&skip=1",
  "TotalCount": 33677
}