ServiceNow MetricBase 集成连接器

警告

此连接器已进入生命周期延长阶段， Amazon IoT Greengrass 不会发布更新来提供功能、现有功能增强、安全补丁或错误修复。有关更多信息，请参阅 Amazon IoT Greengrass Version 1 维护政策。

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

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

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

根据从 Greengrass 设备收集的时间序列数据，创建基于阈值的提醒和警报。
将来自 Greengrass 设备的时间服务数据与基于平台构建的自定义应用程序一起使用。 ServiceNow

此连接器具有以下版本。

版本	ARN
4	`arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/4`
3	`arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/3`
2	`arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/2`
1	`arn:aws:greengrass:region::/connectors/ServiceNowMetricBaseIntegration/versions/1`

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

要求

此连接器具有以下要求：

Version 3 - 4

Amazon IoT Greengrass 核心软件 v1.9.3 或更高版本。 Amazon IoT Greengrass 必须配置为支持本地密钥，如密钥要求中所述。

注意
此要求包括允许访问您的 Secrets Manager 密钥。如果使用的是默认 Greengrass 服务角色，则 Greengrass 有权获得名称以 greengrass- 开头的密钥的值。
Python 版本 3.7 或 3.8 已安装在核心设备上，并已添加到 PATH 环境变量中。
注意
要使用 Python 3.8，请运行以下命令来创建从默认 Python 3.7 安装文件夹到已安装的 Python 3.8 二进制文件的符号链接。
```
sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7
```
这会将设备配置为满足 Amazon IoT Greengrass的 Python 要求。
已激活订阅的 ServiceNow 账户 MetricBase。此外，必须在账户中创建指标和指标表。有关更多信息，请参阅 ServiceNow 文档MetricBase中的。
中的一种文本类型密钥 Amazon Secrets Manager ，用于存储用户名和密码，以便通过基本身份验证登录您的 ServiceNow 实例。该密钥必须包含“用户”和“密码”键及相应的值。有关更多信息，请参阅 Amazon Secrets Manager 用户指南中的创建基本密钥。
Greengrass 组中引用 Secrets Manager 密钥的密钥资源。有关更多信息，请参阅将机密部署到核 Amazon IoT Greengrass 心。

Versions 1 - 2

Amazon IoT Greengrass 核心软件 v1.7 或更高版本。 Amazon IoT Greengrass 必须配置为支持本地密钥，如密钥要求中所述。

注意
此要求包括允许访问您的 Secrets Manager 密钥。如果使用的是默认 Greengrass 服务角色，则 Greengrass 有权获得名称以 greengrass- 开头的密钥的值。
Python 版本 2.7 已安装在核心设备上，并已添加到 PATH 环境变量中。
已激活订阅的 ServiceNow 账户 MetricBase。此外，必须在账户中创建指标和指标表。有关更多信息，请参阅 ServiceNow 文档MetricBase中的。
中的一种文本类型密钥 Amazon Secrets Manager ，用于存储用户名和密码，以便通过基本身份验证登录您的 ServiceNow 实例。该密钥必须包含“用户”和“密码”键及相应的值。有关更多信息，请参阅 Amazon Secrets Manager 用户指南中的创建基本密钥。
Greengrass 组中引用 Secrets Manager 密钥的密钥资源。有关更多信息，请参阅将机密部署到核 Amazon IoT Greengrass 心。

连接器参数

该连接器提供以下参数：

Version 4

PublishInterval

在发布事件之间等待的最大秒数 ServiceNow。最大值为 900。

连接器会在到达或PublishInterval到期 ServiceNow 时PublishBatchSize发布。

Amazon IoT 控制台中的显示名称：发布间隔（以秒为单位）

必需：true

类型：string

有效值：1 - 900

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

PublishBatchSize

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

连接器会在到达或PublishInterval到期 ServiceNow 时PublishBatchSize发布。

Amazon IoT 控制台中的显示名称：发布批次大小

必需：true

类型：string

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

InstanceName

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

Amazon IoT 控制台中的显示名称： ServiceNow 实例名称

必需：true

类型：string

有效模式：.+

DefaultTableName

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

Amazon IoT 控制台中的显示名称：包含指标的表的名称

必需：true

类型：string

有效模式：.+

MaxMetricsToRetain

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

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

注意

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

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

Amazon IoT 控制台中的显示名称：要在内存中保留的最大指标

必需：true

类型：string

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

AuthSecretArn

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

Amazon IoT 控制台中的显示名称：身份验证密钥的 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

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

Amazon IoT 控制台中的显示名称：身份验证令牌资源

必需：true

类型：string

有效模式：.+

IsolationMode

