ServiceNow MetricBase 整合連接器 - AWS IoT Greengrass
要求參數輸入資料輸出資料使用範例licenseChangelog另請參閱

AWS IoT Greengrass Version 1 於 2023 年 6 月 30 日進入延長壽命階段。如需詳細資訊，請參閱 AWS IoT Greengrass V1 維護政策 。在此日期之後， AWS IoT Greengrass V1 不會發佈提供功能、增強功能、錯誤修正或安全修補程式的更新。在 上執行的裝置 AWS IoT Greengrass V1 不會中斷，並會繼續運作和連線至雲端。我們強烈建議您遷移至 AWS IoT Greengrass Version 2，這會新增重要的新功能，並支援其他平台 。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

ServiceNow MetricBase 整合連接器

警告

此連接器已移至延長生命階段，以及AWS IoT Greengrass不會發行提供功能、增強現有功能、安全性修補程式或錯誤修正的更新。如需詳細資訊，請參閱 AWS 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

如需版本變更的詳細資訊，請參閱 Changelog。

要求

此連接器有下列要求：

Version 3 - 4

  • AWS IoT Greengrass核心軟體 1.9.3 版或更新版本。AWS IoT Greengrass必須設定為支援本機私密，如中所述Secrets 要求。

    注意

    這項要求包括允許存取您的 Secrets Manager 秘密。如果您使用的是預設 Greengrass 服務角色，Greengrass 有權取得名稱開頭為的私密資料值。greengrass-。

  • 蟒蛇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

    這會設定您的裝置以符合 AWS IoT Greengrass 的 Python 需求。

  • 一個 ServiceNow 具有訂閱的帳戶 MetricBase。In此外，帳戶中必須建立指標和指標資料表。如需詳細資訊，請參閱「」MetricBase中的 ServiceNow 文件中)。

  • 中的文字類型私密AWS Secrets Manager，存放用於登入您的使用者名稱和密碼 ServiceNow 具有基本身份驗證的實例。此私密必須包含「使用者」和「密碼」金鑰與對應的值。如需詳細資訊，請參閱「」建立基本秘密中的AWS Secrets Manager使用者指南。

  • Greengrass 群組中參考秘密管理員私密的私密資源。如需詳細資訊，請參閱 將私密部署至 AWS IoT Greengrass 核心。

Versions 1 - 2

  • AWS IoT Greengrass核心軟體 1.7 版或更新版本。AWS IoT Greengrass必須設定為支援本機私密，如中所述Secrets 要求。

    注意

    這項要求包括允許存取您的 Secrets Manager 秘密。如果您使用的是預設 Greengrass 服務角色，Greengrass 有權取得名稱開頭為的私密資料值。greengrass-。

  • 蟒蛇2.7 版已安裝在核心裝置上並已新增至 PATH 環境變數。

  • 一個 ServiceNow 具有訂閱的帳戶 MetricBase。In此外，帳戶中必須建立指標和指標資料表。如需詳細資訊，請參閱「」MetricBase中的 ServiceNow 文件中)。

  • 中的文字類型私密AWS Secrets Manager，存放用於登入您的使用者名稱和密碼 ServiceNow 具有基本身份驗證的實例。此私密必須包含「使用者」和「密碼」金鑰與對應的值。如需詳細資訊，請參閱「」建立基本秘密中的AWS Secrets Manager使用者指南。

  • Greengrass 群組中參考秘密管理員私密的私密資源。如需詳細資訊，請參閱 將私密部署至 AWS IoT Greengrass 核心。

連接器參數

此連接器提供下列參數：

Version 4
PublishInterval

將事件發佈到的秒數上限 ServiceNow。最大值為 900。

連接器會發佈到 ServiceNow 何時PublishBatchSize達到或PublishInterval過期。

中的顯示名稱AWS IoT主控台：Publish interval in seconds

必要：true

類型：string

有效值：1 - 900

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

PublishBatchSize

發佈到之前可批次處理的指標值數量上限 ServiceNow。

連接器會發佈到 ServiceNow 何時PublishBatchSize達到或PublishInterval過期。

中的顯示名稱AWS IoT主控台：發佈批次大小

必要：true

類型：string

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

InstanceName

用於連接到的執行個體名稱 ServiceNow。

中的顯示名稱AWS IoT主控台：的名稱 ServiceNow 執行個體

必要：true

類型：string

有效模式：.+

DefaultTableName

包含的表格名稱GlideRecord與時間序列相關 MetricBase 資料庫。輸入訊息承載中的 table 屬性可用來覆寫這個值。

中的顯示名稱AWS IoT主控台：Name in table in metric (要包含指標的資料表格名稱)

必要：true

類型：string

有效模式：.+

MaxMetricsToRetain

由新指標取代之前在記憶體中儲存的指標數目上限。

在沒有網際網路連線且連接器開始緩衝指標來稍後發佈時，就受此限制。當緩衝區已滿時，新指標會取代最舊指標。

注意

如果連接器的主機程序中斷，則不會儲存指標。例如，在群組部署或裝置重新啟動期間就可能發生這種情況。

這個值應該大於批次大小，且根據 MQTT 訊息的傳入速率，大小足夠保留訊息。

中的顯示名稱AWS IoT主控台：記憶體中的指標上限

必要：true

類型：string

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

AuthSecretArn

秘密的必要項目AWS Secrets Manager存放的必要項目 ServiceNow 使用者名稱和密碼。這必須是文字類型私密。此私密必須包含「使用者」和「密碼」金鑰與對應的值。

中的顯示名稱AWS 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 登入資料。

