API de cálculo de emissão generalizada
Microsoft Cloud for Sustainability
Pode utilizar a API msdyn_runEmissionCalculationService para calcular as emissões de atividades utilizando num modelo de cálculo sem criar um perfil de cálculo. Como subscritor do Microsoft Sustainability Manager, pode utilizar este URL para aceder à API:
{organization url}/api/data/v{version}/msdyn_runEmissionCalculationService
Neste URL, o URL da organização refere-se ao URL base da organização Microsoft Sustainability Manager na qual está instalado e ao qual o utilizador pode aceder. Versão refere-se à versão da API Web (por exemplo, 9.2).
Obter IDs de entidade
Existem várias formas de obter os IDs das entidades, tais como os dados de atividade e o modelo de cálculo. Estas incluem a XRM WebAPI, a API do cliente e diretamente através do URL da entidade no Microsoft Sustainability Manager.
Parâmetros de entrada
Tal como a API personalizada Dataverse, o runtime da API de cálculo de emissão generalizada está limitado em dois minutos. Os cálculos mais longos irão exceder o limite de tempo, pelo que o tamanho da entrada está restringido de acordo com a tabela seguinte.
| Nome | Tipo | Necessária? | Descrição |
|---|---|---|---|
| activityIds | Matriz de cadeias de carateres | Sim | A lista de IDs dos registos de dados de atividade a serem utilizados no cálculo. É possível incluir até 500 IDs de atividade na entrada. |
| calculationModelId | Cadeia (de carateres) | Sim | O ID do modelo de cálculo a ser utilizado no cálculo de emissões. |
| versão | Cadeia (de carateres) | Não | O número de versão da API identifica a versão da API que deve ser invocada. Atualmente a única versão disponível é a 1.0.0. Se não for especificado, será utilizada a versão mais recente. |
Parâmetros de saída
Ao nível mais alto, a saída é uma cadeia JSON que contém uma lista de entidades de saída de emissão generalizada. Para cada atividade elegível, a entidade de saída poderá conter emissões avaliadas ou os erros encontrados durante o cálculo com base no êxito do cálculo. Verifique sempre o sinalizador IsErrorRecord de um registo de saída antes de o tentar aceder.
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 generalizada de emissão devolve uma lista destas entidades, com cada entidade correspondente a um registo de dados de atividade elegível na entrada.
A entidade de saída tem os seguintes atributos:
| Nome | Tipo | Descrição |
|---|---|---|
| ActivityId | Cadeia (de carateres) | O ID do registo de dados de atividade utilizado para o cálculo. |
| ActivityName | Cadeia (de carateres) | O nome do registo de dados de atividade utilizado para o cálculo. |
| IsErrorRecord | Booleano | Um valor booleano que indica se o cálculo desta determinada atividade encontrou erros. Se for verdadeiro, o cálculo falhou e os erros encontrados podem ser visualizados através do atributo ErrorJson. |
| ErrorJson | Cadeia (de carateres) | Cadeia JSON que representa quaisquer erros de cálculo encontrados durante o processamento desta determinada atividade. Este valor é nulo se IsErrorRecord for false. |
| Nome | Cadeia (de carateres) | Nome da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro. |
| CH4 | Decimal | Valor CH4 da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver CH4. |
| CH4Unit | Cadeia (de carateres) | Nome da unidade para o valor CH4 da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver CH4. |
| CO2 | Decimal | Valor CO2 da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver CO2. |
| CO2Unit | Cadeia (de carateres) | Nome da unidade para o valor CO2 da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver CO2. |
| CO2e | Decimal | Valor CO2e da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver CO2e. |
| CO2eUnit | Cadeia (de carateres) | Nome da unidade para o valor CO2e da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver CO2e. |
| HFCs | Decimal | Valor HFCs da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver HFCs. |
| HFCsUnit | Cadeia (de carateres) | Nome da unidade para o valor HFCs da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver HFCs. |
| N2O | Decimal | Valor N2O da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver N2O. |
| N2OUnit | Cadeia (de carateres) | Nome da unidade para o valor N2O da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver N2O. |
| NF3 | Decimal | Valor NF3 da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver NF3. |
| NF3Unit | Cadeia (de carateres) | Nome da unidade para o valor NF3 da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver NF3. |
| PFCs | Decimal | Valor PFCs da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver PFCs. |
| PFCsUnit | Cadeia (de carateres) | Nome da unidade para o valor PFCs da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver PFCs. |
| SF6 | Decimal | Valor SF6 da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver SF6. |
| SF6Unit | Cadeia (de carateres) | Nome da unidade para o valor SF6 da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver SF6. |
| OtherGHGs | Decimal | Outro valor de gases com efeito de estufa da emissão calculado para esta atividade. Este valor é 0 se IsErrorRecord for verdadeiro ou se a emissão não tiver outros GHGs. |
| OtherGHGsUnit | Cadeia (de carateres) | Nome da unidade oara outro valor de gases com efeito de estufa da emissão calculado para esta atividade. Este valor é nulo se IsErrorRecord for verdadeiro ou se a emissão não tiver outros GHGs. |
Exemplos
No exemplo seguinte, a API é invocada com um ID de dados de atividade válido que resulta numa resposta de não-erro.
Entrada:
{
"activityDataIds": [
"decc7c96-9180-ed11-aacf-000d3a1477fd”
],
"calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",
"version": "1.0.0"
}
Saída:
[
{
"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 seguinte, a API é invocada com um ID de dados de atividade inválido que resulta numa resposta de erro. Falta o campo de custo no registo de atividade em questão, que é exigido pelo modelo de cálculo da entrada. Como resultado, o registo de saída tem um erro JSON que contém a pilha de exceções de cálculo encontradas durante a avaliação do registo. O código de erro de serviço das exceções encontradas pode ajudar o utilizador a compreender o que correu mal. Neste caso, EmissionCalvalueActionFieldValueNullBlankException 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"
}
Saída:
[
{
"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
}]
]
Invocvar APIs Personalizadas
Para mais informações, aceda a Criar e utilizar APIs Personalizadas.
