通用排放計算 API
您可以使用 msdyn_runEmissionCalculationService API 計算使用計算模型的活動排放，而不需建立計算設定檔。 若為 Microsoft Sustainability Manager 的訂閱者，您可以使用此 URL 來存取 API：
{organization url}/api/data/v{version}/msdyn_runEmissionCalculationService
在此 URL 中，組織 URL 是指已安裝組織 Microsoft Sustainability Manager，且使用者可以存取的基礎 URL。 Version 是指 Web API 版本 (例如 9.2)。
取得實體識別碼
有許多方法可以讓您取得實體 (例如活動資料與計算模型) 的識別碼。 這些包括 XRM WebAPI、用戶端 API，以及直接透過 Microsoft Sustainability Manager 上的實體 URL。
輸入參數
至於 Dataverse 自訂 API，通用排放計算 API 的執行階段上限為兩分鐘。 計算逾時較長，因此根據下表限制輸入大小。
| 名稱 | 類型 | 是必要的嗎？ | 描述 |
|---|---|---|---|
| activityIds | 字串陣列 | .是 | 要在計算中使用的活動資料記錄的識別碼清單。 輸入中最多可以包括 500 個活動識別碼。 |
| calculationModelId | 字串 | .是 | 用於排放計算的計算模型識別碼。 |
| 版本 | 字串 | 無 | API 的版本號碼會標識所應叫用的 API 版本。 目前 1.0.0 是唯一可用的版本。 如果未指定，則使用最新版本。 |
輸出參數
在最高層級，輸出是包含通用排放輸出實體清單的 JSON 字串。 每個合格活動的輸出實體可能都包含評估的排放量，或計算期間根據計算是否成功而發生的錯誤。 嘗試存取輸出記錄之前，請務必檢查輸出記錄的 IsErrorRecord 旗標。
通用排放輸出實體
Dataverse 中不存在通用排放輸出實體。 它是來自排放實體和計算錯誤實體的相關屬性集合。 通用排放計算 API 會傳回這些實體的清單，其中每個實體都對應至輸入中符合條件的活動資料記錄。
輸出實體具有下列屬性：
| 名稱 | 類型 | 描述 |
|---|---|---|
| ActivityId | 字串 | 用於計算之活動資料記錄的識別碼。 |
| ActivityName | 字串 | 用於計算之活動資料記錄的名稱。 |
| IsErrorRecord | 布林值 | 布林值，表示此指定活動的計算是否發生錯誤。 如果是 true，則計算失敗，發生的錯誤可以透過 ErrorJson 屬性查看。 |
| ErrorJson | 字串 | JSON 字串，表示處理此指定活動時發生的任何計算錯誤。 如果 IsErrorRecord 為 false，則此值為 null。 |
| 名稱 | 字串 | 針對此活動計算的排放名稱。 如果 IsErrorRecord 為 true，則此值為 null。 |
| CH4 | 小數點 | 針對此活動計算的 CH4 排放值。 若 IsErrorRecord 為 true 或排放不包含 CH4 時，則此值為 0。 |
| CH4Unit | 字串 | 針對此活動計算的 CH4 排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含 CH4 時，則此值為 null。 |
| CO2 | 小數點 | 針對此活動計算的 CO2 排放值。 若 IsErrorRecord 為 true 或排放不包含 CO2 時，則此值為 0。 |
| CO2Unit | 字串 | 針對此活動計算的 CO2 排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含 CO2 時，則此值為 null。 |
| CO2 當量 | 小數點 | 針對此活動計算的 CO2e 排放值。 若 IsErrorRecord 為 true 或排放不包含 CO2e 時，則此值為 0。 |
| CO2eUnit | 字串 | 針對此活動計算的 CO2e 排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含 CO2e 時，則此值為 null。 |
| HFC | 小數點 | 針對此活動計算的 HFCs 排放值。 若 IsErrorRecord 為 true 或排放不包含 HFCs 時，則此值為 0。 |
| HFCsUnit | 字串 | 針對此活動計算的 HFCs 排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含 HFCs 時，則此值為 null。 |
| N2O | 小數點 | 針對此活動計算的 N2O 排放值。 若 IsErrorRecord 為 true 或排放不包含 N2O 時，則此值為 0。 |
| N2OUnit | 字串 | 針對此活動計算的 N2O 排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含 N2O 時，則此值為 null。 |
| NF3 | 小數點 | 針對此活動計算的 NF3 排放值。 若 IsErrorRecord 為 true 或排放不包含 NF3 時，則此值為 0。 |
| NF3Unit | 字串 | 針對此活動計算的 NF3 排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含 NF3 時，則此值為 null。 |
| PFCs | 小數點 | 針對此活動計算的 PFCs 排放值。 若 IsErrorRecord 為 true 或排放不包含 PFCs 時，則此值為 0。 |
| PFCsUnit | 字串 | 針對此活動計算的 PFCs 排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含 PFCs 時，則此值為 null。 |
| SF6 | 小數點 | 針對此活動計算的 SF6 排放值。 若 IsErrorRecord 為 true 或排放不包含 SF6 時，則此值為 0。 |
| SF6Unit | 字串 | 針對此活動計算的 SF6 排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含 SF6 時，則此值為 null。 |
| OtherGHGs | 小數點 | 針對此活動計算的其他溫室氣體排放值。 若 IsErrorRecord 為 true 或排放不包含其他 GHGs 時，則此值為 0。 |
| OtherGHGsUnit | 字串 | 針對此活動計算的其他溫室氣體排放值單位名稱。 若 IsErrorRecord 為 true 或排放不包含其他 GHGs 時，則此值為 null。 |
範例
在下列範例中，使用有效的活動資料識別碼叫用 API，從而產生非錯誤回應。
輸入：
{
"activityDataIds": [
"decc7c96-9180-ed11-aacf-000d3a1477fd”
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
輸出：
[
{
"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
}
]
在下列範例中，會使用無效的活動資料識別碼叫用 API，並導致錯誤回覆。 上述活動記錄缺少成本欄位，而計算模型在輸入中需要該欄位。 因此，輸出記錄具有錯誤 JSON，包含評估記錄時發生的計算異常堆疊。 發生的例外狀況服務錯誤碼可協助使用者了解哪裡出了問題。 在此案例中，EmissionCalculationActionFieldValueNullBlankException 表示必要欄位為空白。
輸入：
{
"activityDataIds": [
"22a8b098-4b8b-ed11-aad1-000d3a5bc56a"
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
輸出：
[
{
"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
}]
]
叫用自訂 API
如需詳細資訊，請移至建立和使用自訂 API。