中的顯示名稱AWS IoT主控台：Auth 字符資源

必要：true

類型：string

有效模式：.+

IsolationMode

此連接器的容器化模式。預設值為 GreengrassContainer，這表示連接器會在 AWS IoT Greengrass 容器內的隔離執行階段環境中執行。

注意

群組的預設容器化設定不會套用至連接器。

中的顯示名稱AWS IoT主控台：Container 隔離模式

必要：false

類型：string

有效值：GreengrassContainer 或 NoContainer

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

Version 1 - 3
PublishInterval

發佈事件之間等待的秒數上限 ServiceNow。最大值為 900。

連接器會發佈到 ServiceNow 何時PublishBatchSize達到或PublishInterval過期。

中的顯示名稱AWS IoT主控台：Publish interval in seconds

必要：true

類型：string

有效值：1 - 900

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

PublishBatchSize

發佈到之前可批次處理的指標值數量上限 ServiceNow。

連接器會發佈到 ServiceNow 何時PublishBatchSize達到或PublishInterval過期。

中的顯示名稱AWS IoT主控台：發佈批次大小

必要：true

類型：string

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

InstanceName

用於連接到的執行個體名稱 ServiceNow。

中的顯示名稱AWS IoT主控台：的名稱 ServiceNow 執行個體

必要：true

類型：string

有效模式：.+

DefaultTableName

包含的表格名稱GlideRecord與時間序列相關 MetricBase 資料庫。輸入訊息承載中的 table 屬性可用來覆寫這個值。

中的顯示名稱AWS IoT主控台：Name in table in metric (要包含指標的資料表格名稱)

必要：true

類型：string

有效模式：.+

MaxMetricsToRetain

由新指標取代之前在記憶體中儲存的指標數目上限。

在沒有網際網路連線且連接器開始緩衝指標來稍後發佈時，就受此限制。當緩衝區已滿時，新指標會取代最舊指標。

注意

如果連接器的主機程序中斷，則不會儲存指標。例如，在群組部署或裝置重新啟動期間就可能發生這種情況。

這個值應該大於批次大小，且根據 MQTT 訊息的傳入速率，大小足夠保留訊息。

中的顯示名稱AWS IoT主控台：記憶體中的指標上限

必要：true

類型：string

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

AuthSecretArn

秘密的必要項目AWS Secrets Manager存放的必要項目 ServiceNow 使用者名稱和密碼。這必須是文字類型私密。此私密必須包含「使用者」和「密碼」金鑰與對應的值。

中的顯示名稱AWS 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 登入資料。

中的顯示名稱AWS IoT主控台：Auth 字符資源

必要：true

類型：string

有效模式：.+

建立範例連接器 (AWS 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 函數具有長期生命週期。

在 中AWS 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

輸出範例：Success
{
    "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
            }
        ]
    }
}
輸出範例：Failure (失敗)
{
    "response": {
        "error": "InvalidInputException",
        "error_message": "metric value is invalid",
        "status": "fail"
    }
}
注意

如果連接器偵測到可重試的錯誤 (例如，連線錯誤)，它會在下一個批次中重試發佈。

使用範例

使用下列高階步驟，設定可用來試用連接器的範例 Python 3.7 Lambda 函數。

注意

  • 如果您使用其他 Python 執行時間，則可以建立從 Python 3.x 到 Python 3.7 的符號連結。

  • 連接器入門 (主控台) 和 連接器入門 (CLI) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。

  1. 確定您符合連接器的要求。

  2. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。

    將範例程式碼儲存為 PY 檔案。下載並解壓縮AWS IoT Greengrass適用於 Python 的核心 SDK。然後，建立在根層級包含 PY 檔案和 greengrasssdk 資料夾的 zip 套件。此 zip 套件是您上傳至的部署套件AWS Lambda。

    建立 Python 3.7 Lambda 函數後，請發佈函數版本並建立別名。

  3. 設定 Greengrass 群組。

    1. 根據別名新增 Lambda 函數的別名 (建議使用)。將 Lambda 生命週期設定為長時間 (或"Pinned": true在 CLI 中)。

    2. 新增所需的私密資源，並授與 Lambda 函數的讀取存取權。

    3. 新增連接器並設定其參數。

    4. 新增訂閱，允許連接器在支援主題篩選條件上接收輸入資料並傳送輸出資料。

      • 將 Lambda 函數設為來源、將連接器設為目標，並使用支援的輸入主題篩選條件。

      • 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱來檢視中的狀態訊息AWS IoTconsole (&C;

  4. 部署群組。

  5. 在 中AWS IoT主控台、測試頁面上的訂閱輸出資料主題，以檢視來自連接器的狀態訊息。範例 Lambda 函數具有長時間的生命週期，而且在部署完群組後會立即開始傳送訊息。

    完成測試後，您可以將 Lambda 生命週期設為隨需 (或"Pinned": false(在 CLI 中) 並部署群組。這會讓函數停止傳送訊息。

範例

下列範例 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

license

所以此 ServiceNow MetricBase 整合連接器包含以下第三方軟體/授權：

此連接器會在Greengrass Core 軟體授權合約。

Changelog

下表說明連接器每個版本的變更。

版本

變更

4

已新增 IsolationMode 參數，以設定連接器的容器化模式。

3

已將 Lambda 執行時間升級至 Python 3.7，這會改變執行時間要求。

2

可減少過多記錄的修正。

1

初始版本。

Greengrass 群組一次只能包含連接器的一個版本。若要取得有關升級連接器版本的資訊，請參閱升級連接器版本。

另請參閱