Présentation de l’API Cloud for Sustainability (version préliminaire)

Microsoft Cloud for Sustainability fournit des API pour accéder aux données d’émissions liées à votre utilisation d’Azure et de Microsoft 365.

Une comptabilisation précise du carbone nécessite de bonnes informations de la part des partenaires, des vendeurs et des fournisseurs. Les API Cloud for Sustainability vous offrent une transparence sur les émissions de carbone générées par votre utilisation d’Azure et de Microsoft 365. La comptabilité carbone de Microsoft s’étend aux trois périmètres d’émissions avec une méthodologie validée par un tiers. Elle utilise une comptabilité carbone cohérente et précise pour quantifier l’effet de Azure et Microsoft 365 sur l’empreinte environnementale des clients.

Les détails de ces API sont répertoriés dans la Référence des API Microsoft Cloud for Sustainability. Ils comprennent des informations supplémentaires sur les opérations, les paramètres et les réponses.

• Démarrer avec les API Cloud for Sustainability
• Exemples de requêtes
• Attribuer des autorisations
• Gérer les instances
• Afficher l’utilisation de l’API
• FAQ

Premiers pas avec les API Cloud for Sustainability

Commencez avec les API en procédant comme suit :

• Examiner les comptes pris en charge
• connectez-vous et créez une instance
• Configurer les sources de données et activer les API
• Essayez les API

Comptes pris en charge

• Azure : Microsoft Cloud for Sustainability Les API pour Azure prennent en charge les comptes EA Direct, MCA et MPA avec facturation directe Relations avec Microsoft. Les clients qui achètent Azure auprès d’un fournisseur de solutions cloud (CSP) ne sont pas pris en charge et doivent travailler directement avec leur CSP pour en savoir plus sur leurs émissions cloud. Les comptes hérités, les comptes basés sur des crédits, les inscriptions en Chine et les comptes Azure pour le secteur public ne sont pas pris en charge. Pour vérifier votre type de compte, accédez à Vérifier le type de votre compte.

  Remarque

  Azure Avantage hybride l’utilisation n’est actuellement pas capturée ou reflétée dans les émissions.

• Microsoft 365: Microsoft Cloud for Sustainability API pour Microsoft 365 soutenir les abonnements professionnels, d’entreprise ou éducatifs pour Microsoft 365 ou Office 365. Les déploiements cloud nationaux/régionaux, y compris, mais sans s’y limiter, les clouds du gouvernement américain de Microsoft et Office 365 exploité par 21Vianet ne sont pas pris en charge.

Connectez-vous et créez une instance

Une fois que vous avez accès aux API Microsoft Cloud for Sustainability de Microsoft, connectez-vous avec vos identifiants Azure Microsoft Entra ID.

Vous devez créer une instance pour accéder aux API Microsoft Cloud for Sustainability. En créant l’instance, vous devenez l’administrateur de cette instance. Le Administrateur de l’instance peut ajouter des utilisateurs, des groupes et des applications à l’instance.

Regardez cette vidéo pour un aperçu de l’utilisation des API et du portail Cloud for Sustainability :

Configurez les sources de données et activez les API

1. Dans l’onglet Sources de données, activez la connexion pour connecter les données d’émissions Azure ou Microsoft 365. Assurez-vous que l’état est Disponible avant d’utiliser les API. Cette action active les données d’émissions liées à toutes les inscriptions ou tous les comptes de facturation auxquels vous avez accès. Si vous n’avez accès à aucune donnée sur les émissions, continuez avec les données de démonstration uniquement.

   Remarque

   Les données d’émissions Microsoft 365 peuvent prendre jusqu’à 48 heures pour devenir disponibles une fois la source de données activée. La désactivation de la source de données Microsoft 365 supprimera définitivement les données historiques Microsoft 365 sur les émissions.

   

2. Sélectionnez l’onglet Gestion des API, puis sélectionnez Activer.

   L’activation de l’API génère des clés d’API principales et secondaires que votre instance peut utiliser dans les requêtes d’API. Pour regénérer les clés, sélectionnez . Pour copier les clés, sélectionnez .

Vous souhaitez configurer une application pour appeler l’API Cloud for Sustainability ? Visionner cette version de démonstration :

Essayer les API

Dans l’onglet Gestion des API, sélectionnez Essayer l’API pour explorer les API OData et d’exportation. Interrogez les données relatives à vos émissions de manière interactive en connectant les API OData à faible latence à vos tableaux de bord. Ou bien, faites votre propre traitement en bloc en transférant vos données d’émissions directement dans votre Azure Data Lake Storage à l’aide des API d’exportation. Un portail des développeurs s’ouvre dans un nouvel onglet où vous pouvez explorer les schémas de demande et de réponse et effectuer des demandes en direct sur les API Microsoft Cloud for Sustainability.

