生成された排出の算定 API

[アーティクル]
01/17/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 Web API、クライアント API、Microsoft Sustainability Manager のエンティティ URL から直接取得するなどです。

入力パラメーター

Dataverse カスタム API では、標準化排出量算定 API の実行時間は 2 分に制限されています。算定に時間がかかるとタイムアウトになるため、入力サイズは次の表に従って制限されます。

件名	タイプ	必須?	説明
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	10 進法	この活動のために算定された排出量の CH4 値。 IsErrorRecord が true の場合、または排出量に CH4 が含まれていない場合、この値は 0 です。
CH4Unit	文字列	この活動のために算定された排出量の CH4 値の単位名。 IsErrorRecord が true の場合、または排出量に CH4 が含まれていない場合、この値は null です。
CO2	10 進法	この活動のために算定された排出量の CO2 値。 IsErrorRecord が true の場合、または排出量に CO2 が含まれていない場合、この値は 0 です。
CO2Unit	文字列	この活動のために算定された排出量の CO2 値の単位名。 IsErrorRecord が true の場合、または排出量に CO2 が含まれていない場合、この値は null です。
CO2e	10 進法	この活動のために算定された排出量の CO2e 値。 IsErrorRecord が true の場合、または排出量に CO2e が含まれていない場合、この値は 0 です。
CO2eUnit	文字列	この活動のために算定された排出量の CO2e 値の単位名。 IsErrorRecord が true の場合、または排出量に CO2e が含まれていない場合、この値は null です。
HFCs	10 進法	この活動のために算定された排出量の HFCs 値。 IsErrorRecord が true の場合、または排出量に HFCs が含まれていない場合、この値は 0 です。
HFCsUnit	文字列	この活動のために算定された排出量の HFCs 値の単位名。 IsErrorRecord が true の場合、または排出量に HFCs が含まれていない場合、この値は null です。
N2O	10 進法	この活動のために算定された排出量の N2O 値。 IsErrorRecord が true の場合、または排出量に N2O が含まれていない場合、この値は 0 です。
N2OUnit	文字列	この活動のために算定された排出量の N2O 値の単位名。 IsErrorRecord が true の場合、または排出量に N2O が含まれていない場合、この値は null です。
NF3	10 進法	この活動のために算定された排出量の NF3 値。 IsErrorRecord が true の場合、または排出量に NF3 が含まれていない場合、この値は 0 です。
NF3Unit	文字列	この活動のために算定された排出量の NF3 値の単位名。 IsErrorRecord が true の場合、または排出量に NF3 が含まれていない場合、この値は null です。
PFCs	10 進法	この活動のために算定された排出量の PFCs 値。 IsErrorRecord が true の場合、または排出量に PFCs が含まれていない場合、この値は 0 です。
PFCsUnit	文字列	この活動のために算定された排出量の PFCs 値の単位名。 IsErrorRecord が true の場合、または排出量に PFCs が含まれていない場合、この値は null です。
SF6	10 進法	この活動のために算定された排出量の SF6 値。 IsErrorRecord が true の場合、または排出量に SF6 が含まれていない場合、この値は 0 です。
SF6Unit	文字列	この活動のために算定された排出量の SF6 値の単位名。 IsErrorRecord が true の場合、または排出量に SF6 が含まれていない場合、この値は null です。
OtherGHGs	10 進法	この活動のために算定された排出量のその他の温室効果ガス値。 IsErrorRecord が true の場合、または排出量にその他の GHGs が含まれていない場合、この値は 0 です。
OtherGHGsUnit	文字列	この活動のために算定された排出量のその他の温室効果ガス値の単位名。 IsErrorRecord が true の場合、または排出量にその他の GHGs が含まれていない場合、この値は 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 の作成と使用を参照してください。