기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS IoT TwinMaker 데이터 커넥터
전송된 쿼리를 해결하고 결과 또는 오류를 반환하려면 커넥터가 기본 데이터 저장소에 액세스할 수 있어야 합니다.
사용 가능한 커넥터, 요청 인터페이스 및 응답 인터페이스에 대해 알아보려면 다음 주제를 참조하십시오.
커넥터 인터페이스에서 사용되는 속성에 대한 자세한 내용은 [GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 작업을 참조하십시오.
**참고**
일부 커넥터에는 요청 및 응답 인터페이스 모두에 시작 시간 및 종료 시간 속성에 대한 타임스탬프 필드가 두 개 있습니다. `startDateTime` 및 `endDateTime` 모두 에포크 세컨드를 나타내는 데 긴 숫자를 사용하지만, 더 이상 지원되지 않습니다. 이전 버전과의 호환성을 유지하기 위해 여전히 해당 필드에 타임스탬프 값을 전송하지만 API 타임스탬프 형식과 일치하는 `startTime` 및 `endTime` 필드를 사용하는 것이 좋습니다.
**Topics**
+ [스키마 이니셜라이저 커넥터](#SchemaInitializer-connector)
+ [DataReaderByEntity](#DataReaderByEntity-connector)
+ [DataReaderByComponentType](#DataReaderByComponentType-connector)
+ [DataReader](#DataReader-connector)
+ [AttributePropertyValueReaderByEntity](#AttributePropertyValueReaderByEntity-connector)
+ [DataWriter](#DataWriter-connector)
+ [예제](#examples-connector)
## 스키마 이니셜라이저 커넥터
구성 요소 유형 또는 개체 수명 주기의 스키마 이니셜라이저를 사용하여 기본 데이터 소스에서 구성 요소 유형 또는 구성 요소 속성을 가져올 수 있습니다. 스키마 이니셜라이저는 API 작업을 명시적으로 직접적으로 호출하여 `properties`을 설정하지 않고도 구성 요소 유형이나 구성 요소 속성을 자동으로 가져옵니다.
### 스키마이니셜라이저 요청 인터페이스
```
{
"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)를 참조하십시오.
### 스키마 이니셜라이저 응답 인터페이스
```
{
"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
DataReaderByEntity는 단일 구성 요소에 있는 속성의 시계열 값을 가져오는 데 사용되는 데이터 영역 커넥터입니다.
이 커넥터의 속성 유형, 구문 및 형식에 대한 자세한 내용은 [GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 작업을 참조하십시오.
### DataReaderByEntity 요청 인터페이스
```
{
"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 응답 인터페이스
```
{
"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
동일한 구성 요소 유형에서 오는 공통 속성의 시계열 값을 가져오려면 데이터 영역 커넥터 DataReaderByEntity를 사용하십시오. 예를 들어 구성 요소 유형에 시계열 속성을 정의하고 해당 구성 요소 유형을 사용하는 구성 요소가 여러 개 있는 경우, 지정된 시간 범위의 모든 구성 요소에서 해당 속성을 쿼리할 수 있습니다. 이를 위한 일반적인 사용 사례는 여러 구성 요소의 경보 상태를 쿼리하여 개체를 전체적으로 파악하려는 경우입니다.
이 커넥터의 속성 유형, 구문 및 형식에 대한 자세한 내용은 [GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 작업을 참조하십시오.
### DataReaderByComponentType 요청 인터페이스
```
{
"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 응답 인터페이스
```
{
"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
Data Reader는 DataReaderByEntity 및DataReaderByComponentType 사례 모두를 처리할 수 있는 데이터 영역 커넥터입니다.
이 커넥터의 속성 유형, 구문 및 형식에 대한 자세한 내용은 [GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API 작업을 참조하십시오.
### DataReader 요청 인터페이스
`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 응답 인터페이스
```
{
"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
AttributePropertyValueReader ByEntity는 단일 개체의 정적 속성 값을 가져오는 데 사용할 수 있는 데이터 영역 커넥터입니다.
이 커넥터의 속성 유형, 구문 및 형식에 대한 자세한 내용은 [GetPropertyValue](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValue.html) API 작업을 참조하십시오.
### AttributePropertyValueReaderByEntity 요청 인터페이스
```
{
"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 응답 인터페이스
```
{
"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
DataWriter는 단일 구성요소의 속성을 위해 시계열 데이터 포인트를 기본 데이터 저장소에 다시 쓰는 데 사용할 수 있는 데이터 영역 커넥터입니다.
이 커넥터의 속성 유형, 구문 및 형식에 대한 자세한 내용은 [BatchPutPropertyValues](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_BatchPutPropertyValues.html) API 작업을 참조하십시오.
### DataWriter 요청 인터페이스
```
{
"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 응답 인터페이스
```
{
"errorEntries": [
{
"errors": List:BatchPutPropertyError // The value is a list of type [BatchPutPropertyError](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_BatchPutPropertyError.html)
}
]
}
```
## 예제
다음 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 and 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
}
]
}
}
]
}
]
}
```