本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用和创建组件类型
<a name="twinmaker-component-types"></a>

本主题将引导您了解用于创建 AWS IoT TwinMaker 组件类型的值和结构。它向您展示了如何创建可以传递给 [CreateComponentType](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_CreateComponentType.html)API 的请求对象，也可以使用 AWS IoT TwinMaker 控制台中的组件类型编辑器来创建请求对象。

组件为其关联实体的属性和数据提供上下文。

## 内置组件类型
<a name="twinmaker-component-types-built-in"></a>

在 AWS IoT TwinMaker 控制台中，当您选择工作区，然后在左侧窗格中选择**组件类型**时，您会看到以下组件类型。
+ **com.amazon.iotsitewise.resourcesync**：一种组件类型，可自动同步您的 AWS IoT SiteWise 资产和资产模型并将其转换为实体、组件和组件类型。 AWS IoT TwinMaker 有关使用 AWS IoT SiteWise 资产同步的更多信息，请参阅与[资产同步 AWS IoT SiteWise](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/tm-sw-asset-sync.html)。
+ **com.amazon.iottwinmaker.alarm.basic**：一个基本的警报组件，可将警报数据从外部来源提取到实体。此组件未包含连接到特定数据来源的函数。这意味着警报组件是抽象的，可以由另一种组件类型继承，该组件类型指定了数据来源和从该数据来源读取的函数。
+ **com.amazon.iottwinmaker.documents**：包含实体相关信息的文档的标题到 URL 的简单映射。
+ **com.amazon.iotsitewise.connector.edgevideo：一种使用边缘连接器 for Kinesis Video Streams 组件将视频**从物联网设备提取到实体的组件。 AWS IoT Greengrass [Kinesis Video AWS IoT Greengrass Streams 的 Edge Con AWS IoT TwinMaker nec](https://docs.aws.amazon.com/greengrass/v2/developerguide/kvs-edge-connector-component.html) tor 组件不是组件，而是一个部署在物联网设备上的本地 AWS IoT Greengrass 预构建组件。
+ **com.amazon.iotsitewise.connector**：一种将 AWS IoT SiteWise 数据提取到实体的组件。
+ **com.amazon.iottwinmaker.parameters**：一种向实体添加静态键值对的组件。
+ **com.amazon.kvs.video：将视频从 K** inesis Video Streams 提取到实体的组件。 AWS IoT TwinMaker 

![\[组件类型控制台页面，其中列出了几种预定义的组件类型。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/ComponentTypesPredefined.png)


## AWS IoT TwinMaker 组件类型的核心特征
<a name="twinmaker-component-types-core"></a>

下面的列表介绍了组件类型的核心特征。
+ **属性定义**：该[PropertyDefinitionRequest](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_PropertyDefinitionRequest.html)对象定义了一个可以在场景编辑器中填充的属性，也可以使用从外部数据源提取的数据进行填充。您设置的静态属性存储在中 AWS IoT TwinMaker。从数据来源提取的时间序列属性和其他属性存储在外部。

  可以在 `PropertyDefinitionRequest` 映射的字符串中指定属性定义。每个字符串对于映射必须是唯一的。
+ **函数**：该[FunctionRequest](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_FunctionRequest.html)对象指定一个 Lambda 函数，该函数从外部数据源读取并可能写入外部数据源。

  如果组件类型包含一个属性，其值存储在外部但没有相应的函数来检索这些值，则它属于抽象组件类型。您可以从抽象组件类型扩展具体的组件类型。您无法向实体添加抽象组件类型。它们不会出现在场景编辑器中。

  您可以在 `FunctionRequest` 映射的字符串中指定函数。该字符串必须指定以下一个预定义函数类型。
  + `dataReader`：一个从外部来源提取数据的函数。
  + `dataReaderByEntity`：一个从外部来源提取数据的函数。

    当您使用这种类型的数据读取器时，[GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html)API 操作仅支持针对该组件类型的属性的实体特定查询。（只能请求 `componentName` \$1 `entityId` 的属性值历史记录。）
  + `dataReaderByComponentType`：一个从外部来源提取数据的函数。

    当您使用这种类型的数据读取器时，[GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html)API 操作仅支持对该组件类型中的属性的跨实体查询。（只能请求 `componentTypeId` 的属性值历史记录。）
  + `dataWriter`：一种将数据写入外部来源的函数。
  + `schemaInitializer`：一个在每次创建包含组件类型的实体时都会自动初始化属性值的函数。

  非抽象组件类型需要三种类型的数据读取器函数之一。

  [有关实现时间流遥测组件（包括警报）的 Lambda 函数的示例，请参阅AWS IoT TwinMaker 示例](https://github.com/aws-samples/aws-iot-twinmaker-samples/blob/main/src/modules/timestream_telemetry/lambda_function/udq_data_reader.py)中的数据读取器。
**注意**  
由于警报连接器继承自抽象警报组件类型，因此 Lambda 函数必须返回 `alarm_key` 值。如果没有返回此值，Grafana 将无法将其识别为警报。这对于所有返回警报的组件都是必需的。
+ **继承**：组件类型通过继承来提高代码的可重用性。一个组件类型可以继承最多 10 个父组件类型。

  使用 `extendsFrom` 参数指定组件类型，您的组件类型将从那里继承属性和函数。
+  **isSingleton**：某些组件包含属性，如位置坐标，这些属性在一个实体中不能包含多次。将 `isSingleton` 参数的值设置为 `true`，表示组件类型在一个实体中只能包含一次。

## 创建属性定义
<a name="twinmaker-component-types-property-def"></a>

下表描述 `PropertyDefinitionRequest` 的参数。


| 参数 | 描述 | 
| --- | --- | 
| `isExternalId` | 一个布尔值，它指定该属性是否是外部存储的属性值的唯一标识符（例如 AWS IoT SiteWise 资产 ID）。 此属性的默认值为 `false`。 | 
| `isStoredExternally` | 指定是否在外部存储属性的布尔值。 此属性的默认值为 `false`。 | 
| `isTimeSeries` | 指定属性是否存储时间序列数据的布尔值。 此属性的默认值为 `false` | 
| `isRequiredInEntity` | 一个布尔值，用于指定属性在使用该组件类型的实体中是否必须要有一个值。 | 
| `dataType` | 一个[DataType](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_DataType.html)对象，用于指定属性的数据类型（例如字符串、地图、列表和度量单位）。  | 
| `defaultValue` | 一个指定属性的默认值的[DataValue](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_DataValue.html)对象。  | 
| `configuration` | 一种 string-to-string 地图，用于指定连接到外部数据源所需的其他信息。  | 

## 创建函数
<a name="twinmaker-component-types-function"></a>

下表描述 `FunctionRequest` 的参数。


| 参数 | 描述 | 
| --- | --- | 
| ` implementedBy` | 一个[DataConnector](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_DataConnector.html)对象，它指定连接到外部数据源的 Lambda 函数。  | 
| `requiredProperties` | 该函数从外部数据来源读取和写入外部数据来源所需属性的列表。 | 
| `scope` | 函数的范围。`Workspace` 用于范围跨越整个工作区的函数。`Entity` 用于范围仅限于包含该组件的实体的函数。 | 

有关说明如何创建和扩展组件类型的示例，请参阅 [示例组件类型](twinmaker-component-types-examples.md)。

# 示例组件类型
<a name="twinmaker-component-types-examples"></a>

此主题包含的示例说明了如何实现组件类型的关键概念。

## 警报（抽象）
<a name="twinmaker-component-types-examples-alarm"></a>

以下示例是 AWS IoT TwinMaker 控制台中显示的抽象警报组件类型。它包含一个由没有 `implementedBy` 值的 `dataReader` 组成的 `functions` 列表。

```
{
  "componentTypeId": "com.example.alarm.basic:1",
  "workspaceId": "MyWorkspace",
  "description": "Abstract alarm component type",
  "functions": {
    "dataReader": {
         "isInherited": false
    }
  },
  "isSingleton": false,
  "propertyDefinitions": {
    "alarm_key": {
      "dataType": { "type": "STRING" },
      "isExternalId": true,
      "isRequiredInEntity": true,
      "isStoredExternally": false,
      "isTimeSeries": false
    },
    "alarm_status": {
      "dataType": {
        "allowedValues": [
          {
            "stringValue": "ACTIVE"
          },
          {
            "stringValue": "SNOOZE_DISABLED"
          },
          {
            "stringValue": "ACKNOWLEDGED"
          },
          {
            "stringValue": "NORMAL"
          }
        ],
        "type": "STRING"
      },
      "isRequiredInEntity": false,
      "isStoredExternally": true,
      "isTimeSeries": true
    }
  }
}
```

备注：

`componentTypeId` 和 `workspaceID` 的值为必需值。`componentTypeId` 的值对工作区必须是唯一性的。`alarm_key` 的值是函数可用于从外部来源检索警报数据的唯一标识符。密钥的值是必需的，并存储在中 AWS IoT TwinMaker。`alarm_status` 时间序列值存储在外部来源中。

更多示例参见 [AWS IoT TwinMaker 示例](https://github.com/aws-samples/aws-iot-twinmaker-samples)。

## 时间流遥测
<a name="twinmaker-component-types-examples-telemetry"></a>

以下示例是一个简单的组件类型，它从外部来源检索有关特定类型组件（例如警报或 Cookie 混合器）的遥测数据。它指定了组件类型继承的 Lambda 函数。

```
{
    "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": false,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        }
    }
}
```

## 警报（继承自抽象警报）
<a name="twinmaker-component-types-examples-alarm-implementation"></a>

以下示例继承自抽象警报和时间流遥测组件类型。它指定了自己的 Lambda 函数，用于检索警报数据。

```
{
    "componentTypeId": "com.example.cookiefactory.alarm",
    "workspaceId": "MyWorkspace",
    "extendsFrom": [
        "com.example.timestream-telemetry",
        "com.amazon.iottwinmaker.alarm.basic"
    ],
    "propertyDefinitions": {
        "telemetryType": {
            "defaultValue": {
                "stringValue": "Alarm"
            }
        }
    },
    "functions": {
        "dataReader": {
            "implementedBy": {
                "lambda": {
                    "arn": "lambdaArn"
                }
            }
        }
    }
}
```

**注意**  
由于警报连接器继承自抽象警报组件类型，因此 Lambda 函数必须返回 `alarm_key` 值。如果没有返回此值，Grafana 将无法将其识别为警报。这对于所有返回警报的组件都是必需的。

## 设备示例
<a name="twinmaker-component-types-examples-equipment"></a>

本部分的示例说明如何对潜在的设备进行建模。可以使用这些示例来了解如何在自己的流程中对设备进行建模。

### 饼干搅拌机
<a name="twinmaker-component-types-examples-mixer"></a>

以下示例继承自时间流遥测组件类型。它为饼干搅拌机的旋转速度和温度指定了额外的时间序列属性。

```
{
    "componentTypeId": "com.example.cookiefactory.mixer",
    "workspaceId": "MyWorkspace",
    "extendsFrom": [
        "com.example.timestream-telemetry"
    ],
    "propertyDefinitions": {
        "telemetryType": {
            "defaultValue" : { "stringValue": "Mixer" }
        },
        "RPM": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isStoredExternally": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isStoredExternally": true
        }
    }
}
```

### 水箱
<a name="twinmaker-component-types-examples-watertank"></a>

以下示例继承自时间流遥测组件类型。它为水箱的体积和流速指定了额外的时间序列属性。

```
{
    "componentTypeId": "com.example.cookiefactory.watertank",
    "workspaceId": "MyWorkspace",
    "extendsFrom": [
        "com.example.timestream-telemetry"
    ],
    "propertyDefinitions": {
        "telemetryType": {
            "defaultValue" : { "stringValue": "WaterTank" }
        },
        "tankVolume1": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isStoredExternally": true
        },
        "tankVolume2": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isStoredExternally": true
        },
        "flowRate1": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isStoredExternally": true
        },
        "flowrate2": {
            "dataType": { "type": "DOUBLE" },
            "isTimeSeries": true,
            "isStoredExternally": true
        }
    }
}
```

### 空间位置
<a name="twinmaker-component-types-examples-space"></a>

以下示例包含属性，其值存储在中 AWS IoT TwinMaker。由于这些值由用户指定并存储在内部，因此无需任何函数即可检索它们。该示例还使用 `RELATIONSHIP` 数据类型来指定与另一组件类型的关系。

该组件提供了一种用于向数字孪生添加上下文的轻量级机制。可以用它来添加指出某物所在位置的元数据。还可以在逻辑中使用这些信息，用于确定哪些摄像头可以看到设备或空间，或者用于知道如何派人到某个地点。

```
{
    "componentTypeId": "com.example.cookiefactory.space",
    "workspaceId": "MyWorkspace",
    "propertyDefinitions": {
        "position":  {"dataType": {"nestedType": {"type": "DOUBLE"},"type": "LIST"}},
        "rotation":  {"dataType": {"nestedType": {"type": "DOUBLE"},"type": "LIST"}},
        "bounds":  {"dataType": {"nestedType": {"type": "DOUBLE"},"type": "LIST"}},
        "parent_space" : { "dataType": {"type": "RELATIONSHIP"}}
    }
}
```