View a markdown version of this page

En développement AWS IoT TwinMaker connecteurs de données chronologiques - AWS IoT TwinMaker
AWS IoT TwinMaker prérequis pour les connecteurs de données chronologiquesTime-series arrière-plan du connecteur de donnéesDéveloppement d'un connecteur de données chronologiquesAméliorer votre connecteur de donnéesTester votre connecteurSécuritéCréation AWS IoT TwinMaker resourcesQuelle est la prochaine étape

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

En développement AWS IoT TwinMaker connecteurs de données chronologiques

Cette section explique comment développer un connecteur de données chronologiques en suivant un processus étape par étape. En outre, nous présentons un exemple de connecteur de données chronologique basé sur l'ensemble de l'échantillon de l'usine à cookies, qui comprend des modèles 3D, des entités, des composants, des alarmes et des connecteurs. La source d'échantillons de Cookie Factory est disponible dans le GitHub référentiel AWS IoT TwinMaker d'échantillons.

Rubriques

AWS IoT TwinMaker prérequis pour les connecteurs de données chronologiques

Avant de développer votre connecteur de données chronologiques, nous vous recommandons d'effectuer les tâches suivantes :

Note

Pour un exemple de connecteur entièrement implémenté, consultez notre exemple de mise en œuvre d'une usine à cookies.

Time-series arrière-plan du connecteur de données

Imaginez que vous travaillez dans une usine qui possède un ensemble de mélangeurs à biscuits et un réservoir d'eau. Vous souhaitez créer des jumeaux AWS IoT TwinMaker numériques de ces entités physiques afin de pouvoir surveiller leur état de fonctionnement en vérifiant diverses mesures chronologiques.

Vous avez configuré des capteurs sur site et vous diffusez déjà les données de mesure dans une base de données Timestream. Vous voulez être en mesure de visualiser et d'organiser les données de mesure AWS IoT TwinMaker avec un minimum de frais. Vous pouvez accomplir cette tâche à l'aide d'un connecteur de données chronologiques. L'image suivante montre un exemple de tableau de télémétrie, qui est renseigné à l'aide d'un connecteur de séries chronologiques.

Exemple de données de table de télémétrie qui inclut l'ID d'actif, le type, la mesure, l'heure et les valeurs.

Les ensembles de données et la table de flux temporel utilisés dans cette capture d'écran sont disponibles dans le AWS IoT TwinMaker référentiel d'exemples. GitHub Consultez également l'exemple de connecteur Cookie Factory pour l'implémentation, qui produit le résultat illustré dans la capture d'écran précédente.

Time-series flux de données du connecteur de données

Pour les requêtes sur le plan de données AWS IoT TwinMaker , extrait les propriétés correspondantes des composants et des types de composants à partir des définitions des composants et des types de composants. AWS IoT TwinMaker transmet les propriétés aux AWS Lambda fonctions ainsi que tous les paramètres de requête d'API contenus dans la requête.

AWS IoT TwinMaker utilise les fonctions Lambda pour accéder aux requêtes provenant de sources de données, les résoudre et renvoyer les résultats de ces requêtes. Les fonctions Lambda utilisent les propriétés du composant et du type de composant du plan de données pour résoudre la demande initiale.

Les résultats de la requête Lambda sont mappés à une réponse d'API et vous sont renvoyés.

AWS IoT TwinMaker définit l'interface du connecteur de données et l'utilise pour interagir avec les fonctions Lambda. À l'aide de connecteurs de données, vous pouvez interroger votre source de données depuis AWS IoT TwinMaker l'API sans aucun effort de migration des données. L'image suivante présente le flux de données de base décrit dans les paragraphes précédents.

Les demandes et réponses d'API utilisent des requêtes et des réponses du connecteur 3P qui accèdent à une source de données.

Développement d'un connecteur de données chronologiques

