ServiceNow¶
ServiceNow 通知对象将观测云告警以 POST JSON 发送到 ServiceNow 接收入口。接收流程解析告警后,可按实例中的业务规则创建 Incident(故障工单)或触发其他处理流程。
本文使用 Scripted REST API:由 ServiceNow 管理员创建的自定义 HTTP 接口。接收脚本负责将告警字段转换为工单字段,并控制建单、去重、流转和状态维护。
在 ServiceNow 配置接收入口¶
创建 API 和资源需要 ServiceNow 的 web_service_admin 或 admin 角色。调用账号还需满足接收资源的认证策略、ACL(访问控制规则)及目标工单表的权限要求。
- 进入 All > System Web Services > Scripted REST APIs,新建 API,填写名称和 API ID。
- 在 Resources 关联列表中点击 New,创建资源,选择 POST,设置资源路径,例如
/notification。 - 保留或配置
application/json请求格式,在 Script 中通过request.body.data读取告警 JSON,并完成工单字段映射。可参考下方接收脚本示例。 - 在资源的 Security 中启用 Requires authentication。需要限制接口调用权限时,启用 Requires ACL authorization,选择
REST_Endpoint类型的 ACL;ACL 字段留空时使用父 API 的 ACL。接口调用权限和目标工单表、字段权限需分别配置。 - 按实例策略准备认证凭据。首次验证可使用实例允许的 Basic 认证,准备有调用和建单权限的集成账号及密码;也可使用Bearer Token 或 API Key。
- 保存资源,取得包含实例域名、命名空间、API ID 和资源路径的完整 HTTPS URL。
URL 的结构如下;version 仅在该 API 使用版本时填写,以资源实际生成的地址为准:
具体操作参见 Scripted REST API、创建 POST 资源、资源 ACL 配置和 API 访问策略。菜单和认证能力以客户实例版本为准。
接收脚本示例¶
以下示例将每条通知创建为一条 Incident:title 写入摘要,message 和完整通知 JSON 写入描述,保留工作空间、事件上下文及回链。一次聚合通知中的多个事件会保存在同一条工单内。
在测试实例中验证脚本,并按实例的必填字段、字段长度、应用访问权限及业务规则调整后使用。聚合通知较长时,按实例字段容量选择拆分建单或将完整内容另存附件。每次测试请求都会执行建单。
(function process(request, response) {
var data = request.body.data;
if (!data || typeof data !== 'object' || Array.isArray(data)) {
response.setStatus(400);
response.setBody({ error: 'JSON object required' });
return;
}
var incident = new GlideRecordSecure('incident');
incident.initialize();
if (!incident.canCreate() || !incident.short_description.canWrite() ||
!incident.description.canWrite()) {
response.setStatus(403);
response.setBody({ error: 'Incident creation is not permitted' });
return;
}
incident.setValue('short_description', String(data.title || 'Monitoring notification'));
incident.setValue('description', String(data.message || '') +
'\n\n' + JSON.stringify(data, null, 2));
var sysId = incident.insert();
if (!sysId) {
response.setStatus(500);
response.setBody({ error: 'Incident creation failed' });
return;
}
response.setStatus(201);
response.setBody({ sys_id: String(sysId), number: incident.getValue('number') });
})(request, response);
该示例通过 GlideRecordSecure 按当前调用用户的 ACL 执行建单。接收脚本也可根据业务需要,遍历 events 分别建单,或按事件标识更新已有记录。
脚本接口参见 ServiceNow Scripted REST 示例、记录创建权限 canCreate()、字段写入权限 canWrite()和 RESTAPIResponse。
在观测云新建通知对象¶
进入监控 > 通知对象管理 > 新建通知对象,选择 ServiceNow。
- 输入名称,用于在列表和告警策略中识别通知对象。名称在当前工作空间内唯一,最多 200 字。
- 在 Webhook 地址中填写上述 POST 资源的完整 HTTPS URL,使用最终接收地址。
- 认证方式选择 Basic,填写该入口允许的用户名和密码;或按接收端配置选择其他认证方式。
- 按需开启自定义请求头,填写接收端额外要求的键和值。
- 点击测试通知发送,预览并确认发送;在 ServiceNow 核对接收请求、脚本执行和生成的工单。
- 配置操作权限,确认保存。
- 在告警策略中选择该通知对象,配置需要发送的事件等级和范围。
认证方式与请求头¶
接收资源的 API 访问策略需要允许您选用的认证方式。平台按提供的凭据发送请求,令牌的获取和更新由您维护。
| 认证方式 | 填写内容 | 接收端准备 |
|---|---|---|
| Basic | 用户名、密码 | 使用实例允许的集成账号;用户名保持非空且不含冒号。 |
| Bearer Token | Token | 按实例 OAuth 配置取得有效的 Access Token,填写原值,系统添加 Bearer 前缀;到期或撤销后及时更新。 |
| API Key | 请求头名称、API Key | 完成下方 API Key 配置。请求头名称按实例配置填写,例如 x-sn-apikey;实例要求前缀时,填写包含前缀的完整 Key 值。 |
| 无认证 | — | 按接收资源的实际认证要求设置自定义请求头。 |
实例开始强制执行 Basic Auth Restriction 后,集成账号还需满足允许条件,例如设为 Web Services Access Only(仅 Web 服务访问)账号,或具有 snc_basic_auth_api_access 角色,由管理员按实例策略配置。
使用 API Key 时,配置人员需具备 api_service_admin、adaptive_auth_policy_admin 角色;实例需启用 API Key and HMAC Authentication 插件(com.glide.tokenbased_auth),并完成以下配置:
- 创建 API Key 的入站认证 Profile,认证参数选择请求头方式,例如
x-sn-apikey: Auth Header。 - 创建 REST API Key,关联调用用户,复制生成的 Token。
- 创建并启用 API 访问策略,将该认证 Profile 关联至目标 API 的 POST 资源和适用版本。
详细步骤参见 ServiceNow API Key 配置;Access Token 的获取参见 REST OAuth 示例。Basic 的实例限制参见 Basic authentication restriction。
自定义请求头名称按大小写无关去重;所选认证方式生成的请求头优先于同名自定义头。Content-Type 固定为 application/json,Accept 默认为 application/json;API Key 请求头名称需使用 Content-Type 以外的合法名称。
编辑凭据¶
同一地址、认证方式及身份下,编辑时密码、Token 或 API Key 留空可保留原值,输入新值可替换。更换地址、认证方式、用户名或 API Key 请求头名称后,需要填写对应凭据。
自定义请求头值加密保存。在上述配置保持一致时,已保存的同名请求头值留空可保留,输入新值可替换;删除行会移除该头。新增或重命名请求头,以及更换上述配置后,请填写完整的请求头值。
测试使用当前表单中的有效配置;保存后,后续告警使用新配置。
通知内容与告警聚合¶
ServiceNow 通知对象沿用简单 HTTP 请求的告警聚合形式,支持普通、规则聚合和智能聚合通知:
| 字段 | 含义 |
|---|---|
title、message、status |
当前通知的标题、正文和状态。 |
events |
事件列表。普通告警包含一个事件;聚合告警包含对应的一组事件,保留事件上下文和回链。 |
workspace_uuid、workspace_name |
事件所属工作空间的 ID 和名称。 |
monitor_checker_links |
规则聚合和智能聚合通知中的监控器名称与事件列表链接。 |
告警策略决定哪些事件组成同一条通知;通知内容构造完成后启动发送。配置了显式延迟的通知仍按指定时间发送。接收脚本按上述告警结构完成字段转换,再调用实例中的工单处理逻辑。
测试与排查¶
测试通知的字段以接收端实际收到的 JSON 为准。完成入口和认证测试后,再用实际普通、聚合告警验证字段映射及 events 的处理结果。
接收入口返回 HTTP 2xx,仅表示请求完成。请同时检查 ServiceNow 接收日志、脚本执行和工单字段,确认接收流程完成了预期动作。
| 现象 | 检查方式 |
|---|---|
| 认证失败或无访问权限 | 检查账号、令牌或 API Key 有效性,以及对应 POST 资源的访问策略和 ACL。 |
| 请求完成,工单未生成 | 检查接收脚本、目标表权限、实例必填字段及业务规则。 |
| 工单内容缺失 | 检查 request.body.data 的字段映射,用实际普通、聚合告警分别验证;聚合告警需处理 events 列表。 |
| 发送失败 | 检查最终 HTTPS 地址、证书和网络连通性。HTTP 3xx 重定向按发送失败处理。 |