Effectuer votre premier appel d’API

Article
06/13/2024

Cette page explique comment effectuer votre premier appel d’API aux applications et aux jeux.

Modèle d’appel d’API

Le diagramme suivant montre le modèle d’appel d’API utilisé pour créer un modèle de rapport, planifier le rapport personnalisé et récupérer des données d’échec.

Cette liste fournit plus d’informations sur le diagramme du modèle d’appel d’API.

L’application cliente peut définir le schéma/modèle de rapport personnalisé en appelant l’API Créer une requête de rapport. Vous pouvez également utiliser un modèle (QueryId) de rapport dans la liste des requêtes système.
En cas de réussite, l’API Créer un modèle de rapport retourne le QueryIdfichier .
L’application cliente appelle ensuite l'API Créer un rapport à l’aide de QueryID avec la date de début du rapport, l’intervalle de répétition, la périodicité et un URI de rappel facultatif.
En cas de réussite, l'API Créer un rapport renvoie le ReportID.
L’application cliente appelle l’API Status pour obtenir l’état du rapport.
L’application cliente utilise ensuite l'API Obtenir des exécutions de rapport pour interroger l’état du rapport avec Report ID et la plage de dates.
En cas de réussite, le lien de téléchargement du rapport est renvoyé et l’application peut lancer le téléchargement des données.

Spécifier le langage de requête de rapport

Bien que nous fournissons des requêtes système que vous pouvez utiliser pour créer des rapports, vous pouvez également créer vos propres requêtes en fonction des besoins de votre entreprise. Pour en savoir plus sur les requêtes personnalisées, consultez Spécification de requête personnalisée.

Authentification

Tout d’abord, intégrez-vous au compte espace partenaires en effectuant les conditions préalables à l’utilisation de l’API d’analytique du Microsoft Store. Ensuite, obtenez un jeton d’accès Microsoft Entra. Suivez l’étape 1 et l’étape 2 uniquement. L’étape 3 est redondante pour ce flux.

Appel d’API programmatique

Après avoir obtenu le jeton Microsoft Entra comme décrit dans la section précédente, procédez comme suit pour créer votre premier rapport d’accès par programmation.

Les données peuvent être téléchargées à partir des jeux de données suivants (datasetName) :

Nom du rapport	Nom du jeu de données dans l’API
Acquisition	Acquisitions
Acquisition de modules complémentaires	AddOnAcquisitions
Canaux et conversion	ChannelsAndConversions
Utilisation de Gamepass	GamePass
Gamepass Performance	GamePassPurchase
Intégrité : incidents et événements	HealthFailureHits
Installations	Installations
Évaluations	Évaluations
Révisions	Révisions
Durabilité	Durabilité
Utilisation quotidienne	UsageDaily
Utilisation mensuelle	Utilisation mensuelle
Liste de souhaits	Liste de souhaits
Engagement des événements	Xevents_Metrics
Promotions tarifaires - Flexible	Xprice_Flexible_Offer
Promotions de tarification - Ciblé	Xprice_Targeted_Offer

Les sections suivantes montrent des exemples d’accès par programmation au contenu à partir du jeu de données Acquisition.

Effectuer un appel REST à l’aide de l’API Get Datasets

La réponse de l’API fournit le nom du jeu de données à partir duquel vous pouvez télécharger le rapport. Pour le jeu de données spécifique, la réponse de l’API fournit également la liste des colonnes sélectionnables pouvant être utilisées pour votre modèle de rapport personnalisé.

API Créer une requête de rapport

Cette API permet de créer des requêtes personnalisées qui définissent le jeu de données à partir duquel les colonnes et les mesures doivent être exportées. L’API offre la flexibilité nécessaire pour créer un nouveau modèle de rapport basé sur les besoins de votre entreprise.

Vous pouvez également utiliser les requêtes système que nous fournissons. Lorsque les modèles de rapport personnalisés ne sont pas nécessaires, vous pouvez appeler l’API Créer un rapport directement à l’aide des QueryIds des requêtes système que nous fournissons.

