AWS IoT TwinMaker time-series 資料連接器先決條件時間序列資料連接器背景開發時間序列資料連接器改善您的資料連接器測試您的連接器安全建立 AWS IoT TwinMaker 資源下一步

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

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

主題

AWS IoT TwinMaker time-series 資料連接器先決條件
時間序列資料連接器背景
開發時間序列資料連接器
改善您的資料連接器
測試您的連接器
安全
建立 AWS IoT TwinMaker 資源
下一步
AWS IoT TwinMaker Cookie 原廠範例時間序列連接器

AWS IoT TwinMaker time-series 資料連接器先決條件

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

建立AWS IoT TwinMaker 工作區。
建立AWS IoT TwinMaker 元件類型。
建立AWS IoT TwinMaker 實體。
（選用）使用讀取和建立元件類型。
（選用）讀取AWS IoT TwinMaker 資料連接器界面，以全面了解 AWS IoT TwinMaker 資料連接器。

注意

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

時間序列資料連接器背景

假設您正在與具有一組 Cookie 混音器和儲水盒的工廠合作。您想要建置這些實體 AWS IoT TwinMaker 的數位分身，以便透過檢查各種時間序列指標來監控其操作狀態。

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

此螢幕擷取畫面中使用的資料集和 Timestream 資料表可在AWS IoT TwinMaker 範例 GitHub 儲存庫中使用。另請參閱實作的 Cookie 原廠範例連接器，該連接器會產生上述螢幕擷取畫面所示的結果。

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

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

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

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

AWS IoT TwinMaker 會定義資料連接器界面，並使用與 Lambda 函數互動。使用資料連接器，您可以從 API AWS IoT TwinMaker 查詢資料來源，而無需進行任何資料遷移。下圖概述前幾段所述的基本資料流程。

開發時間序列資料連接器

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

建立有效的基本元件類型

在元件類型中，您可以定義跨元件共用的常見屬性。若要進一步了解如何定義元件類型，請參閱使用和建立元件類型。

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。
TelemetryId 會將新增至元件類型做為外部 ID，以便在 Timestream 資料表中識別項目。

使用元件類型建立元件

若要使用您建立的元件類型，您必須建立元件，並將其連接到您要從中擷取資料的實體。下列步驟詳細說明建立該元件的程序：
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 是您填入您想要 Timestream 測量之屬性的清單。
startDateTime、EndDateTime、 startTime和 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 上的 Snowflake 連接器範例。

改善您的資料連接器

處理例外狀況

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

處理分頁

在此範例中，Timestream 提供公用程式函數，可協助原生支援分頁。不過，對於一些其他查詢界面，例如 SQL，可能需要額外的精力來實作有效的分頁演算法。有一個 Snowflake 連接器範例可處理 SQL 界面中的分頁。

當新的字符 AWS IoT TwinMaker 透過連接器回應界面傳回至時，字符會在傳回至 API 用戶端之前加密。當字符包含在另一個請求中時，會在轉送到 Lambda 連接器之前 AWS IoT TwinMaker 對其進行解密。建議您避免將敏感資訊新增至字符。

測試您的連接器

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

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

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

安全

如需 Timestream 安全最佳實務的文件，請參閱 Timestream 中的安全。

如需 SQL Injection 預防的範例，請參閱 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運作。您可以透過 GetPropertyValueHistory API 或在AWS IoT TwinMaker 主控台中輕鬆執行。

在 AWS IoT TwinMaker 主控台中，前往元件詳細資訊，然後在測試下，您會在其中看到元件中的所有屬性。主控台的測試區域可讓您測試時間序列屬性non-time-series屬性。對於時間序列屬性，您也可以使用 GetPropertyValueHistory API，對於non-time-series屬性，請使用 GetPropertyValue API。如果您的 Lambda 連接器支援多個屬性查詢，您可以選擇多個屬性。

下一步

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

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

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

文件慣用形式

Athena 表格式資料連接器

AWS IoT TwinMaker Cookie 原廠資料連接器