API aberta da Gestão de notificações de eventos

A API aberta da Gestão de notificações de eventos fornece um endpoint para criar, atualizar e excluir eventos da tabela Eventos [em_event].

A API aberta da Gestão de notificações de eventos (sn_ind_tmf688) é uma implementação ServiceNow da especificação da API aberta do TM Fórum. Esta API é baseada no Guia do usuário da API de gestão de eventos TMF688 v4.0.0. Você pode localizar informações adicionais sobre alarmes no Guia do usuário da API de gestão de alarmes TMF642.

Esta API pode ser estendida para fazer personalizações em torno dos parâmetros necessários, validação do corpo da solicitação, operações REST adicionais e mapeamentos de campo. Para obter mais informações, consulte o Guia do desenvolvedor da Open API da Gestão de notificações de eventos.

API aberta da Gestão de notificações de eventos – POST instance_name/scope_id/GUID

Coloca a carga da solicitação associada na fila do NowMQ. Essa fila é processada em segundo plano para criar, atualizar e excluir eventos na tabela Eventos [em_event].

Este endpoint é diferente de outros endpoints na plataforma ServiceNow. Em vez de ter um endpoint para cada tarefa específica, como criar, atualizar e excluir, há apenas um único endpoint para todas as funcionalidades. O parâmetro eventType na carga da chamada determina a tarefa a ser executada com base no valor passado de AlarmCreateEvent, AlarmUpdateEventou AlarmDeleteEvent.

O formato da chamada REST também é diferente das implementações REST padrão. Cada sistema externo que usará esta API, como Kafka, monitores de banco de dados ou outras aplicações, deve primeiro ser registrado na plataforma ServiceNow. Eles também devem ter seu próprio webhook em vigor que usa as informações fornecidas durante o registro para gerar a assinatura necessária para chamar este endpoint, incluindo o instance_name, o scope_idda aplicação e o GUIDexclusivo. O GUID identifica o sistema de rede externo de onde veio a solicitação.

A carga que você passa para este endpoint deve estar correlacionada com a carga definida na inclusão de script TMFAlarmAPIConstants para o valor do parâmetro eventType correspondente. Todos os parâmetros passados na carga útil e não definidos no esquema são ignorados pelo endpoint.

• AlarmCreateEvent: ALARM_CREATE_EVENT_SCHEMA
• AlarmUpdateEvent: ALARM_CHANGE_EVENT_SCHEMA
• AlarmDeleteEvent: ALARM_DELETE_EVENT_SCHEMA

Formato da URL

URL padrão:<instance_name> /<scope_id> /<GUID>

Parâmetros de solicitação compatíveis

Tabela 1. Parâmetros de caminho

Nome	Descrição
Nenhum(a)

Tabela 2. Parâmetros de consulta

Nome	Descrição
Nenhum(a)

Tabela 3. Parâmetros do corpo da solicitação

Nome	Descrição
evento	Detalhes sobre o evento ocorrido. Tipo de dados: objeto "event": { "alarm": {Object} }
evento.alarme	Obrigatório quando eventType for AlarmCreateEvent. Detalhes sobre o alarme associado. Tipo de dados: objeto "alarm": { "affectedService": [Array], "alarmedObject": {Object}, "alarmType": "String", "crossedThresholdInformation": {Object}, "externalAlarmId": "String", "href": "String", "id": "String", "perceivedSeverity": "String", "probableCause": "String", "sourceSystemId": "String", "specificProblem": "String", }
evento.alarme.serviçoafetado	Lista de um ou mais serviços afetados pelo alarme. Tipo de dados: matriz de objetos "affectedService":[ { "href": "String", "id": "String" }, ]
evento.alarme.serviçoafetado.href	Referência de URL que fornece detalhes do serviço afetado. Tipo de dados: cadeia de caracteres
event.alarm.affectedService.id	Identificador do serviço afetado pelo alarme. Este valor é mapeado para o item de configuração (IC) afetado no alerta. Tipo de dados: cadeia de caracteres
event.alarm.alarmedObject	Necessário ao criar um evento. Detalhes do objeto de alarme. Tipo de dados: objeto "alarmedObject": { "href": "String", "id": "String" }
event.alarm.alarmedObject.href	Necessário ao criar um evento. Referência de URL para obter os detalhes do objeto de alarme. Tipo de dados: cadeia de caracteres
event.alarm.alarmedObject.id	Obrigatório quando eventType for AlarmCreateEvent. Identificador exclusivo do objeto de alarme. Este valor é mapeado para um IC no sistema. Tipo de dados: cadeia de caracteres
event.alarm.alarmType	Obrigatório quando eventType for AlarmCreateEvent. Tipo de alarme. Usado para categorizar o alarme. Por exemplo: "QualityOfServiceAlarm" Tipo de dados: cadeia de caracteres
event.alarm.crossedThresholdInfomation	Detalhes sobre o limite ultrapassado. Tipo de dados: objeto "crossedThresholdInformation": { "thresholdId": "String" }
event.alarm.crossedThresholdInfomation.thresholdId	Identificador exclusivo do limite que causou o alarme. Tipo de dados: cadeia de caracteres
event.alarm.externalAlarmId	Obrigatório quando eventType for AlarmCreateEvent. Obrigatório quando eventType for AlarmDeleteEvent ou AlarmChangeEvent se o parâmetro Id não for especificado. Identificador exclusivo do alarme do sistema de origem que publica o alarme. Tipo de dados: cadeia de caracteres
evento.alarme.href	Referência de URL para o alarme. Por exemplo: "http://api/alarm/ROUTER_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00" Tipo de dados: cadeia de caracteres
event.alarm.id	Obrigatório quando eventType for AlarmDeleteEvent ou AlarmChangeEvent se externalAlarmId não for especificado. Identificador exclusivo do alarme. Especificado pelo sistema proprietário do alarme. Por exemplo: "8675399" Tipo de dados: cadeia de caracteres
evento.alarme.severidadepercebida	Obrigatório quando eventType for AlarmCreateEvent. Possíveis gravidades associadas ao alarme. Os valores são consistentes com a recomendação X.733 do ITU-T. Depois que um alarme é limpo, sua severidade percebida é definida como "CLEAR" e não pode mais ser definida. Valores válidos: LIMPAR CRÍTICO PRINCIPAL BAIXO AVISO Tipo de dados: cadeia de caracteres
evento.alarme.provávelCausa	Obrigatório quando eventType for AlarmCreateEvent. Situação mais provável para acionar o alarme. Use com alarmType para qualificar o alarme. Os valores possíveis são consistentes com a Recomendação ITU-T X.733 ou 3GPP TS 32.111-2 Anexo B. Por exemplo: "Limite ultrapassado" Tipo de dados: cadeia de caracteres
event.alarm.sourceSystemId	Obrigatório quando eventType for AlarmCreateEvent. Identificador exclusivo do sistema de origem do alarme. Por exemplo: "SOURCE_SYSTEM_vManage_00000_000_00" Tipo de dados: cadeia de caracteres
evento.alarme.problemaespecífico	Problema específico que aciona o alarme. Use com o parâmetro probableCause para qualificar o alarme. Por exemplo: "Limite de tráfego de entrada ultrapassado" Tipo de dados: cadeia de caracteres
eventType	Obrigatório. Tipo de evento a ser processado. Valores válidos: AlarmChangeNotification AlarmCreateNotification AlarmDeleteNotification Tipo de dados: cadeia de caracteres

