API di calcolo delle emissioni generate

Articolo
01/17/2024

Puoi usare l'API msdyn_runEmissionCalculationService per calcolare le emissioni per le attività utilizzando un modello di calcolo senza creare un profilo di calcolo. Come sottoscrittore di Microsoft Sustainability Manager, puoi utilizzare questo URL per accedere all'API:

{organization url}/api/data/v{version}/msdyn_runEmissionCalculationService

In questo URL, url organizzazione si riferisce all'URL di base dell'organizzazione Microsoft Sustainability Manager in cui è installato e a cui l'utente può accedere. Versione si riferisce alla versione dell'API Web (ad esempio, 9.2).

Ottenere gli ID entità

Esistono molti modi per ottenere gli ID per entità come i dati di attività e il modello di calcolo. Questi includono XRM WebAPI, l'API client e direttamente tramite l'URL dell'entità in Microsoft Sustainability Manager.

Parametri di input

Come API personalizzata Dataverse, il tempo di esecuzione dell'API per il calcolo delle emissioni generalizzate è limitato a due minuti. I calcoli più lunghi restituiscono un timeout, quindi la dimensione dell'input è limitata in base alla tabella seguente.

Name	Type	Obbligatorio?	Descrzione
activityIds	Matrice di stringhe	Sì	Elenco degli ID dei record di dati di attività da utilizzare nel calcolo. È possibile includere nell'input fino a 500 ID attività.
calculationModelId	String	Sì	ID del modello di calcolo da utilizzare nel calcolo delle emissioni.
versione	String	No	Il numero di versione dell'API identifica la versione dell'API da richiamare. Attualmente 1.0.0 è l'unica versione disponibile. Se non specificata, viene utilizzata l'ultima versione.

Parametri di output

Al livello più alto, l'output è una stringa JSON contenente un elenco di entità di output di emissione generalizzate. Per ciascuna attività idonea, l'entità di output può contenere le emissioni valutate o gli errori riscontrati durante il calcolo in base all'esito positivo del calcolo. Verifica sempre la presenza del flag IsErrorRecord del record di output prima di provare ad accedervi.

Entità di output delle emissioni generalizzate

L'entità di output delle emissioni generalizzate non esiste in Dataverse. È una raccolta di attributi pertinenti dall'entità di emissione e dall'entità di errore di calcolo. L'API per il calcolo delle emissioni generalizzate restituisce un elenco di queste entità, con ciascuna entità corrispondente a un record di dati di attività idoneo nell'input.

L'entità di output ha gli attributi seguenti:

Name	Type	Descrzione
ActivityId	String	ID del record di dati dell'attività utilizzato per il calcolo.
ActivityName	String	Nome del record di dati dell'attività utilizzato per il calcolo.
IsErrorRecord	Boolean	Un valore booleano che indica se il calcolo per questa determinata attività ha rilevato errori. Se true, il calcolo non è riuscito e gli errori riscontrati possono essere visualizzati tramite l'attributo ErrorJson.
ErrorJson	String	Stringa JSON che rappresenta eventuali errori di calcolo rilevati durante l'elaborazione di questa determinata attività. Questo valore è null se IsErrorRecord è false.
Name	String	Nome dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true.
CH4	Decimale	Valore CH4 dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene CH4.
CH4Unit	String	Nome dell'unità del valore CH4 dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene CH4.
CO2	Decimale	Valore CO2 dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene CO2.
CO2Unit	String	Nome dell'unità del valore CO2 dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene CO2.
CO2e	Decimale	Valore CO2e dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene CO2e.
CO2eUnit	String	Nome dell'unità del valore CO2e dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene CO2e.
HFCs	Decimale	Valore HFCs dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene HFCs.
HFCsUnit	String	Nome dell'unità del valore HFCs dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene HFCs.
N2O	Decimale	Valore N2O dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene N2O.
N2OUnit	String	Nome dell'unità del valore N2O dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene N2O.
NF3	Decimale	Valore NF3 dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene NF3.
NF3Unit	String	Nome dell'unità del valore NF3 dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene NF3.
PFCs	Decimale	Valore PFCs dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene PFCs.
PFCsUnit	String	Nome dell'unità del valore PFCs dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene PFCs.
SF6	Decimale	Valore SF6 dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene SF6.
SF6Unit	String	Nome dell'unità del valore SF6 dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene SF6.
OtherGHGs	Decimale	Valore di altri gas serra dell'emissione calcolata per questa attività. Questo valore è 0 se IsErrorRecord è true o se l'emissione non contiene altri GHG.
OtherGHGsUnit	String	Nome dell'unità di altri gas serra dell'emissione calcolata per questa attività. Questo valore è null se IsErrorRecord è true o se l'emissione non contiene altri GHG.

Esempi

Nell'esempio seguente, l'API viene richiamata con un ID dati attività valido che genera una risposta non di errore.

Input:

{

  "activityDataIds": [
    "decc7c96-9180-ed11-aacf-000d3a1477fd”
  ],

  "calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",

  "version": "1.0.0"

}

Output:

[
{
"ActivityId": "decc7c96-9180-ed11-aacf-000d3a1477fd",
"ActivityName": "Passenger car",
"IsErrorRecord": false,
"ErrorJson": null,
"Name": "Employee Commuting 526",
"CH4": 2267.832,
"CH4Unit": "g",
"CO2": 107560.032,
"CO2Unit": "kg",
"CO2e": 108292.541736,
"CO2eUnit": kg,
"HFCs": 0,
"HFCsUnit": null,
"N2O": 2267.832,
"N2OUnit": "g",
"NF3": 0,
"NF3Unit": null,
"PFCs": 0,
"PFCsUnit": null,
"SF6": 0,
"SF6Unit": null,
"OtherGHGs": 0,
"OtherGHGsUnit": null
}
]

Nell'esempio seguente, l'API viene richiamata con un ID dati attività non valido che genera una risposta di errore. Nel record dell'attività in questione manca il campo del costo, richiesto dal modello di calcolo nell'input. Di conseguenza, il record di output presenta un JSON di errore contenente lo stack di eccezioni di calcolo rilevate durante la valutazione del record. Il codice di errore del servizio delle eccezioni riscontrate può aiutare l'utente a capire cosa è andato storto. In questo caso, EmissionCalculationActionFieldValueNullBlankException indica che un campo obbligatorio è vuoto.