Amazon IoT TwinMaker 数据连接器 - Amazon IoT TwinMaker
架构初始值连接器DataReaderByEntityDataReaderByComponentTypeDataReaderAttributePropertyValueReaderByEntityDataWriter示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

Amazon IoT TwinMaker 数据连接器

连接器需要访问您的基础数据存储，才能解析已发送的查询并返回结果或错误。

要了解可用连接器、请求接口和响应接口信息，请参阅以下主题。

有关连接器接口中使用的属性的更多信息，请参阅 GetPropertyValueHistoryAPI 操作。

注意

部分连接器在请求和响应接口有两个时间戳字段，分别表示起始时间和结束时间属性。startDateTime 和 endDateTime 使用长数字表示纪元秒，不再支持这种表示方式。为了保持向后兼容性，我们仍会向该字段发送时间戳值，但我们建议使用与 API 时间戳格式一致的 startTime 和 endTime 字段。

架构初始值连接器

您可按组件类型或整个周期使用架构初始值设定项，或从基础数据来源获取组件类型或组件属性。架构初始值设定项自动导入组件类型或组件属性，无需显式调用 API 操作设置 properties。

SchemaInitializer 请求接口

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

此请求接口中的属性映射为 PropertyRequest。有关更多信息，请参阅PropertyRequest。

SchemaInitializer 响应接口

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

此请求接口中的属性映射为 PropertyResponse。有关更多信息，请参阅PropertyResponse。

DataReaderByEntity

DataReaderByEntity 是一个数据平面连接器，用于获取单个组件中属性的时间序列值。

有关此连接器的属性类型、语法和格式的信息，请参阅 GetPropertyValueHistoryAPI 操作。

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 
    "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
      "values": [
        {
        "timestamp": long, // Epoch sec, deprecated
        "time": "string", // ISO-8601 timestamp format
        "value": DataValue // The same as DataValue
        }
      ]  
    }
  ],
  "nextToken": "string"
}

DataReaderByComponentType

要获取来自相同组件类型的常用属性的时间序列值，请使用数据平面连接器 DataReaderByEntity。例如，如果您按组件类型定义时间序列属性，并且您有多个词类型组件，您可以查询给定时间范围内所有组件的属性。常见用例如：当您想要查询多个组件的警报状态以获取实体全局视图时。

有关此连接器的属性类型、语法和格式的信息，请参阅 GetPropertyValueHistoryAPI 操作。

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 
    "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
      "entityId": "string",
      "componentName": "string",
      "values": [
        {
        "timestamp": long, // Epoch sec, deprecated
        "time": "string", // ISO-8601 timestamp format
        "value": DataValue // The same as DataValue
        }
      ]  
    }
  ],
  "nextToken": "string"
}

DataReader

DataReader 是一种数据平面连接器，可以同时处理 DataReaderByEntity 和的情况 DataReaderByComponentType。

有关此连接器的属性类型、语法和格式的信息，请参阅 GetPropertyValueHistoryAPI 操作。

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
      "values": [
        {
        "timestamp": long, // Epoch sec, deprecated
        "time": "string", // ISO-8601 timestamp format
        "value": DataValue // The same as DataValue
        }
      ]  
    }
  ],
  "nextToken": "string"
}

AttributePropertyValueReaderByEntity

AttributePropertyValueReaderByEntity 是一个数据平面连接器，可用于获取单个实体中静态属性的值。

有关此连接器的属性类型、语法和格式的信息，请参阅 GetPropertyValueAPI 操作。

AttributePropertyValueReaderByEntity 请求接口

{
  "properties": {
    // property name as key,
    // value is of type PropertyResponse 
    "string": "PropertyResponse"
  }
  
  "workspaceId": "string",
  "entityId": "string",
  "componentName": "string",
  "selectedProperties": List:"string",
}

AttributePropertyValueReaderByEntity 响应接口

{
  "propertyValues": {
    "string": { // property name as key
        "propertyReference": EntityPropertyReference, // The same as EntityPropertyReference
        "propertyValue": DataValue // The same as DataValue
    }
}

DataWriter

DataWriter 是一个数据平面连接器，可用于将时间序列数据点写回底层数据存储中，以获取单个组件中的属性。

有关此连接器的属性类型、语法和格式的信息，请参阅 BatchPutPropertyValuesAPI 操作。

DataWriter 请求接口

{
  "workspaceId": "string",
  "properties": {
    // entity id as key
    "String": {
      // property name as key,
      // value is of type PropertyResponse      
      "string": PropertyResponse
    } 
  },
  "entries": [
    {
      "entryId": "string",
      "entityPropertyReference": EntityPropertyReference, // The same as EntityPropertyReference
      "propertyValues": [
        {
        "timestamp": long, // Epoch sec, deprecated
        "time": "string", // ISO-8601 timestamp format
        "value": DataValue // The same as DataValue
        }
      ]
    }
  ]
}

DataWriter 响应接口

{
  "errorEntries": [
    {
      "errors": List:BatchPutPropertyError // The value is a list of type BatchPutPropertyError
    } 
  ]
}

示例

以下 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
                            }
                        ]
                    }
                }
            ]
        }
    ]
}