泛化排放计算 API

项目
08/20/2024

您可以使用 msdyn_runEmissionCalculationService API 和计算模型来计算活动的排放量，而无需创建计算配置文件。作为 Microsoft Sustainability Manager的订阅者，您可以使用此 URL 访问 API：

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

在此 URL 中，组织 url指的是安装了组织 Microsoft Sustainability Manager 并且用户可以访问的基本 URL。版本是指 Web API 版本（例如 9.2）。

获取实体 ID

获取活动数据和计算模型等实体的 ID 的方法有很多种。其中包括 XRM WebAPI、客户端 API以及直接通过 Microsoft Sustainability Manager 上实体的 URL。

输入参数

作为 Dataverse 自定义 API，泛化排放计算 API 的运行时间上限为两分钟。计算超时时间较长，因此根据下表限制了输入大小。

客户	类型	是否为必填?	说明
activityIds	字符串数组	是	要在计算中使用的活动数据记录的 ID 列表。输入中最多可以包含 500 个活动 ID。
calculationModelId	字符串	是	用于排放计算的计算模型的 ID。
版本	字符串	否	API 的版本号标识应该调用的 API 的版本。目前 1.0.0 是唯一可用的版本。如果未指定，则使用最新版本。

输出参数

在最高级别，输出是包含泛化排放输出实体列表的 JSON 字符串。对于每个合格的活动，输出实体可能包含评估的排放量，或者根据计算是否成功包含计算过程中遇到的错误。在尝试访问输出记录之前，始终检查输出记录的 IsErrorRecord 标志。

泛化排放输出实体

Dataverse 中不存在泛化排放输出实体。它是来自排放实体和计算错误实体的相关属性的集合。泛化排放计算 API 返回这些实体的列表，每个实体都对应于输入中符合条件的活动数据记录。

输出实体拥有以下属性：

客户	类型	说明
ActivityId	字符串	用于计算的活动数据记录的 ID。
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。
CO2e	小数	为此活动计算的排放的 CO2e 值。如果 IsErrorRecord 为 true 或排放不包含 CO2e，则此值为 0。
CO2eUnit	字符串	为此活动计算的排放的 CO2e 值单位名称。如果 IsErrorRecord 为 true 或排放不包含 CO2e，则此值为 NULL。
HFC	小数	为此活动计算的排放的 HFC 值。如果 IsErrorRecord 为 true 或排放不包含 HFC，则此值为 0。
HFCsUnit	字符串	为此活动计算的排放的 HFC 值单位名称。如果 IsErrorRecord 为 true 或排放不包含 HFC，则此值为 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。
PFC	小数	为此活动计算的排放的 PFC 值。如果 IsErrorRecord 为 true 或排放不包含 PFC，则此值为 0。
PFCsUnit	字符串	为此活动计算的排放的 PFC 值单位名称。如果 IsErrorRecord 为 true 或排放不包含 PFC，则此值为 NULL。
SF6	小数	为此活动计算的排放的 SF6 值。如果 IsErrorRecord 为 true 或排放不包含 SF6，则此值为 0。
SF6Unit	字符串	为此活动计算的排放的 SF6 值单位名称。如果 IsErrorRecord 为 true 或排放不包含 SF6，则此值为 NULL。
OtherGHGs	小数	为此活动计算的排放的其他温室气体。如果 IsErrorRecord 为 true 或排放不包含其他 GHG，则此值为 0。
OtherGHGsUnit	字符串	为此活动计算的排放的其他温室气体单位名称。如果 IsErrorRecord 为 true 或排放不包含其他 GHG，则此值为 NULL。

示例

在下面的示例中，使用有效的活动数据 ID 调用 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
}
]

在以下示例中，使用无效的活动数据 ID 调用了 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。

📄 产品页面
 🎓 培训

✅ 免费试用
 🎥 YouTube 渠道

💻 社区
 LinkedIn 群组

通过