Obtener datos de adquisiciones de complementos para sus aplicaciones y juegosGet add-on acquisitions data for your games and apps

Use este método en la API de Microsoft Store Analytics para obtener datos de adquisición de complementos de agregado en formato JSON para aplicaciones UWP y juegos de Xbox One que se ingeriron a través del portal para desarrolladores de Xbox (XDP) y que están disponibles en el panel del centro de Partners de XDP Analytics.Use this method in the Microsoft Store analytics API to get aggregate add-on acquisition data in JSON format for UWP apps and Xbox One games that were ingested through the Xbox Developer Portal (XDP) and available in the XDP Analytics Partner Center dashboard.

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.

Nota

Esta API no proporciona datos agregados diarios antes del 1 de octubre de 2016.This API does not provide daily aggregate data before Oct 1st 2016.

SolicitudRequest

Sintaxis de la solicitudRequest syntax

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

Encabezado de solicitudRequest header

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

Parámetros de solicitudRequest parameters

El parámetro ApplicationID o addonProductId es obligatorio.The applicationId or addonProductId 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 adquisición para un único complemento, especifique el parámetro addonProductId .To retrieve acquisition data for a single add-on, specify the addonProductId 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 ProductId del juego Xbox One para el que se recuperan los datos de adquisición.The productId of the Xbox One game for which you are retrieving acquisition data. Para obtener el ProductID del juego, navegue hasta el juego en el programa XDP Analytics y recupere el ProductID de la dirección URL.To get the productId of your game, navigate to your game in the XDP Analytics Program and retrieve the productId from the URL. Como alternativa, si descarga los datos de adquisiciones del informe del centro de Partners, el productId se incluye en el archivo. TSV.Alternatively, if you download your acquisitions data from the Partner Center analytics report, the productId is included in the .tsv file. Yes
addonProductIdaddonProductId stringstring ProductId del complemento para el que desea recuperar los datos de adquisición.The productId 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. Cada instrucción contiene un nombre de campo del cuerpo de la respuesta y el valor que están asociados a los operadores EQ o NE, y las instrucciones se pueden combinar con and u or.Each statement contains a field name from the response body and value that are associated with the eq or ne operators, and statements can be combined using and or or. 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. Por ejemplo, filtro = Market EQ ' EE. UU. ' y sexo EQ ' m '.For example, filter=market eq 'US' and gender eq 'm'.
Puede especificar los siguientes campos del cuerpo de la respuesta:You can specify the following fields from the response body:
  • acquisitionTypeacquisitionType
  • antigage
  • storeClientstoreClient
  • sexogender
  • datamarketmarket
  • osVersionosVersion
  • TipoDeDispositivodeviceType
  • sandboxIdsandboxId
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
  • antigage
  • 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
  • addonProductNameaddonProductName
  • acquisitionTypeacquisitionType
  • antigage
  • storeClientstoreClient
  • sexogender
  • datamarketmarket
  • osVersionosVersion
  • TipoDeDispositivodeviceType
  • paymentInstrumentTypepaymentInstrumentType
  • sandboxIdsandboxId
  • xboxTitleIdHexxboxTitleIdHex
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
  • addonProductIdaddonProductId
  • acquisitionQuantityacquisitionQuantity
Puedes usar el parámetro groupby con aggregationLevel.The groupby parameter can be used with the aggregationLevel parameter. Por ejemplo: &GroupBy = Age, market&aggregationLevel = WeekFor example: &groupby=age,market&aggregationLevel=week
NoNo

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. Reemplace los valores addonProductId y APPLICATIONID por el identificador de almacén adecuado para el complemento o la aplicación.Replace the addonProductId and applicationId values with the appropriate Store ID for your add-on or app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&skip=0 HTTP/1.1 

Authorization: Bearer <your access token> 

 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&skip=0&filter=market eq 'GB' and gender eq 'm' 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.