La procédure suivante décrit un modèle de développement qui aboutit progressivement à un connecteur de données chronologique fonctionnel. La procédure de base est la suivante :

  1. Création d'un type de composant de base valide

    Dans un type de composant, vous définissez des propriétés communes qui sont partagées entre vos composants. Pour en savoir plus sur la définition des types de composants, voir Utilisation et création de types de composants.

    AWS IoT TwinMaker utilise un modèle de modélisation entité-composant afin que chaque composant soit attaché à une entité. Nous vous recommandons de modéliser chaque élément physique en tant qu'entité et de modéliser différentes sources de données avec leurs propres types de composants.

    L'exemple suivant montre un type de composant de modèle Timestream avec une propriété :

    {"componentTypeId": "com.example.timestream-telemetry",
    "workspaceId": "MyWorkspace",
    "functions": {
        "dataReader": {
            "implementedBy": {
                "lambda": {
                    "arn": "lambdaArn"
                }
            }
        }
    },
    "propertyDefinitions": {
        "telemetryType": {
            "dataType": { "type": "STRING" },
            "isExternalId": false,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "telemetryId": {
            "dataType": { "type": "STRING" },
            "isExternalId": true,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        }
    }
}

    Les principaux éléments du type de composant sont les suivants :

    • La telemetryId propriété identifie la clé unique de l'élément physique dans la source de données correspondante. Le connecteur de données utilise cette propriété comme condition de filtre pour interroger uniquement les valeurs associées à l'élément donné. En outre, si vous incluez la valeur de la telemetryId propriété dans la réponse de l'API du plan de données, le côté client prend l'ID et peut effectuer une recherche inversée si nécessaire.

    • Le lambdaArn champ identifie la fonction Lambda à laquelle le type de composant s'engage.

    • Le isRequiredInEntity drapeau impose la création de l'identifiant. Cet indicateur est obligatoire pour que l'ID de l'élément soit également instancié lors de la création du composant.

    • Le TelemetryId est ajouté au type de composant en tant qu'identifiant externe afin que l'élément puisse être identifié dans le tableau des flux temporels.

  2. Création d'un composant avec le type de composant

    Pour utiliser le type de composant que vous avez créé, vous devez créer un composant et l'associer à l'entité à partir de laquelle vous souhaitez récupérer les données. Les étapes suivantes détaillent le processus de création de ce composant :

    1. Accédez à la console AWS IoT TwinMaker.

    2. Sélectionnez et ouvrez l'espace de travail dans lequel vous avez créé les types de composants.

    3. Accédez à la page de l'entité.

    4. Créez une nouvelle entité ou sélectionnez une entité existante dans le tableau.

    5. Une fois que vous avez sélectionné l'entité que vous souhaitez utiliser, choisissez Ajouter un composant pour ouvrir la page Ajouter un composant.

    6. Donnez un nom au composant et, pour le Type, choisissez le type de composant que vous avez créé avec le modèle en 1. Créez un type de composant de base valide.

  3. Faites en sorte que votre type de composant appelle un connecteur Lambda

    Le connecteur Lambda doit accéder à la source de données, générer l'instruction de requête en fonction de l'entrée et la transmettre à la source de données. L'exemple suivant montre un modèle de requête JSON qui effectue cette opération. 

    {
  "workspaceId": "MyWorkspace",
  "entityId": "MyEntity",
  "componentName": "TelemetryData",
  "selectedProperties": ["Temperature"],
  "startTime": "2022-08-25T00:00:00Z",
  "endTime": "2022-08-25T00:00:05Z",
  "maxResults": 3,
  "orderByTime": "ASCENDING",
  "properties": {
      "telemetryType": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "Mixer"
          }
      },
      "telemetryId": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": true,
              "isFinal": true,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": true,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "item_A001"
          }
      },
      "Temperature": {
          "definition": {
              "dataType": { "type": "DOUBLE", },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      }
  }
}

    Les principaux éléments de la demande :

    • selectedPropertiesIl s'agit d'une liste que vous remplissez avec les propriétés pour lesquelles vous souhaitez obtenir des mesures Timestream.

    • Les endTime champs startDateTimestartTime,EndDateTime, et indiquent un intervalle de temps pour la demande. Cela détermine la plage d'échantillonnage pour les mesures renvoyées.

    • entityIdIl s'agit du nom de l'entité auprès de laquelle vous interrogez des données.

    • componentNameIl s'agit du nom du composant à partir duquel vous interrogez des données.

    • Utilisez le orderByTime champ pour organiser l'ordre dans lequel les résultats sont affichés.

    Dans l'exemple de demande précédent, nous nous attendons à obtenir une série d'échantillons pour les propriétés sélectionnées pendant la fenêtre de temps donnée pour l'élément donné, avec l'ordre temporel sélectionné. La déclaration de réponse peut être résumée comme suit :

    {
  "propertyValues": [
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "Temperature"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 588.168
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 592.4224
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 594.9383
          }
        }
      ]
    }
  ],
  "nextToken": "..."
}

  4. Mettez à jour votre type de composant pour qu'il ait deux propriétés

    Le modèle JSON suivant montre un type de composant valide avec deux propriétés :

    {
    "componentTypeId": "com.example.timestream-telemetry",
    "workspaceId": "MyWorkspace",
    "functions": {
        "dataReader": {
            "implementedBy": {
                "lambda": {
                    "arn": "lambdaArn"
                }
            }
        }
    },
    "propertyDefinitions": {
        "telemetryType": {
            "dataType": { "type": "STRING" },
            "isExternalId": false,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "telemetryId": {
            "dataType": { "type": "STRING" },
            "isExternalId": true,
            "isStoredExternally": false,
            "isTimeSeries": false,
            "isRequiredInEntity": true
        },
        "Temperature": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        },
        "RPM": {
            "dataType": { "type": "DOUBLE" },
            "isExternalId": false,
            "isTimeSeries": true,
            "isStoredExternally": true,
            "isRequiredInEntity": false
        }
    }
}

  5. Mettez à jour le connecteur Lambda pour gérer la deuxième propriété

    L'API du plan de AWS IoT TwinMaker données prend en charge l'interrogation de plusieurs propriétés en une seule demande et AWS IoT TwinMaker suit une seule demande adressée à un connecteur en fournissant une liste deselectedProperties.

    La requête JSON suivante montre un modèle modifié qui prend désormais en charge une demande pour deux propriétés.

    {
  "workspaceId": "MyWorkspace",
  "entityId": "MyEntity",
  "componentName": "TelemetryData",
  "selectedProperties": ["Temperature", "RPM"],
  "startTime": "2022-08-25T00:00:00Z",
  "endTime": "2022-08-25T00:00:05Z",
  "maxResults": 3,
  "orderByTime": "ASCENDING",
  "properties": {
      "telemetryType": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "Mixer"
          }
      },
      "telemetryId": {
          "definition": {
              "dataType": { "type": "STRING" },
              "isExternalId": true,
              "isFinal": true,
              "isImported": false,
              "isInherited": false,
              "isRequiredInEntity": true,
              "isStoredExternally": false,
              "isTimeSeries": false
          },
          "value": {
              "stringValue": "item_A001"
          }
      },
      "Temperature": {
          "definition": {
              "dataType": { "type": "DOUBLE" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      },
      "RPM": {
          "definition": {
              "dataType": { "type": "DOUBLE" },
              "isExternalId": false,
              "isFinal": false,
              "isImported": true,
              "isInherited": false,
              "isRequiredInEntity": false,
              "isStoredExternally": false,
              "isTimeSeries": true
          }
      }
  }
}

    De même, la réponse correspondante est également mise à jour, comme illustré dans l'exemple suivant :

    {
  "propertyValues": [
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "Temperature"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 588.168
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 592.4224
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 594.9383
          }
        }
      ]
    },
    {
      "entityPropertyReference": {
        "entityId": "MyEntity",
        "componentName": "TelemetryData",
        "propertyName": "RPM"
      },
      "values": [
        {
          "time": "2022-08-25T00:00:00Z",
          "value": {
            "doubleValue": 59
          }
        },
        {
          "time": "2022-08-25T00:00:01Z",
          "value": {
            "doubleValue": 60
          }
        },
        {
          "time": "2022-08-25T00:00:02Z",
          "value": {
            "doubleValue": 60
          }
        }
      ]
    }
  ],
  "nextToken": "..."
}
    Note

    En termes de pagination, dans ce cas, la taille de page de la demande s'applique à toutes les propriétés. Cela signifie qu'avec cinq propriétés dans la requête et une taille de page de 100, s'il y a suffisamment de points de données dans la source, vous devriez vous attendre à voir 100 points de données par propriété, avec 500 points de données au total.

    Pour un exemple d'implémentation, consultez l'exemple de connecteur Snowflake sur. GitHub

