支援終止通知：2026 年 10 月 7 日 AWS 將停止 的支援 AWS IoT Greengrass Version 1。2026 年 10 月 7 日之後，您將無法再存取 AWS IoT Greengrass V1 資源。如需詳細資訊，請造訪[從 遷移 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。

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

# ServiceNow MetricBase 整合連接器
<a name="servicenow-connector"></a>

**警告**  <a name="connectors-extended-life-phase-warning"></a>
此連接器已進入*延長生命週期階段*， AWS IoT Greengrass 且不會發佈提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。

ServiceNow MetricBase 整合[連接器](connectors.md)會將時間序列指標從 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](#servicenow-connector-changelog)。

## 要求
<a name="servicenow-connector-req"></a>

此連接器有下列要求：

------
#### [ Version 3 - 4 ]
+ <a name="conn-req-ggc-v1.9.3-secrets"></a>AWS IoT Greengrass 核心軟體 v1.9.3 或更新版本。 AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。
**注意**  
此要求包括允許存取您的 Secrets Manager 秘密。如果您使用的是預設 Greengrass 服務角色，Greengrass 具有許可，可取得名稱開頭為 *greengrass-* 的秘密值。
+ <a name="conn-req-py-3.7-and-3.8"></a>安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 3.7 或 3.8 版。
**注意**  <a name="use-runtime-py3.8"></a>
若要使用 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 需求。
+ <a name="conn-servicenow-req-servicenow-account"></a>具有 MetricBase 有效訂閱的 ServiceNow 帳戶。此外，帳戶中必須建立指標和指標資料表。如需詳細資訊，請參閱 ServiceNow 文件中的 [MetricBase](https://docs.servicenow.com/bundle/london-servicenow-platform/page/administer/metricbase/concept/metricbase.html)。
+ <a name="conn-servicenow-req-secret"></a>在 中 AWS Secrets Manager 存放使用者名稱和密碼的文字類型秘密，以使用基本身分驗證登入您的 ServiceNow 執行個體。此私密必須包含「使用者」和「密碼」金鑰與對應的值。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。
+ Greengrass 群組中參考 Secrets Manager 秘密的秘密資源。如需詳細資訊，請參閱[將秘密部署到 AWS IoT Greengrass 核心](secrets.md)。

------
#### [ Versions 1 - 2 ]
+ <a name="conn-req-ggc-v1.7.0-secrets"></a>AWS IoT Greengrass 核心軟體 v1.7 或更新版本。 AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。
**注意**  
此要求包括允許存取您的 Secrets Manager 秘密。如果您使用預設 Greengrass 服務角色，Greengrass 具有許可，可取得名稱開頭為 *greengrass-* 的秘密值。
+ [Python](https://www.python.org/) 2.7 版安裝在核心裝置上，並新增至 PATH 環境變數。
+ <a name="conn-servicenow-req-servicenow-account"></a>具有 MetricBase 有效訂閱的 ServiceNow 帳戶。此外，帳戶中必須建立指標和指標資料表。如需詳細資訊，請參閱 ServiceNow 文件中的 [MetricBase](https://docs.servicenow.com/bundle/london-servicenow-platform/page/administer/metricbase/concept/metricbase.html)。
+ <a name="conn-servicenow-req-secret"></a>在 中 AWS Secrets Manager 存放使用者名稱和密碼的文字類型秘密，以使用基本身分驗證登入您的 ServiceNow 執行個體。此私密必須包含「使用者」和「密碼」金鑰與對應的值。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。
+ Greengrass 群組中參考 Secrets Manager 秘密的秘密資源。如需詳細資訊，請參閱[將秘密部署到 AWS IoT Greengrass 核心](secrets.md)。

------

## 連接器參數
<a name="servicenow-connector-param"></a>

此連接器提供下列參數：

------
#### [ Version 4 ]

`PublishInterval`  <a name="service-now-PublishInterval"></a>
將事件發佈到 ServiceNow 之間等待的秒數上限。最大值為 900。  
連接器`PublishBatchSize`會在達到或`PublishInterval`過期時發佈至 ServiceNow。  
在 AWS IoT 主控台中顯示名稱：以**秒為單位發佈間隔**  
必要： `true`  
類型：`string`  
有效值：`1 - 900`  
有效模式： `[1-9]|[1-9]\d|[1-9]\d\d|900`

`PublishBatchSize`  <a name="service-now-PublishBatchSize"></a>
發佈到 ServiceNow 之前可批次處理的指標值數量上限。  
連接器`PublishBatchSize`會在達到或`PublishInterval`過期時發佈至 ServiceNow。  
在 AWS IoT 主控台中顯示名稱：**發佈批次大小**  
必要： `true`  
類型：`string`  
有效模式： `^[0-9]+$`

`InstanceName`  <a name="service-now-InstanceName"></a>
用於連接到 ServiceNow 的執行個體名稱。  
在 AWS IoT 主控台中顯示名稱：**ServiceNow 執行個體的名稱**  
必要： `true`  
類型：`string`  
有效模式： `.+`

`DefaultTableName`  <a name="service-now-DefaultTableName"></a>
資料表的名稱，其中包含與時間序列 MetricBase 資料庫相關聯的 `GlideRecord`。輸入訊息承載中的 `table` 屬性可用來覆寫這個值。  
在 AWS IoT 主控台中顯示名稱：**要包含指標的資料表名稱**  
必要： `true`  
類型：`string`  
有效模式： `.+`

`MaxMetricsToRetain`  <a name="service-now-MaxMetricsToRetain"></a>
由新指標取代之前在記憶體中儲存的指標數目上限。  
在沒有網際網路連線且連接器開始緩衝指標來稍後發佈時，就受此限制。當緩衝區已滿時，新指標會取代最舊指標。  
如果連接器的主機程序中斷，則不會儲存指標。例如，在群組部署或裝置重新啟動期間就可能發生這種情況。
這個值應該大於批次大小，且根據 MQTT 訊息的傳入速率，大小足夠保留訊息。  
在 AWS IoT 主控台中顯示名稱：**記憶體中保留的指標上限**  
必要： `true`  
類型：`string`  
有效模式： `^[0-9]+$`

`AuthSecretArn`  <a name="service-now-AuthSecretArn"></a>
中 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`  <a name="service-now-AuthSecretArn-ResourceId"></a>
群組中參考 ServiceNow 登入資料的 Secrets Manager 秘密的秘密資源。  
 AWS IoT 主控台中的顯示名稱：**Auth 字符資源**  
必要： `true`  
類型：`string`  
有效模式： `.+`

`IsolationMode`  <a name="IsolationMode"></a>
此連接器的[容器化](connectors.md#connector-containerization)模式。預設值為 `GreengrassContainer`，這表示連接器在 AWS IoT Greengrass 容器內的隔離執行時間環境中執行。  
群組的預設容器化設定不會套用至連接器。
在 AWS IoT 主控台中顯示名稱：**容器隔離模式**  
必要： `false`  
類型：`string`  
有效值：`GreengrassContainer` 或 `NoContainer`  
有效模式： `^NoContainer$|^GreengrassContainer$`

------
#### [ Version 1 - 3 ]

`PublishInterval`  <a name="service-now-PublishInterval"></a>
將事件發佈到 ServiceNow 之間等待的秒數上限。最大值為 900。  
連接器`PublishBatchSize`會在達到或`PublishInterval`過期時發佈至 ServiceNow。  
在 AWS IoT 主控台中顯示名稱：以**秒為單位發佈間隔**  
必要： `true`  
類型：`string`  
有效值：`1 - 900`  
有效模式： `[1-9]|[1-9]\d|[1-9]\d\d|900`

`PublishBatchSize`  <a name="service-now-PublishBatchSize"></a>
發佈到 ServiceNow 之前可批次處理的指標值數量上限。  
連接器`PublishBatchSize`會在達到或`PublishInterval`過期時發佈至 ServiceNow。  
在 AWS IoT 主控台中顯示名稱：**發佈批次大小**  
必要： `true`  
類型：`string`  
有效模式： `^[0-9]+$`

`InstanceName`  <a name="service-now-InstanceName"></a>
用於連接到 ServiceNow 的執行個體名稱。  
在 AWS IoT 主控台中顯示名稱：**ServiceNow 執行個體的名稱**  
必要： `true`  
類型：`string`  
有效模式： `.+`

`DefaultTableName`  <a name="service-now-DefaultTableName"></a>
資料表的名稱，其中包含與時間序列 MetricBase 資料庫相關聯的 `GlideRecord`。輸入訊息承載中的 `table` 屬性可用來覆寫這個值。  
在 AWS IoT 主控台中顯示名稱：**要包含指標的資料表名稱**  
必要： `true`  
類型：`string`  
有效模式： `.+`

`MaxMetricsToRetain`  <a name="service-now-MaxMetricsToRetain"></a>
由新指標取代之前在記憶體中儲存的指標數目上限。  
在沒有網際網路連線且連接器開始緩衝指標來稍後發佈時，就受此限制。當緩衝區已滿時，新指標會取代最舊指標。  
如果連接器的主機程序中斷，則不會儲存指標。例如，在群組部署或裝置重新啟動期間就可能發生這種情況。
這個值應該大於批次大小，且根據 MQTT 訊息的傳入速率，大小足夠保留訊息。  
在 AWS IoT 主控台中顯示名稱：**記憶體中保留的指標上限**  
必要： `true`  
類型：`string`  
有效模式： `^[0-9]+$`

`AuthSecretArn`  <a name="service-now-AuthSecretArn"></a>
中 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`  <a name="service-now-AuthSecretArn-ResourceId"></a>
群組中參考 ServiceNow 登入資料的 Secrets Manager 秘密的秘密資源。  
在 AWS IoT 主控台中顯示名稱：**Auth 字符資源**  
必要： `true`  
類型：`string`  
有效模式： `.+`

------

### 建立範例連接器 (AWS CLI)
<a name="servicenow-connector-create"></a>

下列 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 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。

在 AWS IoT Greengrass 主控台中，您可以從群組的連接器頁面新增**連接器**。如需詳細資訊，請參閱[Greengrass 連接器入門 (主控台)](connectors-console.md)。

## 輸入資料
<a name="servicenow-connector-data-input"></a>

此連接器接受 MQTT 主題上的時間序列指標，並將指標發佈至 ServiceNow。輸入訊息必須是 JSON 格式。

<a name="topic-filter"></a>**訂閱中的主題篩選條件**  
`servicenow/metricbase/metric`

**訊息屬性**    
`request`  
資料表、記錄和指標的相關資訊。這個請求代表時間序列 POST 請求中的 `seriesRef` 物件。如需詳細資訊，請參閱 [Clotho 時間序列 API - POST](https://docs.servicenow.com/bundle/london-application-development/page/integrate/inbound-rest/concept/Clotho-Time-Series-API.html#clotho-POST-put)。  
  
必要： `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"
    }
}
```

## 輸出資料
<a name="servicenow-connector-data-output"></a>

這個連接器會將狀態資訊發佈為輸出資料，且主題為 MQTT。

<a name="topic-filter"></a>**訂閱中的主題篩選條件**  
`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"
    }
}
```
如果連接器偵測到可重試的錯誤 （例如連線錯誤），則會在下一個批次中重試發佈。

## 使用範例
<a name="servicenow-connector-usage"></a>

<a name="connectors-setup-intro"></a>使用下列高階步驟來設定範例 Python 3.7 Lambda 函數，您可以用來嘗試連接器。

**注意**  <a name="connectors-setup-get-started-topics"></a>
如果您使用其他 Python 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。
[連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。

1. 確定您符合連接器的[要求](#servicenow-connector-req)。

1. <a name="connectors-setup-function"></a>建立並發佈 Lambda 函數，將輸入資料傳送至連接器。

   將[範例程式碼](#servicenow-connector-usage-example)儲存為 PY 檔案。<a name="connectors-setup-function-sdk"></a>下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 核心 SDK](lambda-functions.md#lambda-sdks-core)。然後，建立在根層級包含 PY 檔案和 `greengrasssdk` 資料夾的 zip 套件。此 zip 套件是您上傳至 的部署套件 AWS Lambda。

   <a name="connectors-setup-function-publish"></a>建立 Python 3.7 Lambda 函數後，發佈函數版本並建立別名。

1. 設定 Greengrass 群組。

   1. <a name="connectors-setup-gg-function"></a>依別名新增 Lambda 函數 （建議）。將 Lambda 生命週期設定為長期 （或在 CLI `"Pinned": true`中）。

   1. <a name="connectors-setup-secret-resource"></a>新增必要的秘密資源，並授予 Lambda 函數的讀取存取權。

   1. 新增連接器並設定其[參數](#servicenow-connector-param)。

   1. 新增訂閱，允許連接器在支援主題篩選條件上接收[輸入資料](#servicenow-connector-data-input)並傳送[輸出資料](#servicenow-connector-data-output)。
      + <a name="connectors-setup-subscription-input-data"></a>將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。
      + <a name="connectors-setup-subscription-output-data"></a>將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。

1. <a name="connectors-setup-deploy-group"></a>部署群組。

1. <a name="connectors-setup-test-sub"></a>在 AWS IoT 主控台**的測試**頁面上，訂閱輸出資料主題，以檢視連接器的狀態訊息。Lambda 函數範例為長期函數，並在部署群組後立即開始傳送訊息。

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

### 範例
<a name="servicenow-connector-usage-example"></a>

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

## 授權
<a name="servicenow-connector-license"></a>

ServiceNow MetricBase 整合連接器包含下列第三方軟體/授權：
+ [pysnow](https://github.com/rbw/pysnow)/MIT

此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。

## 變更記錄
<a name="servicenow-connector-changelog"></a>

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


| 版本 | 變更 | 
| --- | --- | 
| 4 | <a name="isolation-mode-changelog"></a>已新增 `IsolationMode` 參數，以設定連接器的容器化模式。 | 
| 3 | <a name="upgrade-runtime-py3.7"></a>將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 | 
| 2 | 可減少過多記錄的修正。 | 
| 1 | 初始版本。  | 

<a name="one-conn-version"></a>Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。

## 另請參閱
<a name="servicenow-connector-see-also"></a>
+ [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md)
+ [Greengrass 連接器入門 (主控台)](connectors-console.md)
+ [Greengrass 連接器入門 (CLI)](connectors-cli.md)