API de cálculo de emissão generalizada
Você pode usar a API msdyn_runEmissionCalculationService para calcular emissões para atividades usando um modelo de cálculo sem criar um perfil de cálculo. Como assinante do Microsoft Sustainability Manager, você pode usar esta URL para acessar a API:
{organization url}/api/data/v{version}/msdyn_runEmissionCalculationService
Nesta URL, a URL da organização refere-se à URL base da organização em que o Microsoft Sustainability Manager está instalado e o usuário pode acessar. Versão refere-se à versão da API da web (por exemplo, 9.2).
Como obter IDs de entidades
Há muitas maneiras de obter as IDs de entidades, como dados de atividade e modelo de cálculo. Elas incluem a API Web XRM, a API do cliente e diretamente pela URL da entidade no Microsoft Sustainability Manager.
Parâmetros de entrada
Como uma API personalizada do Dataverse, o tempo de execução da API de cálculo de emissão generalizada é limitado a dois minutos. Como cálculos mais longos expiram, o tamanho da entrada é restrito de acordo com a tabela a seguir.
| Nome | Tipo | Obrigatório? | Descrição |
|---|---|---|---|
| activityIds | Matriz de cadeia de caracteres | Sim | Lista de IDs dos registros de dados de atividade a serem usados no cálculo. Até 500 IDs de atividade podem ser incluídos na entrada. |
| calculationModelId | Cadeia de caracteres | Sim | ID do modelo de cálculo a ser utilizado no cálculo das emissões. |
| versão | Cadeia de caracteres | Não | O número de versão da API identifica a versão da API que deve ser chamada. Atualmente, 1.0.0 é a única versão disponível. Se não for especificado, a versão mais recente será usada. |
Parâmetros de saída
No nível mais alto, a saída é uma string JSON contendo uma lista de entidades de saída de emissão generalizada. Para cada atividade elegível, a entidade de saída pode conter as emissões avaliadas ou os erros encontrados durante o cálculo com base no êxito do cálculo. Sempre verifique o sinalizador IsErrorRecord de um registro de saída antes de tentar acessá-lo.
Entidade de saída de emissão generalizada
A entidade de saída de emissões generalizadas não existe no Dataverse. É uma coleção de atributos relevantes da entidade de emissão e da entidade de erro de cálculo. A API de cálculo de emissão generalizada retorna uma lista dessas entidades, com cada entidade correspondendo a um registro de dados de atividade elegível na entrada.
A entidade de saída tem os seguintes atributos:
| Nome | Tipo | Descrição |
|---|---|---|
| ActivityId | Cadeia de Caracteres | A ID do registro de dados da atividade usado para o cálculo. |
| ActivityName | Cadeia de Caracteres | O nome do registro de dados da atividade usado para o cálculo. |
| IsErrorRecord | Boolean | Um valor booliano que indica se o cálculo dessa atividade específica encontrou erros. Se for verdadeiro, o cálculo falhou e os erros encontrados podem ser visualizados por meio do atributo ErrorJson. |
| ErrorJson | Cadeia de caracteres | Cadeia de caracteres JSON representando qualquer erro de cálculo encontrado durante o processamento desta determinada atividade. Este valor é nulo se IsErrorRecord for falso. |
| Nome | Cadeia de caracteres | Nome da emissão calculada para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro. |
| CH4 | Decimal | Valor de emissão de CH4 calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver CH4. |
| CH4Unit | Cadeia de caracteres | Nome da unidade para o valor de emissão de CH4 calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver CH4. |
| CO2 | Decimal | Valor de emissão de CO2 calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver CO2. |
| CO2Unit | Cadeia de caracteres | Nome da unidade para o valor de emissão de CO2 calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver CO2. |
| CO2e | Decimal | Valor de emissão de CO2e calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver CO2e. |
| CO2eUnit | Cadeia de caracteres | Nome da unidade para o valor de emissão de CO2e calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver CO2e. |
| HFCs | Decimal | Valor de emissão de HFCs calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver HFCs. |
| HFCsUnit | Cadeia de caracteres | Nome da unidade para o valor de emissão de HFCs calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver HFCs. |
| N2O | Decimal | Valor de emissão de N2O calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver N2O. |
| N2OUnit | Cadeia de caracteres | Nome da unidade para o valor de emissão de N2O calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver N2O. |
| NF3 | Decimal | Valor de emissão de NF3 calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver NF3. |
| NF3Unit | Cadeia de caracteres | Nome da unidade para o valor de emissão de NF3 calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver NF3. |
| PFCs | Decimal | Valor de emissão de PFCs calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver PFCs. |
| PFCsUnit | Cadeia de caracteres | Nome da unidade para o valor de emissão de PFCs calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver PFCs. |
| SF6 | Decimal | Valor de emissão de SF6 calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver SF6. |
| SF6Unit | Cadeia de caracteres | Nome da unidade para o valor de emissão de SF6 calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver SF6. |
| OtherGHGs | Decimal | Valor de emissão de outros gases de efeito estufa calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não contiver outros GHGs. |
| OtherGHGsUnit | Cadeia de caracteres | Nome da unidade para outros valores de emissão de gases de efeito estufa calculados para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não contiver outros GHGs. |
Exemplos
No exemplo a seguir, a API é chamada com uma ID de dados de atividade válida, resultando em uma resposta sem erro.
Entrada:
{
"activityDataIds": [
"decc7c96-9180-ed11-aacf-000d3a1477fd”
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
Resultado:
[
{
"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
}
]
No exemplo a seguir, a API é chamada com uma ID de dados de atividade inválido, resultando em uma resposta de erro. O registro da atividade em questão tem o campo de custo ausente, o qual o modelo de cálculo requer na entrada. Como resultado, o registro de saída tem um erro JSON contendo a pilha de exceções de cálculo encontradas durante a avaliação do registro. O código de erro de serviço das exceções encontradas pode ajudar o usuário a entender o que deu errado. Nesse caso, EmissionCalculationActionFieldValueNullBlankException indica que um campo obrigatório está em branco.
Entrada:
{
"activityDataIds": [
"22a8b098-4b8b-ed11-aad1-000d3a5bc56a"
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
Resultado:
[
{
"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
}]
]
Invocação de APIs personalizadas
Para obter mais informações, acesse Criar e usar APIs personalizadas.