addonProductIdaddonProductId stringstring ProductId del complemento para el que se recuperan los datos de adquisición.The productId of the add-on for which you are retrieving acquisition data.
addonProductNameaddonProductName 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 está establecido en Day, a menos que especifique el campo addonProductName 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 addonProductName field in the groupby parameter.
applicationIdapplicationId stringstring El productId de la aplicación para la que desea recuperar los datos de adquisición del complemento.The productId of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring El nombre para mostrar del juego.The display name of the game.
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:
  • PC"PC"
  • Número"Phone"
  • "Consola: Xbox One""Console-Xbox One"
  • "Consola: serie Xbox X""Console-Xbox Series X"
  • IOT"IoT"
  • Servidor"Server"
  • Tableta"Tablet"
  • Holográfica"Holographic"
  • Unknown"Unknown"
storeClientstoreClient stringstring Una de las siguientes cadenas que indica la versión del almacén donde se produjo la adquisición:One of the following strings that indicates the version of the Store where the acquisition occurred:
  • "Almacén de Windows Phone (cliente)""Windows Phone Store (client)"
  • "Microsoft Store (cliente)" (o "tienda Windows (cliente)" si se consultan los datos antes del 23 de marzo de 2018)"Microsoft Store (client)" (or "Windows Store (client)" if querying for data before March 23, 2018)
  • "Microsoft Store (Web)" (o "tienda Windows (Web)" si se consultan los datos antes del 23 de marzo de 2018)"Microsoft Store (web)" (or "Windows Store (web)" if querying for data before March 23, 2018)
  • "Compras por volumen por organizaciones""Volume purchase by organizations"
  • Distinta"Other"
osVersionosVersion stringstring Versión del sistema operativo en el que se realizó la compra.The OS version on which the acquisition occurred. Para este método, este valor siempre es "Windows 10".For this method, this value is always "Windows 10".
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 Una de las siguientes cadenas que especifica el sexo del usuario que realizó la adquisición:One of the following strings that specifies the gender of the user who made the acquisition:
  • "m""m"
  • "f""f"
  • Unknown"Unknown"
ageage stringstring Una de las siguientes cadenas que indica el grupo de edad del usuario que realizó la adquisición:One of the following strings that indicates the age group of the user who made the acquisition:
  • "menor que 13""less than 13"
  • "13-17""13-17"
  • "18-24""18-24"
  • "25-34""25-34"
  • "35-44""35-44"
  • "44-55""44-55"
  • "mayor que 55""greater than 55"
  • Unknown"Unknown"
acquisitionTypeacquisitionType stringstring Una de las siguientes cadenas que indica el tipo de adquisición:One of the following strings that indicates the type of acquisition:
  • Ningún"Free"
  • Periodo"Trial"
  • Abonen"Paid"
  • "Código promocional""Promotional code"
  • IAP"Iap"
  • "Suscripción IAP""Subscription Iap"
  • "Público privado""Private Audience"
  • "Orden previo""Pre Order"
  • "Paso de juego de Xbox" (o "paso de juego" si se consultan los datos antes del 23 de marzo de 2018)"Xbox Game Pass" (or "Game Pass" if querying for data before March 23, 2018)
  • Discos"Disk"
  • "Código de prepago""Prepaid Code"
  • "Pedido anterior cargado""Charged Pre Order"
  • "Se canceló el pedido anterior""Cancelled Pre Order"
  • "Error de orden anterior""Failed Pre Order"
