Obtener los datos de las adquisiciones de complementos
Usa este método en la API de análisis de Microsoft Store para obtener datos de adquisición agregados para complementos de tu aplicación en formato JSON durante un intervalo de fechas determinado y otros filtros opcionales. Esta información también está disponible en el informe Adquisiciones de complementos del Centro de partners.
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/inappacquisitions |
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
El parámetro applicationId o inAppProductId son obligatorios. Para recuperar los datos de adquisición de todos los complementos registrados en la aplicación, especifica el parámetro applicationId. Para recuperar los datos de adquisición de un único complemento, especifica el parámetro inAppProductId. Si especificas ambos, se omite el parámetro applicationId.
| 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 complementos. | Sí |
| inAppProductId | string | Id. de Store del complemento para el que quieres recuperar los datos de adquisición. | Sí |
| startDate | date | Fecha de inicio del intervalo de fechas de los datos de adquisición de complementos 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 de complementos 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 10000. 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=10000 y skip=0 recupera las primeras 10000 filas de datos, top=10000 y skip=10000 recupera las siguientes 10000 filas de datos, etc. | No |
| filter | string | Una o varias instrucciones que filtran las filas de la respuesta. Para más información, consulte la sección campos de filtro a continuación. | 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. 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:
Las filas de datos devueltas contendrán los campos especificados en el parámetro groupby, además de los siguientes:
El parámetro groupby se puede usar con el parámetro aggregationLevel. Por ejemplo: &groupby=ageGroup,market&aggregationLevel=week |
No |
Campos de filtro
El parámetro filter de la solicitud contiene una o varias instrucciones que filtran las filas de la respuesta. Cada instrucción contiene un campo y un valor asociados a los operadores eq o ne, y las instrucciones se pueden combinar mediante y u o. Estos son algunos ejemplos de parámetros de filtro:
- filter=market eq 'US' and gender eq 'm'
- 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’)
Consulta la siguiente tabla para ver una lista de los campos admitidos. Los valores de cadena deben estar entre comillas simples en el parámetro de filtro.
| Campos | Descripción |
|---|---|
| acquisitionType | Una de las cadenas siguientes:
|
| ageGroup | Una de las cadenas siguientes:
|
| storeClient | Una de las cadenas siguientes:
|
| gender | Una de las cadenas siguientes:
|
| market | Cadena que contiene el código de país ISO 3166 del mercado donde se produjo la adquisición. |
| osVersion | Una de las cadenas siguientes:
|
| deviceType | Una de las cadenas siguientes:
|
| orderName | Cadena que especifica el nombre del pedido del código promocional que se usó para adquirir el complemento (esto solo se aplica si el usuario adquirió el complemento canjeando un código promocional). |
Ejemplo de solicitud
En los ejemplos siguientes se muestran varias solicitudes para obtener datos de adquisición de complementos. Reemplaza los valores inAppProductId y applicationId por el Id. de Store adecuado del complemento o la aplicación.
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>
Respuesta
Cuerpo de la respuesta
| Valor | Tipo | Descripción |
|---|---|---|
| Valor | array | Matriz de objetos que contienen datos de adquisición de complementos agregados. Para obtener más información sobre los datos de cada objeto, consulta la sección valores de adquisición de complementos 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 10000, pero hay más de 10000 filas de datos de adquisición de complementos 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 complementos
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. |
| inAppProductId | string | Id. de Store del complemento para el que se recuperan los datos de adquisición. |
| inAppProductName | string | Nombre para mostrar del complemento. Este valor solo aparece en los datos de respuesta si el parámetro aggregationLevel se establece en día, a menos que especifique el campo inAppProductName en el parámetro groupby. |
| applicationId | string | El Id. de Store de la aplicación para la que quieres recuperar los datos de adquisición de complementos. |
| applicationName | string | Nombre para mostrar de la aplicación. |
| deviceType | string | Tipo de dispositivo que completó la adquisición. Para obtener una lista de las cadenas admitidas, consulta la sección campos de filtro más arriba. |
| orderName | string | Nombre del orden. |
| storeClient | string | Versión de la Tienda donde se produjo la adquisición. Para obtener una lista de las cadenas admitidas, consulta la sección campos de filtro más arriba. |
| osVersion | string | Versión del sistema operativo en la que se produjo la adquisición. Para obtener una lista de las cadenas admitidas, consulta la sección campos de filtro más arriba. |
| market | string | El código de país ISO 3166 del mercado en el que se produjo la adquisición. |
| gender | string | El género del usuario que realizó la adquisición. Para obtener una lista de las cadenas admitidas, consulta la sección campos de filtro más arriba. |
| ageGroup | string | Grupo de edad del usuario que realizó la adquisición. Para obtener una lista de las cadenas admitidas, consulta la sección campos de filtro más arriba. |
| acquisitionType | string | Tipo de adquisición (gratis, pagado, etc.). Para obtener una lista de las cadenas admitidas, consulta la sección campos de filtro más arriba. |
| acquisitionQuantity | integer | Número de adquisiciones que se produjeron. |
Ejemplo de solicitud y respuesta
En el fragmento de código siguiente se muestra un ejemplo de solicitud y un cuerpo de la respuesta en formato JSON para esa solicitud.
Solicitud de muestra
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>
Respuesta de ejemplo
{
"Value": [
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Deluxe Collector's Edition",
"addonProductId": "9NBLGGAAGZDQ",
"date": "2022-07-29",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 18.12,
"purchasePriceLocalAmount": 18.12,
"purchaseTaxUSDAmount": 1.13,
"purchaseTaxLocalAmount": 1.13
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Episode 4",
"addonProductId": "9NAAAAAAAAAQ",
"date": "2017-01-07",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 4.147206,
"purchasePriceLocalAmount": 3.99,
"purchaseTaxUSDAmount": 0.686004,
"purchaseTaxLocalAmount": 0.66
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Deluxe Collector's Edition",
"addonProductId": "9NALGGGZ5QDQ",
"date": "2018-04-01",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 1.99,
"purchasePriceLocalAmount": 1.99,
"purchaseTaxUSDAmount": 0.0,
"purchaseTaxLocalAmount": 0.0
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Strategy Guide Episode 4",
"addonProductId": "9NBLGGGZ5QDQ",
"date": "2021-11-25",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 1.31902922876179,
"purchasePriceLocalAmount": 150.0,
"purchaseTaxUSDAmount": 0.114315866492689,
"purchaseTaxLocalAmount": 13.0
},
],
"TotalCount": 4,
"DataFreshnessTimestamp": "2022-07-29T05:54:00"
}
Temas relacionados
- Informe de adquisiciones de complementos
- Acceso a datos analíticos mediante los servicios de Microsoft Store
- Obtener conversiones de complementos por canal
- Obtener los datos de las adquisiciones de la aplicación
- Obtener datos de embudo de adquisiciones de aplicaciones
- Obtener conversiones de aplicaciones por canal