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

Article
06/14/2024

Ce diagramme montre le modèle d’appel d’API utilisé pour créer un nouveau 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.

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.
En cas de réussite, l’API Créer un modèle de rapport renvoie QueryId.
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 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.
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écification du langage de requête de rapport

Bien que nous fournissions des requêtes système à 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.

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.

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

Syntaxe de la requête

Méthode	URI de demande
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

En-tête de requête

En-tête	Type	Description
Autorisation	string	Obligatoire. Jeton d’accès Microsoft Entra. Le format est `Bearer <token>`.
Type de contenu	`string`	`application/JSON`

Paramètre de chemin

Aucune

Paramètre de requête

Aucune

Exemple de charge utile de requête

{
    "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 définitions clés des éléments dans la charge utile de requête.

Paramètre	Obligatoire	Description	Valeurs autorisées
`Name`	Oui	Nom convivial de la requête	string
`Description`	Non	Description de la requête créée	string
`Query`	Oui	Chaîne de requête basée sur les besoins métier	string

Remarque

Pour obtenir des exemples de requêtes personnalisées, consultez les exemples de requêtes.

Exemple de réponse

La charge utile de la 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 définitions clés des éléments dans la réponse.

Paramètre	Description
`QueryId`	Identificateur unique universel (UUID) de la requête créée
`Name`	Nom fourni dans la charge utile de la requête lors de la création de la requête
`Description`	Description fournie dans la charge utile de la requête lors de la création de la requête
`Query`	Requête de rapport personnalisée fournie dans la charge utile de la requête lors de la création de la requête
`Type`	Définir sur la valeur pour `userDefined` les requêtes créées manuellement
`User`	ID d’utilisateur utilisé pour créer la requête
`CreatedTime`	Heure UTC lors de la création de la requête. Format : aaaa-MM-ddTHH :mm :ssZ
`TotalCount`	Nombre d’enregistrements dans le tableau Valeur
`StatusCode`	Code de résultat Les valeurs possibles sont 200, 400, 401, 403, 500
`message`	Message d’état d’’exécution de l’API

API Créer un rapport

Lors de la création d’un modèle de rapport personnalisé et de la réception de QueryID dans la réponse Créer 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 une planification pour le rapport à remettre. Pour les requêtes système que nous fournissons, l’API Créer un rapport peut également être appelée avec QueryId.

Syntaxe de la requête

Méthode	URI de demande
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

En-tête de requête

En-tête	Type	Description
Autorisation	string	Obligatoire. Jeton d’accès Microsoft Entra. Le format est `Bearer <token>`.
Type de contenu	string	`application/JSON`

Paramètre de chemin

Aucune

Paramètre de requête

Aucune

Exemple de charge utile de requête

{
  "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 définitions clés des éléments dans la charge utile de requête.

Paramètre	Obligatoire	Description	Valeurs autorisées
`ReportName`	Oui	Nom convivial attribué au rapport	Chaîne
`Description`	Non	Description du rapport créé	Chaîne
`QueryId`	Oui	ID de requête à utiliser pour la génération de rapports	Chaîne
`StartTime`	Oui	Horodatage UTC à partir duquel la génération du rapport commence. Le format doit être aaaa-MM-jjTHH:mm:ssZ	Chaîne
`ExecuteNow`	Non	Ce paramètre doit être utilisé pour créer un rapport exécuté une seule fois. `StartTime`, `RecurrenceInterval`, `RecurrenceCount`et `EndTime` sont ignorés si cette valeur est définie sur `true`	Boolean
`QueryStartTime`	Non	(Facultatif) Spécifie l’heure de début de la requête qui extrait les données. Ce paramètre s’applique uniquement à un rapport à exécution ponctuelle dont la valeur `ExecuteNow` est définie sur `true`. Le format doit être aaaa-MM-jjTHH:mm:ssZ	Timestamp sous forme de chaîne
`QueryEndTime`	Non	(Facultatif) Spécifie l’heure de fin de la requête qui extrait les données. Ce paramètre s’applique uniquement à un rapport à exécution ponctuelle dont la valeur `ExecuteNow` est définie sur `true`. Le format doit être aaaa-MM-jjTHH:mm:ssZ	Timestamp sous forme de chaîne
`RecurrenceInterval`	Oui	Fréquence en heures à laquelle le rapport doit être généré. La valeur minimale est 1 et la valeur maximale est 17520	Integer
`RecurrenceCount`	Oui	Nombre de rapports à générer. La limite dépend de l’intervalle de périodicité	Integer
`Format`	Non	Format du fichier exporté. Le format par défaut est CSV	CSV/TSV
`CallbackUrl`	Non	URL accessible publiquement qui peut être configurée éventuellement comme destination de rappel	Chaîne
`CallbackMethod`	Non	Méthode Get/Post qui peut être configurée avec l’URL de rappel	GET/POST
`EndTime`	Oui	Horodatage UTC auquel la génération de rapport se termine. Le format doit être aaaa-MM-jjTHH:mm:ssZ	Chaîne

Remarque

Lors de la création du rapport, soit EndTime en combinaison, soit RecurrenceCount obligatoireRecurrenceInterval.

Exemple de réponse

La charge utile de la 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 définitions clés des éléments dans la réponse.

Paramètre	Description
`ReportId`	Identificateur unique universel (UUID) du rapport créé
`ReportName`	Nom fourni dans la charge utile de la demande lors de la création du rapport
`Description`	Description fournie dans la charge utile de la demande lors de la création du rapport
`QueryId`	ID de requête fourni dans la charge utile de la requête lors de la création du rapport
`Query`	Texte de requête qui sera exécuté pour ce rapport
`User`	ID d’utilisateur utilisé pour créer le rapport
`CreatedTime`	Heure UTC de création du rapport au format suivant : aaaa-MM-jjTHH:mm:ssZ
`ModifiedTime`	Heure UTC de dernière modification du rapport au format suivant : aaaa-MM-jjTHH:mm:ssZ
`ExecuteNow`	Paramètre ExecuteNow fourni dans la charge utile de la demande lors de la création du rapport
`queryStartTime`	Heure de début de la requête fournie dans la charge utile de la requête lors de la création du rapport. Cela s’applique uniquement s’il `ExecuteNow` est défini sur « True »
`queryEndTime`	Heure de fin de requête fournie dans la charge utile de la requête lors de la création du rapport. Cela s’applique uniquement s’il `ExecuteNow` est défini sur « True »
`StartTime`	Heure de début fournie dans la charge utile de la demande lors de la création du rapport
`ReportStatus`	État d’exécution du rapport. Les valeurs possibles sont Paused, Active et Inactive.
`RecurrenceInterval`	Intervalle de périodicité fourni dans la charge utile de la requête lors de la création du rapport
`RecurrenceCount`	Nombre de périodicités restantes pour le rapport
`CallbackUrl`	URL de rappel fournie dans la charge utile de la demande lors de la création du rapport
`CallbackMethod`	Méthode de rappel fournie dans la charge utile de la demande lors de la création du rapport
`Format`	Format des fichiers de rapport fournis dans la charge utile de la demande lors de la création du rapport
`EndTime`	Heure de fin fournie dans la charge utile de la demande lors de la création du rapport. Cela s’applique uniquement s’il `ExecuteNow` est défini sur « True »
`TotalRecurrenceCount`	`RecurrenceCount` fourni dans la charge utile de la demande lors de la création du rapport
`nextExecutionStartTime`	Horodatage UTC au démarrage de l’exécution du rapport suivant
`TotalCount`	Nombre d’enregistrements dans le tableau Valeur
`StatusCode`	Code de résultat Les valeurs possibles sont 200, 400, 401, 403, 500
`message`	Message d’état d’’exécution de l’API

API Obtenir les exécutions de rapport

Vous pouvez utiliser cette méthode pour interroger l’état d’exécution d’un rapport à l’aide du ReportId reçu à partir de l'API Créer un rapport. La méthode renvoie le lien de téléchargement du rapport si le rapport 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 intervenues pour un rapport donné.

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 renvoie 404. Les exécutions en attente peuvent être obtenues en définissant executionStatus=Pending.

Syntaxe de la requête

Méthode	URI de demande
Get	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

En-tête de requête

En-tête	Type	Description
Autorisation	string	Obligatoire. Jeton d’accès Microsoft Entra. Le format est `Bearer <token>`.
Type de contenu	string	`application/json`

Paramètre de chemin

Aucune

Paramètre de requête

Nom du paramètre	Requis	Type	Description
`reportId`	Oui	string	Filtre permettant d’obtenir les détails d’exécution des rapports avec `reportId` fourni dans cet argument.
`executionId`	Non	string	Filtre permettant d’obtenir les détails des seuls rapports avec `executionId` fourni dans cet argument. Plusieurs `executionIds` peuvent être spécifiés en les séparant par un point-virgule « ; ».
`executionStatus`	Non	chaîne/énumération	Filtre permettant d’obtenir les détails des seuls rapports avec `executionStatus` fourni dans cet argument. Les valeurs valides sont `Pending`, `Running`, `Paused` et `Completed`. La valeur par défaut est `Completed`.
`getLatestExecution`	Non	booléen	L’API renvoie les détails d’exécution du rapport le plus récent. Par défaut, ce paramètre a la valeur `true`. Si vous choisissez de transmettre la valeur de ce paramètre en tant que `false`, l’API renvoie les instances d’exécution des 90 derniers jours.

Charge utile de la demande

Aucune

Exemple de réponse

La charge utile de la 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 d’exécution Completed est affiché. Vous pouvez télécharger le rapport en sélectionnant l’URL dans le reportAccessSecureLink.

Glossaire

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

Paramètre	Description
`ExecutionId`	Identificateur unique universel (UUID) de l’instance d’exécution
`ReportId`	ID de rapport associé à l’instance d’exécution
`RecurrenceInterval`	Intervalle de périodicité fourni lors de la création du rapport
`RecurrenceCount`	Nombre de récurrences fourni lors de la création du rapport
`CallbackUrl`	URL de rappel associée à l’instance d’exécution
`CallbackMethod`	Méthode de rappel fournie dans la charge utile de la demande lors de la création du rapport
`Format`	Format du fichier généré à la fin de l’exécution
`ExecutionStatus`	État de l’instance d’exécution du rapport. Les valeurs valides sont `Pending`, `Running`, `Paused` et `Completed`.
`ReportLocation`	Emplacement où le rapport est téléchargé.
`ReportAccessSecureLink`	Lien permettant d’accéder en toute sécurité au rapport
`ReportExpiryTime`	Heure UTC après laquelle le lien du rapport expire au format suivant : aaaa-MM-jjTHH:mm:ssZ
`ReportGeneratedTime`	Heure UTC à laquelle le rapport a été généré au format suivant : aaaa-MM-jjTHH:mm:ssZ
`EndTime`	Heure de fin fournie dans la charge utile de la demande lors de la création du rapport. Cela s’applique uniquement s’il `ExecuteNow` est défini sur « True »
`TotalRecurrenceCount`	`RecurrenceCount` fourni dans la charge utile de la demande lors de la création du rapport
`nextExecutionStartTime`	Horodatage UTC au démarrage de l’exécution du rapport suivant
`TotalCount`	Nombre de jeux de données dans le tableau de valeur
`StatusCode`	Code de résultat Les valeurs possibles sont 200, 400, 401, 403, 404 et 500.
`message`	Message d’état d’’exécution de l’API

Vous pouvez tester les API à l’aide de l’URL d’API Swagger.

Effectuez votre premier appel d’API pour les rapports Marketplace Insights

Partager via

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

Spécification du langage de requête de rapport

API Créer une requête de rapport

API Créer un rapport

API Obtenir les exécutions de rapport

Commentaires

Ressources supplémentaires

Partager via

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

Spécification du langage de requête de rapport

API Créer une requête de rapport

API Créer un rapport

API Obtenir les exécutions de rapport

Contenu connexe

Commentaires

Ressources supplémentaires