acquisitionQuantityacquisitionQuantity integerinteger Número de compras que se realizaron.The number of acquisitions that occurred.
inAppProductIdinAppProductId stringstring IDENTIFICADOR del producto en el que se usa este complemento.Product ID of the product where this add-on is used.
inAppProductNameinAppProductName stringstring Nombre del producto en el que se usa este complemento.Product Name of the product where this add-on is used.
paymentInstrumentTypepaymentInstrumentType stringstring Tipo de instrumento de pago usado para la adquisición.Payment instrument type used for the acquisition.
sandboxIdsandboxId stringstring El identificador de espacio aislado creado para el juego.The Sandbox ID created for the game. Puede ser el valor comercial o un identificador de espacio aislado privado.This can be the value RETAIL or a private sandbox ID.
xboxTitleIdxboxTitleId stringstring IDENTIFICADOR de título de Xbox del producto de XDP, si procede.Xbox Title ID of the product from XDP, if applicable.
localCurrencyCodelocalCurrencyCode stringstring Código de moneda local basado en el país de la cuenta del centro de Partners.Local Currency code based on the country of the Partner Center account.
xboxProductIdxboxProductId stringstring ID. de producto de Xbox del producto de XDP, si procede.Xbox Product ID of the product from XDP, if applicable.
availabilityIdavailabilityId stringstring IDENTIFICADOR de disponibilidad del producto de XDP, si procede.Availability ID of the product from XDP, if applicable.
skuIdskuId stringstring IDENTIFICADOR de SKU del producto de XDP, si procede.SKU ID of the product from XDP, if applicable.
skuDisplayNameskuDisplayName stringstring Nombre para mostrar de SKU del producto de XDP, si procede.SKU Display Name of the product from XDP, if applicable.
xboxParentProductIdxboxParentProductId stringstring IDENTIFICADOR del producto primario de Xbox del producto de XDP, si procede.Xbox Parent Product ID of the product from XDP, if applicable.
parentProductNameparentProductName stringstring Nombre del producto primario del producto de XDP, si procede.Parent Product Name of the product from XDP, if applicable.
productTypeNameproductTypeName stringstring Nombre del tipo de producto del producto de XDP, si procede.Product Type Name of the product from XDP, if applicable.
purchaseTaxTypepurchaseTaxType stringstring Tipo de impuesto de compra del producto de XDP, si procede.Purchase Tax Type of the product from XDP, if applicable.
purchasePriceUSDAmountpurchasePriceUSDAmount numbernumber La cantidad pagada por el cliente para el complemento, convertido a USD.The amount paid by the customer for the add-on, converted to USD.
purchasePriceLocalAmountpurchasePriceLocalAmount numbernumber Importe de impuestos aplicado al complemento.The tax amount applied to the add-on.
purchaseTaxUSDAmountpurchaseTaxUSDAmount numbernumber Importe de impuestos que se aplica al complemento, convertido a USD.The tax amount applied to the add-on, converted to USD.
purchaseTaxLocalAmountpurchaseTaxLocalAmount numbernumber Importe local del impuesto de compra del producto de XDP, si procede.Purchase Tax Local Amount of the product from XDP, if applicable.

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": [ 
    { 
            "inAppProductId": "9NBLGGH1864K", 
            "inAppProductName": "866879", 
            "addonProductId": "9NBLGGH1864K", 
            "addonProductName": "866879", 
            "date": "2017-11-05", 
            "applicationId": "9WZDNCRFJ314", 
            "applicationName": "Tetris Blitz", 
            "acquisitionType": "Iap", 
            "age": "35-49", 
            "deviceType": "Phone", 
            "gender": "m", 
            "market": "US", 
            "osVersion": "Windows Phone 8.1", 
            "paymentInstrumentType": "Credit Card", 
            "sandboxId": "RETAIL", 
            "storeClient": "Windows Phone Store (client)", 
            "xboxTitleId": "", 
            "localCurrencyCode": "USD", 
            "xboxProductId": "00000000-0000-0000-0000-000000000000", 
            "availabilityId": "", 
            "skuId": "", 
            "skuDisplayName": "Full", 
            "xboxParentProductId": "", 
            "parentProductName": "Tetris Blitz", 
            "productTypeName": "Add-On", 
            "purchaseTaxType": "", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 1.08, 
            "purchasePriceLocalAmount": 0.09, 
            "purchaseTaxUSDAmount": 1.08, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null, 
    
    "TotalCount": 7601 
}