Essayer les API OData

1. Dans le volet de navigation de gauche, assurez-vous que Regrouper par balise est activé et sélectionnez le regroupement OData pour examiner les API OData d’Azure et de Microsoft 365.

2. Pour faire une demande en direct, sélectionnez Essayer. Renseignez tous les champs obligatoires :

   • Autorisation : Jeton d’autorisation renseigné automatiquement
   • Clé d’abonnement :Rempli automatiquement avec la clé API du Gestion des API languette
   • identifiant d’inscription :Votre identifiant d’inscription, également appelé identifiant de compte de facturation. Azure uniquement. Si vous n’avez pas accès à une inscription, vous pouvez explorer l’API à l’aide des données de démonstration en saisissant demodata dans ce champ.
   • instanceId : Trouvé dans l’URL de pour le Microsoft Cloud for Sustainability Portail API
   • identifiant du locataire : Microsoft 365 identifiant du locataire.

   

3. Ajoutez tous les paramètres de requête nécessaires. Faites défiler vers le bas du volet latéral et sélectionnez Envoyer. La réponse HTTP s’affiche en bas du volet.

Regardez cette vidéo pour en savoir plus sur les API Cloud for Sustainability avec OData :

Essayer les API d’exportation

1. Dans le volet de navigation de gauche, assurez-vous que Regrouper par balise est activé et sélectionnez le regroupement Exporter pour commencer à exporter les données sur les émissions et l’utilisation dans votre lac de données. Sélectionnez RunExportJob.

2. Sélectionnez Essayer. Saisissez tous les champs obligatoires et sélectionnez Envoyer.

   • Autorisation : Jeton d’autorisation renseigné automatiquement
   • Clé d’abonnement :Rempli automatiquement avec la clé API du Gestion des API languette
   • instanceId : Trouvé dans l’URL de pour le Microsoft Cloud for Sustainability Portail API
   • exportJobType : Sélectionner Azure ou Microsoft 365 pour désigner le source de données pour les données d’émissions et d’utilisation à exporter.
   • démodonnées :Saisissez "true" si vous souhaitez explorer cette fonctionnalité en exportant des données de démonstration.

3. Après avoir sélectionné Envoyer, faites défiler vers le bas pour voir la réponse HTTP. Si vous exportez des données Azure, la réponse répertorie les ID d’inscription pour les données exportées. Si vous n’avez pas accès aux données Azure ou Microsoft 365, cette opération échoue. Assurez-vous d’avoir correctement configuré vos sources de données.

   Initialement, la réponse indique que la tâche a le statut NotStarted. L’exécution de la tâche d’exportation nécessite 2 à 3 minutes et vous pouvez utiliser le jobID pour vérifier le statut de l’exportation à l’aide de l’API ExportJobStatus. Assurez-vous que la tâche a réussi, ce qui indique que les données exportées sont désormais disponibles dans le stockage blob intermédiaire.

   Vous pouvez utiliser LatestExportJob pour consulter les informations concernant votre dernière tâche d’exportation.

   Vous pouvez utiliser l’API ExportJobs pour consulter les informations concernant vos rapports historiques.

4. Utilisez l’API ExportLocation pour obtenir l’URL SAS. L’URL SAS expirera après une heure. Copiez l’URL SAS pour accéder aux données exportées à partir du stockage blob intermédiaire.

