AWS IoT TwinMaker 時間序列資料連接器必要時間序列資料連接器背景開發時間序列資料連接器改善您的資料連接器測試您的連接器安全建立 AWS IoT TwinMaker 資源下一步是什麼

開發 AWS IoT TwinMaker 時間序列資料連接器

本節說明如何在程序中開發時間 step-by-step序列資料連接器。此外，我們還提供以整個 Cookie Factory 範例為基礎的時間序列資料連接器範例，其中包括 3D 模型、實體、元件、警示和連接器。Cookie 工廠範例來源可在AWS IoT TwinMaker 範例 GitHub 儲存庫中取得。

主題

AWS IoT TwinMaker 時間序列資料連接器必要
時間序列資料連接器背景
開發時間序列資料連接器
改善您的資料連接器
測試您的連接器
安全
建立 AWS IoT TwinMaker 資源
下一步是什麼
AWS IoT TwinMaker餅乾工廠示例時間序列連接器

AWS IoT TwinMaker 時間序列資料連接器必要

在開發時間序列資料連接器之前，建議您先完成下列工作：

建立AWS IoT TwinMaker 工作區。
建立AWS IoT TwinMaker 元件類型。
建立AWS IoT TwinMaker 實體。
(選擇性) 讀取使用並建立元件類型。
(選擇性) 讀取AWS IoT TwinMaker 資料連接器介面，以大致瞭解資 AWS IoT TwinMaker 料連接器。

注意

如需完全實作的連接器範例，請參閱我們的 Cookie 工廠範例實作。

時間序列資料連接器背景

想像一下，您正在與一家擁有一套餅乾混合器和水箱的工廠合作。您想要建立這些實體的 AWS IoT TwinMaker 數位雙胞胎，以便您可以透過檢查各種時間序列指標來監視其運作狀態。

您已經設定了現場感應器，而且您已經將測量資料串流到 Timestream 資料庫中。您希望能夠以最小的額外負荷檢視和組織測量資料。 AWS IoT TwinMaker 您可以使用時間序列資料連接器來完成此工作。下圖顯示範例遙測表格，透過使用時間序列連接器填入。

此螢幕擷取畫面中使用的資料集和 Timestream 表格可在AWS IoT TwinMaker 範例 GitHub 儲存庫中取得。另請參閱實施的 cookie 工廠示例連接器，該連接器會產生上述屏幕截圖中顯示的結果。

時間序列資料連接器資料流程

對於資料平面查詢，請從元件和元件類型定義中 AWS IoT TwinMaker 擷取元件和元件類型的對應屬性。 AWS IoT TwinMaker 將屬性與查詢中的任何 API 查詢參數一起轉發給 AWS Lambda 函數。

AWS IoT TwinMaker 使用 Lambda 函數存取和解析來自資料來源的查詢，並傳回這些查詢的結果。Lambda 函數使用資料平面中的元件和元件類型屬性來解決初始請求。

Lambda 查詢的結果會對應至 API 回應並傳回給您。

AWS IoT TwinMaker 定義資料連接器介面，並使用該介面與 Lambda 函數互動。使用資料連接器，您可以從 AWS IoT TwinMaker API 查詢資料來源，而無需進行任何資料移轉工作。下列影像概述了前幾段所述的基本資料流程。

開發時間序列資料連接器

下列程序概述逐步建立至功能性時間序列資料連接器的開發模型。基本步驟如下：

建立有效的基本元件類型

在元件類型中，您可以定義跨元件共用的通用性質。若要深入瞭解如何定義元件類型，請參閱使用和建立元件類型。

AWS IoT TwinMaker 使用實體元件塑型陣列，以便將每個元件貼附至一個圖元。我們建議您將每個實體項目建模為實體，並使用各自的元件類型來建模不同的資料來源。

下列範例會顯示具有一個屬性的 Timestream 範本元件類型：


