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

# 開發 AWS IoT TwinMaker 時間序列資料連接器
<a name="time-series-data-connectors"></a>

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

**Topics**
+ [AWS IoT TwinMaker time-series 資料連接器先決條件](#time-series-data-connectors-prereqs)
+ [時間序列資料連接器背景](#time-series-data-connectors-background)
+ [開發時間序列資料連接器](#time-series-data-connectors-develop)
+ [改善您的資料連接器](#time-series-data-connectors-improve)
+ [測試您的連接器](#time-series-data-connectors-test)
+ [安全](#time-series-data-connectors-security)
+ [建立 AWS IoT TwinMaker 資源](#time-series-data-connectors-resources)
+ [下一步](#time-series-data-connectors-wn)
+ [AWS IoT TwinMaker Cookie 原廠範例時間序列連接器](time-series-data-connectors-example.md)

## AWS IoT TwinMaker time-series 資料連接器先決條件
<a name="time-series-data-connectors-prereqs"></a>

在開發時間序列資料連接器之前，建議您完成下列任務：
+ 建立[AWS IoT TwinMaker 工作區](twinmaker-gs-workspace.md)。
+ 建立[AWS IoT TwinMaker 元件類型](https://docs.aws.amazon.com//iot-twinmaker/latest/guide/twinmaker-component-types.html)。
+ 建立[AWS IoT TwinMaker 實體](https://docs.aws.amazon.com//iot-twinmaker/latest/guide/twinmaker-gs-entity.html)。
+ （選用） [使用 讀取和建立元件類型](https://docs.aws.amazon.com//iot-twinmaker/latest/guide/twinmaker-component-types.htm)。
+ （選用） 讀取[AWS IoT TwinMaker 資料連接器界面](https://docs.aws.amazon.com//iot-twinmaker/latest/guide/data-connector-interface.html)，以全面了解 AWS IoT TwinMaker 資料連接器。

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

## 時間序列資料連接器背景
<a name="time-series-data-connectors-background"></a>

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

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

![\[包含資產 ID、類型、量值、時間和值的遙測資料表資料範例。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/image(1).png)


此螢幕擷取畫面中使用的資料集和 Timestream 資料表可在[AWS IoT TwinMaker 範例 GitHub 儲存庫](https://github.com/aws-samples/aws-iot-twinmaker-samples)中使用。另請參閱實作的 [Cookie 原廠範例連接器](time-series-data-connectors-example.md)，該連接器會產生上述螢幕擷取畫面所示的結果。

### 時間序列資料連接器資料流程
<a name="time-series-data-connectors-dataflow"></a>

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

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

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

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

![\[API 請求和回應使用存取資料來源的 3P Connector 請求和回應。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/data_flow.drawio.png)


## 開發時間序列資料連接器
<a name="time-series-data-connectors-develop"></a>

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

1. **建立有效的基本元件類型**

   在元件類型中，您可以定義跨元件共用的常見屬性。若要進一步了解如何定義元件類型，請參閱[使用和建立元件類型](https://docs.aws.amazon.com//iot-twinmaker/latest/guide/twinmaker-component-types.html)。

   AWS IoT TwinMaker 使用[實體元件建模模式](https://en.wikipedia.org/wiki/Entity_component_system)，讓每個元件都連接到實體。我們建議您將每個實體項目建模為實體，並使用自己的元件類型建模不同的資料來源。

   下列範例顯示具有一個屬性的 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. **使用 元件類型建立元件**

   若要使用您建立的元件類型，您必須建立元件，並將其連接至您要從中擷取資料的實體。下列步驟詳細說明建立該元件的程序：

   1. 導覽至 [AWS IoT TwinMaker 主控台](https://console.aws.amazon.com/iottwinmaker/)。

   1. 選取並開啟您建立元件類型的相同工作區。

   1. 導覽至實體頁面。

   1. 建立新的實體，或從資料表中選取現有的實體。

   1. 選取要使用的實體後，請選擇**新增元件**以開啟**新增元件**頁面。

   1. 為元件命名，並為**類型**選擇您在 **1 中使用範本建立的元件類型。建立有效的基本元件類型**。

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": "..."
   }
   ```

1. **更新您的元件類型以有兩個屬性**

   下列 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
           }
       }
   }
   ```

1. **更新 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 連接器範例](https://github.com/aws-samples/aws-iot-twinmaker-samples-snowflake/blob/main/src/modules/snowflake/data-connector/lambda_connectors/data_reader_by_entity.py)。

## 改善您的資料連接器
<a name="time-series-data-connectors-improve"></a>



### 處理例外狀況
<a name="time-series-data-connectors-handle-exceptions"></a>

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

### 處理分頁
<a name="time-series-data-connectors-handle-pagination"></a>

在此範例中，Timestream 提供[公用程式函數](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/timestream-query.html#TimestreamQuery.Client.query)，可協助原生支援分頁。不過，對於一些其他查詢界面，例如 SQL，可能需要額外的努力來實作有效的分頁演算法。有一個 [Snowflake](https://github.com/aws-samples/aws-iot-twinmaker-samples-snowflake/blob/main/src/modules/snowflake/data-connector/lambda_connectors/data_reader_by_entity.py) 連接器範例可處理 SQL 介面中的分頁。

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

## 測試您的連接器
<a name="time-series-data-connectors-test"></a>

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

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

如需測試 Lambda 函數的詳細資訊，請參閱[測試 Lambda 函數](https://docs.aws.amazon.com//lambda/latest/dg/testing-functions.html)和[本機測試 AWS CDK 應用程式](https://docs.aws.amazon.com//serverless-application-model/latest/developerguide/serverless-cdk-testing.html)。

## 安全
<a name="time-series-data-connectors-security"></a>

如需 Timestream 安全最佳實務的文件，請參閱 [Timestream 中的安全](https://docs.aws.amazon.com//timestream/latest/developerguide/security.html)。

如需 SQL Injection 預防的範例，請參閱 AWS IoT TwinMaker 範例 GitHub 儲存庫中的下列 [Python 指令碼](https://github.com/aws-samples/aws-iot-twinmaker-samples/blob/main/src/libs/udq_helper_utils/udq_utils/sql_detector.py)。

## 建立 AWS IoT TwinMaker 資源
<a name="time-series-data-connectors-resources"></a>

實作 Lambda 函數後，您可以透過[AWS IoT TwinMaker 主控台](https://console.aws.amazon.com/iottwinmaker/)或 API 建立元件類型、實體和元件等 AWS IoT TwinMaker 資源。

**注意**  
如果您遵循 GitHub 範例中的設定指示，則會自動提供所有 AWS IoT TwinMaker 資源。您可以在 [AWS IoT TwinMaker GitHub 範例中](https://github.com/aws-samples/aws-iot-twinmaker-samples/tree/main/src/workspaces/cookiefactory/component_types)檢查元件類型定義。一旦任何元件使用元件類型，就無法更新元件類型的屬性定義和函數。

### 整合測試
<a name="time-series-data-connectors-resources-testing"></a>

我們建議您使用 進行整合測試 AWS IoT TwinMaker ，以驗證資料平面查詢是否end-to-end運作。您可以透過 [GetPropertyValueHistory](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 或在[AWS IoT TwinMaker 主控台](https://console.aws.amazon.com/iottwinmaker/)中輕鬆執行。

![\[TwinMaker 元件資訊主控台頁面會顯示元件的名稱、類型、狀態等。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/image(3).png)


在 AWS IoT TwinMaker 主控台中，前往**元件詳細資訊**，然後在**測試**下，您會在其中看到元件中的所有屬性。主控台**的測試**區域可讓您測試時間序列屬性non-time-series屬性。對於時間序列屬性，您也可以使用 [ GetPropertyValueHistory](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API，對於non-time-series屬性，請使用 [ GetPropertyValue](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetPropertyValue.html) API。如果您的 Lambda 連接器支援多個屬性查詢，您可以選擇多個屬性。

![\[TwinMaker 元件資訊主控台頁面的一部分，顯示元件的測試。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/image(4).png)


## 下一步
<a name="time-series-data-connectors-wn"></a>

您現在可以設定 [AWS IoT TwinMaker Grafana 儀表板](https://docs.aws.amazon.com//iot-twinmaker/latest/guide/grafana-integration.html)來視覺化指標。您也可以在[AWS IoT TwinMaker 範例 GitHub 儲存庫](https://github.com/aws-samples/aws-iot-twinmaker-samples/tree/main/src/modules/s3)中探索其他資料連接器範例，以查看是否符合您的使用案例。

# AWS IoT TwinMaker Cookie 原廠範例時間序列連接器
<a name="time-series-data-connectors-example"></a>

您可以在 GitHub 上取得 [Cookie 原廠 Lambda 函數的完整程式碼](https://github.com/aws-samples/aws-iot-twinmaker-samples/blob/main/src/modules/timestream_telemetry/lambda_function/udq_data_reader.py)。雖然您仍然可以在將連接器連結至元件類型後更新實作，但我們強烈建議您在與 整合之前驗證 Lambda 連接器 AWS IoT TwinMaker。您可以在 Lambda 主控台或本機的 中測試 Lambda 函數 AWS CDK。如需測試 Lambda 函數的詳細資訊，請參閱[測試 Lambda 函數](https://docs.aws.amazon.com//lambda/latest/dg/testing-functions.html)和[本機測試 AWS CDK 應用程式](https://docs.aws.amazon.com//serverless-application-model/latest/developerguide/serverless-cdk-testing.html)。

## Cookie 原廠元件類型範例
<a name="time-series-data-connectors-example-ct"></a>

在元件類型中，我們會定義跨元件共用的常見屬性。對於 Cookie 工廠範例，相同類型的實體元件共用相同的測量，因此我們可以在元件類型中定義測量結構描述。例如，下列範例中會定義混合器類型。

```
{
    "componentTypeId": "com.example.cookiefactory.mixer"
    "propertyDefinitions": {
        "RPM": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isRequiredInEntity": false,
            "isExternalId": false,
            "isStoredExternally": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isRequiredInEntity": false,
            "isExternalId": false,
            "isStoredExternally": true
        }
    }
}
```

例如，實體元件在 Timestream 資料庫中可能會有測量結果、SQL 資料庫中的維護記錄，或警示系統中的警示資料。建立多個元件並將其與實體建立關聯，將不同的資料來源連結到實體，並填入實體元件圖表。在此內容中，每個元件都需要 `telemetryId` 屬性來識別對應資料來源中元件的唯一金鑰。指定 `telemetryId` 屬性有兩個優點：在資料連接器中可以使用 屬性做為篩選條件，以僅查詢指定元件的值，而且如果您在資料平面 API 回應中包含 `telemetryId` 屬性值，則用戶端會取得 ID，並視需要執行反向查詢。

如果您將 `TelemetryId` 新增至元件類型做為外部 ID，它會識別`TimeStream`資料表中的元件。

```
{
    "componentTypeId": "com.example.cookiefactory.mixer"
    "propertyDefinitions": {
        "telemetryId": {
            "dataType": { "type": "STRING" },
            "isTimeSeries": false,
            "isRequiredInEntity": true,
            "isExternalId": true,
            "isStoredExternally": false
        },
        "RPM": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isRequiredInEntity": false,
            "isExternalId": false,
            "isStoredExternally": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isRequiredInEntity": false,
            "isExternalId": false,
            "isStoredExternally": true
        }
    }
}
```

同樣地，我們有 的元件類型`WaterTank`，如下列 JSON 範例所示。

```
{
  "componentTypeId": "com.example.cookiefactory.watertank",
  "propertyDefinitions": {
    "flowRate1": {
      "dataType": { "type": "DOUBLE" },
      "isTimeSeries": true,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": true
    },
    "flowrate2": {
      "dataType": { "type": "DOUBLE" },
      "isTimeSeries": true,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": true
    },
    "tankVolume1": {
      "dataType": { "type": "DOUBLE" },
      "isTimeSeries": true,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": true
    },
    "tankVolume2": {
      "dataType": { "type": "DOUBLE" },
      "isTimeSeries": true,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": true
    },
    "telemetryId": {
      "dataType": { "type": "STRING" },
      "isTimeSeries": false,
      "isRequiredInEntity": true,
      "isExternalId": true,
      "isStoredExternally": false
    }
  }
}
```

如果元件類型旨在查詢實體範圍內的屬性值，則 `TelemetryType`是元件類型的選用屬性。如需範例，請參閱[AWS IoT TwinMaker 範例 GitHub 儲存庫](https://github.com/aws-samples/aws-iot-twinmaker-samples/tree/main/src/workspaces/cookiefactory/component_types)中定義的元件類型。也有警示類型內嵌在相同的資料表中，因此`TelemetryType`會定義 ，您可以將 `TelemetryId`和 等常見屬性擷取`TelemetryType`到父元件類型，供其他子類型共用。

## 範例 Lambda
<a name="time-series-data-connectors-example-lam"></a>

Lambda 連接器需要存取資料來源，並根據輸入產生查詢陳述式，並將其轉送至資料來源。傳送至 Lambda 的範例請求會顯示在下列 JSON 範例中。

```
{
    'workspaceId': 'CookieFactory', 
    'selectedProperties': ['Temperature'], 
    'startDateTime': 1648796400, 
    'startTime': '2022-04-01T07:00:00.000Z', 
    'endDateTime': 1650610799, 
    'endTime': '2022-04-22T06:59:59.000Z', 
    'properties': {
        'telemetryId': {
            'definition': {
                'dataType': { 'type': 'STRING' },
                'isTimeSeries': False, 
                'isRequiredInEntity': True, 
                'isExternalId': True, 
                'isStoredExternally': False, 
                'isImported': False, 
                'isFinal': False, 
                'isInherited': True, 
            }, 
            'value': {
                'stringValue': 'Mixer_22_680b5b8e-1afe-4a77-87ab-834fbe5ba01e'
            }
        }
        'Temperature': {
            'definition': {
                'dataType': { 'type': 'DOUBLE' }, 
                'isTimeSeries': True, 
                'isRequiredInEntity': False, 
                'isExternalId': False, 
                'isStoredExternally': True, 
                'isImported': False, 
                'isFinal': False, 
                'isInherited': False
            }
        }
        'RPM': {
            'definition': {
                'dataType': { 'type': 'DOUBLE' }, 
                'isTimeSeries': True, 
                'isRequiredInEntity': False, 
                'isExternalId': False, 
                'isStoredExternally': True, 
                'isImported': False, 
                'isFinal':False, 
                'isInherited': False
            }
        }, 
    'entityId': 'Mixer_22_d133c9d0-472c-48bb-8f14-54f3890bc0fe', 
    'componentName': 'MixerComponent', 
    'maxResults': 100, 
    'orderByTime': 'ASCENDING'
}
```

Lambda 函數的目標是查詢指定實體的歷史測量資料。 AWS IoT TwinMaker 提供元件屬性映射，您應該指定元件 ID 的執行個體化值。例如，若要處理元件類型層級查詢 （警示使用案例很常見） 並傳回工作區中所有元件的警示狀態，則屬性映射具有元件類型屬性定義。

對於最直接的情況，如同上述請求，我們希望在給定元件的給定時段內，以遞增的時間順序取得一系列的溫度樣本。查詢陳述式可以摘要如下：

```
...
SELECT measure_name, time, measure_value::double
    FROM {database_name}.{table_name} 
    WHERE time < from_iso8601_timestamp('{request.start_time}')
    AND time >= from_iso8601_timestamp('{request.end_time}')
    AND TelemetryId = '{telemetry_id}'
    AND measure_name = '{selected_property}'
    ORDER BY time {request.orderByTime}
...
```