翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# AWS IoT TwinMaker データコネクタ
<a name="data-connector-interfaces"></a>

コネクタは、送信されたクエリを解決し、結果またはエラーを返すために、基になるデータストアにアクセスする必要があります。

利用可能なコネクタ、そのリクエストインターフェイス、レスポンスインターフェイスについては、以下のトピックを参照してください。

コネクタインターフェイスで使用されるプロパティの詳細については、[GetPropertyValueHistory](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html) API アクションを参照してください。

**注記**  
一部のコネクタでは、リクエストインターフェイスとレスポンスインターフェイスの両方に、開始時刻と終了時刻のプロパティ用に 2 つのタイムスタンプフィールドがあります。`startDateTime`、`endDateTime` のどちらもエポック秒を表すのに長い数字を使用していますが、これはもうサポートされていません。後方互換性を維持するため、このフィールドにはタイムスタンプ値を送信しますが、API のタイムスタンプ形式と一致する `startTime` フィールドと `endTime` フィールドを使用することをお勧めします。

**Topics**
+ [

## スキーマイニシャライザコネクタ
](#SchemaInitializer-connector)
+ [

## DataReaderByEntity
](#DataReaderByEntity-connector)
+ [

## DataReaderByComponentType
](#DataReaderByComponentType-connector)
+ [

## データリーダー
](#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 は、1 つのコンポーネントに含まれるプロパティの時系列値を取得するために使用されるデータプレーンコネクタです。

[このコネクタのプロパティタイプ、構文、および形式については、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"
}
```

## データリーダー
<a name="DataReader-connector"></a>

データリーダーは 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"
        }
      }
    }
  }
  ```
+ **データライター**:

  **リクエスト**:

  ```
  {
    "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
                              }
                          ]
                      }
                  }
              ]
          }
      ]
  }
  ```