Realice su primera llamada API

Artículo
01/31/2025

En esta página se explica cómo realizar la primera llamada API a Aplicaciones y Juegos.

Patrón de llamada API

En el diagrama siguiente se muestra el patrón de llamada API que se usa para crear una nueva plantilla de informe, programar el informe personalizado y recuperar los datos de error.

En esta lista se proporcionan más detalles sobre el diagrama de patrones de llamada api.

La aplicación cliente puede definir el esquema o plantilla de informe personalizado llamando a la API Create Report Query. Como alternativa, puede usar una plantilla (QueryId) de informe de la lista de consultas del sistema.
Si se ejecuta correctamente, la API Create Report Template (Crear plantilla de informe) devuelve .QueryId
A continuación, la aplicación cliente llama a la API de creación de informes con el elemento QueryID junto con la fecha de inicio del informe, el intervalo de repetición, la periodicidad y un URI de devolución de llamada opcional.
Si se ejecuta correctamente, la API de creación de informes devuelve el elemento ReportID.
La aplicación cliente llama a la API status para obtener el estado del informe.
A continuación, la aplicación cliente usa la API de obtención de ejecuciones de informes para consultar el estado del informe con el Report ID y el intervalo de fechas.
Si se ejecuta correctamente, se devuelve el vínculo de descarga del informe y la aplicación puede iniciar la descarga de los datos.

Especificar el lenguaje de consulta del informe

Aunque proporcionamos consultas del sistema que puede usar para crear informes, también puede crear sus propias consultas en función de sus necesidades empresariales. Para obtener más información sobre las consultas personalizadas, consulte Especificación de consultas personalizadas.

Autenticación

En primer lugar, incorpore a la cuenta del Centro de partners completando los requisitos previos para usar la API de análisis de Microsoft Store. A continuación, obtenga un token de acceso de Microsoft Entra. Siga solo el paso 1 y el paso 2. El paso 3 es redundante para este flujo.

Llamada API mediante programación

Después de obtener el token de Microsoft Entra como se describe en la sección anterior, siga estos pasos para crear el primer informe de acceso mediante programación.

Los datos se pueden descargar de los siguientes conjuntos de datos (datasetName):

Nombre del informe	Nombre del conjunto de datos en la API
Adquisición	Adquisiciones
Adquisición de complementos	AddOnAcquisitions
Canales y conversión	ChannelsAndConversions
Uso de Gamepass	GamePass
Rendimiento de Gamepass	GamePassPurchase
Estado: bloqueos y eventos	HealthFailureHits
Instalaciones	Instalaciones
Clasificaciones	Clasificaciones
Revisiones	Revisiones
Sostenibilidad	Sostenibilidad
Uso diario	UsageDaily
Uso mensual	UsageMonthly
Lista de deseos	Lista de deseos
Interacción de eventos	Xevents_Metrics
Promociones de precios: flexible	Xprice_Flexible_Offer
Promociones de precios: dirigida	Xprice_Targeted_Offer

En las secciones siguientes se muestran ejemplos de cómo acceder mediante programación al contenido desde el conjunto de datos de adquisición.

Realización de una llamada REST mediante get datasets API

La respuesta de la API proporciona el nombre del conjunto de datos desde donde puede descargar el informe. Para el conjunto de datos específico, la respuesta de la API también proporciona la lista de columnas seleccionables que se pueden usar para la plantilla de informe personalizada.

API de creación de consultas de informes

Esta API ayuda a crear consultas personalizadas que definen el conjunto de datos del que deben exportarse las columnas y métricas. La API proporciona la flexibilidad para crear una nueva plantilla de informes en función de sus necesidades empresariales.

También puede usar las consultas del sistema que proporcionamos. Cuando no se necesitan plantillas de informe personalizadas, puede llamar directamente a Create Report API mediante queryIds de las consultas del sistema que proporcionamos.

Ejemplo de solicitud

curl  
--location  
--request GET https://manage.devcenter.microsoft.com/consumer/insights/v1.1 /ScheduledDataset' \  
--header 'Authorization: Bearer <AzureADToken>'

Ejemplo de respuesta

