Esempi di query OData per l'API Cloud for Sustainability (anteprima)
Importante
Alcune o tutte queste funzionalità sono disponibili come parte di una versione di anteprima. Il contenuto e la funzionalità sono soggetti a modifiche.
OData (Open Data Protocol) è un protocollo di accesso ai dati basato su protocolli di base come HTTP. Utilizza metodologie comunemente accettate come REST per il Web. Puoi usare vari tipi di raccolte e strumenti che consentono di utilizzare i servizi OData.
Per creare implementazioni basate sull'API Microsoft Cloud for Sustainability, puoi esaminare alcuni di questi esempi di query richiesti di frequente.
Modifica gli esempi di query perché funzionino negli ambienti di destinazione:
{serviceRoot}:
https://api.mcfs.microsoft.com/api/v1.0/instances/{instanceId}{instanceId}: GUID del Cloud for Sustainability ambiente che vuoi interrogare, ad esempio 20aec369-f1c8-4814-a89d-4d449dd7e8a1.
{serviceRootM365}:
{serviceRoot}/m365{serviceRootAzure}:
{serviceRoot}/enrollments/{enrollmentId}{enrollmentId}: ID di iscrizione, noto anche come ID dell'account di fatturazione. Ad esempio 12345678.
{tenantId}: Microsoft 365 ID dell'inquilino.
Nota
Alcune query relative alle API conterranno molti risultati e saranno suddivise su più pagine. L'API restituisce al massimo 1000 risultati per pagina. Se sono disponibili più risultati, l'API restituisce una proprietà @odata.nextLink contenente un URL alla successiva pagina dei risultati.
Entità EnrollmentEmission (per le emissioni di Azure)
Rappresenta i dati sulle emissioni per un account di fatturazione, denominato anche registrazione.
| Proprietà | Tipo | Note |
|---|---|---|
| dateKey | int32 | Data nel formato aaaammgg; gg è sempre 01. |
| enrollmentId | stringa | Nota anche come ID account di fatturazione. |
| orgName | stringa | Uguale al nome TP o al nome padre principale. |
| subscriptionId | stringa | ID dell'abbonamento. |
| subscriptionName | stringa | Nome dell'abbonamento. |
| azureServiceName | string | Nome di un servizio di Azure, ad esempio Servizio app |
| subService | string | Ad esempio, Archiviazione di Azure o Calcolo di Azure. |
| azureRegionName | stringa | Area di Azure in cui il servizio è distribuito. |
| ambito | stringa | Ambito relativo ai gas serra, ad esempio ambito 1, ambito 2 o ambito 3. |
| scopeId | int32 | ID dell'ambito. |
| totalEmissions | doppio | Emissioni totali per il record (mtCO2e). |
Esempi di query per l'entità EnrollmentEmission (per emissioni di Azure)
| Tipo di query | Esempio |
|---|---|
| Emissioni per registrazione | {serviceRootAzure}/emissioni |
| Seleziona determinati campi | {serviceRootAzure}/emissioni?$Seleziona=enrollmentId,totalEmissions,scopeId |
| Includi conteggio | {serviceRootAzure}/emissioni?$count=true |
| Limita numero di risultati | {serviceRootAzure}/emissioni?$top=100 |
| Paging | {serviceRootAzure}/emissioni?$skip=100&$top=50 |
| Filtra per ambito | {serviceRootAzure}/emissioni?$filter=ScopeId eq 1 |
| Filtra e aggrega | {serviceRootAzure}/emissions?$apply=filter(ScopeId eq 1)/aggregate($count come Conteggio, totalEmissions con media come Media, totalEmissions con somma come Somma) |
| Filtra e raggruppa | {serviceRootAzure}/emissioni?$apply=filter(totalEmissions gt 0.05)/groupby((ScopeId), aggregate($count as Count))` |
Entità Microsoft365Emission (per le emissioni di Microsoft 365)
Rappresenta le emissioni dei data center di Microsoft 365 associate alle seguenti applicazioni:
- Exchange Online
- SharePoint
- OneDrive
- Microsoft Teams
- Word
- Excel
- PowerPoint
- Outlook
| Proprietà | Tipo | Note |
|---|---|---|
| dateKey | int32 | Data nel formato aaaammgg; gg è sempre 01. |
| tenantId | stringa | ID del tenant. |
| tenantName | stringa | Nome del tenant. |
| officeRegionName | stringa | Area del data center di Microsoft 365. |
| ambito | stringa | Ambito relativo ai gas serra, ad esempio ambito 1, ambito 2 o ambito 3. |
| totalEmissions | doppio | Emissioni totali per il record (mtCO2e). |
Esempi di query per l'entità Microsoft365Emission (per emissioni di Microsoft 365)
| Tipo di query | Esempio |
|---|---|
| Emissioni per il tenant | {serviceRootM365}/emissioni dell'inquilino |
| Seleziona determinati campi | {serviceRootM365}/emissioni?$Seleziona=tenantId,totalEmissions,ambito |
| Includi conteggio | {serviceRootM365}/emissionitenant?$count=true |
| Limita numero di risultati | {serviceRootM365}/emissionitenant?$top=100 |
| Paging | {serviceRootM365}/emissioniinquilino?$skip=100&$top=50 |
| Filtra per ambito | {serviceRootM365}/terantemissions?$filter=Ambito eq 'FILLMEIN' |
| Filtra e aggrega | {serviceRootserviceRootM365Azure}/terantemissions?$apply=filter(scope eq 'FILLMEIN')/aggregate($count come Conteggio, totalEmissions con media come Media, totalEmissions con somma come Somma) |
| Filtra e raggruppa | {serviceRootM365}/tenantemissions?$apply=filter(totalEmissions gt 0.05)/groupby((Ambito), aggregate($count as Conteggio))` |
Entità EnrollmentUsage (per le emissioni di Azure)
Rappresenta un fattore di utilizzo calcolato delle risorse cloud Microsoft.
| Proprietà | Tipo | Note |
|---|---|---|
| dateKey | int32 | Data nel formato aaaammgg; gg è sempre 01. |
| enrollmentId | stringa | Nota anche come ID account di fatturazione. |
| orgName | stringa | Uguale al nome TP o al nome padre principale. |
| subscriptionId | stringa | ID dell'abbonamento. |
| subscriptionName | stringa | Nome dell'abbonamento. |
| subService | stringa | Ad esempio, Archiviazione di Azure o Calcolo di Azure. |
| azureRegionName | stringa | Area di Azure in cui il servizio è distribuito. |
| attivamente | doppio | Utilizzo totale del record. Non contiene l'unità perché rappresenta l'utilizzo normalizzato del servizio nell'area specificata. |
Per ulteriori informazioni sulla metodologia di calcolo di Microsoft, vai a Metodologia di calcolo dell'API di Microsoft Cloud for Sustainability.|
Esempi di query per l'entità EnrollmentUsage
| Tipo di query | Esempio | Nota |
|---|---|---|
| Tutti i dati sull'utilizzo | {serviceRootAzure}/uso | |
| Utilizzo totale per mese per sottoscrizione | {serviceRootAzure}/usage?$apply=groupby((SubscriptionName,DateKey),aggregate(utilizzo con somma come TotalUsage))&$orderby=SubscriptionName,DateKey |
Entità EnrollmentProjection (per le emissioni di Azure)
Rappresenta le emissioni previste per il resto dell'anno solare, sulla base di una media mobile dei cinque mesi precedenti. Per le visualizzazioni annualizzate.
| Proprietà | Tipo | Note |
|---|---|---|
| dateKey | int32 | Data nel formato aaaammgg; gg è sempre 01. |
| enrollmentId | stringa | Nota anche come ID account di fatturazione. |
| actualEmissions | doppio | Incluso solo per date passate (mtCO2e). |
| projectedEmissions | doppio | Basato su una media mobile dei cinque mesi precedenti o meno in base ai dati effettivi disponibili per l'anno in corso (mtCO2e). |
| actualUsage | doppio | Inclusa solo per le date passate. |
| projectedUsage | doppio | Basato su una media mobile dei cinque mesi precedenti o meno in base ai dati effettivi disponibili per l'anno in corso. |
Esempi di query per l'entità EnrollmentProjection (per emissioni di Azure)
| Tipo di query | Esempio | Nota |
|---|---|---|
| Proiezioni oltre luglio 2022 | {serviceRootAzure}/proiezioni?$filter=dateKey gt 20220701 | |
| Tutte le proiezioni per anno | {serviceRootAzure}/proiezioni |
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.
Domande frequenti
In che modo Microsoft calcola le emissioni e l'utilizzo?
Per informazioni sulla metodologia di calcolo di Microsoft, vai a Metodologia di calcolo dell'API di Microsoft Cloud for Sustainability.
Cos'è Rownum?
L'API utilizza rownum per un'impaginazione coerente. Il valore è soggetto a modifiche, quindi la tua applicazione non dipendere da tale valore.
Che cos'è un ID registrazione?
Un ID registrazione fa riferimento a un ID account di fatturazione. Trova il tuo ID di iscrizione e l'ID dell'account di fatturazione nel portale di Azure.
Come ottengo un token di autorizzazione per l'ambiente di destinazione?
L'API richiede un token per l'autorizzazione OAuth. Consigliamo di usare la raccolta di autenticazione Microsoft (MSAL).
È possibile ottenere altre informazioni su come usare nextLink per la paginazione?
L'API restituisce una proprietà @odata.nextLink se sono presenti più risultati di quelli restituiti nella risposta corrente. La tua app deve eseguire un altro GET su questo nextLink per ottenere la pagina successiva dei risultati. L'ultima pagina non contiene un nextLink.
Vedi questo esempio di codice per ulteriori dettagli sulla paginazione con una raccolta client OData.
Informazioni correlate
- Panoramica dell'API Cloud for Sustainability
- Microsoft Cloud for Sustainability Metodologia di calcolo API
- Microsoft Cloud for Sustainability API
