AWS IoT Greengrass
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

ServiceNow MetricBase 集成 连接器

ServiceNow MetricBase 集成 连接器将时间序列指标从 Greengrass 设备发布到 ServiceNow MetricBase。这样一来,您可以存储、分析和可视化 Greengrass 核心环境中的时间序列数据,并对本地事件执行操作。

此连接器定期接收关于 MQTT 主题的时间序列数据,并将数据发布到 ServiceNow API。

您可以使用此连接器支持如下情况:

  • 根据从 Greengrass 设备收集的时间序列数据,创建基于阈值的提醒和警报。

  • 使用 Greengrass 设备中的时间服务数据,且自定义应用程序在 ServiceNow 平台上构建。

此连接器具有以下版本。

版本

ARN

2

arn:aws:greengrass:区域::/connectors/ServiceNowMetricBaseIntegration/versions/2

1

arn:aws:greengrass:区域::/connectors/ServiceNowMetricBaseIntegration/versions/1

有关版本更改的信息,请参阅更改日志

要求

此连接器具有以下要求:

  • AWS IoT Greengrass 核心软件 v1.7 or later。AWS IoT Greengrass 必须配置为支持本地密钥,如密钥要求中所述。

    注意

    其中包括允许访问您的 Secrets Manager 密钥。如果使用的是默认 Greengrass 服务角色,则Greengrass有权获得名称以 greengrass- 开头的密钥的值。

  • Python 版本 2.7 已安装在核心设备上并且已添加到 PATH 环境变量。

  • 激活了 MetricBase 订阅的 ServiceNow 账户。此外,必须在账户中创建指标和指标表。有关更多信息,请参阅 ServiceNow 文档中的 MetricBase

  • AWS Secrets Manager 中的文本类型密钥,存储 ServiceNow 实例的用户名和密码(用于基本身份验证)。该密钥必须包含“用户”和“密码”键及相应的值。有关更多信息,请参阅 AWS Secrets Manager 用户指南中的创建基本密钥

  • Greengrass 组中引用 Secrets Manager 密钥的密钥资源。有关更多信息,请参阅 将密钥部署到 AWS IoT Greengrass 核心

连接器参数

该连接器提供以下参数:

PublishInterval

将事件发布到 ServiceNow 需要等待的最长时间间隔(秒数)。最大值为 900。

当达到 PublishBatchSizePublishInterval 到期时,连接器会发布到 ServiceNow。

在控制台中显示名称:以秒为单位的发布间隔

必需:true

类型:string

有效值:1 - 900

有效模式:[1-9]|[1-9]\d|[1-9]\d\d|900

PublishBatchSize

可在发布到 ServiceNow 之前进行批处理的指标值的最大数量。

当达到 PublishBatchSizePublishInterval 到期时,连接器会发布到 ServiceNow。

在控制台中显示名称:发布批处理大小

必需:true

类型:string

有效模式:^[0-9]+$

InstanceName

用于连接到 ServiceNow 的实例的名称。

在控制台中显示名称:ServiceNow 实例的名称

必需:true

类型:string

有效模式:.+

DefaultTableName

包含与时间序列 MetricBase 数据库关联的 GlideRecord 的表的名称。输入消息负载中的 table 属性可用于覆盖该值。

在控制台中显示名称:包含指标的表的名称

必需:true

类型:string

有效模式:.+

MaxMetricsToRetain

替换为新指标之前可在内存中保存的指标的最大数量。

此限制适用于没有 Internet 连接并且连接器稍后开始缓冲要发布的指标的情况。当缓冲区已满时,最旧的指标将被新的指标所替换。

注意

如果连接器的宿主进程中断,则不会保存指标。例如,在组部署或设备重新启动期间,可能会发生此情况。

该值应大于批处理大小,且大到足以根据传入 MQTT 消息的速率来容纳消息。

在控制台中显示名称:内存中最多可保留的指标的数量

必需:true

类型:string

有效模式:^[0-9]+$

AuthSecretArn

AWS Secrets Manager 中用于存储 ServiceNow 用户名和密码的密钥。这必须是文本类型密钥。该密钥必须包含“用户”和“密码”键及相应的值。

在控制台中显示名称:身份验证密钥的 ARN

必需:true

类型:string

有效模式:arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

AuthSecretArn-ResourceId