5. Les données sont définies pour expirer 28 jours après l’exécution de la tâche d’exportation et doivent être copiées avant l’expiration. Sinon, les données sont supprimées de l’emplacement intermédiaire. Les utilisateurs peuvent réexécuter une tâche d’exportation à tout moment pour obtenir un autre lot de données avec une expiration de 28 jours et incluant l’ensemble de données le plus récent. Vous pouvez accéder aux données exportées de plusieurs façons.

   1. Explorateur de stockage Azure

      Installez et ouvrez l’Explorateur de stockage Azure. Sélectionnez le bouton Ouvrir la boîte de dialogue de connexion, puis sélectionnez Conteneur ou répertoire ADLS Gen2. Sélectionnez URL de signature d’accès partagé (SAS) et collez l’URL SAS de l’étape 4 dans l’entrée URL SAS du conteneur blob ou du répertoire. Sélectionnez Suivant, puis sélectionnez Connecter. Vous devez localiser ou créer un conteneur dans un compte de stockage nouveau ou existant à utiliser pour stocker ces données exportées. Copiez les données Azure ou Microsoft 365 du stockage blob intermédiaire et collez-les dans le conteneur de votre choix.

   2. Utilisez azcopy. À l’aide de l’URL SAS de l’étape 4 et de l’URL du compte de stockage où vous stockez vos émissions exportées (URL de destination), exécutez la commande azcopy.exe :

      • azcopy login
      • azcopy list <SAS URL>
      • azcopy cp <SAS URL> <destination URL>

   3. Script Spark

      Utilisez mssparkutils dans Microsoft Fabric ou Synapse. Vous pouvez choisir d’utiliser d’autres bibliothèques et environnements.

      import subprocess
      from notebookutils import mssparkutils
      
      result = subprocess.run(['pip', 'install', 'azure-storage-blob'], capture_output=True)
      
      # replace with SAS URI from API request
      source_sas_url = 'https://<account_name>.blob.windows.net/<container_name>/<path>?<sas_token>'
      
      start_index = source_sas_url.find('https://') + len('https://')
      end_index = source_sas_url.find('.blob', start_index)
      account_name = source_sas_url[start_index:end_index]
      split = source_sas_url.split('?', 1)
      domain_path = split[0]
      sas_token = split[1]
      container_name = domain_path.split('/')[3]
      
      source_mount_point = '/src'
      destination_mount_point = '/dest'
      
      mssparkutils.fs.unmount(source_mount_point)
      mssparkutils.fs.mount(
          f'abfss://{container_name}@{account_name}.blob.core.windows.net',
          source_mount_point,
          { 'sasToken': sas_token })
      
      mssparkutils.fs.unmount(destination_mount_point)
      mssparkutils.fs.mount( 
          'abfss://<destinationPath>', # replace with destination connection string
          destination_mount_point)
      
      mssparkutils.fs.cp(src_path, dest_path, True)
      

Exemples de requêtes

Pour une courte liste d’exemples de requêtes OData à utiliser avec les API, accédez à Exemples de requêtes OData.

Attribuer des autorisations

L’accès aux API Microsoft Cloud for Sustainability est limité aux utilisateurs de votre organisation qu’un administrateur d’une instance ajoute à l’application. Un utilisateur peut être un utilisateur unique, un groupe ou une application. Les comptes invités ne sont pas pris en charge. Il existe trois types de rôles que vous pouvez attribuer :

• Téléspectateur :Peut afficher toutes les pages dans le Microsoft Cloud for Sustainability API.
• collaborateur :Peut interagir avec toutes les pages du Microsoft Cloud for Sustainability Portail API. Impossible d’ajouter ou de supprimer des utilisateurs.
• Administrateur :Toutes les autorisations disponibles, y compris la possibilité d’ajouter ou de supprimer des utilisateurs.

Pour ajouter des utilisateurs, des groupes ou des applications en tant qu’administrateur :

1. Sélectionnez l’onglet Autorisations, puis sélectionnez Ajouter des utilisateurs.
2. Utilisez le champ Rechercher pour trouver l’utilisateur, l’application ou le groupe Microsoft Entra ID que vous souhaitez ajouter.
3. Sélectionnez une attribution de rôle, puis sélectionnez Enregistrer.

Gérer les instances

Accédez à l’icône d’instance pour trouver une liste de toutes les instances, créer des instances ou supprimer des instances.

Afficher l’utilisation de l’API

Afficher des détails sur l’utilisation de l’API en temps réel.

1. Accédez à l’onglet Gestion des API, puis sélectionnez Utilisation.
2. Sélectionner un délai d’exécution pour afficher les données.

La page Utilisation de l’API contient trois sections :

• Appels API :Un graphique qui visualise le nombre agrégé d’appels à l’API dans le délai d’exécution sélectionné.
• Transfert de données :Un graphique qui montre la quantité de données qui ont été transférées via l’API dans le délai d’exécution sélectionné.
• Opérations :Un tableau avec des lignes pour chaque opération API disponible et des détails sur l’utilisation des opérations.

FAQ

Comment Microsoft calcule-t-il les émissions de carbone du cloud mises à disposition par l’API ?

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.

Où puis-je en savoir plus sur l’écriture de requêtes avec OData ?

Pour en savoir plus sur OData, accédez à Présentation des options de requête.

Où sont stockées les données utilisées pour produire ce rapport ?

Les données sont stockées aux États-Unis.

Pourquoi ne puis-je pas voir les données d’émissions du mois précédent ?

Les données d’émissions pour un mois donné sont disponibles au plus tard le 14e jour après la fin du mois en question (y compris les jours non ouvrables).

Je ne peux pas créer une instance. Pourquoi ?

Vous essayez peut-être d’accéder au portail API Cloud for Sustainability avec un compte associé à un ID de locataire hôte différent de celui fourni sur le formulaire d’intégration. Cette situation peut se produire lorsque vous utilisez un compte invité. Les comptes invités ne sont pas pris en charge. Si vous souhaitez que nous intégrions un autre client, renvoyez le formulaire d’intégration.

J’ai un ID client différent pour Microsoft 365 et Azure. Puis-je toujours utiliser l’API Microsoft Cloud for Sustainability ?

