AWS IoT TwinMaker conectores de datos

Los conectores necesitan acceder al banco de datos subyacente para resolver las consultas enviadas y devolver resultados o un error.

Para obtener información sobre los conectores disponibles, sus interfaces de solicitud y sus interfaces de respuesta, consulte los siguientes temas.

Para obtener más información sobre las propiedades utilizadas en las interfaces de los conectores, consulte la acción de la GetPropertyValueHistoryAPI.

nota

Algunos conectores tienen dos campos de marca de tiempo en las interfaces de solicitud y respuesta para las propiedades de hora de inicio y finalización. Ambos startDateTime y endDateTime utilizan un número largo para representar el segundo de tiempo Unix, lo que ya no se admite. Para mantener la compatibilidad con versiones anteriores, seguimos enviando un valor de marca de tiempo a ese campo, pero recomendamos utilizar los campos startTime y endTime que sean coherentes con el formato de marca de tiempo de nuestra API.

Conector de inicialización de esquemas

Puede utilizar el inicializador de esquemas en el tipo de componente o en el ciclo de vida de la entidad para obtener el tipo de componente o las propiedades del componente del origen de datos subyacente. El inicializador de esquemas importa automáticamente el tipo o las propiedades del componente sin solicitar explícitamente una acción de API para configurar properties.

SchemaInitializer interfaz de solicitud

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

nota

El mapa de propiedades de esta interfaz de solicitud es un PropertyRequest. Para obtener más información, consulte PropertyRequest.

SchemaInitializer interfaz de respuesta

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

nota

El mapa de propiedades de esta interfaz de solicitud es un PropertyResponse. Para obtener más información, consulte PropertyResponse.

DataReaderByEntity

DataReaderByEntity es un conector de plano de datos que se utiliza para obtener los valores de series temporales de las propiedades de un único componente.

Para obtener información sobre los tipos de propiedades, la sintaxis y el formato de este conector, consulte la acción de la GetPropertyValueHistoryAPI.

DataReaderByEntityinterfaz de solicitud

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

DataReaderByEntityinterfaz de respuesta

{
  "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

Para obtener los valores de series temporales de las propiedades comunes que provienen del mismo tipo de componente, utilice el conector DataReaderByEntity del plano de datos. Por ejemplo, si define propiedades de series temporales en el tipo de componente y tiene varios componentes que utilizan ese tipo de componente, puede consultar esas propiedades en todos los componentes de un intervalo de tiempo determinado. Un caso de uso habitual es cuando se quiere consultar el estado de alarma de varios componentes para obtener una vista global de las entidades.

Para obtener información sobre los tipos de propiedades, la sintaxis y el formato de este conector, consulte la acción de la GetPropertyValueHistoryAPI.

DataReaderByComponentType interfaz de solicitud

{
  "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 interfaz de respuesta

{
  "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 es un conector de plano de datos que puede gestionar tanto el caso DataReaderByEntity de DataReaderByComponentType como

Para obtener información sobre los tipos de propiedades, la sintaxis y el formato de este conector, consulte la acción de la GetPropertyValueHistoryAPI.

DataReader interfaz de solicitud

Los parámetros EntityId y componentName son opcionales.

{
  "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 interfaz de respuesta

{
  "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 es un conector de plano de datos que se puede utilizar para obtener el valor de las propiedades estáticas de una sola entidad.

Para obtener información sobre los tipos de propiedades, la sintaxis y el formato de este conector, consulte la acción de la GetPropertyValueAPI.

AttributePropertyValueReaderByEntity interfaz de solicitud

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

AttributePropertyValueReaderByEntity interfaz de respuesta

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

DataWriter

DataWriter es un conector de plano de datos que se puede utilizar para volver a escribir puntos de datos de series temporales en el banco de datos subyacente para las propiedades de un solo componente.

Para obtener información sobre los tipos de propiedades, la sintaxis y el formato de este conector, consulte la acción de la BatchPutPropertyValuesAPI.

DataWriter interfaz de solicitud

{
  "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 interfaz de respuesta

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

Ejemplos

Los siguientes ejemplos de JSON son ejemplos de la sintaxis de respuesta y solicitud para varios conectores.

• SchemaInitializer:

  Los siguientes ejemplos muestran el inicializador de esquemas en el ciclo de vida de un tipo de componente.

  Solicitud:

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

  Respuesta:

  {
    "properties": {
      "myProperty1": {
        "definition": {
          "dataType": {
            "type": "DOUBLE",
            "unitOfMeasure": "%"
          },
          "configuration": {
            "myProperty1Id": "idValue"
          },
          "isTimeSeries": true
        }
      },
      "myProperty2": {
        "definition": {
          "dataType": { "type": "STRING" },
          "isTimeSeries": false,
          "defaultValue": {
            "stringValue": "property2Value"
          }
        }
      }
    }
  }

• Inicializador de esquemas en el ciclo de vida de la entidad:

  Solicitud:

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

  Respuesta:

  {
    "properties": {
      "myProperty1": {
        "definition": {
          "dataType": {
            "type": "DOUBLE",
            "unitOfMeasure": "%"
          },
          "configuration": {
            "myProperty1Id": "idValue"
          },
          "isTimeSeries": true
        }
      },
      "myProperty2": {
        "definition": {
          "dataType": { "type": "STRING" },
          "isTimeSeries": false
        },
        "value": {
          "stringValue": "property2Value"
        }
      }
    }
  }

• DataReaderByEntity y DataReader:

  Solicitud:

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

  Respuesta:

  {
    "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:

  Solicitud:

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

  Respuesta:

  
  {
    "propertyValues": {
      "manufacturer": {
        "propertyReference": {
          "propertyName": "manufacturer",
          "entityId": "myEntity",
          "componentName": "myComponent"
        },
        "propertyValue": {
          "stringValue": "Amazon"
        }
      }
    }
  }

• DataWriter:

  Solicitud:

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

  Respuesta:

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