组中引用 ServiceNow 凭证的 Secrets Manager 密钥的密钥资源。

在控制台中显示名称:身份验证令牌资源

必需:true

类型:string

有效模式:.+

创建连接器示例 (CLI)

以下 CLI 命令创建一个 ConnectorDefinition,其初始版本包含 ServiceNow MetricBase 集成连接器。

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyServiceNowMetricBaseIntegrationConnector", "ConnectorArn": "arn:aws:greengrass:区域::/connectors/ServiceNowMetricBaseIntegration/versions/2", "Parameters": { "PublishInterval" : "10", "PublishBatchSize" : "50", "InstanceName" : "myinstance", "DefaultTableName" : "u_greengrass_app", "MaxMetricsToRetain" : "20000", "AuthSecretArn" : "arn:aws-cn:secretsmanager:region:account-id:secret:greengrass-secret-hash", "AuthSecretArn-ResourceId" : "MySecretResource" } } ] }'

注意

该连接器中的 Lambda 函数具有很长的生命周期。

在 AWS IoT Greengrass 控制台 中,您可以从该组的 Connectors (连接器)页面添加一个连接器。有关更多信息,请参阅 Greengrass 连接器入门(控制台)

输入数据

此连接器接受关于 MQTT 主题的时间序列指标,并将指标发布到 ServiceNow。输入消息必须采用 JSON 格式。

主题筛选条件

servicenow/metricbase/metric

消息属性
request

有关表、记录和指标的信息。该请求表示时间序列 POST 请求中的 seriesRef 对象。有关更多信息,请参阅 Clotho 时间序列 API - POST

必需:true

类型:包含以下属性的 object

subject

表中特定记录的 sys_id

必需:true

类型:string

metric_name

指标字段名称。

必需:true

类型:string

table

用于存储记录的表的名称。指定该值以覆盖 DefaultTableName 参数。

必需:false

类型:string

value

单个数据点的值。

必需:true

类型:float

timestamp

单个数据点的时间戳。默认值为当前时间。

必需:false

类型:string

示例输入
{ "request": { "subject":"ef43c6d40a0a0b5700c77f9bf387afe3", "metric_name":"u_count", "table": "u_greengrass_app" "value": 1.0, "timestamp": "2018-10-14T10:30:00" } }

输出数据

此连接器将状态信息发布为输出数据。

主题筛选条件

servicenow/metricbase/metric/status

示例输出:成功
{ "response": { "metric_name": "Errors", "table_name": "GliderProd", "processed_on": "2018-10-14T10:35:00", "response_id": "khjKSkj132qwr23fcba", "status": "success", "values": [ { "timestamp": "2016-10-14T10:30:00", "value": 1.0 }, { "timestamp": "2016-10-14T10:31:00", "value": 1.1 } ] } }
示例输出:失败
{ "response": { "error": "InvalidInputException", "error_message": "metric value is invalid", "status": "fail" } }

注意

如果连接器检测到可重试的错误(例如,连接错误),它将在下一个批处理中重试发布操作。

示例用法

以下是 Lambda 功能将输入消息发送到连接器的示例。

注意

该 Python 功能使用 AWS IoT Greengrass Core 开发工具包 来发布 MQTT 消息。您可以使用以下 pip 命令在核心设备上安装 SDK 的 Python 版本:

pip install greengrasssdk
import greengrasssdk import json iot_client = greengrasssdk.client('iot-data') SEND_TOPIC = 'servicenow/metricbase/metric' def create_request_with_all_fields(): return { "request": { "subject": '2efdf6badbd523803acfae441b961961', "metric_name": 'u_count', "value": 1234, "timestamp": '2018-10-20T20:22:20', "table": 'u_greengrass_metricbase_test' } } def publish_basic_message(): messageToPublish = create_request_with_all_fields() print "Message To Publish: ", messageToPublish iot_client.publish(topic=SEND_TOPIC, payload=json.dumps(messageToPublish)) publish_basic_message() def function_handler(event, context): return

许可证

ServiceNow MetricBase 集成 连接器包含以下第三方软件/许可:

此连接器按照 Greengrass 核心软件许可协议发布。

Changelog

下表描述了连接器每个版本中所做的更改。

版本

更改

2

进行了修复,以减少过多的日志记录。

1

首次发布。

Greengrass 组一次只能包含一个版本的连接器。

另请参阅