使用 AWS IoT Core 規則導入資料 - AWS IoT SiteWise

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

使用 AWS IoT Core 規則導入資料

您可以使用 AWS IoT Core 中的規則,將資料從 AWS IoT 物件和其他 AWS 服務傳送到 AWS IoT SiteWise。規則會轉換 MQTT 訊息並執行動作,以與 AWS 服務進行互動。所以此AWS IoT SiteWise規則動作會將訊息資料轉送到BatchPutAssetProperty數值操作從AWS IoT SiteWiseAPI。如需詳細資訊,請參閱「」規則AWS IoT SiteWise行動中的AWS IoT開發人員指南

您可以遵循教學課程的指示,逐步執行有關設定透過其裝置陰影從 AWS IoT 物件中擷取資料規則所需的步驟。如需詳細資訊,請參閱 從 AWS IoT 實物將資料導入 AWS IoT SiteWise

您也可以將資料從 AWS IoT SiteWise 傳送到其他 AWS 服務。如需詳細資訊,請參閱 與其他 AWS 服務互動

授予 AWS IoT 所需的存取權

您使用 IAM 角色,控制每個規則存取的 AWS 資源。建立規則之前,您必須先建立一個允許存取所需的AWS資源。AWS IoT執行角色時便會擔任該角色。

如果在AWS IoT主控台中,您可以選擇根資產來建立可存取所選資產階層的角色。如需如何手動定義規則角色的詳細資訊,請參授予AWS IoT所需的存取權傳送角色許可中的AWS IoT開發人員指南

針對 AWS IoT SiteWise 規則動作,您必須定義角色,允許 iotsitewise:BatchPutAssetPropertyValue 存取規則將資料傳送到其中的資產屬性。若要改善安全性,您可以在 Condition 屬性中指定 AWS IoT SiteWise 資產階層路徑。

