Exemples de requêtes OData de l’API Cloud for Sustainability (version préliminaire)
Important
Tout ou partie de cette fonctionnalité est accessible dans le cadre d’une version préliminaire. Le contenu et la fonctionnalité sont susceptibles d’être modifiés.
L’Open Data Protocol (OData) est un protocole d’accès aux données basé sur des protocoles de base comme HTTP. Il utilise des méthodologies communément acceptées comme REST pour le Web. Vous pouvez utiliser différentes bibliothèques et divers outils pour utiliser les services OData.
Pour vous aider à créer vos propres implémentations selon l’API Microsoft Cloud for Sustainability, vous pouvez passer en revue certains exemples de requêtes les plus fréquemment posées.
Modifiez les exemples de requêtes pour les faire fonctionner sur vos environnements cibles :
{serviceRoot}:
https://api.mcfs.microsoft.com/api/v1.0/instances/{instanceId}{instanceId}:Le GUID du Cloud for Sustainability environnement que vous souhaitez interroger, par exemple 20aec369-f1c8-4814-a89d-4d449dd7e8a1.
{serviceRootM365}:
{serviceRoot}/m365{serviceRootAzure}:
{serviceRoot}/enrollments/{enrollmentId}{enrollmentId}:L’ID d’inscription, également appelé ID de compte de facturation. Par exemple : 12345678.
{tenantId}: Microsoft 365 identifiant du locataire.
Remarque
Certaines requêtes d’API contiendront de nombreux résultats et seront réparties sur plusieurs pages. L’API retourne un maximum de 1 000 résultats par page. Si d’autres résultats sont disponibles, l’API renvoie une propriété @odata.nextLink contenant une URL vers la page de résultats suivante.
Entité EnrollmentEmission (pour les émissions Azure)
Représente les données d’émissions pour un compte de facturation, également appelé inscription.
| Property | Type | Remarques |
|---|---|---|
| dateKey | int32 | Date au format aaaammjj ; jj vaut toujours 01. |
| enrollmentId | chaine | Également appelé ID de compte de facturation. |
| orgName | chaine | Identique au Nom TP ou au Nom du parent principal. |
| subscriptionId | chaine | ID de l’abonnement. |
| subscriptionName | chaine | Nom de l’abonnement. |
| azureServiceName | chaine | Nom d’un service Azure, par exemple App Service |
| subService | chaine | Par exemple, Azure Storage ou Azure Compute. |
| azureRegionName | chaine | Région Azure où le service est déployé. |
| portée | chaine | Champ des gaz à effet de serre, par exemple, champ 1, champ 2 ou champ 3. |
| scopeId | int32 | ID du champ. |
| totalEmissions | double | Émissions totales pour l’enregistrement (mtCO2e). |
Exemples de requêtes pour l’entité EnrollmentEmission (pour les émissions Azure)
| Type de requête | Exemple |
|---|---|
| Émissions par inscription | {serviceRootAzure}/émissions |
| Sélectionner certains champs | {serviceRootAzure}/émissions?$Sélectionner=enrollmentId,totalEmissions,scopeId |
| Inclure le nombre | {serviceRootAzure}/émissions?$count=true |
| Limiter le nombre de résultats | {serviceRootAzure}/émissions?$top=100 |
| Pagination | {serviceRootAzure}/émissions?$skip=100&$top=50 |
| Filtrer par scope | {serviceRootAzure}/émissions?$filter=ScopeId eq 1 |
| Filtrer et agréger | {serviceRootAzure}/emissions?$apply=filter(ScopeId eq 1)/aggregate($count comme Count, totalEmissions avec average comme Average, totalEmissions avec sum comme Sum) |
| Filtrer et regrouper | {serviceRootAzure}/émissions?$apply=filter(totalEmissions gt 0,05)/groupby((ScopeId), aggregate($count comme Count))` |
Entité Microsoft365Emission (pour les émissions Microsoft 365)
Représente les émissions du centre de données Microsoft 365 associées aux applications suivantes :
- Exchange Online
- SharePoint
- OneDrive
- Microsoft Teams
- Word
- Excel
- PowerPoint
- Outlook
| Property | Type | Remarques |
|---|---|---|
| dateKey | int32 | Date au format aaaammjj ; jj vaut toujours 01. |
| tenantId | chaine | ID du client. |
| tenantName | chaine | Nom du client. |
| officeRegionName | chaine | Région des centres de données Microsoft 365. |
| portée | chaine | Champ des gaz à effet de serre, par exemple, champ 1, champ 2 ou champ 3. |
| totalEmissions | double | Émissions totales pour l’enregistrement (mtCO2e). |
Exemples de requêtes pour l’entité Microsoft365Emission (pour les émissions Microsoft 365)
| Type de requête | Exemple |
|---|---|
| Émissions pour un locataire | {serviceRootM365}/émissions des locataires |
| Sélectionner certains champs | {serviceRootM365}/émissions?$Sélectionner=tenantId,totalEmissions,portée |
| Inclure le nombre | {serviceRootM365}/tenantemissions?$count=true |
| Limiter le nombre de résultats | {serviceRootM365}/tenantemissions?$top=100 |
| Pagination | {serviceRootM365}/tenantemissions?$skip=100&$top=50 |
| Filtrer par scope | {serviceRootM365}/tenantemissions?$filter=Équation de portée ’FILLMEIN’ |
| Filtrer et agréger | {serviceRootserviceRootM365Azure}/tenantemissions?$apply=filter(scope eq ’FILLMEIN’)/aggregate($count comme Count, totalEmissions avec average comme Average, totalEmissions avec sum comme Sum) |
| Filtrer et regrouper | {serviceRootM365}/tenantemissions?$apply=filter(totalEmissions gt 0.05)/groupby((Portée), agrégat($count comme Count))` |
Entité EnrollmentUsage (pour les émissions Azure)
Représente un facteur d’utilisation calculé des ressources cloud Microsoft.
| Property | Type | Remarques |
|---|---|---|
| dateKey | int32 | Date au format aaaammjj ; jj vaut toujours 01. |
| enrollmentId | chaine | Également appelé ID de compte de facturation. |
| orgName | chaine | Identique au nom TP ou au nom du parent principal. |
| subscriptionId | chaine | ID de l’abonnement. |
| subscriptionName | chaine | Nom de l’abonnement. |
| subService | chaine | Par exemple, Azure Storage ou Azure Compute. |
| azureRegionName | chaine | Région Azure où le service est déployé. |
| utilisation active | double | Utilisation totale de l’enregistrement. N’a pas l’unité, car elle représente une utilisation normalisée du service dans la région spécifiée. |
Pour plus d’informations sur la méthodologie de calcul de Microsoft, accédez à Méthodologie de calcul de l’API Microsoft Cloud for Sustainability.|
Exemples de requêtes pour l’entité EnrollmentUsage
| Type de requête | Exemple | Remarque |
|---|---|---|
| Toutes les données d’utilisation | {serviceRootAzure}/usage | |
| Utilisation totale par mois par abonnement | {serviceRootAzure}/usage?$apply=groupby((SubscriptionName,DateKey),aggregate(utilisation avec la somme comme TotalUsage))&$orderby=SubscriptionName,DateKey |
Entité EnrollmentProjection (pour les émissions Azure)
Représente les émissions projetées pour le reste de l’année civile, sur la base d’une moyenne mobile des cinq mois précédents. Destiné aux visualisations annualisées.
| Property | Type | Remarques |
|---|---|---|
| dateKey | int32 | Date au format aaaammjj ; jj vaut toujours 01. |
| enrollmentId | chaine | Également appelé ID de compte de facturation. |
| actualEmissions | double | Inclus uniquement pour les dates passées (mtCO2e). |
| projectedEmissions | double | Basé sur un moyenne mobile des cinq mois précédents ou moins sur la base des données réelles disponibles pour l’année en cours (mtCO2e). |
| actualUsage | double | Uniquement inclus pour les dates passées. |
| projectedUsage | double | Basé sur un moyenne mobile des cinq mois précédents ou moins sur la base des données réelles disponibles pour l’année en cours. |
Exemples de requêtes pour l’entité EnrollmentProjection (pour les émissions Azure)
| Type de requête | Exemple | Remarque |
|---|---|---|
| Projections passées 7-2022 | {serviceRootAzure}/projections?$filter=dateKey gt 20220701 | |
| Toutes les projections pour l’année | {serviceRootAzure}/projections |
Important
L’API Microsoft Cloud for Sustainability est actuellement en version préliminaire et elle est susceptible d’être modifiée. Vos chiffres d’émissions historiques peuvent également être mis à jour à mesure que Microsoft améliore l’exactitude et l’exhaustivité des données.
FAQ
Comment Microsoft calcule-t-il les émissions et l’utilisation ?
Pour plus d’informations sur la méthodologie de calcul de Microsoft, accédez à Méthodologie de calcul de l’API Microsoft Cloud for Sustainability.
Qu’est-ce que Rownum ?
L’API utilise rownum pour une pagination cohérente. La valeur est susceptible de changer, votre application ne devrait donc pas en dépendre.
Qu’est-ce qu’un ID d’inscription ?
Un ID d’inscription fait référence à un ID de compte de facturation. Trouvez votre identifiant d’inscription et votre identifiant de compte de facturation dans le portail Azure.
Comment puis-je obtenir un jeton d’autorisation pour mon environnement cible ?
L’API nécessite un jeton d’autorisation OAuth. Nous vous recommandons d’utiliser la Bibliothèque d’authentification Microsoft (MSAL).
Pouvez-vous fournir plus d’informations sur l’utilisation de nextLink pour la pagination ?
L’API renvoie une propriété @odata.nextLink s’il y a plus de résultats que ceux renvoyés dans la réponse actuelle. Votre application doit effectuer un autre GET sur ce lien suivant pour obtenir la page de résultats suivante. La dernière page ne contient pas de nextLink.
Explorez cet exemple de code pour plus de détails sur la pagination avec une bibliothèque cliente OData.
Informations associées
- Présentation de l’API Cloud for Sustainability
- Microsoft Cloud for Sustainability Méthodologie de calcul API
- Microsoft Cloud for Sustainability API