{"componentTypeId": "com.example.timestream-telemetry",
    "workspaceId": "MyWorkspace",
    "functions": {
        "dataReader": {
            "implementedBy": {
                "lambda": {
                    "arn": "lambdaArn"
                }
            }
        }
    },
    "propertyDefinitions": {
        "telemetryType": {
            "dataType": { "type": "STRING" },
            "isExternalId": false,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "telemetryId": {
            "dataType": { "type": "STRING" },
            "isExternalId": true,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        }
    }
}

組件類型的關鍵元素如下：

此telemetryId屬性會識別對應資料來源中實體項目的唯一索引鍵。資料連接器使用此性質做為篩選條件，以僅查詢與指定項目相關聯的值。此外，如果您在資料平面 API 回應中包含telemetryId屬性值，則用戶端會取得 ID，並在必要時執行反向查詢。
此lambdaArn欄位會識別元件類型參與的 Lambda 函數。
此isRequiredInEntity旗標會強制建立 ID。此標誌是必需的，以便在創建組件時，也實例化項目的 ID。
會以外部 ID 的形式新增至元件類型，以便在「時間串流」表格中識別項目。TelemetryId

使用元件類型建立元件

若要使用您建立的元件類型，您必須建立一個元件，並將其附加至您要從中擷取資料的圖元。下列步驟詳細說明建立該元件的程序：
1. 導覽至 AWS IoT TwinMaker 主控台。
2. 選取並開啟您在其中建立元件類型的相同工作區。
3. 導覽至實體頁面。
4. 建立新實體或從表格中選取現有實體。
5. 選取要使用的實體之後，請選擇新增元件以開啟 [新增元件] 頁面。
6. 為元件命名，並為「類型」選擇您在 1 中使用範本建立的元件類型。建立有效的基本元件類型。

讓您的元件類型呼叫 Lambda 連接器

Lambda 連接器需要存取資料來源，並根據輸入產生查詢陳述式，並將其轉寄至資料來源。下列範例會顯示執行此動作的 JSON 要求範本。


{
  "workspaceId": "MyWorkspace",
  "entityId": "MyEntity",
  "componentName": "TelemetryData",
  "selectedProperties": ["Temperature"],
  "startTime": "2022-08-25T00:00:00Z",
  "endTime": "2022-08-25T00:00:05Z",
  "maxResults": 3,
  "orderByTime": "ASCENDING",
  "properties": {
      "telemetryType": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "Mixer"
          }
      },
      "telemetryId": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": true,
              "isFinal": true,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": true,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "item_A001"
          }
      },
      "Temperature": {
          "definition": {
              "dataType": { "type": "DOUBLE", },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      }
  }
}

請求的關鍵要素：

這selectedProperties是一份清單，其中包含您要進行時間流測量的屬性。
startDateTime、startTimeEndDateTime、和endTime欄位指定要求的時間範圍。這決定了返回的測量的樣本範圍。
這entityId是您要從中查詢資料的實體名稱。
這componentName是您要從中查詢資料之元件的名稱。
使用此orderByTime欄位來組織結果的顯示順序。

在前面的示例請求中，我們希望在給定項目的給定時間段內獲得所選屬性的一系列樣本，並具有所選時間順序。響應語句可以歸納為以下內容：


{
  "propertyValues": [
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "Temperature"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 588.168
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 592.4224
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 594.9383
          }
        }
      ]
    }
  ],
  "nextToken": "..."
}

將元件類型更新為具有兩個屬性

下列 JSON 範本顯示具有兩個屬性的有效元件類型：


{
    "componentTypeId": "com.example.timestream-telemetry",
    "workspaceId": "MyWorkspace",
    "functions": {
        "dataReader": {
            "implementedBy": {
                "lambda": {
                    "arn": "lambdaArn"
                }
            }
        }
    },
    "propertyDefinitions": {
        "telemetryType": {
            "dataType": { "type": "STRING" },
            "isExternalId": false,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "telemetryId": {
            "dataType": { "type": "STRING" },
            "isExternalId": true,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        },
        "RPM": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        }
    }
}

更新 Lambda 連接器以處理第二個屬性

AWS IoT TwinMaker 資料平面 API 支援在單一要求中查詢多個屬性，並透過提供清單來追 AWS IoT TwinMaker 蹤連接器的單一要求selectedProperties。

下列 JSON 要求會顯示已修改的範本，該範本現在支援兩個屬性的要求。


