Condividi tramite

Panoramica dell'API Cloud for Sustainability (anteprima)

  • Articolo

Prova gratuita

Microsoft Cloud for Sustainability Tech Summit novembre 2024.

Importante

Alcune o tutte queste funzionalità sono disponibili come parte di una versione di anteprima. Il contenuto e la funzionalità sono soggetti a modifiche.

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.

Importante

L'API Microsoft Cloud for Sustainability è attualmente in fase di anteprima ed è soggetta a modifiche. Le cifre storiche sulle emissioni possono anche essere aggiornate man mano che Microsoft apporta miglioramenti all'accuratezza e alla completezza dei dati. Questa anteprima non è destinata per scopi di conformità legale, marketing o report.

Introduzione alle API Cloud for Sustainability

Nota

Se la tua organizzazione desidera ottenere l'accesso all'API Microsoft Cloud for Sustainability(anteprima), invia questo modulo di iscrizione.

Inizia a usare le API mediante le procedure seguenti:

Account supportati

  • Azzurro : Microsoft Cloud for Sustainability Le API per Azure supportano gli account EA Direct, MCA e MPA con fatturazione diretta Relazioni 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

    Vantaggio di Azure Hybrid l'utilizzo non viene attualmente rilevato né riflesso nelle emissioni.

  • Microsoft 365: Microsoft Cloud for Sustainability API per Microsoft 365 supportare abbonamenti aziendali, aziendali o didattici 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

Importante

Per abilitare correttamente l'accesso ai dati della tua organizzazione, questo passaggio deve essere eseguito dall'amministratore pertinente. Per gli account di Azure MCA, è necessario un account amministratore di fatturazione con un ruolo di lettore, collaboratore o proprietario. Per gli account di Azure EA, è richiesto un amministratore aziendale di sola lettura. Controlla il ruolo nel portale di Azure. Per Microsoft 365, è richiesto uno dei seguenti ruoli: amministratore di Exchange, amministratore di Skype for Business, amministratore di SharePoint, Lettore globale, Lettore di report. Gli amministratori di Azure e Microsoft 365 possono creare istanze o essere aggiunti alle istanze per abilitare le origini dati e l'API. Se non disponi di un ruolo amministratore necessario per abilitare i dati, puoi esplorare l'API usando solo dati dimostrativi.

  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.

    Origini dati.

  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 Icona Aggiorna.. Per copiare le chiavi, seleziona Icona Copia..

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 compilato automaticamente
    • Chiave di abbonamento : Compilato automaticamente con la chiave API dal Gestione API scheda
    • ID iscrizione : Il tuo ID di iscrizione, noto anche come ID dell'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.
    • ID istanza : Trovato nell'URL per il Microsoft Cloud for Sustainability Portale API
    • ID inquilino : Microsoft 365 ID dell'inquilino.

    Pagina Prova.

  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 compilato automaticamente
    • Chiave di abbonamento : Compilato automaticamente con la chiave API dal Gestione API scheda
    • ID istanza : Trovato nell'URL per il Microsoft Cloud for Sustainability Portale API
    • esportatipolavoro : Seleziona Azzurro o Microsoft 365 per designare origine dati per i dati sulle emissioni e sull'utilizzo da esportare.
    • demodati : Inserisci "true" se desideri esplorare questa funzionalità esportando 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:

  • Spettatore : Può visualizzare tutte le pagine all'interno del Microsoft Cloud for Sustainability API.
  • contributore : Può interagire con tutte le pagine in Microsoft Cloud for Sustainability Portale API. Non è possibile aggiungere o rimuovere utenti.
  • Amministratore : Tutte le autorizzazioni disponibili, inclusa la possibilità di aggiungere o rimuovere utenti.

Nota

I collaboratori e gli amministratori non possono disabilitare o abilitare l'origine dati di Microsoft 365 a meno che non abbiano ruoli di amministratore di Exchange, amministratore di Skype for Business, amministratore di SharePoint, Lettore globale o Lettore di report.

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 Icona 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 dati : Un grafico che mostra la quantità di dati trasferiti tramite l'API nel intervallo di tempo selezionato.
  • Operazioni : Una tabella con righe per ciascuna 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?

  • Azzurro : I dati sull'utilizzo e sulle emissioni riguardano gli ultimi cinque anni di dati associati all'iscrizione.
  • Microsoft 365: I dati sulle emissioni coprono gli ultimi 12 mesi di dati associati all' Microsoft 365 sottoscrizione.

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.

Microsoft Cloud for Sustainability Esempi di query API OData
Microsoft Cloud for Sustainability Metodologia di calcolo API
Microsoft Cloud for Sustainability API

📄 Pagina del prodotto
🎓 Formazione

✅ Canale di prova gratuito
🎥 YouTube

💻 Comunità
Icona LinkedIn.Gruppo LinkedIn