Cabeçalhos

Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

Tabela 4. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Oferece suporte somente a application/json.

Tabela 5. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum(a)

Códigos de status

Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

Tabela 6. Códigos de status

Código do status	Descrição
200	Retornado para cada chamada, independentemente do status de processamento real da chamada. Somente indica que o endpoint recebeu a solicitação.

Parâmetros do corpo da resposta

Nome	Descrição
Nenhum(a)	Este endpoint é assíncrono e, portanto, não retorna nenhum dado de resposta.

Solicitação de cURL

Veja a seguir a carga possível para um evento de alarme de criação. Este exemplo reflete os parâmetros que estão na implementação padrão (AlarmCreateEventSchema).

--data "{
  "eventType": "AlarmCreateNotification",
  "event": {
    "alarm": {
      "id": "",
      "externalAlarmId": "ext123456",
      "alarmType": "QualityOfServiceAlarm",
      "perceivedSeverity": "MINOR",
      "alarmedObject": {
        "id": "vManage_000000",
        "href": " http://api/alarmedobject/000000"
      },
      "probableCause": "Threshold crossed",
      "sourceSystemId": "SOURCE_SYSTEM_vManage_00000_000_00",
      "href": "http://api/alarm/ROUTER_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00",
      "specificProblem": "Inbound Traffic threshold crossed",
      "crossedThresholdInformation": {
        "thresholdId": "12fasdfasdfasd"
      },
      "affectedService": [
        {
          "id": "SD WAN Enterprise Solutions",
          "href": "http://api/service/vlan_dot0_dot0"
        }
      ]
    }
  }
}

Nenhuma resposta retornada.

Solicitação de cURL

Veja a seguir a carga possível para um evento de alarme de mudança. Este exemplo reflete os parâmetros que estão na implementação padrão (AlarmChangeEventSchema).

--data "{
  "eventType": "AlarmChangeEventSchema",
  "event": {
    "alarm": {
      "id": "",
      "externalAlarmId": "ext123456",
      "perceivedSeverity": "MAJOR",
      "probableCause": "Threshold crossed",
      "crossedThresholdInformation": {
        "thresholdId": "12fasdfasdfasd"
      },
      "affectedService": [
        {
          "id": "SD WAN Enterprise Solutions",
          "href": "http://api/service/vlan_dot0_dot0"
        }
      ]
    }
  }
}

Nenhuma resposta retornada.

Solicitação de cURL

Veja a seguir a carga possível para um evento de alarme de exclusão (limpar). Este exemplo reflete os parâmetros que estão na implementação padrão (AlarmDeleteEventSchema).

--data "{
  "eventType": "AlarmDeleteEventSchema",
  "event": {
    "alarm": {
      "id": "",
      "externalAlarmId": "ext123456",
      "perceivedSeverity": "MAJOR",
      "probableCause": "Threshold crossed",
      "crossedThresholdInformation": {
        "thresholdId": "12fasdfasdfasd"
      }
    }
  }
}

Nenhuma resposta retornada.