Paradigme de l’accès programmatique
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 choisir un modèle de rapport (QueryId) à partir des exemples de bibliothèque de modèles de rapport dans la Liste des requêtes système pour l’accès par programmation aux insights partenaires.
- En cas de réussite, l'API Créer une requête de rapport renvoie le QueryId.
- L’application cliente doit ensuite appeler l'API Créer un rapport à l’aide de appelle 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’URL 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 l’ID de rapport 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 des 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 fournies.
L’exemple suivant montre comment créer une requête personnalisée pour obtenir les 10 premiers clients par chiffre d’affaires pour le mois dernier.
Syntaxe de la requête
| Méthode | URI de demande |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1/mpn/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>. |
| Content-Type | string | Application/JSON |
Paramètre de chemin
Aucune
Paramètre de requête.
Aucune
Exemple de charge utile de requête
{
"Name": "CustomersRevenueQuery",
"Description": "Query to get top 10 customers by revenue for last month",
"Query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH"
}
Glossaire de la demande
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 |
|---|---|---|---|
| Nom | Oui | Nom convivial de la requête | string |
| Description | Non | Description de ce que la requête renvoie | string |
| Requête | Oui | Chaîne de requête de rapport | Type de données : chaîne Requête personnalisée basée sur les besoins de l’entreprise |
Remarque
Pour obtenir des exemples de requêtes personnalisées, consultez 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": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"name": "CustomersRevenueQuery",
"description": "Query to get top 10 customers by revenue for last month",
"query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
"type": "userDefined",
"user": "GAUser@PITEST2.onmicrosoft.com",
"createdTime": "2021-03-30T12:52:39Z"
}
],
"nextLink": null,
"totalCount": 1,
"message": "Query created successfully",
"statusCode": 200,
"dataRedacted": false
}
Glossaire de réponse
Ce tableau fournit les définitions clés des éléments dans la charge utile de requête.
| Paramètre | Description |
|---|---|
| QueryId | Identificateur unique universel (UUID) de la requête créée |
| Nom | Nom convivial donné à la requête dans la charge utile de requête |
| Description | Description donnée lors de la création de la requête |
| Requête | Requête de rapport transmise en tant qu’entrée lors de la création de la requête |
| Type | Paramètre à définir sur userDefined |
| Utilisateur | ID d’utilisateur utilisé pour créer la requête |
| CreatedTime | Heure UTC de création de la requête au format suivant : aaaa-MM-jjThh:mm:ssZ |
| 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, 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é avec succès et de la réception du 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.
Callback URL (URL de rappel)
L’API créer un rapport accepte une URL de rappel. Cette URL sera appelée une fois la génération de rapport réussie. L’URL de rappel doit être accessible publiquement. Outre l’URL, une méthode de rappel peut également être donnée. La méthode de rappel ne peut être GET que ou POST. La méthode par défaut si aucune valeur n’est passée sera POST. Le reportId qui a terminé la génération est toujours repassé pendant le rappel.
Rappel POST : si l’URL passée a été https://www.contosso.com/callback, alors l’URL rappelée sera https://www.contosso.com/callback/<reportID>
Rappel GET : si l’URL passée a été https://www.contosso.com/callback, alors l’URL rappelée sera https://www.contosso.com/callback?reportId=<reportID>
Rapports ExecuteNow
Il existe une configuration pour générer un rapport sans planification. La charge utile de l’API de création de rapport peut accepter un paramètre ExecuteNow, qui met en file d’attente le rapport à générer dès que l’API est appelée. Quand ExecuteNow la valeur est true, les champs : StartTime, RecurrenceCountsont RecurrenceInterval ignorés, car ces rapports ne sont pas planifiés.
Deux champs supplémentaires peuvent être passés lorsque la valeur ExecuteNow est true, QueryStartTime et QueryEndTime. Ces deux champs remplacent le champ TIMESPAN dans la requête. Ces champs ne s’appliquent pas aux rapports planifiés, car les données seront générées en continu pendant une période fixe qui ne change pas.
Syntaxe de la requête
| Méthode | URI de demande |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1/mpn/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>. |
| Content-Type | string | Application/JSON |
Paramètre de chemin
Aucune
Paramètre de requête
Aucune
Exemple de charge utile de requête
{
"ReportName": "Top10_CustomersReport",
"Description": "Top 10 customers by revenue for last month",
"QueryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"StartTime": "2021-03-31T18:41:00Z",
"ExecuteNow": false,
"QueryStartTime": null,
"QueryEndTime": null,
"RecurrenceInterval": 24,
"RecurrenceCount": 100,
"Format": "CSV",
"CallbackUrl": "https://<SampleCallbackUrl>",
"CallbackMethod": "GET"
}
Glossaire
Les définitions clés des éléments de la charge utile de la requête sont décrites ci-dessous :
| Paramètre | Obligatoire | Description | Valeurs autorisées |
|---|---|---|---|
| ReportName | Oui | Nom à assigner au rapport | string |
| Description | Non | Description du rapport créé | string |
| QueryId | Oui | ID de equête de rapport | string |
| StartTime | Oui | Horodatage UTC à partir duquel la génération du rapport commence. Le format doit être : aaaaa-MM-jjTHH:mm:ssZ |
string |
| ExecuteNow | Non | Ce paramètre doit être utilisé pour créer un rapport à exécution unique. StartTime, RecurrenceIntervalet RecurrenceCount sont ignorés si cette valeur est définie sur true. Le rapport est immédiatement exécuté de manière asynchrone. |
true/false |
| 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 aux rapports d’exécution unique qui ont ExecuteNow défini sur true. La définition de ce paramètre remplace les TIMESPAN donnés dans la requête. 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 aux rapports d’exécution unique qui ont ExecuteNow défini sur true. La définition de ce paramètre remplace les TIMESPAN donnés dans la requête. 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 4 et la valeur maximale 2160. |
entier |
| RecurrenceCount | Non | Nombre de rapports à générer. | entier |
| Format | Non | Format du fichier exporté. La valeur par défaut est CSV. |
"CSV"/"TSV" |
| CallbackUrl | Non | URL publiquement accessible pouvant être optionnellement configurée en tant que destination de rappel. | Chaîne (URL http) |
| CallbackMethod | Non | Méthode à utiliser pour le rappel | GET/POST |
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": [
{
"reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
"reportName": "Top10_CustomersReport",
"description": "Top 10 customers by revenue for last month",
"queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
"user": "GAUser@PITEST2.onmicrosoft.com",
"createdTime": "2021-03-30T13:11:58Z",
"modifiedTime": null,
"executeNow": false,
"startTime": "2021-03-31T18:41:00Z",
"reportStatus": "Active",
"recurrenceInterval": 24,
"recurrenceCount": 100,
"callbackUrl": "https://<SampleCallbackUrl>",
"callbackMethod": "GET",
"format": "csv"
}
],
"nextLink": null,
"totalCount": 1,
"message": "Report created successfully",
"statusCode": 200,
"dataRedacted": false
}
Glossaire
Les définitions clés des éléments de la réponse sont décrites ci-dessous :
| Paramètre | Description |
|---|---|
| ReportId | Identificateur unique universel (UUID) du rapport créé |
| ReportName | Nom donné au rapport dans la charge utile de la requête |
| Description | Description donnée lors de la création du rapport |
| QueryId | ID de requête transmis au moment où vous avez créé le rapport |
| Requête | Texte de requête qui sera exécuté pour ce rapport |
| Utilisateur | 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 | ExecuteNow indicateur défini au moment de la création du rapport |
| StartTime | Heure UTC de début d’exécution du rapport au format suivant : aaaa-MM-jjTHH:mm:ssZ |
| ReportStatus | État d’exécution du rapport. Les valeurs possibles sont Paused, Activeet Inactive |
| 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 fournie dans la requête |
| CallbackMethod | CallbackMethod fourni dans la requête |
| Format | Format des fichiers de rapport Les valeurs possibles sont CSV ou TSV. |
| TotalCount | Nombre d’enregistrements dans le tableau Valeur |
| StatusCode | Code de résultat |
| message | Les valeurs possibles sont 200, 400, 401, 403, 500. Message d’état d’’exécution de l’API |
Obtenir l’API d’exécution 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/mpn/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>. |
| Content-Type | string | Application/JSON |
Paramètre de chemin
| Nom du paramètre | Requis | Type | Description |
|---|---|---|---|
| reportId | Oui | string | Filtre pour obtenir les détails d’exécution des rapports avec le reportId fourni dans cet argument. Plusieurs reportIds peuvent être spécifiés en les séparant par un point-virgule « ; » |
Paramètre de requête.
| Nom du paramètre | Requis | Type | Description |
|---|---|---|---|
| executionId | Non | string | Filtre pour obtenir les détails des rapports avec l’executionId indiqué dans cet argument. Plusieurs executionId peuvent être spécifiés en les séparant par un point-virgule « ; ». |
| executionStatus | Non | Chaîne/énumération | Filtre pour obtenir les détails des rapports avec l’executionStatus indiqué dans cet argument. Les valeurs valides sont Pending, Running, Paused, et Completed. La valeur par défaut est Completed. Plusieurs états peuvent être spécifiés en les séparant par un point-virgule « ; ». |
| getLatestExecution | Non | booléen | L’API renvoie les détails de la dernière exécution. Par défaut, ce paramètre a la valeur true. Si vous choisissez de modifier la valeur de ce paramètre par false, alors l’API renvoie les instances d’exécution des 90 derniers jours. |
Exemple de charge utile de requête
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": "906931dc-4f2f-4195-bbb2-d7295c7550d3",
"reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
"recurrenceInterval": 24,
"recurrenceCount": 100,
"callbackUrl": null,
"callbackMethod": null,
"format": "csv",
"executionStatus": "Completed",
"reportLocation": null,
"reportAccessSecureLink": "https://<path to report for download>",
"reportExpiryTime": null,
"reportGeneratedTime": "2021-03-31T18:41:00Z"
}
],
"nextLink": null,
"totalCount": 1,
"message": null,
"statusCode": 200,
"dataRedacted": false
}
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 associée à l’instance d’exécution |
| 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. |
| 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 |
| 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 |
Essayer les API via l’URL de l’API Swagger