Panoramica dell'API Cloud for Sustainability (anteprima)

Microsoft Cloud for Sustainability fornisce API per accedere ai dati sulle emissioni relativi all'utilizzo di Azure e Microsoft 365.

Una contabilizzazione accurata del carbonio richiede informazioni precise da parte di partner, venditori e fornitori. Le API di Cloud per la sostenibilità ti offrono trasparenza sulle emissioni di carbonio generate dall'utilizzo di Azure e Microsoft 365. La contabilizzazione di carbonio di Microsoft si estende a tutti e tre gli ambiti delle emissioni con una metodologia convalidata da terze parti. La metodologia utilizza una contabilizzazione del carbonio coerente e accurata per quantificare l'effetto di Azure e Microsoft 365 sull'impronta ambientale dei clienti.

I dettagli dell'API sono elencati nel Riferimento API Microsoft Cloud for Sustainability. Includono informazioni aggiuntive su operazioni, parametri e risposte.

• Introduzione alle API Cloud for Sustainability
• Esempi di query
• Assegnare autorizzazioni
• Gestire le istanze
• Visualizzare l'utilizzo delle API
• Domande frequenti

Introduzione alle API Cloud for Sustainability

Inizia a usare le API mediante le procedure seguenti:

• Esaminare gli account supportati
• Eseguire l'accesso e creare un'istanza
• Configurare le origini dati e abilitare le API
• Provare le API

Account supportati

• Azure: le API Microsoft Cloud for Sustainability per Azure supportano gli account EA Direct, MCA e MPA con relazioni di fatturazione diretta con Microsoft. I clienti che acquistano Azure da un provider di soluzioni cloud (CSP) non sono supportati e devono contattare direttamente il proprio CSP per ottenere informazioni sulle proprie emissioni cloud. Gli account legacy, gli account basati su crediti, le registrazioni in Cina e gli account di Azure per enti pubblici non sono supportati. Per verificare il tipo di account, vai a Controllare il tipo di account.

  Nota

  L'utilizzo di Vantaggio Azure Hybrid non è attualmente acquisito o riflesso nelle emissioni.

• Microsoft 365 : le API Microsoft Cloud for Sustainability per Microsoft 365 supportano sottoscrizioni Business, Enterprise o Education per Microsoft 365 o Office 365. Le distribuzioni di cloud nazionali/regionali, inclusi, a titolo esemplificativo ma non esaustivo, i cloud del governo degli Stati Uniti di Microsoft e Office 365 gestite da 21Vianet.

Effettuare l'accesso e creare un'istanza

Dopo aver ricevuto l'accesso alle API Microsoft Cloud for Sustainability da Microsoft, accedi con le credenziali di Azure Microsoft Entra ID.

Devi creare un'istanza per accedere alle API Microsoft Cloud for Sustainability. In seguito alla creazione dell'istanza, ne diventi l'amministratore. L'amministratore dell'istanza può aggiungere utenti, gruppi e applicazioni all'istanza.

Guarda questo video per una panoramica sull'utilizzo delle API e del portale di Cloud for Sustainability:

Configurare le origini dati e abilitare le API

1. Nella scheda Origini dati, attiva la connessione per connettere i dati sulle emissioni di Azure o Microsoft 365. Assicurati che lo stato sia Disponibile prima di usare le API. Questa azione abilita i dati sulle emissioni relativi a tutte le registrazioni o a tutti gli account di fatturazione a cui hai accesso. Se non hai accesso ai dati sulle emissioni, procedi solo con i dati dimostrativi.

   Nota

   Potrebbero essere necessarie fino a 48 ore prima che i dati sulle emissioni di Microsoft 365 diventino disponibili dopo aver abilitato l'origine dati. La disattivazione dell'origine dati di Microsoft 365 eliminerà definitivamente i dati storici sulle emissioni di Microsoft 365.

   

2. Seleziona la scheda Gestione API, quindi seleziona Abilita.

   L'abilitazione dell'API genera chiavi API primarie e secondarie per l'istanza da usare nelle richieste API. Per rigenerare le chiavi, seleziona . Per copiare le chiavi, seleziona .

Ti interessa configurare un'app per chiamare l'API Cloud for Sustainability? Guarda questa demo:

Provare le API