{
  "workspaceId": "MyWorkspace",
  "entityId": "MyEntity",
  "componentName": "TelemetryData",
  "selectedProperties": ["Temperature", "RPM"],
  "startTime": "2022-08-25T00:00:00Z",
  "endTime": "2022-08-25T00:00:05Z",
  "maxResults": 3,
  "orderByTime": "ASCENDING",
  "properties": {
      "telemetryType": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "Mixer"
          }
      },
      "telemetryId": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": true,
              "isFinal": true,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": true,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "item_A001"
          }
      },
      "Temperature": {
          "definition": {
              "dataType": { "type": "DOUBLE" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      },
      "RPM": {
          "definition": {
              "dataType": { "type": "DOUBLE" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      }
  }
}

同樣地，對應的回應也會更新，如下列範例所示：


{
  "propertyValues": [
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "Temperature"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 588.168
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 592.4224
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 594.9383
          }
        }
      ]
    },
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "RPM"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 59
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 60
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 60
          }
        }
      ]
    }
  ],
  "nextToken": "..."
}

注意

就這種情況的分頁而言，請求中的頁面大小適用於所有屬性。這表示查詢中有五個屬性，頁面大小為 100，如果來源中有足夠的資料點，您應該預期會看到每個屬性 100 個資料點，總共有 500 個資料點。

如需實作範例，請參閱中的雪花連接器範例 GitHub。

改善您的資料連接器

處理例外狀況

Lambda 連接器擲回例外狀況是安全的。在資料平面 API 呼叫中， AWS IoT TwinMaker 服務會等待 Lambda 函數傳回回應。如果連接器實作擲回例外狀況，則會將例外狀況類型 AWS IoT TwinMaker 轉譯為ConnectorFailure，讓 API 用戶端知道連接器內部發生了問題。

處理分頁

在這個例子中，Timestream 提供了一個實用程序功能，可以幫助本地支持分頁。但是，對於其他一些查詢接口（例如 SQL），可能需要額外的努力來實現有效的分頁算法。有一個雪花連接器範例可以在 SQL 介面中處理分頁。

AWS IoT TwinMaker 透過連接器回應介面傳回新權杖時，該權杖會先加密，然後再傳回 API 用戶端。當權杖包含在另一個請求中時，請先將其 AWS IoT TwinMaker 解密，然後再將其轉寄至 Lambda 連接器。我們建議您避免在權杖中新增敏感資訊。

測試您的連接器

雖然您仍然可以在連接器連結至元件類型之後更新實作，但我們強烈建議您在與之整合之前先驗證 Lambda 連接器 AWS IoT TwinMaker。

有多種方法可以測試 Lambda 連接器：您可以在 Lambda 主控台或本機中測試 Lambda 連接器 AWS CDK。

如需有關測試 Lambda 函數的詳細資訊，請參閱測試 Lambda 函數和本機測試 AWS CDK 應用程式。

安全

如需有關 Timestream 安全性最佳做法的說明文件，請參閱時間串流中的安全性。

如需 SQL 注入預防範例的範例，請參閱 AWS IoT TwinMaker 範例 GitHub 存放庫中的下列 Python 指令碼。

建立 AWS IoT TwinMaker 資源

實作 Lambda 函數後，您可以透過AWS IoT TwinMaker 主控台或 API 建立元件類型、實體和元件等 AWS IoT TwinMaker 資源。

注意

如果您遵循 GitHub 範例中的設定指示，則會自動提供所有 AWS IoT TwinMaker 資源。您可以檢查範AWS IoT TwinMaker GitHub 例中的元件類型定義。一旦任何元件使用元件類型，就無法更新元件類型的性質定義和函數。

集成測試

我們建議您進行整合測試， AWS IoT TwinMaker 以驗證資料平面查詢的運作方式 end-to-end。您可以通過 GetPropertyValueHistoryAPI 執行，也可以輕鬆地在AWS IoT TwinMaker 控制台中執行。

在 AWS IoT TwinMaker 控制台中，轉到組件詳細信息，然後在測試下，您將看到組件中的所有屬性列在那裡。主控台的 [測試] 區域可讓您測試時間序列屬性和 non-time-series 屬性。對於時間序列屬性，您也可以使用 GetPropertyValueHistoryAPI 和 non-time-series 屬性使用 GetPropertyValueAPI。如果您的 Lambda 連接器支援多個內容查詢，您可以選擇多個屬性。

下一步是什麼

您現在可以設定 AWS IoT TwinMaker Grafana 儀表板以視覺化指標。您也可以瀏覽範例 GitHub 存放庫中的其他資料連接器AWS IoT TwinMaker 範例，以查看它們是否符合您的使用案例。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Athena 表格資料連接

AWS IoT TwinMaker 餅乾工廠數據連接器