Generalizované rozhraní API pro výpočet emisí
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ší časový limit výpočtů vyprší, takže velikost vstupu je omezena podle následující tabulky.
| Název | 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. Pro každou způsobilou činnost 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. |
| Název | Ř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 činnosti chybí pole nákladů, které model výpočtu vyžaduje na 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é.
Vstup:
{
"activityDataIds": [
"22a8b098-4b8b-ed11-aad1-000d3a5bc56a"
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
Výstup:
[
{
"ActivityId": "22a8b098-4b8b-ed11-aad1-000d3a5bc56a",
"ActivityName": null,
"IsErrorRecord": true,
"ErrorJson": {
"ServiceErrorCode": "ActivityCalculationModelExecutionException",
"UserMessageParameters": [
"Invalid Fugitive Emissions"
],
"InnerException": {
"ServiceErrorCode": "EmissionCalculationActionFieldValueNullBlankException",
"UserMessageParameters": [
"Action 1"
],
"InnerException": {
"ServiceErrorCode": null,
"UserMessageParameters": null,
"InnerException": {
"ServiceErrorCode": null,
"UserMessageParameters": null,
"InnerException": null
}
}
}
},
"Name": null,
"CH4": 0,
"CH4Unit": null,
"CO2": 0,
"CO2Unit": null,
"CO2e": 0,
"CO2eUnit": null,
"HFCs": 0,
"HFCsUnit": null,
"N2O": 0,
"N2OUnit": null,
"NF3": 0,
"NF3Unit": null,
"PFCs": 0,
"PFCsUnit": null,
"SF6": 0,
"SF6Unit": null,
"OtherGHGs": 0,
"OtherGHGsUnit": null
}]
]
Vyvolání vlastních rozhraní API
Další informace najdete v tématu Vytvoření a použití vlastních rozhraní API.