下列範例信任政策可允許存取特定資產及其子系。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iotsitewise:BatchPutAssetPropertyValue", "Resource": "*", "Condition": { "StringLike": { "iotsitewise:assetHierarchyPath": [ "/root node asset ID", "/root node asset ID/*" ] } } } ] }

您可以從政策中移除 Condition,以允許存取您的所有資產。下列範例信任政策允許存取您目前「Region」(區域) 中的所有資產。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iotsitewise:BatchPutAssetPropertyValue", "Resource": "*" } ] }

設定 AWS IoT SiteWise 規則動作

所以此AWS IoT SiteWise規則動作會從啟動規則的 MQTT 訊息傳送資料至AWS IoT SiteWise。您可以同時將多個資料項目上傳到不同的資產屬性,這樣就能在一個訊息中傳送裝置的所有感測器更新。您也可以針對每個資料項目一次上傳多個資料點。

注意

當您使用規則動作將資料傳送到 AWS IoT SiteWise 時,資料必須符合 BatchPutAssetPropertyValue 操作的所有需求。例如,您的資料不能有早於目前 Unix Epoch 時間 7 天的時間戳記。如需詳細資訊,請參閱使用 AWS IoT SiteWise API 導入資料

針對規則動作中的每個資料項目,您需要識別資產屬性並指定時間戳記、品質,以及該資產屬性的每個資料點的值。規則動作預期會接受所有參數的字串。

若要識別項目中的資產屬性,請指定下列其中一個項目:

  • 您要傳送資料到其中的資產屬性的 Asset ID (資產 ID) (assetId) 和 Property ID (屬性 ID) (propertyId)。如果您選擇此選項,請在AWS IoT主控台,您可以使用列表從AWS IoT SiteWise在目前AWS區域。

  • Property alias (屬性別名) (propertyAlias),這是資料串流別名 (例如 /company/windfarm/3/turbine/7/temperature)。若要使用這個選項,您必須先設定您的資產屬性別名。若要了解如何設定屬性別名,請參閱將工業資料串流對應到資產屬性

如需每個項目中的時間戳記,您可以使用設備報告的時間戳記或AWS IoT Core。時間戳有兩個參數:

  • 以秒為單位的時間(timeInSeconds) — 感應器或設備報告資料的 Unix 時間 (以秒為單位)。

  • 在納米內位移(offsetInNanos) — (選用) 從該時間 (以秒為單位) 開始的奈秒位移。

重要

如果您的時間戳記是字串,有小數部分或不是以秒為單位,AWS IoT SiteWise拒絕請求。必須將時間戳轉換為秒和納秒偏移量。使用AWS IoT規則引擎來轉換時間戳。如需詳細資訊,請參閱下列內容:

您可以在動作中使用若幹個參數的替代模板來執行計算、調用函數和從消息負載中提取值。如需詳細資訊,請參閱「」替代範本中的AWS IoT開發人員指南

注意

因為替代範本中的運算式與 SELECT 陳述式是分開計算的,所以您不能使用替代範本來參考使用 AS 子句所建立的別名。除了支援的函數與運算子以外,您可以僅參照原始承載中出現的資訊。

獲取不報告準確時間的設備的時間戳

如果您的傳感器或設備沒有報告準確的時間數據,您可以從AWS IoT規則引擎timestamp()。此函數會輸出以毫秒為單位的時間,因此您必須將值轉換為以秒為單位的時間和以奈米秒為單位的位移。為此,請使用下列轉換:

  • 針對 Time in seconds (以秒為單位的時間) (timeInSeconds),使用 ${floor(timestamp() / 1E3)} 將時間從毫秒轉換為秒。

  • 針對 Offset in nanos (以奈米為單位的位移) (offsetInNanos),使用 ${(timestamp() % 1E3) * 1E6} 計算時間戳記的奈米秒位移。

轉換字符串格式的時間戳

如果您的感應器或設備會以字串格式報告時間資料 (例如2020-03-03T14:57:14.699Z),您可以使用time_to_epoch(String, String)。此函數輸入時間戳和格式模式作為參數,輸出時間(以毫秒為單位)。然後,您必須將時間轉換為以秒為單位的時間和以奈米秒為單位的位移。為此,請使用下列轉換:

  • 適用於以秒為單位的時間(timeInSeconds),使用${floor(time_to_epoch("2020-03-03T14:57:14.699Z", "yyyy-MM-dd'T'HH:mm:ss'Z'") / 1E3)}將時間戳字符串轉換為毫秒,然後轉換為秒。

  • 適用於在納米內位移(offsetInNanos),使用${(time_to_epoch("2020-03-03T14:57:14.699Z", "yyyy-MM-dd'T'HH:mm:ss'Z'") % 1E3) * 1E6}來計算時間戳記字串的奈秒位移。

注意

所以此time_to_epoch函數支持高達毫秒精度的時間戳字符串。要使用微秒或納秒精度轉換字符串,可以配置AWS Lambda函數,您的規則調用該函數將時間戳轉換為數值。如需詳細資訊,請參閱 轉換納秒精度時間戳字符串

轉換納秒精度時間戳字符串

如果您的設備以奈米秒精度傳送字串格式的時間戳記資訊 (例如2020-03-03T14:57:14.699728491Z),請使用下列程序來設定規則動作。您可以建立AWS Lambda函數,該函數將時間戳從字符串轉換為以秒為單位的時間(timeInSeconds)和在納米內位移(offsetInNanos。然後,您可以使用aws_lambda (functionArn、inputJson)來呼叫該 Lambda 函數,並使用規則中的輸出。

注意

本節包含進階說明,會假設您已熟悉如何建立以下資源:

建立會剖析時間戳記字串的 AWS IoT SiteWise 規則動作

  1. 建立具備下列屬性的 Lambda 函數:

    • 函數名稱— 使用描述性函數名稱 (例如ConvertNanosecondTimestampFromString

    • 執行時間— 使用 Python 3 執行時間,例如Python 3.8(python3.8

    • Permissions (許可)— 建立具備基本 Lambda 許可的角色 (AWSLambdaBasicExecutionRole

    • 圖層— 新增AWS蘭布達-畢通 38-SciPy1X圖層,以便 Lambda 函數使用numpy

    • 函數程式碼— 使用下列函數程式碼,其會取用名為timestamp和輸出timeInSecondsoffsetInNanos值。

      import json import math import numpy # Converts a timestamp string into timeInSeconds and offsetInNanos in Unix epoch time. # The input timestamp string can have up to nanosecond precision. def lambda_handler(event, context): timestamp_str = event['timestamp'] # Parse the timestamp string as nanoseconds since Unix epoch. nanoseconds = numpy.datetime64(timestamp_str, 'ns').item() time_in_seconds = math.floor(nanoseconds / 1E9) # Slice to avoid precision issues. offset_in_nanos = int(str(nanoseconds)[-9:]) return { 'timeInSeconds': time_in_seconds, 'offsetInNanos': offset_in_nanos }

      此 Lambda 函數將時間戳字符串輸入ISO 8601格式使用日期時間 64從NumPy。

      注意

      如果您的時間戳字符串不是 ISO 8601 格式,則可以使用pandas,它定義了時間戳格式。如需詳細資訊,請參閱「」熊貓到日期時間

  2. 當您為規則設定 AWS IoT SiteWise 動作時,請針對 Time in seconds (以秒為單位的時間) (timeInSeconds) 和 Offset in nanos (以奈米為單位的位移) (offsetInNanos) 使用以下替代範本。這些替代範本會假設您的訊息承載包含 timestamp 中的時間戳記字串。aws_lambda 函數會針對其秒數參數取用 JSON 結構,因此您可視需要修改以下替代範本。

    • 針對 Time in seconds (以秒為單位的時間) (timeInSeconds),使用以下替代範本。

      ${aws_lambda('arn:aws:lambda:region:account-id:function:ConvertNanosecondTimestampFromString', {'timestamp': timestamp}).timeInSeconds}
    • 針對 Offset in nanos (以奈米為單位的位移) (offsetInNanos),使用以下替代範本。

      ${aws_lambda('arn:aws:lambda:region:account-id:function:ConvertNanosecondTimestampFromString', {'timestamp': timestamp}).offsetInNanos}

    對於每個參數,將區域account-id和您的區域和AWS帳户 ID。如果您為 Lambda 函數使用了其他名稱,也請跟著變更。

  3. 使用 lambda:InvokeFunction 許可來授予 AWS IoT 呼叫您函數的許可。如需詳細資訊,請參閱 aws_lambda(functionArn, inputJson)

  4. 測試您的規則 (例如,使用 AWS IoT MQTT 測試用戶端),並確認 AWS IoT SiteWise 會收到您傳送的資料。

    如果規則無法正常運作,請參閱 針對 AWS IoT SiteWise 規則動作進行故障診斷

注意

此解決方案會針對每個時間戳記字串呼叫 Lambda 函數兩次。如果您的規則處理在每個負載中具有相同時間戳記的多個資料點,您可以建立另一個規則來減少 Lambda 函數的呼叫次數。

若要執行此作業,請建立具有會呼叫 Lambda 的重新發佈動作規則,並將時間戳記字串轉換為timeInSecondsoffsetInNanos。接著,建立具有 AWS IoT SiteWise 規則動作的規則來取用轉換的承載。使用此方法,您可以減少規則呼叫 Lambda 的次數,但會增加AWS IoT規則動作。如果您要將此解決方案套用到您的使用案例,請考慮定價。

範例規則配置

本部分包含示例規則配置,您可以使用這些規則配置創建具有AWS IoT SiteWise動作。

範例 使用屬性別名做為訊息主題的範例規則動作

下列範例會建立具有 AWS IoT SiteWise 動作的規則,使用主題 (透過 topic()) 做為屬性別名來識別資產屬性。您可以使用此範例來定義一個規則,將雙類型資料攝取至所有風力發電廠中的所有風力渦輪機。此示例要求您在所有渦輪機資產的屬性上定義屬性別名。您需要定義第二個類似的規則來接收整數類型的資料。

aws iot create-topic-rule \ --rule-name SiteWiseWindFarmRule \ --topic-rule-payload file://sitewise-rule-payload.json

sitewise-rule-payload.json 中的範例裝載包含以下內容。

{ "sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+' WHERE type = 'double'", "description": "Sends data to the wind turbine asset property with the same alias as the topic", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [ { "iotSiteWise": { "putAssetPropertyValueEntries": [ { "propertyAlias": "${topic()}", "propertyValues": [ { "timestamp": { "timeInSeconds": "${timeInSeconds}" }, "value": { "doubleValue": "${value}" } } ] } ], "roleArn": "arn:aws:iam::account-id:role/MySiteWiseActionRole" } } ] }

透過此規則動作,您可以將下列訊息傳送到風力渦輪機屬性別名 (例如 /company/windfarm/3/turbine/7/temperature),做為擷取資料的主題。

{ "type": "double", "value": "38.3", "timeInSeconds": "1581368533" }

範例 使用 timestamp() 定義時間的範例規則動作

下列範例會建立具有 AWS IoT SiteWise 動作的規則,依據 ID 識別資產屬性並使用 timestamp() 來判斷目前的時間。

aws iot create-topic-rule \ --rule-name SiteWiseAssetPropertyRule \ --topic-rule-payload file://sitewise-rule-payload.json

sitewise-rule-payload.json 中的範例裝載包含以下內容。

{ "sql": "SELECT * FROM 'my/asset/property/topic'", "description": "Sends device data to an asset property", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [ { "iotSiteWise": { "putAssetPropertyValueEntries": [ { "assetId": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE", "propertyId": "a1b2c3d4-5678-90ab-cdef-33333EXAMPLE", "propertyValues": [ { "timestamp": { "timeInSeconds": "${floor(timestamp() / 1E3)}", "offsetInNanos": "${(timestamp() % 1E3) * 1E6}" }, "value": { "doubleValue": "${value}" } } ] } ], "roleArn": "arn:aws:iam::account-id:role/MySiteWiseActionRole" } } ] }

透過此規則動作,您可以將下列訊息傳送到 my/asset/property/topic 以擷取資料。

{ "type": "double", "value": "38.3" }

使用基本導入降低成本

AWS IoT Core 提供一項稱為「基本擷取」的功能,可用來透過 AWS IoT Core 傳送資料,而不會產生 AWS IoT 傳訊費用。基本擷取可從擷取路徑移除發佈/訂閱訊息代理程式,以最佳化大量資料擷取工作負載的資料流程。如果您知道應將訊息路由到哪些規則,您可以使用基本擷取。

若要使用基本擷取,請使用 $aws/rules/rule-name 特殊主題,將訊息直接傳送到特定規則。例如,若要將訊息傳送到名為 SiteWiseWindFarmRule 的規則,請將訊息傳送到 $aws/rules/SiteWiseWindFarmRule 主題。

如果規則動作使用包含 topic(Decimal) 的替代範本,您可以在基本擷取特殊主題的結尾處 (例如 $aws/rules/rule-name/original-topic) 傳遞原始主題。例如,若要使用基本擷取搭配上一節中的風力發電廠屬性別名範例,您可以傳送訊息到下列主題。

$aws/rules/SiteWiseWindFarmRule//company/windfarm/3/turbine/7/temperature
注意

以上範例包含第二個斜線 (//),因為 AWS IoT 會從規則動作可看到的主題中移除基本擷取前置詞 ($aws/rules/rule-name/)。在此範例中,規則會收到 /company/windfarm/3/turbine/7/temperature 主題。

如需詳細資訊,請參閱「」使用基本擷取減少簡訊費用中的AWS IoT開發人員指南

針對 AWS IoT SiteWise 規則動作進行故障診斷

故障診斷AWS IoT SiteWise規則動作AWS IoT Core,您可以配置CloudWatch日誌,或者您也可以針對規則設定重新發佈錯誤動作。如需詳細資訊,請參閱 針對 AWS IoT SiteWise 規則動作進行故障診斷