Nella scheda Gestione API, seleziona Prova API per esplorare OData ed esportare le API. Interroga in modo interattivo i tuoi dati sulle emissioni collegando le API OData a bassa latenza ai tuoi dashboard. Oppure, esegui la tua elaborazione in blocco trasferendo i dati sulle emissioni direttamente in Azure Data Lake Storage utilizzando le API di esportazione. Un portale per sviluppatori si apre in una nuova scheda in cui puoi esplorare gli schemi di richiesta e risposta ed effettuare richieste in tempo reale per le API Microsoft Cloud for Sustainability.

Provare le API OData

1. Nella barra di navigazione a sinistra, assicurati che Raggruppa per tag sia abilitato e seleziona il raggruppamento OData per esaminare le API OData di Azure e Microsoft 365.

2. Per effettuare una richiesta in tempo reale, seleziona Prova. Inmmettere un valore in tutti i campi richiesti:

   • Autorizzazione: token di autorizzazione popolato automaticamente
   • Chiave di sottoscrizione: popolata automaticamente con la chiave API nella scheda Gestione API
   • enrollmentId: l'ID registrazione, noto anche come ID account di fatturazione. Solo Azure. Se non hai accesso a una registrazione, puoi esplorare l'API utilizzando i dati demo inserendo demodata in questo campo.
   • instanceId: nell'URL del portale dell'API Microsoft Cloud for Sustainability
   • tenantId: l'ID tenant di Microsoft 365.

   

3. Aggiungi tutti i parametri di query necessari. Scorri fino alla fine del riquadro laterale e seleziona Invia. La risposta HTTP viene visualizzata nella parte inferiore del riquadro.

Guarda questo video per saperne di più sulle API di Cloud for Sustainability con OData:

Provare le API di esportazione

1. Sulla barra di navigazione a sinistra, assicurati che Raggruppa per tag sia abilitato e seleziona il raggruppamento Esporta per iniziare a esportare le emissioni e l'utilizzo dati nel tuo data lake. Seleziona RunExportJob.

2. Seleziona Prova. Inserisci tutti i campi obbligatori e seleziona Invia.

   • Autorizzazione: token di autorizzazione popolato automaticamente
   • Chiave di sottoscrizione: popolata automaticamente con la chiave API nella scheda Gestione API
   • instanceId: nell'URL del portale dell'API Microsoft Cloud for Sustainability
   • exportJobType: seleziona Azure o Microsoft 365 per designare l'origine dati per i dati sulle emissioni e sull'utilizzo da esportare.
   • demodata: inserisci "true" se desideri esplorare questa funzionalità esportando i dati demo.

3. Dopo aver selezionato Invia, scorri verso il basso per visualizzare la risposta HTTP. Se si esportano dati di Azure, la risposta elenca gli ID di registrazione per i dati esportati. Se non hai accesso ai dati di Azure o Microsoft 365, questa operazione non riesce. Assicurati di configurare correttamente le tue origini dati.

   Inizialmente, la risposta indica che il processo è NotStarted. Il processo di esportazione richiede 2-3 minuti per essere completato e puoi utilizzare il jobID per verificare lo stato dell'esportazione utilizzando l'API ExportJobStatus. Verificare che il processo sia riuscito, il che indica che i dati esportati sono ora disponibili nell'archivio BLOB di staging.

   Puoi utilizzare LatestExportJob per rivedere le informazioni relative al tuo ultimo processo di esportazione.

   Puoi utilizzare l'API ExportJobs per rivedere le informazioni relative alle esportazioni storiche.

4. Utilizza l'API ExportLocation per ottenere l'URL SAS. L'URL SAS scadrà dopo un'ora. Copia l'URL SAS per accedere ai dati esportati dall'archivio BLOB di gestione temporanea.

