Yleisen päästölaskennan ohjelmointirajapinta
Voit käyttää yleistettyä msdyn_runEmissionCalculationService-ohjelmointirajapintaa toimintojen päästöjen laskemiseen laskentamallin avulla luomatta laskentaprofiilia. Tämän URL-osoitteen avulla voit Microsoft Sustainability Manager -tilaajana käyttää ohjelmointirajapintaa:
{organization url}/api/data/v{version}/msdyn_runEmissionCalculationService
Tässä URL-osoitteessa organisaation URL-osoite viittaa organisaation perus-URL-osoitteeseen, jonka Microsoft Sustainability Manager on asentanut ja johon käyttäjällä voi käyttöoikeus. Versio viittaa verkko-ohjelmointirajapinnan versioon (esimerkiksi 9.2).
Entiteettitunnuksen hankkiminen
Entiteettien, kuten aktiviteettitietojen ja laskentamallin, tunnuksia voi käyttää monella eri tavalla. Näitä ovat XRM WebAPI, asiakkaan ohjelmointirajapinta ja suoraan entiteetin URL-osoite Microsoft Sustainability Managerissa.
Syöteparametrit
Dataversen mukautettuna ohjelmointirajapintana yleisen päästölaskennan ohjelmointirajapinna:n suoritusaika on rajoitettu kahteen minuuttiin. Pitkät laskelmat aikakatkaistaan, joten syötön kokoa rajoitetaan seuraavan taulukon mukaisesti.
| Name | Type | Onko pakollinen? | Kuvaus |
|---|---|---|---|
| activityIds | Merkkijonomatriisi | Kyllä | Laskutoimituksessa käytettävä aktiviteettitietotietueiden tunnusluettelo. Tuloksissa voi olla enintään 500 aktiviteettitunnusta. |
| calculationModelId | String | Kyllä | Päästöjen laskennassa käytettävä laskentamallin tunnus. |
| version | String | Ei | Ohjelmointirajapinnan versionumero määrittää sen ohjelmointirajapinnan version, joka tulisi käynnistää. Tällä hetkellä 1.0.0 on ainoa käytettävissä oleva versio. Käytetään uusinta versiota ellei muuta ole määritetty. |
Tulosparametrit
Ylimmällä tasolla tulos on JSON-merkkijono, joka sisältää luettelon yleisistä päästöjen tulosentiteeteistä. Kunkin hyväksyttävän aktiviteetin osalta tulosentiteetti voi sisältää arvioidut päästöt tai laskelman aikana havaitut virheen sen perusteella, onnistuiko laskelma. Tarkista aina IsErrorRecord-lippu, ennen kuin yrität käyttää sitä.
Yleinen päästöjen tulosentiteetti
Yleistä päästöjen tulosentiteettiä ei ole olemassa Dataversessä. Se on olennaisten määritteiden kokoelma päästöjen entiteetistä ja laskennan virhe-entiteetistä. Yleisesti käytettävä laskennan ohjelmointirajapinta palauttaa luettelon näistä entiteeteistä, ja kukin kohde vastaa syötteessä vastaavaa oikeutettua aktiviteettitietuetta.
Tulosentiteetillä on seuraavat määritteet:
| Name | Type | Description |
|---|---|---|
| ActivityId | String | Laskelmassa käytetyn aktiviteetin tietotietueen tunnus. |
| ActivityName | String | Laskelmassa käytetyn aktiviteetin tietotietueen nimi. |
| IsErrorRecord | Totuusarvo | Totuusarvo, joka ilmaisee, onko tässä aktiviteetissa tapahtunut laskentavirheitä. Jos arvo on tosi, laskutoimituksen epäonnistuminen ja kohdatut virheet voidaan tarkastella ErrorJson-määritteen kautta. |
| ErrorJson | String | JSON-merkkijono, joka vastaa annettua aktiviteettia käsiteltäessä ilmenneitä laskentavirheitä. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on epätosi. |
| Name | String | Tälle aktiviteetille lasketun päästön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi. |
| CH4 | Desimaaliluku | Tälle aktiviteetille lasketun päästön CH4-arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä CH4:ta. |
| CH4Unit | String | Tälle aktiviteetille lasketun päästön CH4-arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä CH4:ta. |
| CO2 | Desimaaliluku | Tälle aktiviteetille lasketun päästön CO2-arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä CO2:ta. |
| CO2Unit | String | Tälle aktiviteetille lasketun päästön CO2-arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä CO2:ta. |
| CO2e | Desimaaliluku | Tälle aktiviteetille lasketun päästön CO2e-arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä CO2e:tä. |
| Co2eUnit | String | Tälle aktiviteetille lasketun päästön CO2e-arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä CO2e:tä. |
| HFC-yhdisteet | Desimaaliluku | Tälle aktiviteetille lasketun päästön HFCs-arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä HFCs:ä. |
| HFCsUnit | String | Tälle aktiviteetille lasketun päästön HFCs-arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä HFCs:ä. |
| N2O | Desimaaliluku | Tälle aktiviteetille lasketun päästön N2O-arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä N2O:ta. |
| N2OUnit | String | Tälle aktiviteetille lasketun päästön N2O-arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä N2O:ta. |
| NF3 | Desimaaliluku | Tälle aktiviteetille lasketun päästön NF3-arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä NF3:ta. |
| NF3Unit | String | Tälle aktiviteetille lasketun päästön NF3-arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä NF3:ta. |
| PFC-yhdisteet | Desimaaliluku | Tälle aktiviteetille lasketun päästön PFCs-arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä PFCs:ta. |
| PFCsUnit | String | Tälle aktiviteetille lasketun päästön PFCs-arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä PFCs:ta. |
| SF6 | Desimaaliluku | Tälle aktiviteetille lasketun päästön SF6-arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä SF6:ta. |
| SF6Unit | String | Tälle aktiviteetille lasketun päästön SF6-arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä SF6:ta. |
| OtherGHGs | Desimaaliluku | Tälle aktiviteetille laskettujen päästöjen muiden kasvihuonekaasujen arvo. Tämä arvo on 0, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä muuta GHGs:ta. |
| OtherGHGsUnit | String | Tälle aktiviteetille laskettujen päästöjen muiden kasvihuonekaasujen arvon yksikön nimi. Tämä arvo on tyhjäarvo, jos IsErrorRecord-arvo on tosi tai jos se ei sisällä muita GHGs:ta. |
Esimerkkejä
Seuraavassa esimerkissä ohjelmointirajapinta käynnistetään kelvollisella aktiviteetin tietotunnuksella, mikä aiheuttaa nonerror-vastauksen.
Syöte:
{
"activityDataIds": [
"decc7c96-9180-ed11-aacf-000d3a1477fd”
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
Tuloste:
[
{
"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
}
]
Seuraavassa esimerkissä ohjelmointirajapinta käynnistetään virheellisen aktiviteettitietotunnuksen avulla, jolloin saadaan virhevastaus. Kyseisestä aktiviteettitietueesta puuttuu kustannuskenttä, jota laskentamalli tarvitsee syötteessä. Tämän vuoksi tulostietueessa on JSON-virhe, joka sisältää tietuetta arvioitaessa kohdattujen laskentapoikkeusten pinon. Poikkeusten palveluvirhekoodi voi auttaa käyttäjää ymmärtämään, mikä meni vikaan. Tässä tapauksessa EmissionCalculationActionFieldValueNullBlankException ilmaisee, että pakollinen kenttä on tyhjä.
Syöte:
{
"activityDataIds": [
"22a8b098-4b8b-ed11-aad1-000d3a5bc56a"
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
Tuloste:
[
{
"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
}]
]
Mukautettujen ohjelmointirajapintojen kutsuminen
Lisätietoja on kohdassa Mukautettujen ohjelmointirajapintojen luominen ja käyttö.