{ 
    "value": [ 
        { 
            "columnFilters": {}, 
            "aggregationToDateRangeMapping": { 
                "Hourly": "LAST_72_HOURS", 
                "Daily": "LAST_30_DAYS,LAST_3_MONTHS", 
                "Weekly": "LAST_6_MONTHS,LAST_12_MONTHS", 
                "Monthly": "LAST_2_YEARS,LAST_3_YEARS,LAST_4_YEARS" 
            }, 
            "datasetName": "Acquisitions", 
            "selectableColumns": [ 
                "TitleId", 
                "ProductId", 
                "XboxProductId", 
                "ProductTypeName", 
                "TitleName", 
                "CatalogId", 
                "SandboxId", 
                "SkuId", 
                "SkuTypeName", 
                "SkuDisplayName", 
                "AvailabilityId", 
                "RegionName", 
                "CountryName", 
                "Market", 
                "PaymentType", 
                "StoreClientName", 
                "StoreClientCategory", 
                "ParentProductName", 
                "ParentProductId", 
                "XboxParentProductId", 
                "AcquisitionType", 
                "PurchaseTaxType", 
                "LocalCurrencyCode", 
                "SupportedPlatform", 
                "Age", 
                "Gender", 
                "OsVersion", 
                "DeviceType", 
                "DateStamp" 
            ], 
            "availableMetrics": [ 
                "PurchaseQuantity", 
                "PurchasePriceUSDAmount", 
                "PurchaseTaxUSDAmount", 
                "PurchasePriceLocalAmount", 
                "PurchaseTaxLocalAmount" 
            ], 
            "availableDateRanges": [ 
                "LAST_72_HOURS", 
                "LAST_30_DAYS", 
                "LAST_3_MONTHS", 
                "LAST_6_MONTHS", 
                "LAST_12_MONTHS", 
                "LAST_2_YEARS", 
                "LAST_3_YEARS", 
                "LAST_4_YEARS" 
            ], 
            "minimumRecurrenceInterval": 1 
        } 
}

Creación de la consulta personalizada

En este paso, creamos una consulta personalizada para el informe que queremos. Esta consulta creada se usa cada vez que se requiere un informe (execute now o schedule).

Ejemplo de solicitud

curl  
--location  
--request POST ' https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \  
--header ' Authorization: Bearer <AzureAD_Token>' \  
--header 'Content-Type: application/json' \  
--data-raw  
            '{  
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily",  
    "Name": "Consumer public API Create query",  
    "Description": "Acquisition query creation."  
}'

Ejemplo de respuesta

{ 
    "value": [ 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "name": "Consumer public API Create query", 
            "description": "Acquisition query creation", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-03-26T11:26:48Z" 
        } 
    ], 
    "totalCount": 1, 
    "message": "Query created successfully", 
    "statusCode": 200 
}

Al ejecutar correctamente la consulta, se genera un queryId que debe usarse para generar el informe.

Obtener consulta

Enumera todas las consultas disponibles. La consulta existente creada en el paso anterior debe reflejarse aquí.

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \ 
--header 'Authorization: Bearer <token> \

Ejemplo de respuesta

{ 
    "value": [ 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "name": "Consumer public API Create query", 
            "description": "Acquisition query creation", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-03-26T11:26:48Z" 
        }, 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "9PDC2J734M08", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "724c796e-ea64-438f-b784-f2e284349d2f", 
            "name": "Acquisition_Daily_30days_next2months", 
            "description": null, 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, DateStamp, PurchaseQuantity, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-01-23T17:21:42Z" 
        } 
    ], 
    "totalCount": 2, 
    "message": "Queries fetched successfully", 
    "statusCode": 200 
}

Creación de un informe asincrónico instantáneo

En este paso, se usa el queryId generado anteriormente para crear el informe. La consulta siguiente se usa para ejecutar ahora el informe. La generación de informes es asincrónica y requiere una llamada API independiente para capturar el informe.

Ejemplo de solicitud

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer {{token}} \  
--header 'Content-Type: application/json' \ 
--data '{ 
"Description": "Acquisition report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create Report - Acquisition", 
"executeNow": true 
}'

Ejemplo de respuesta

