Développement de connecteurs AWS IoT TwinMaker de données de séries chronologiques - AWS IoT TwinMaker
AWS IoT TwinMaker prérequis pour les connecteurs de données chronologiquesContexte du connecteur de données chronologiquesDéveloppement d'un connecteur de données chronologiquesAméliorer votre connecteur de donnéesTest de votre connecteurSécuritéCréation de AWS IoT TwinMaker ressources Quelle 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.

Développement de connecteurs AWS IoT TwinMaker de données de séries chronologiques

Cette section explique comment développer un connecteur de données de séries chronologiques dans le step-by-step cadre d'un processus. En outre, nous présentons un exemple de connecteur de données chronologiques basé sur l'ensemble de l'échantillon de Cookie Factory, qui inclut 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 d'implémentation d'une fabrique de cookies.

Contexte du connecteur de données chronologiques

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

Vous avez installé 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 table de télémétrie, qui est renseignée à l'aide d'un connecteur de séries chronologiques.

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

Les ensembles de données et la table Timestream 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 indiqué dans la capture d'écran précédente.

Flux de données du connecteur de données chronologique

Pour les requêtes de 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 de données. L'image suivante décrit le flux de données de base décrit dans les paragraphes précédents.

Les demandes et réponses d'API utilisent les demandes et 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 se développe progressivement pour devenir un connecteur de données de séries chronologiques 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 partagées entre vos composants. Pour en savoir plus sur la définition des types de composants, consultez la section 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 doté d'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 éléments clés 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 n'interroger que 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 avec laquelle le type de composant s'engage.

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

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

  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écrivent le processus de création de ce composant :

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

    2. Sélectionnez et ouvrez le même 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 demande 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 renseignez avec les propriétés pour lesquelles vous souhaitez obtenir des mesures Timestream.

    • Les endTime champs startDateTimestartTime,EndDateTime, et spécifient une plage 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é à partir de laquelle vous demandez des données.

    • componentNameIl s'agit du nom du composant à partir duquel vous interrogez les 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 attendrions à obtenir une série d'échantillons pour les propriétés sélectionnées pendant la fenêtre temporelle 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 indiqué 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, le format de page indiqué dans 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é, soit 500 points de données au total.

    Pour un exemple d'implémentation, voir Exemple de connecteur Snowflake activé. GitHub

Améliorer votre connecteur de données

Gestion des exceptions

Le connecteur Lambda peut lancer des exceptions en toute sécurité. Dans 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, le type d'exception est AWS IoT TwinMaker traduit par : le client API est ainsi informé qu'un problème s'est produit dans le connecteur. ConnectorFailure

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, le jeton est crypté 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.

Test de 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 manières de 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 les applications localement. AWS CDK

Sécurité

Pour obtenir de la documentation sur les meilleures pratiques en matière 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 de AWS IoT TwinMaker ressources

Une fois que vous avez implémenté la fonction Lambda, vous pouvez créer des AWS IoT TwinMaker 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 d'effectuer un test intégré AWS IoT TwinMaker pour vérifier que la requête du plan de données fonctionne end-to-end. Vous pouvez le faire via GetPropertyValueHistoryl'API ou facilement dans AWS IoT TwinMaker la console.

Une TwinMaker page de console d'informations sur les composants indique 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 les propriétés des séries chronologiques ainsi que les non-time-series propriétés. Pour les propriétés des séries chronologiques, vous pouvez également utiliser l' GetPropertyValueHistoryAPI et pour les non-time-series propriétés, utilisez l' GetPropertyValueAPI. Si votre connecteur Lambda prend en charge les requêtes de propriétés multiples, vous pouvez choisir plusieurs propriétés.

Partie d'une page de console d'informations sur les TwinMaker composants présentant 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 échantillons pour voir s'ils correspondent à votre cas d'utilisation.