Paradigme d’accès par programmation pour la Place de marché Microsoft

Ce diagramme illustre le modèle d’appel d’API utilisé pour créer un modèle de rapport, planifier le rapport personnalisé et récupérer les données d’échec.

Figure 1 : Flux de haut niveau du modèle d’appel d’API

Cette liste fournit plus de détails sur la figure 1.

1. 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 de rapport (QueryId) à partir de la liste des requêtes système.
2. En cas de réussite, l’API Créer un modèle de rapport renvoie le QueryIdfichier .
3. L’application cliente appelle ensuite l’API Créer un rapport à l’aide de la date de début du rapport, de l’intervalle de répétition, de QueryID la récurrence et d’un URI de rappel facultatif.
4. En cas de réussite, l’API de création de rapport renvoie le ReportIDfichier .
5. L’application cliente est avertie au niveau de l’URI de rappel dès que les données du rapport sont prêtes à être téléchargées.
6. L’application cliente utilise ensuite l’API Obtenir les exécutions de rapport pour interroger l’état du rapport avec la Report ID plage de dates et .
7. En cas de succès, le lien de téléchargement du rapport est renvoyé et l’application peut lancer le téléchargement des données.

Spécification du langage de requête de rapport

Bien que nous fournissions 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 des requêtes personnalisées.

Créer une API de requête de rapport

Cette API permet de créer des requêtes personnalisées qui définissent l’ensemble de données à partir duquel les colonnes et les métriques doivent être exportées. L’API offre la possibilité de créer un nouveau modèle de rapport en fonction des 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.

L’exemple suivant montre comment créer une requête personnalisée pour obtenir l’utilisation normalisée et les frais financiers estimés pour les références SKU PAID à partir de l’ensemble de données ISVUsage pour le dernier mois.

Syntaxe de la requête

En-tête de requête

Paramètre de chemin

Aucun

Paramètre de requête

Aucun

Exemple de charge utile de demande

{
    "Name": "ISVUsageQuery",
    "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
    "Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}

Glossaire

Ce tableau fournit les principales définitions des éléments de la charge utile de la demande.

Exemple de réponse

La charge utile de réponse est structurée comme suit :

Codes de réponse : 200, 400, 401, 403, 500

Exemple de charge utile de réponse :

{
  "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " ISVUsageQuery",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

Glossaire

Ce tableau fournit les principales définitions des éléments de la réponse.

Créer une API de rapport

Une fois que vous avez réussi à créer un modèle de rapport personnalisé et que vous avez reçu la réponse dans le cadre de la QueryID création d’une requête de rapport , cette API peut être appelée pour planifier l’exécution d’une requête à intervalles réguliers. Vous pouvez définir une fréquence et un calendrier pour la remise du rapport. Pour les requêtes système que nous fournissons, l’API Create Report peut également être appelée avec QueryId.

Syntaxe de la requête

En-tête de requête

Paramètre de chemin

Aucun

Paramètre de requête

Aucun

Exemple de charge utile de demande

{
  "ReportName": "ISVUsageReport",
  "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
  "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
  "StartTime": "2021-01-06T19:00:00Z ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

Glossaire

Ce tableau fournit les principales définitions des éléments de la charge utile de la demande.

Exemple de réponse

La charge utile de réponse est structurée comme suit :

Code de réponse : 200, 400, 401, 403, 404, 500

Charge utile de réponse :

{
  "Value": [
    {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVUsageReport",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "user": "142344300",
            "createdTime": "2024-01-06T05:46:00Z",
            "modifiedTime": null,
            "startTime": "2024-01-06T19:00:00Z",
            "reportStatus": "Active",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": "https://<SampleCallbackUrl>",
            "callbackMethod": "GET",
            "format": "csv"
    }
  ],
  "TotalCount": 1,
  "Message": "Report created successfully",
  "StatusCode": 200
}

Glossaire

Ce tableau fournit les principales définitions des éléments de la réponse.

Obtenir l’API d’exécution de rapports

Vous pouvez utiliser cette méthode pour interroger l’état de l’exécution d’un rapport à l’aide de l’API ReportIdde création de rapport. La méthode renvoie le lien de téléchargement du rapport si celui-ci est prêt à être téléchargé. Sinon, la méthode renvoie l’état. Vous pouvez également utiliser cette API pour obtenir toutes les exécutions qui ont eu lieu pour un rapport donné.

Syntaxe de la requête

En-tête de requête

Paramètre de chemin

Aucun

Paramètre de requête

Charge utile de demande

Aucun

Exemple de réponse

La charge utile de réponse est structurée comme suit :

Codes de réponse : 200, 400, 401, 403, 404, 500

Exemple de charge utile de réponse :

{
    "value": [
        {
            "executionId": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "recurrenceInterval": 4,
            "recurrenceCount": 10,
            "callbackUrl": null,
            "format": "csv",
            "executionStatus": "Completed",
            "reportAccessSecureLink": "https://<path to report for download>",
            "reportExpiryTime": null,
            "reportGeneratedTime": "2021-01-13T14:40:46Z"
        }
    ],
    "totalCount": 1,
    "message": null,
    "statusCode": 200
}

Une fois l’exécution du rapport terminée, l’état Completed d’exécution s’affiche. Vous pouvez télécharger le rapport en sélectionnant l’URL dans le fichier reportAccessSecureLink.

Glossaire

Définitions clés des éléments de la réponse.

Vous pouvez essayer les API via l’URL de l’API Swagger .

Contenu connexe

• Effectuer votre premier appel d’API pour les rapports Marketplace Insights