5. I dati scadono 28 giorni dopo l'esecuzione del processo di esportazione e devono essere copiati prima della scadenza. In caso contrario, i dati vengono eliminati dalla posizione di gestione temporanea. Gli utenti possono eseguire nuovamente un processo di esportazione in qualsiasi momento per ottenere un altro batch di dati con una scadenza di 28 giorni e che includa il set di dati più recente. Ci sono alcuni modi per accedere ai dati esportati.

   1. Azure Storage Explorer

      Installa e apri Azure Storage Explorer. Seleziona il pulsante Apri finestra di dialogo di connessione quindi seleziona Contenitore o directory ADLS Gen2. Seleziona URL della firma di accesso condiviso (SAS) e incolla l'URL SAS del passaggio 4 in URL SAS del contenitore BLOB o della directory. Seleziona Avanti e quindi Connetti. È necessario individuare o creare un contenitore in un account di archiviazione nuovo o esistente da usare per archiviare questi dati esportati. Copia i dati di Azure o Microsoft 365 dall'archivio BLOB di gestione temporanea e incollali nel contenitore che preferisci.

   2. Utilizza azcopy. Utilizzando l'URL SAS del passaggio 4 e l'URL dell'account di archiviazione in cui si archiviano le emissioni esportate (URL di destinazione), esegui il comando azcopy.exe:

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

   3. Script Spark

      Usa mssparkutils in Microsoft Fabric o Synapse. Puoi scegliere di utilizzare raccolte e ambienti alternativi.

      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)
      

Query di esempio

Per un breve elenco di esempi di query OData da usare con le API, vedi Esempi di query OData.

Assegnare autorizzazioni

L'accesso alle API Microsoft Cloud for Sustainability è limitato agli utenti della tua organizzazione che un amministratore di un'istanza aggiunge all'applicazione. Un utente può essere un singolo utente, gruppo o applicazione. Gli account guest non sono supportati. Esistono tre tipi di provider di ruoli che puoi assegnare:

• Visualizzatore: può visualizzare tutte le pagine nell'API Microsoft Cloud for Sustainability.
• Collaboratore: può interagire con tutte le pagine del portale delle API Microsoft Cloud for Sustainability. Non è possibile aggiungere o rimuovere utenti.
• Amministratore: tutte le autorizzazioni disponibili, inclusa la possibilità di aggiungere o rimuovere utenti.

Per aggiungere utenti, gruppi o app come amministratore:

1. Seleziona la scheda Autorizzazioni e quindi Aggiungi utenti.
2. Utilizza il campo Cerca per trovare il gruppo, l'applicazione o l'utente Microsoft Entra ID che intendi aggiungere.
3. Seleziona un'assegnazione di ruolo e quindi Salva.

Gestire le istanze

Vai all'icona dell'istanza per trovare un elenco di tutte le istanze, creare istanze o rimuovere istanze.

Visualizzare l'utilizzo dell'API

Visualizza i dettagli sull'utilizzo dell'API in tempo reale.

1. Accedi alla scheda Gestione API, quindi seleziona Utilizzo.
2. Seleziona un intervallo di tempo da visualizzare.

La pagina Utilizzo API contiene tre sezioni:

• Chiamate API: un grafico che visualizza il numero aggregato di chiamate all'API nel intervallo di tempo selezionato.
• Trasferimento dei dati: un grafico che mostra la quantità di dati trasferiti tramite l'API nella intervallo di tempo selezionata.
• Operazioni: una tabella con righe per ogni operazione API disponibile e dettagli sull'utilizzo delle operazioni.

Domande frequenti

In che modo Microsoft calcola le emissioni di carbonio del cloud rese disponibili mediante l'API?

Per informazioni sulla metodologia di calcolo di Microsoft, vai a Metodologia di calcolo dell'API di Microsoft Cloud for Sustainability.

Dove posso trovare ulteriori informazioni sulla scrittura di query con OData?

Per ulteriori informazioni su OData, vai a Panoramica delle opzioni di query.

Dove sono archiviati i dati usati per generare questo report?

I data sono archiviati negli Stati Uniti.

Perché non riesco a visualizzare i dati sulle emissioni del mese precedente?

I dati sulle emissioni per un dato mese saranno disponibili entro il 14° giorno dopo la fine di quel mese compresi i giorni non lavorativi.

Non riesco a creare un'istanza. Perché?

Potresti provare ad accedere al portale API di Cloud for Sustainability con un account associato a un ID tenant host diverso da quello fornito nel modulo di onboarding. Questa situazione può verificarsi quando utilizzi un account ospite. Gli account guest non sono supportati. Se desideri eseguire l'onboarding di un altro tenant, invia nuovamente il modulo di onboarding.

Ho un ID tenant diverso per Microsoft 365 e Azure. Posso sempre utilizzare l'API Microsoft Cloud for Sustainability?

Puoi comunque accedere alle API, ma il portale non supporta più i tenant per istanza. Dovrai eseguire l'onboarding di questi tenant nelle API separatamente.

Come si configura un'app per chiamare l'API Microsoft Cloud for Sustainability?