Exemple de requête

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

Exemple de réponse

{ 
    "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 
        } 
}

Créer la requête personnalisée

Dans cette étape, nous créons une requête personnalisée pour le rapport souhaité. Cette requête créée est utilisée chaque fois qu’un rapport est requis (execute now ou schedule).

Exemple de requête

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."  
}'

Exemple de réponse

{ 
    "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 
}

Lors de l’exécution réussie de la requête, un queryId est généré qui doit être utilisé pour générer le rapport.

Obtenir la requête

Répertorie toutes les requêtes disponibles. La requête existante créée à l’étape ci-dessus doit refléter ici.

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

Exemple de réponse

{ 
    "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 
}

Créer un rapport asynchrone instantané

Dans cette étape, nous utilisons l’ID de requête généré précédemment pour créer le rapport. La requête ci-dessous est utilisée pour exécuter maintenant le rapport. La génération de rapport est asynchrone et nécessite un appel d’API distinct pour extraire le rapport.

Exemple de requête

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 
}'

Exemple de réponse

{ 
    "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 : « execution » est généré. Cet ID doit être utilisé pour planifier un téléchargement du rapport.

Remarque

Pour plus d’informations sur le totalRecurrenceCount champ, consultez Comprendre le champ totalRecurrenceCount pour les rapports planifiés.

Télécharger le rapport instantané

Exemple de requête

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

Exemple de réponse

{ 
    "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 
}

Le reportAccessSecureLink peut être appelé pour télécharger le rapport.

Créer un rapport de planification

Les appels d’API aident à créer un rapport de planification.

Requête

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 
}'

Response

{ 
    "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 
}

Obtenir l’état du rapport et télécharger les détails

Maintenant que nous avons créé un rapport, nous allons effectuer un appel d’API pour obtenir l’état du rapport et son lien téléchargeable afin que le rapport puisse être téléchargé sur le client. Pour effectuer cet appel, nous interrogeons avec le même reportId généré à l’étape précédente.

Requête

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

Response

{ 
    "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 
}

Créer un rapport de planification avec webhook

Le webhook fonctionne comme point de terminaison appelé dès que le rapport est prêt. Le paramètre callbackURL doit être fourni.

Les partenaires doivent écrire leur gestionnaire de webhook. Dans l’exemple précédent, une fois le rapport prêt, le «https://msnotify.com » est appelé en tant que notification. Dans l’appel, les partenaires peuvent obtenir la liste des rapports planifiés et leurs états, puis utiliser les API mentionnées ci-dessus pour télécharger le fichier.

Requête

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" 
}'

Documentation sur les API

Reportez-vous à la spécification OpenAPI. Collez le contenu de la spécification dans l’éditeur Swagger public pour afficher les API et générer des clients dans des langages préférés (C#, python, etc.) pour consommer les API.

Important

Les paramètres de requête par défaut de cette API sont définis pour executionStatus=Completed et getLatestExecution=true. Par conséquent, l’appel de l’API avant la première exécution réussie du rapport retourne une erreur 404. Les exécutions en attente peuvent être obtenues en définissant executionStatus=Pending.

Partager via

Effectuer votre premier appel d’API

Modèle d’appel d’API

Spécifier le langage de requête de rapport

Authentification

Appel d’API programmatique

Effectuer un appel REST à l’aide de l’API Get Datasets

API Créer une requête de rapport

Exemple de requête

Exemple de réponse

Créer la requête personnalisée

Exemple de requête

Exemple de réponse

Obtenir la requête

Exemple de réponse

Créer un rapport asynchrone instantané

Exemple de requête

Exemple de réponse

Télécharger le rapport instantané

Exemple de requête

Exemple de réponse

Créer un rapport de planification

Requête

Response

Obtenir l’état du rapport et télécharger les détails

Requête

Response

Créer un rapport de planification avec webhook

Requête

Documentation sur les API

Commentaires

Ressources supplémentaires