Vous pouvez toujours accéder aux API, mais le portail ne prend pas en charge plusieurs clients par instance. Vous devez intégrer ces clients aux API séparément.

Comment configurer une application pour appeler l’API Microsoft Cloud for Sustainability ?

Vous souhaitez configurer une application pour appeler l’API Cloud for Sustainability ? Visionner cette version de démonstration :

Sur le portail Azure, accédez à votre Microsoft Entra ID, sélectionnez Inscriptions d’applications, puis + Nouvelle inscription. Dans la nouvelle page d’inscription, attribuez un nom à votre inscription d’application, personnalisez les options selon vos besoins, puis sélectionnez Inscrire. Accédez à la page Microsoft Entra ID, sélectionnez le panneau Applications d’entreprise, définissez Type d’application sur Applications Microsoft et recherchez par nom d’application MCFS SDS. Le paramètre ApplicationId que vous avez transmis dans la commande New-AzADServicePrincipal requise lors de l’intégration est l’ApplicationId du Microsoft Cloud for Sustainability API (00001111-aaaa-2222-bbbb-3333cccc4444) avec lequel vous avez créé une instance (application d’entreprise) du Microsoft Cloud for Sustainability Enregistrement de l’application API dans votre propre locataire.

Une fois cela en place, vous pouvez maintenant accéder à la page de votre inscription d’application et sélectionner le panneau Autorisations de l’API. Pour ajouter une autorisation permettant à votre inscription d’application d’appeler l’API Microsoft Cloud for Sustainability, sélectionnez + Ajouter une autorisation, suivi de l’option API utilisées par mon organisation. Recherchez ensuite l’ApplicationId de l’ Microsoft Cloud for Sustainability API (00001111-aaaa-2222-bbbb-3333cccc4444), Sélectionner MCFS SDS, puis Sélectionner l’autorisation App.Emissions.Read de la lame Autorisations d’application .

Cette autorisation de type d’application doit obtenir le consentement de l’administrateur en sélectionnant Accorder le consentement de l’administrateur pour {your-tenant}.

Enfin, visitez la page d’accueil de l’API Microsoft Cloud for Sustainability, accédez au panneau Autorisations, puis sélectionnez + Ajouter. Dans le volet latéral qui apparaît, choisissez Lecteur comme rôle dans l’entrée Utilisateur, Groupe ou Application et procédez à la recherche de votre inscription d’application. Sélectionnez Enregistrer.

J’obtiens un jeton d’accès pour mon application, quelle est l’URL de la ressource ?

00001111-aaaa-2222-bbbb-3333cccc4444/.default

Combien de données historiques sont disponibles ?

• Azure : Les données d’utilisation et d’émissions couvrent les cinq dernières années de données associées à l’inscription.
• Microsoft 365:Les données sur les émissions couvrent les 12 derniers mois de données associées à l’abonnement. Microsoft 365

Exclusion de responsabilité

L’API Microsoft Cloud for Sustainability (version préliminaire) est basée sur les normes industrielles pour le calcul du carbone des serveurs. Il fournit des estimations générales pour aider les organisations à mieux comprendre les émissions de carbone de l’infrastructure informatique associées à l’utilisation des services cloud Azure. Les résultats, interprétations et conclusions présentés avec l’API Microsoft Cloud for Sustainability (version préliminaire), y compris les calculs, ne constituent pas des conseils ou des recommandations spécifiques. Les informations et opinions exprimées peuvent changer sans préavis. L’API Microsoft Cloud for Sustainability (version préliminaire) est fournie en l’état, sans aucune déclaration ou garantie d’aucune sorte, expresse ou implicite, y compris, sans s’y limiter, les déclarations ou approbations concernant l’utilisation, les résultats ou les performances de l’API Microsoft Cloud for Sustainability (version préliminaire), sa pertinence, sa précision, sa fiabilité ou son exactitude. Vous assumez tous les risques liés à l’utilisation de l’API Microsoft Cloud for Sustainability (version préliminaire). Microsoft n’assume aucune responsabilité pour l’utilisation de l’API Microsoft Cloud for Sustainability (version préliminaire). En aucun cas Microsoft ne sera responsable d’autres dommages directs ou indirects, y compris toute perte de bénéfices ou d’économies, ou tout dommage accessoire ou consécutif découlant de tout défaut, ou de l’utilisation ou de l’impossibilité d’utiliser l’API Microsoft Cloud for Sustainability (version préliminaire), même si Microsoft a été informé de la possibilité de tels dommages.

Informations associées

Microsoft Cloud for Sustainability Exemples de requêtes API OData
Microsoft Cloud for Sustainability Méthodologie de calcul API
Microsoft Cloud for Sustainability API