Ti interessa configurare un'app per chiamare l'API Cloud for Sustainability? Guarda questa demo:

Nel portale di Azure, vai ad Microsoft Entra ID, seleziona Registrazioni app e quindi + Nuova registrazione. Nella nuova pagina di registrazione, assegna un nome alla registrazione dell'app, personalizza le opzioni in base alle tue esigenze, quindi seleziona Registra. Vai alla pagina Microsoft Entra ID, seleziona il pannello Applicazioni aziendali imposta Tipo di applicazione su be Applicazioni Microsoft e cerca in base al nome dell'applicazione MCFS SDS. Il parametro ApplicationId passato nel comando New-AzADServicePrincipal richiesto durante l'onboarding è ApplicationId dell'API Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9) con cui hai creato un'istanza (applicazione aziendale) della registrazione dell'app API Microsoft Cloud for Sustainability nel tuo tenant.

Ora puoi andare alla pagina di registrazione dell'app e selezionare il pannello Autorizzazioni API. Per aggiungere l'autorizzazione alla registrazione dell'app per poter chiamare l'API Microsoft Cloud for Sustainability, seleziona + Aggiungi un'autorizzazione, seguito dall'opzione API utilizzate dalla mia organizzazione. Quindi, cerca l'ApplicationId dell'API Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9), seleziona SDS MCFS, quindi seleziona l'autorizzazione App.Emissions.Read del pannello Autorizzazioni dell'applicazione.

Questo tipo di autorizzazione per l'applicazione deve ricevere il consenso dell'amministratore selezionando Concedi il consenso dell'amministratore per {your-tenant}.

Infine, visita la home page dell'API Microsoft Cloud for Sustainability, vai al pannello Autorizzazioni e seleziona + Aggiungi. Nel pannello laterale che appare, scegli Visualizzatore come ruolo nell'utente, nel gruppo o nell'applicazione e procedi alla ricerca della registrazione dell'applicazione. Seleziona Salva.

Sto ottenendo un token di accesso per la mia applicazione, qual è l'URL della risorsa?

c3163bf1-092f-436b-b260-7ade5973e5b9/.default

Quanti dati storici sono disponibili?

• Azure: i dati sull'utilizzo e sulle emissioni coprono gli ultimi cinque anni di dati associati alla registrazione.
• Microsoft 365 : i dati sulle emissioni coprono gli ultimi 12 mesi di dati associati all'abbonamento Microsoft 365.

Dichiarazione di non responsabilità

L'API Microsoft Cloud for Sustainability (anteprima) si basa sugli standard di settore per il calcolo delle emissioni di carbonio dei server. Fornisce stime generali per aiutare le organizzazioni a ottenere informazioni dettagliate sulle emissioni di carbonio dell'infrastruttura IT associate all'uso dei servizi cloud di Azure. I risultati, le interpretazioni e le conclusioni presentate con l'API Microsoft Cloud for Sustainability (anteprima), compresi i calcoli, non sono consigli o raccomandazioni specifici. Le informazioni e le opinioni espresse possono cambiare senza preavviso. L'API Microsoft Cloud for Sustainability (anteprima) viene fornita così com'è, senza alcuna dichiarazione o garanzia di alcun tipo, espressa o implicita, incluse, a titolo esemplificativo, dichiarazioni o approvazioni riguardanti l'uso, i risultati o le prestazioni dell'API Microsoft Cloud for Sustainability (anteprima), la sua adeguatezza, accuratezza, affidabilità o correttezza. L'intero rischio relativo all'uso dell'API Microsoft Cloud for Sustainability (anteprima) è a tuo carico. Microsoft non si assume alcuna responsabilità per l'utilizzo dell'API Microsoft Cloud for Sustainability (anteprima). In nessun caso Microsoft sarà ritenuta responsabile per altri danni diretti o indiretti, inclusi eventuali mancati profitti, perdite di risparmi o eventuali danni incidentali o consequenziali derivanti da eventuali difetti o dall'uso o dall'impossibilità di usare l'API Microsoft Cloud for Sustainability (anteprima), anche se Microsoft è stata informata della possibilità di tali danni.

Informazioni correlate

Esempi di query OData per l'API Microsoft Cloud for Sustainability
Metodologia di calcolo dell'API di Microsoft Cloud for Sustainability
API Microsoft Cloud for Sustainability