{ 
    "value": [ 
        { 
            "productInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "reportId": "b58f9802-b118-485f-a0f1-edc273dea275", 
            "reportName": "Create Report - Acquisition", 
            "description": " Acquisition report ", 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "user": "", 
            "createdTime": "", 
            "modifiedTime": null, 
            "executeNow": true, 
            "queryStartTime": null, 
            "queryEndTime": null, 
            "startTime": "2024-03-26T11:33:16Z", 
            "reportStatus": "Active", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": "Report created successfully", 
    "statusCode": 200 
}

ReportId: se genera 'execution'. Este identificador debe usarse para programar una descarga del informe.

Nota:

Para obtener más información sobre el totalRecurrenceCount campo, consulte Descripción del campo totalRecurrenceCount para los informes programados.

Descarga del informe instantáneo

Ejemplo de solicitud

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/b58f9802-b118-485f-a0f1-edc273dea275' \ 
--header 'Authorization: Bearer <token>' \

Ejemplo de respuesta

{ 
    "value": [ 
        { 
            "executionId": "28016f06-6bbf-459e-ba30-429da6910192", 
            "reportId": "b58f9802-b118-485f-a0f1-edc273dea275", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "executionStatus": "Completed", 
            "reportLocation": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv", 
            "reportAccessSecureLink": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv? <SAS token> ", 
            "reportExpiryTime": null, 
            "reportGeneratedTime": "2024-03-26T11:46:19Z", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": null, 
    "statusCode": 200 
}

Se puede invocar reportAccessSecureLink para descargar el informe.

Creación de un informe de programación

Las llamadas API ayudan a crear un informe de programación.

Solicitar

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer <token> \ 
--header 'Content-Type: application/json' \ 
--data '{ 
"Description": "Creating a scheduled report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create scheduled report - Acquisition", 
"StartTime": "2024-03-26T18:00:19Z", 
"RecurrenceCount": 49, 
"RecurrenceInterval": 1 
}'

Respuesta

{ 
    "value": [ 
        { 
            "productInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "reportId": "5e49796b-8146-4d98-9dde-aa14d2f78f0f", 
            "reportName": "Create scheduled report - Acquisition", 
            "description": "Acquisition description", 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "user": "", 
            "createdTime": "2024-03-26T11:38:20Z", 
            "modifiedTime": null, 
            "executeNow": false, 
            "queryStartTime": null, 
            "queryEndTime": null, 
            "startTime": "2024-03-26T18:00:19Z", 
            "reportStatus": "Active", 
            "recurrenceInterval": 1, 
            "recurrenceCount": 49, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "endTime": "2024-03-28T18:00:19Z", 
            "totalRecurrenceCount": 49, 
            "nextExecutionStartTime": "2024-03-26T17:00:19Z" 
        } 
    ], 
    "totalCount": 1, 
    "message": "Report created successfully", 
    "statusCode": 200 
}

Obtención del estado del informe y detalles de descarga

Ahora que hemos creado un informe, realizaremos una llamada API para obtener el estado del informe y su vínculo descargable para que el informe se pueda descargar en el cliente. Para realizar esta llamada, estamos consultando con el mismo reportId generado en el paso anterior.

Solicitar

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/3b6c1ec2-53c2-48f6-9c9b-a46e5ca69d7d' \ 
--header 'Authorization: Bearer<token>' \

Respuesta

{ 
    "value": [ 
        { 
            "executionId": "28016f06-6bbf-459e-ba30-429da6910192", 
            "reportId": "5e49796b-8146-4d98-9dde-aa14d2f78f0f", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "executionStatus": "Completed", 
            "reportLocation": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv", 
            "reportAccessSecureLink": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv? <SAS token> ", 
            "reportExpiryTime": null, 
            "reportGeneratedTime": "2024-03-26T11:46:19Z", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": null, 
    "statusCode": 200 
}

Creación de un informe de programación con webhook

El webhook funciona como un punto de conexión que se invoca tan pronto como el informe esté listo. Es necesario proporcionar el parámetro callbackURL .

Los asociados deben escribir su controlador de webhook. En el ejemplo anterior, una vez que el informe esté listo, se invoca "https://msnotify.com" como una notificación. En la invocación, los asociados pueden obtener la lista de informes programados y sus estados y, a continuación, usar las API mencionadas anteriormente para descargar el archivo.

Solicitar

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer<token>' \ 
--header 'Content-Type: application/json' \ 
--header 'Cookie: ApplicationGatewayAffinity=3ebb3a6588e1f91ad543ccd7cdf31ec0; ApplicationGatewayAffinityCORS=3ebb3a6588e1f91ad543ccd7cdf31ec0' \ 
--data '{ 
"Description": "Acquisition report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create scheduled report - Acquisition", 
"StartTime": "2024-03-26T18:00:19Z", 
"RecurrenceCount": 49, 
"RecurrenceInterval": 1, 
"callbackURL": "https://msnotify.com", 
"callbackMethod": "get" 
}'

Documentación de la API

Consulte la especificación openAPI. Pegue el contenido de la especificación en el editor de Swagger público para ver las API y generar clientes en lenguajes preferidos (C#, python, etc.) para consumir las API.

Importante

Esta API tiene parámetros de consulta predeterminados establecidos para executionStatus=Completed y getLatestExecution=true. Por lo tanto, llamar a la API antes de la primera ejecución correcta del informe devolverá un error 404. Las ejecuciones pendientes se pueden obtener estableciendo executionStatus=Pending.

Compartir a través de

Realice su primera llamada API

Patrón de llamada API

Especificar el lenguaje de consulta del informe

Autenticación

Llamada API mediante programación

Realización de una llamada REST mediante get datasets API

API de creación de consultas de informes

Ejemplo de solicitud

Ejemplo de respuesta

Creación de la consulta personalizada

Ejemplo de solicitud

Ejemplo de respuesta

Obtener consulta

Ejemplo de respuesta

Creación de un informe asincrónico instantáneo

Ejemplo de solicitud

Ejemplo de respuesta

Descarga del informe instantáneo

Ejemplo de solicitud

Ejemplo de respuesta

Creación de un informe de programación

Solicitar

Respuesta

Obtención del estado del informe y detalles de descarga

Solicitar

Respuesta

Creación de un informe de programación con webhook

Solicitar

Documentación de la API

Comentarios

Recursos adicionales