Améliorer votre connecteur de données

Gestion des exceptions

Le connecteur Lambda peut émettre des exceptions en toute sécurité. Lors de l'appel d'API du plan de données, le AWS IoT TwinMaker service attend que la fonction Lambda renvoie une réponse. Si l'implémentation du connecteur génère une exception, AWS IoT TwinMaker traduit le type d'exception en «ConnectorFailure, en informant le client de l'API qu'un problème s'est produit dans le connecteur.

Gestion de la pagination

Dans l'exemple, Timestream fournit une fonction utilitaire qui peut aider à prendre en charge la pagination de manière native. Cependant, pour certaines autres interfaces de requête, telles que SQL, la mise en œuvre d'un algorithme de pagination efficace peut nécessiter des efforts supplémentaires. Il existe un exemple de connecteur Snowflake qui gère la pagination dans une interface SQL.

Lorsque le nouveau jeton est renvoyé AWS IoT TwinMaker via l'interface de réponse du connecteur, il est chiffré avant d'être renvoyé au client API. Lorsque le jeton est inclus dans une autre demande, il le AWS IoT TwinMaker déchiffre avant de le transmettre au connecteur Lambda. Nous vous recommandons d'éviter d'ajouter des informations sensibles au jeton.

Tester votre connecteur

Bien que vous puissiez toujours mettre à jour l'implémentation après avoir lié le connecteur au type de composant, nous vous recommandons vivement de vérifier le connecteur Lambda avant de l'intégrer. AWS IoT TwinMaker

