Generalizované rozhraní API pro výpočet emisí

Článek
01/17/2024

Rozhraní API msdyn_runEmissionCalculationService slouží k výpočtu emisí jednotlivých aktivit pomocí výpočtového modelu bez vytvoření výpočtového profilu. Jako předplatitel Microsoft Sustainability Manager můžete pro přístup k API použít tuto adresu URL:

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

V této adrese URL odkazuje část url organizace na základní adresu URL organizace, na které je Microsoft Sustainability Manager nainstalováno a kam má uživatel přístup. Verze odkazuje na verzi webového rozhraní API (například 9.2).

Získávání ID entit

Existuje mnoho způsobů, jak získat ID pro entity, jako jsou data aktivity a model výpočtu. Patří mezi ně XRM WebAPI, klientské API a přímé získání prostřednictvím adresy URL entity na Microsoft Sustainability Manager.

Vstupní parametry

Ve vlastním API Dataverse je doba běhu API pro výpočet zobecněných emisí omezena na dvě minuty. Delší výpočty vyprší, takže velikost vstupu je omezena podle následující tabulky.

Name	Type	Povinné?	Popis
ID aktivit	Pole řetězců	Ano	Seznam ID záznamů dat aktivit, které mají být použity při výpočtu. Do vstupu lze zahrnout až 500 ID aktivit.
calculationModelId	Řetězcové	Ano	ID modelu výpočtu, který se má použít při výpočtu emisí.
version	Řetězcové	Ne	Číslo verze rozhraní API označuje verzi rozhraní API, která by měla být vyvolána. V současnosti je verze 1.0.0 jedinou dostupnou verzí. Pokud není zadána, použije se nejnovější verze.

Výstupní parametry

Na nejvyšší úrovni je výstupem řetězec JSON obsahující seznam zobecněných výstupních entit emise. U každé způsobilé činnosti může výstupní entita obsahovat vyhodnocené emise nebo chyby zjištěné během výpočtu na základě toho, zda byl výpočet úspěšný. Před pokusem o přístup k výstupnímu záznamu vždy zkontrolujte příznak IsErrorRecord.

Zobecněná výstupní entita emise

Zobecněná výstupní entita emise v Dataverse neexistuje. Je to kolekce relevantních atributů z entity emise a entity chyby výpočtu. Zobecněné rozhraní API pro výpočet emisí vrací seznam těchto entit, přičemž každá entita odpovídá vhodnému záznamu dat aktivity ve vstupu.

Výstupní entita má následující atributy:

Name	Type	Popis
ActivityId	Řetězcové	ID záznamu dat aktivity použitého pro výpočet.
ActivityName	Řetězcové	Název záznamu dat aktivity použitého pro výpočet.
IsErrorRecord	Logické	Logická hodnota udávající, zda při výpočtu pro danou aktivitu došlo k chybám. Pokud má hodnotu pravda, výpočet selhal a zjištěné chyby lze zobrazit prostřednictvím atributu ErrorJson.
ErrorJson	Řetězcové	Řetězec JSON představující jakékoli chyby ve výpočtu, ke kterým došlo při zpracování této dané aktivity. Tato hodnota je null, pokud je IsErrorRecord nepravda.
Name	Řetězcové	Název emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud je IsErrorRecord pravda.
CH4	Desetinné	Hodnota CH4 emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje CH4.
CH4Unit	Řetězcové	Název jednotky pro hodnotu CH4 emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje CH4.
CO2	Desetinné	Hodnota CO2 emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje CO2.
CO2Unit	Řetězcové	Název jednotky pro hodnotu CO2 emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje CO2.
CO2e	Desetinné	Hodnota CO2e emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje CO2e.
CO2eUnit	Řetězcové	Název jednotky pro hodnotu CO2e emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje CO2e.
HFC	Desetinné	Hodnota HFCs emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje HFCs.
HFCsUnit	Řetězcové	Název jednotky pro hodnotu HFCs emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje HFCs.
N2O	Desetinné	Hodnota N2O emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje N2O.
N2OUnit	Řetězcové	Název jednotky pro hodnotu N2O emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje N2O.
NF3	Desetinné	Hodnota NF3 emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje NF3.
NF3Unit	Řetězcové	Název jednotky pro hodnotu NF3 emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje NF3.
PFC	Desetinné	Hodnota PFCs emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje PFCs.
PFCsUnit	Řetězcové	Název jednotky pro hodnotu PFCs emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje PFCs.
SF6	Desetinné	Hodnota SF6 emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje SF6.
SF6Unit	Řetězcové	Název jednotky pro hodnotu SF6 emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje SF6.
OtherGHGs	Desetinné	Hodnota ostatních skleníkových plynů emise vypočtené pro tuto aktivitu. Tato hodnota je 0, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje jiné skleníkové plyny.
OtherGHGsUnit	Řetězcové	Název jednotky ostatních skleníkových plynů emise vypočtené pro tuto aktivitu. Tato hodnota je null, pokud má IsErrorRecord hodnotu pravda nebo pokud emise neobsahuje jiné skleníkové plyny.

Příklady

V následujícím příkladu je API vyvoláno s platným ID dat aktivity, což má za následek nechybovou odpověď.

Vstup:

{

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

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

  "version": "1.0.0"

}

Výstup:

[
{
"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
}
]

V následujícím příkladu je API vyvoláno s neplatným ID dat aktivity, což má za následek chybovou odpověď. V předmětném záznamu aktivity chybí pole nákladů, které model výpočtu vyžaduje ve vstupu. Výsledkem je, že výstupní záznam obsahuje chybový JSON obsahující zásobník výjimek výpočtu, ke kterému došlo při vyhodnocování záznamu. Kód chyby služby u zjištěných výjimek může uživateli pomoci pochopit, co se pokazilo. V tomto případě EmissionCalculationActionFieldValueNullBlankException znamená, že povinné pole je prázdné.