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

# AWS IoT TwinMaker 資料連接器
<a name="data-connector-interfaces"></a>

連接器需要存取基礎資料存放區，以解決傳送的查詢，並傳回結果或錯誤。

若要了解可用的連接器、其請求界面及其回應界面，請參閱下列主題。

如需連接器界面中所用屬性的詳細資訊，請參閱 [GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 動作。

**注意**  
有些連接器在開始時間和結束時間屬性的請求和回應界面中有兩個時間戳記欄位。`startDateTime` 和 都`endDateTime`使用長數字來表示不再支援的 epoch 秒。為了維持回溯相容性，我們仍會將時間戳記值傳送至該欄位，但建議使用符合 API 時間戳記格式的 `startTime`和 `endTime` 欄位。

**Topics**
+ [結構描述初始化器連接器](#SchemaInitializer-connector)
+ [DataReaderByEntity](#DataReaderByEntity-connector)
+ [DataReaderByComponentType](#DataReaderByComponentType-connector)
+ [DataReader](#DataReader-connector)
+ [AttributePropertyValueReaderByEntity](#AttributePropertyValueReaderByEntity-connector)
+ [DataWriter](#DataWriter-connector)
+ [範例](#examples-connector)

## 結構描述初始化器連接器
<a name="SchemaInitializer-connector"></a>

您可以使用元件類型或實體生命週期中的結構描述初始化器，從基礎資料來源擷取元件類型或元件屬性。結構描述初始化器會自動匯入元件類型或元件屬性，而無需明確呼叫 API 動作來設定 `properties`。

### SchemaInitializer 請求界面
<a name="SchemaInitializer-request-interface"></a>

```
{
  "workspaceId": "string",
  "entityId": "string",
  "componentName": "string",
  "properties": {
    // property name as key,
    // value is of type PropertyRequest 
    "string": "PropertyRequest"
  }
}
```

**注意**  
此請求界面中的屬性映射是 `PropertyRequest`。如需詳細資訊，請參閱 [PropertyRequest](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_PropertyRequest.html)。

### SchemaInitializer 回應界面
<a name="SchemaInitializer-response-interface"></a>

```
{
  "properties": {
    // property name as key,
    // value is of type PropertyResponse 
    "string": "PropertyResponse"
  }
}
```

**注意**  
此請求界面中的屬性映射是 `PropertyResponse`。如需詳細資訊，請參閱 [PropertyResponse](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_PropertyResponse.html)。

## DataReaderByEntity
<a name="DataReaderByEntity-connector"></a>

DataReaderByEntity 是一種資料平面連接器，用於取得單一元件中屬性的時間序列值。

如需有關此連接器的屬性類型、語法和格式的資訊，請參閱 [GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 動作。

### DataReaderByEntity 請求界面
<a name="DataReaderByEntity-request-interface"></a>

```
{
  "startDateTime": long, // In epoch sec, deprecated
  "startTime": "string", // ISO-8601 timestamp format
  "endDateTime": long, // In epoch sec, deprecated
  "endTime": "string", // ISO-8601 timestamp format
  "properties": { 
    // A map of properties as in the get-entity API response
    // property name as key,
    // value is of type [PropertyResponse](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_PropertyResponse.html) 
    "string": "PropertyResponse"
   }, 
  "workspaceId": "string",
  "selectedProperties": List:"string",
  "propertyFilters": List:PropertyFilter,
  "entityId": "string",
  "componentName": "string",
  "componentTypeId": "string",
  "interpolation": InterpolationParameters,
  "nextToken": "string",
  "maxResults": int,
  "orderByTime": "string"
  }
```

### DataReaderByEntity 回應界面
<a name="DataReaderByEntity-response-interface"></a>

```
{
  "propertyValues": [
    {
      "entityPropertyReference": EntityPropertyReference, // The same as [EntityPropertyReference](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_EntityPropertyReference.html)
      "values": [
        {
        "timestamp": long, // Epoch sec, deprecated
        "time": "string", // ISO-8601 timestamp format
        "value": DataValue // The same as [DataValue](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_DataValue.html)
        }
      ]  
    }
  ],
  "nextToken": "string"
}
```

## DataReaderByComponentType
<a name="DataReaderByComponentType-connector"></a>

若要取得來自相同元件類型的常見屬性的時間序列值，請使用資料平面連接器 DataReaderByEntity。例如，如果您在元件類型中定義時間序列屬性，並使用該元件類型擁有多個元件，則您可以在指定的時間範圍中跨所有元件查詢這些屬性。常見的使用案例是當您想要查詢多個元件的警示狀態，以取得實體的全域檢視時。

如需有關此連接器的屬性類型、語法和格式的資訊，請參閱 [GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 動作。

### DataReaderByComponentType 請求界面
<a name="DataReaderByComponentType-request-interface"></a>

```
{
  "startDateTime": long, // In epoch sec, deprecated
  "startTime": "string", // ISO-8601 timestamp format
  "endDateTime": long, // In epoch sec, deprecated
  "endTime": "string", // ISO-8601 timestamp format
  "properties": { // A map of properties as in the get-entity API response
    // property name as key,
    // value is of type [PropertyResponse](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_PropertyResponse.html) 
    "string": "PropertyResponse"
   },  
  "workspaceId": "string",
  "selectedProperties": List:"string",
  "propertyFilters": List:PropertyFilter,
  "componentTypeId": "string",
  "interpolation": InterpolationParameters,
  "nextToken": "string",
  "maxResults": int,
  "orderByTime": "string" 
}
```

### DataReaderByComponentType 回應界面
<a name="DataReaderByComponentType-response-interface"></a>

```
{
  "propertyValues": [
    {
      "entityPropertyReference": EntityPropertyReference, // The same as [EntityPropertyReference](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_EntityPropertyReference.html)
      "entityId": "string",
      "componentName": "string",
      "values": [
        {
        "timestamp": long, // Epoch sec, deprecated
        "time": "string", // ISO-8601 timestamp format
        "value": DataValue // The same as [DataValue](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_DataValue.html)
        }
      ]  
    }
  ],
  "nextToken": "string"
}
```

## DataReader
<a name="DataReader-connector"></a>

DataReader 是一種資料平面連接器，可同時處理 DataReaderByEntity 和 DataReaderByComponentType 的情況。

如需有關此連接器的屬性類型、語法和格式的資訊，請參閱 [GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 動作。

### DataReader 請求界面
<a name="-request-interface"></a>

 `EntityId` 和 `componentName` 是選擇性使用的。

```
{
  "startDateTime": long, // In epoch sec, deprecated
  "startTime": "string", // ISO-8601 timestamp format
  "endDateTime": long, // In epoch sec, deprecated  
  "endTime": "string", // ISO-8601 timestamp format
  "properties": { // A map of properties as in the get-entity API response
    // property name as key,
    // value is of type PropertyRequest 
    "string": "PropertyRequest"
  },
  
  "workspaceId": "string",
  "selectedProperties": List:"string",
  "propertyFilters": List:PropertyFilter,
  "entityId": "string",
  "componentName": "string",
  "componentTypeId": "string",
  "interpolation": InterpolationParameters,
  "nextToken": "string",
  "maxResults": int,
  "orderByTime": "string"
}
```

### DataReader 回應界面
<a name="DataReader-response-interface"></a>

```
{
  "propertyValues": [
    {
      "entityPropertyReference": EntityPropertyReference, // The same as [EntityPropertyReference](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_EntityPropertyReference.html)
      "values": [
        {
        "timestamp": long, // Epoch sec, deprecated
        "time": "string", // ISO-8601 timestamp format
        "value": DataValue // The same as [DataValue](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_DataValue.html)
        }
      ]  
    }
  ],
  "nextToken": "string"
}
```

## AttributePropertyValueReaderByEntity
<a name="AttributePropertyValueReaderByEntity-connector"></a>

AttributePropertyValueReaderByEntity 是資料平面連接器，可用來擷取單一實體中靜態屬性的值。

如需有關此連接器的屬性類型、語法和格式的資訊，請參閱 [ GetPropertyValue](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValue.html) API 動作。

### AttributePropertyValueReaderByEntity 請求界面
<a name="AttributePropertyValueReaderByEntity-request-interface"></a>

```
{
  "properties": {
    // property name as key,
    // value is of type [PropertyResponse](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_PropertyResponse.html) 
    "string": "PropertyResponse"
  }
  
  "workspaceId": "string",
  "entityId": "string",
  "componentName": "string",
  "selectedProperties": List:"string",
}
```

### AttributePropertyValueReaderByEntity 回應界面
<a name="AttributePropertyValueReaderByEntity-response-interface"></a>

```
{
  "propertyValues": {
    "string": { // property name as key
        "propertyReference": EntityPropertyReference, // The same as [EntityPropertyReference](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_EntityPropertyReference.html)
        "propertyValue": DataValue // The same as [DataValue](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_DataValue.html)
    }
}
```

## DataWriter
<a name="DataWriter-connector"></a>

DataWriter 是一種資料平面連接器，可用來將時間序列資料點寫回基礎資料存放區，以取得單一元件中的屬性。

如需有關此連接器的屬性類型、語法和格式的資訊，請參閱 [BatchPutPropertyValues](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_BatchPutPropertyValues.html) API 動作。

### DataWriter 請求界面
<a name="DataWriter-request-interface"></a>

```
{
  "workspaceId": "string",
  "properties": {
    // entity id as key
    "String": {
      // property name as key,
      // value is of type [PropertyResponse](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_PropertyResponse.html)      
      "string": PropertyResponse
    } 
  },
  "entries": [
    {
      "entryId": "string",
      "entityPropertyReference": EntityPropertyReference, // The same as [EntityPropertyReference](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_EntityPropertyReference.html)
      "propertyValues": [
        {
        "timestamp": long, // Epoch sec, deprecated
        "time": "string", // ISO-8601 timestamp format
        "value": DataValue // The same as [DataValue](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_DataValue.html)
        }
      ]
    }
  ]
}
```

### DataWriter 回應界面
<a name="DataWriter-response-interface"></a>

```
{
  "errorEntries": [
    {
      "errors": List:BatchPutPropertyError // The value is a list of type [BatchPutPropertyError](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_BatchPutPropertyError.html)
    } 
  ]
}
```

## 範例
<a name="examples-connector"></a>

下列 JSON 範例是多個連接器的回應和請求語法範例。
+ **SchemaInitializer**：

  下列範例顯示元件類型生命週期中的結構描述初始化器。

  **要求:**

  ```
  {
    "workspaceId": "myWorkspace",
    "properties": {
      "modelId": {
        "definition": {
            "dataType": { "type": "STRING" },
            "isExternalId": true,
            "isFinal": true,
            "isImported": false,
            "isInherited": false,
            "isRequiredInEntity": true,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "defaultValue": {
                "stringValue": "myModelId"
            }
        },
        "value": {
            "stringValue": "myModelId"
        }
      },
      "tableName": {
        "definition": {
            "dataType": { "type": "STRING" },
            "isExternalId": false,
            "isFinal": false,
            "isImported": false,
            "isInherited": false,
            "isRequiredInEntity": false,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "defaultValue": {
                "stringValue": "myTableName"
            }
        },
        "value": {
            "stringValue": "myTableName"
        }
      }
    }
  }
  ```

  **回應：**

  ```
  {
    "properties": {
      "myProperty1": {
        "definition": {
          "dataType": {
            "type": "DOUBLE",
            "unitOfMeasure": "%"
          },
          "configuration": {
            "myProperty1Id": "idValue"
          },
          "isTimeSeries": true
        }
      },
      "myProperty2": {
        "definition": {
          "dataType": { "type": "STRING" },
          "isTimeSeries": false,
          "defaultValue": {
            "stringValue": "property2Value"
          }
        }
      }
    }
  }
  ```
+ **實體生命週期中的結構描述初始化器**：

  **要求:**

  ```
  {
    "workspaceId": "myWorkspace",
    "entityId": "myEntity",
    "componentName": "myComponent",
    "properties": {
      "assetId": {
        "definition": {
            "dataType": { "type": "STRING" },
            "isExternalId": true,
            "isFinal": true,
            "isImported": false,
            "isInherited": false,
            "isRequiredInEntity": true,
            "isStoredExternally": false,
            "isTimeSeries": false
        },
        "value": {
            "stringValue": "myAssetId"
        }
      },
      "tableName": {
        "definition": {
            "dataType": { "type": "STRING" },
            "isExternalId": false,
            "isFinal": false,
            "isImported": false,
            "isInherited": false,
            "isRequiredInEntity": false,
            "isStoredExternally": false,
            "isTimeSeries": false
        },
        "value": {
            "stringValue": "myTableName"
        }
      }
    }
  }
  ```

  **回應：**

  ```
  {
    "properties": {
      "myProperty1": {
        "definition": {
          "dataType": {
            "type": "DOUBLE",
            "unitOfMeasure": "%"
          },
          "configuration": {
            "myProperty1Id": "idValue"
          },
          "isTimeSeries": true
        }
      },
      "myProperty2": {
        "definition": {
          "dataType": { "type": "STRING" },
          "isTimeSeries": false
        },
        "value": {
          "stringValue": "property2Value"
        }
      }
    }
  }
  ```
+ **DataReaderByEntity 和 DataReader**：

  **要求:**

  ```
  {
    "workspaceId": "myWorkspace",
    "entityId": "myEntity",
    "componentName": "myComponent",
    "selectedProperties": [
      "Temperature",
      "Pressure"
    ],
    "startTime": "2022-04-07T04:04:42Z",
    "endTime": "2022-04-07T04:04:45Z",
    "maxResults": 4,
    "orderByTime": "ASCENDING",
    "properties": {
        "assetId": {
            "definition": {
                "dataType": { "type": "STRING" },
                "isExternalId": true,
                "isFinal": true,
                "isImported": false,
                "isInherited": false,
                "isRequiredInEntity": true,
                "isStoredExternally": false,
                "isTimeSeries": false
            },
            "value": {
                "stringValue": "myAssetId"
            }
        },
        "Temperature": {
            "definition": {
                "configuration": {
                    "temperatureId": "xyz123"
                },
                "dataType": {
                    "type": "DOUBLE",
                    "unitOfMeasure": "DEGC"
                },
                "isExternalId": false,
                "isFinal": false,
                "isImported": true,
                "isInherited": false,
                "isRequiredInEntity": false,
                "isStoredExternally": false,
                "isTimeSeries": true
            }
        },
        "Pressure": {
            "definition": {
                "configuration": {
                    "pressureId": "xyz456"
                },
                "dataType": {
                    "type": "DOUBLE",
                    "unitOfMeasure": "MPA"
                },
                "isExternalId": false,
                "isFinal": false,
                "isImported": true,
                "isInherited": false,
                "isRequiredInEntity": false,
                "isStoredExternally": false,
                "isTimeSeries": true
            }
        }
    }
  }
  ```

  **回應：**

  ```
  {
    "propertyValues": [
      {
        "entityPropertyReference": {
          "entityId": "myEntity",
          "componentName": "myComponent",
          "propertyName": "Temperature"
        },
        "values": [
          {
            "time": "2022-04-07T04:04:42Z",
            "value": {
              "doubleValue": 588.168
            }
          },
          {
            "time": "2022-04-07T04:04:43Z",
            "value": {
              "doubleValue": 592.4224
            }
          }
        ]
      }
    ],
    "nextToken": "qwertyuiop"
  }
  ```
+ **AttributePropertyValueReaderByEntity**：

  **要求:**

  ```
  {
    "workspaceId": "myWorkspace",
    "entityId": "myEntity",
    "componentName": "myComponent",
    "selectedProperties": [
      "manufacturer",
    ],
    "properties": {
      "assetId": {
        "definition": {
          "dataType": { "type": "STRING" },
          "isExternalId": true,
          "isFinal": true,
          "isImported": false,
          "isInherited": false,
          "isRequiredInEntity": true,
          "isStoredExternally": false,
          "isTimeSeries": false
        },
        "value": {
            "stringValue": "myAssetId"
        }
      },
      "manufacturer": {
        "definition": {
          "dataType": { "type": "STRING" },
          "configuration": {
              "manufacturerPropId": "M001"
          },
          "isExternalId": false,
          "isFinal": false,
          "isImported": false,
          "isInherited": false,
          "isRequiredInEntity": false,
          "isStoredExternally": true,
          "isTimeSeries": false
        }
      }
    }
  }
  ```

  **回應：**

  ```
  {
    "propertyValues": {
      "manufacturer": {
        "propertyReference": {
          "propertyName": "manufacturer",
          "entityId": "myEntity",
          "componentName": "myComponent"
        },
        "propertyValue": {
          "stringValue": "Amazon"
        }
      }
    }
  }
  ```
+ **DataWriter**：

  **要求:**

  ```
  {
    "workspaceId": "myWorkspaceId",
    "properties": {
      "myEntity": {
        "Temperature": {
            "definition": {
                "configuration": {
                    "temperatureId": "xyz123"
                },
                "dataType": {
                    "type": "DOUBLE",
                    "unitOfMeasure": "DEGC"
                },
                "isExternalId": false,
                "isFinal": false,
                "isImported": true,
                "isInherited": false,
                "isRequiredInEntity": false,
                "isStoredExternally": false,
                "isTimeSeries": true
            }
        }
      }
    },
    "entries": [
      {
        "entryId": "myEntity",
        "entityPropertyReference": {
          "entityId": "myEntity",
          "componentName": "myComponent",
          "propertyName": "Temperature"
        },
        "propertyValues": [
          {
            "timestamp": 1626201120,
            "value": {
              "doubleValue": 95.6958
            }
          },
          {
            "timestamp": 1626201132,
            "value": {
              "doubleValue": 80.6959
            }
          }
        ]
      }
    ]
  }
  ```

  **回應：**

  ```
  {
      "errorEntries": [
          {
              "errors": [
                  {
                      "errorCode": "409",
                      "errorMessage": "Conflict value at same timestamp",
                      "entry": {
                          "entryId": "myEntity",
                          "entityPropertyReference": {
                              "entityId": "myEntity",
                              "componentName": "myComponent",
                              "propertyName": "Temperature"
                          },
                          "propertyValues": [
                              "time": "2022-04-07T04:04:42Z",
                              "value": {
                                  "doubleValue": 95.6958
                              }
                          ]
                      }
                  }
              ]
          }
      ]
  }
  ```