Il existe plusieurs méthodes pour tester votre connecteur Lambda : vous pouvez tester le connecteur Lambda dans la console Lambda ou localement dans le. AWS CDK

Pour plus d'informations sur le test de vos fonctions Lambda, consultez Tester les fonctions Lambda et Tester AWS CDK localement les applications.

Sécurité

Pour obtenir de la documentation sur les meilleures pratiques de sécurité avec Timestream, consultez la section Sécurité dans Timestream.

Pour un exemple de prévention des injections SQL, consultez le script Python suivant dans AWS IoT TwinMaker Samples GitHub Repository.

Création AWS IoT TwinMaker resources

Une fois que vous avez implémenté la fonction Lambda, vous pouvez créer AWS IoT TwinMaker des ressources telles que des types de composants, des entités et des composants via la AWS IoT TwinMaker console ou l'API.

Note

Si vous suivez les instructions de configuration de l' GitHub exemple, toutes les AWS IoT TwinMaker ressources sont disponibles automatiquement. Vous pouvez vérifier les définitions des types de composants dans l'AWS IoT TwinMaker GitHub exemple. Une fois que le type de composant est utilisé par un composant, les définitions de propriétés et les fonctions du type de composant ne peuvent pas être mises à jour.

Tests d'intégration

Nous vous recommandons de réaliser un test intégré AWS IoT TwinMaker pour vérifier que la requête du plan de données fonctionne de bout en bout. Vous pouvez le faire via GetPropertyValueHistory l'API ou facilement dans AWS IoT TwinMaker la console.

Une TwinMaker page de console d'informations sur les composants affiche le nom, le type, l'état du composant, etc.

Dans la AWS IoT TwinMaker console, accédez aux détails du composant, puis sous Test, vous verrez que toutes les propriétés du composant y sont répertoriées. La zone Test de la console vous permet de tester des propriétés de séries chronologiques ainsi que des propriétés autres que des séries chronologiques. Pour les propriétés de séries chronologiques, vous pouvez également utiliser l' GetPropertyValueHistoryAPI et pour les propriétés autres que des séries chronologiques, utilisez l'API. GetPropertyValue Si votre connecteur Lambda prend en charge plusieurs requêtes de propriétés, vous pouvez choisir plusieurs propriétés.

Partie de la page de la console d'informations sur les TwinMaker composants montrant le test d'un composant.

Quelle est la prochaine étape

Vous pouvez désormais configurer un tableau de bord AWS IoT TwinMaker Grafana pour visualiser les métriques. Vous pouvez également explorer d'autres exemples de connecteurs de données dans le GitHub référentiel d'AWS IoT TwinMaker exemples pour voir s'ils correspondent à votre cas d'utilisation.