Generalisierte Emissionsberechnungs-API
Verwenden Sie msdyn_runEmissionCalculationService API, um Emissionen für Aktivitäten mithilfe eines Berechnungsmodells zu berechnen, ohne ein Berechnungsprofil zu erstellen. Als Abonnent von Microsoft Sustainability Manager können Sie diese URL verwenden, um auf die API zuzugreifen:
{organization url}/api/data/v{version}/msdyn_runEmissionCalculationService
In dieser URL bezieht sich Organisations-URL auf die Basis-URL der Organisation, Microsoft Sustainability Manager in der sie installiert ist und auf die der Benutzer zugreifen kann. „Version“ bezieht sich auf die Web-API-Version (z. B. 9.2).
Abrufen von Entitäts-IDs
Es gibt viele Möglichkeiten, die IDs für Entitäten wie Aktivitätsdaten und Berechnungsmodell abzurufen. Dazu gehören XRM WebAPI, die Client-API und direkt über die URL der Entität auf Microsoft Sustainability Manager.
Eingabeparameter
Als Dataverse benutzerdefinierte API ist die Laufzeit der generalisierten Emissionsberechnungs-API auf zwei Minuten begrenzt. Bei längeren Berechnungen kommt es zu einem Timeout. Daher ist die Eingabegröße gemäß der folgenden Tabelle beschränkt.
| Name des Dataflows | Typ | Erforderlich? | Beschreibung |
|---|---|---|---|
| activityIds | Zeichenfolgenarray | Ja | Liste der IDs der Aktivitätsdatensätze, die zur Berechnung verwendet werden sollen. Bis zu 500 Aktivitäts-IDs können in die Eingabe aufgenommen werden. |
| calculationModelId | Zeichenfolge | Ja | ID des Berechnungsmodells, das bei der Emissionsberechnung verwendet werden soll. |
| Version | Zeichenfolge | Nein | Die Versionsnummer der API identifiziert die Version der API, die aufgerufen werden soll. Aktuell ist 1.0.0 die einzig verfügbare Version. Falls nicht anders definiert wird die neueste Version verwendet. |
Ausgabe...parameter
Auf der höchsten Ebene ist die Ausgabe eine JSON-Zeichenfolge, die eine Liste mit verallgemeinerten Emissionsausgabeeinheiten enthält. Für jede zulässige Aktivität kann die Ausgabeentität bewertete Emissionen oder die während der Berechnung aufgetretenen Fehler enthalten, je nachdem, ob die Berechnung erfolgreich war. Überprüfen Sie immer, ob ein eine Markierung IsErrorRecor eines Ausgabedatensatzes vorhanden ist, bevor Sie versuchen, darauf zuzugreifen.
Verallgemeinerte Emissionsausgabeeinheit
Die verallgemeinerte Emissionsausgabeentität existiert nicht in Dataverse. Es ist eine Sammlung relevanter Attribute der Emissionsentität und der Berechnungsfehlerentität. Die allgemeine Emissionsberechnungs-API gibt eine Liste dieser Entitäten zurück, wobei jede Entität einem zulässigen Aktivitätsdatensatz in der Eingabe entspricht.
Die Ausgabeentität hat die folgenden Attribute:
| Name des Dataflows | typ | Eigenschaft |
|---|---|---|
| ActivityId | String | Die ID des Datensatzes der Aktivitätsdaten, der für die Berechnung verwendet wird. |
| ActivityName | String | Der Name des Datensatzes der Aktivitätsdaten, der für die Berechnung verwendet wird. |
| IsErrorRecord | Boolesch | Ein boolescher Wert, der angibt, ob bei der Berechnung für diese bestimmte Aktivität Fehler aufgetreten sind. Bei „true“ ist die Berechnung fehlgeschlagen und die aufgetretenen Fehler können über das Attribut „ErrorJson“ angezeigt werden. |
| ErrorJson | Zeichenfolge | JSON-Zeichenfolge, die alle Berechnungsfehler darstellt, die während der Verarbeitung dieser bestimmten Aktivität aufgetreten sind. Dieser Wert ist null, wenn IsErrorRecord falsch ist. |
| Name des Dataflows | Zeichenfolge | Name der für diese Aktivität berechneten Emission. Dieser Wert ist null, wenn IsErrorRecord true ist. |
| CH4 | Dezimal | Für diese Aktivität wird der CH4-Wert der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission kein CH4 enthält. |
| CH4Unit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den CH4-Wert der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission kein CH4 enthält. |
| CO2 | Dezimal | Für diese Aktivität wird der CO2-Wert der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission kein CO2 enthält. |
| CO2Unit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den CO2-Wert der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission kein CO2 enthält. |
| CO2e | Dezimal | Für diese Aktivität wird der CO2e-Wert der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission kein CO2e enthält. |
| CO2eUnit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den CO2e-Wert der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission kein CO2e enthält. |
| HFCs | Dezimal | Für diese Aktivität wird der HFCs-Wert der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission kein HFCs enthält. |
| HFCsUnit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den HFCs-Wert der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission kein HFCs enthält. |
| N2O | Dezimal | Für diese Aktivität wird der N2O-Wert der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission kein N2O enthält. |
| N2OUnit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den N2O-Wert der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission kein N2O enthält. |
| NF3 | Dezimal | Für diese Aktivität wird der NF3-Wert der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission kein NF3 enthält. |
| NF3Unit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den NF3-Wert der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission kein NF3 enthält. |
| PFCs | Dezimal | Für diese Aktivität wird der PFCs-Wert der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission kein PFCs enthält. |
| PFCsUnit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den PFCs-Wert der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission kein PFCs enthält. |
| SF6 | Dezimal | Für diese Aktivität wird der SF6-Wert der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission kein SF6 enthält. |
| SF6Unit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den SF6-Wert der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission kein SF6 enthält. |
| OtherGHGs | Dezimal | Für diese Aktivität wird der Name der Einheit für den Wert anderer Treibhausgase der Emission berechnet. Dieser Wert ist 0, wenn IsErrorRecord wahr ist oder wenn die Emission keine anderen Treibhausgase enthält. |
| OtherGHGsUnit | Zeichenfolge | Für diese Aktivität wird der Name der Einheit für den Wert anderer Treibhausgase der Emission berechnet. Dieser Wert ist Null, wenn IsErrorRecord wahr ist oder wenn die Emission keine anderen GHGs enthält. |
Beispiele
Im folgenden Beispiel wird die API mit einer gültigen Aktivitätsdaten-ID aufgerufen, was zu einer fehlerfreien Antwort führt.
Eingabe:
{
"activityDataIds": [
"decc7c96-9180-ed11-aacf-000d3a1477fd”
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
Ausgabe:
[
{
"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
}
]
Im folgenden Beispiel wird die API mit einer ungültigen Aktivitätsdaten-ID aufgerufen, was zu einer fehlerhaften Antwort führt. Im betreffenden Aktivitätsdatensatz fehlt das Kostenfeld, welches das Berechnungsmodell in der Eingabe erfordert. Als Ergebnis weist der Ausgabedatensatz eine Fehler-JSON auf, die den Stapel von Berechnungsausnahmen enthält, die beim Auswerten des Datensatzes aufgetreten sind. Der Servicefehlercode der aufgetretenen Ausnahmen kann dem Benutzer helfen zu verstehen, wo der Fehler liegt. In diesem Fall gibt EmissionCalculationActionFieldValueNullBlankException an, dass ein erforderliches Feld leer ist.
Eingabe:
{
"activityDataIds": [
"22a8b098-4b8b-ed11-aad1-000d3a5bc56a"
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
Ausgabe:
[
{
"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
}]
]
Aufrufen von angepassten APIs
Weitere Informationen unter: Benutzerdefinierte APIs erstellen und verwenden.