此连接器的容器化模式。默认值为GreengrassContainer，这意味着连接器在 Amazon IoT Greengrass 容器内的隔离运行时环境中运行。

注意

组的默认容器化设置不适用于连接器。

Amazon IoT 控制台中的显示名称：容器隔离模式

必需：false

类型：string

有效值：GreengrassContainer 或 NoContainer

有效模式：^NoContainer$|^GreengrassContainer$

Version 1 - 3

PublishInterval

在发布事件之间等待的最大秒数 ServiceNow。最大值为 900。

连接器会在到达或PublishInterval到期 ServiceNow 时PublishBatchSize发布。

Amazon IoT 控制台中的显示名称：发布间隔（以秒为单位）

必需：true

类型：string

有效值：1 - 900

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

PublishBatchSize

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

连接器会在到达或PublishInterval到期 ServiceNow 时PublishBatchSize发布。

Amazon IoT 控制台中的显示名称：发布批次大小

必需：true

类型：string

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

InstanceName

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

Amazon IoT 控制台中的显示名称： ServiceNow 实例名称

必需：true

类型：string

有效模式：.+

DefaultTableName

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

Amazon IoT 控制台中的显示名称：包含指标的表的名称

必需：true

类型：string

有效模式：.+

MaxMetricsToRetain

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

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

注意

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

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

Amazon IoT 控制台中的显示名称：要在内存中保留的最大指标

必需：true

类型：string

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

AuthSecretArn

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

Amazon IoT 控制台中的显示名称：身份验证密钥的 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

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

Amazon IoT 控制台中的显示名称：身份验证令牌资源

必需：true

类型：string

有效模式：.+

创建连接器示例 (Amazon CLI)

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


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

注意

此连接器中的 Lambda 函数的生命周期很长。

在 Amazon IoT Greengrass 控制台中，您可以从群组的 “连接器” 页面添加连接器。有关更多信息，请参阅 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"
    }
}

输出数据

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

订阅中的主题筛选条件

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"
    }
}

注意

如果连接器检测到可重试的错误（如连接错误），它会在下一批次中重试发布。

用法示例

使用以下概括步骤设置可用于尝试连接器的示例 Python 3.7 Lambda 函数。

注意

如果要使用其他 Python 运行时，您可以创建从 Python3.x 到 Python 3.7 的符号链接。
连接器入门（控制台）和连接器入门 (CLI) 主题包含详细步骤，说明如何配置和部署示例 Twilio 通知连接器。

确保满足连接器的要求。
创建并发布将输入数据发送到连接器的 Lambda 函数。

将示例代码保存为 PY 文件。下载并解压适用于 Python 的Amazon IoT Greengrass Core 软件开发工具包。然后，创建一个 zip 包，其中在根级别包含 PY 文件和 greengrasssdk 文件夹。此 zip 包是您上传到 Amazon Lambda的部署包。

创建 Python 3.7 Lambda 函数后，请发布函数版本并创建别名。
配置 Greengrass 组。
1. 通过别名来添加 Lambda 函数（推荐）。将 Lambda 生命周期配置为长时间生存（或在 CLI 中设置为 "Pinned": true）。
2. 添加所需的密钥资源并授予对 Lambda 函数的读取访问权限。
3. 添加连接器并配置其参数。
4. 添加允许连接器接收输入数据并针对支持的主题筛选条件发送输出数据的订阅。
  - 将 Lambda 函数设置为源，将连接器设置为目标，并使用支持的输入主题筛选条件。
  - 将连接器设置为源，将 Amazon IoT Core 设置为目标，并使用支持的输出主题筛选条件。您可以使用此订阅在 Amazon IoT 控制台中查看状态消息。
部署组。
在 Amazon IoT 控制台的 “测试” 页面上，订阅输出数据主题以查看来自连接器的状态消息。示例 Lambda 函数是长时间生存的，并且在部署组后立即开始发送消息。

完成测试后，您可以将 Lambda 生命周期设置为按需（或在 CLI 中设置为 "Pinned": false）并部署组。这会阻止函数发送消息。

示例

以下示例 Lambda 函数向连接器发送一条输入消息。


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 lambda_handler(event, context):
    return

许可证

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

pysnow/MIT

该连接器在 Greengrass Core 软件许可协议下发布。

更改日志

下表介绍每个版本连接器的更改。

版本	更改
4	增加了用于配置连接器容器化模式的 `IsolationMode` 参数。
3	已将 Lambda 运行时升级到 Python 3.7，这会更改运行时要求。
2	进行了修复，以减少过多的日志记录。
1	首次发布。

Greengrass 组在一个时间上只能包含一个版本的连接器。有关升级连接器版本的信息，请参阅升级连接器版本。

另请参阅

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

串行流

SNS