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

# 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}
...
```