Documentation sur Oracle Cloud Infrastructure

Création d'un adaptateur jumeau numérique

Créez un adaptateur jumeau numérique pour convertir les données brutes provenant d'un appareil physique ou d'un système externe en données de télémétrie normalisées basées sur le modèle jumeau numérique.

Les données sont transmises à l'adaptateur jumeau numérique en tant qu'objet JSON contenant les données et le mappage.

Concepts

Un adaptateur jumeau numérique est requis pour l'utilisation de données structurées.

Il existe deux façons d'utiliser un adaptateur jumeau numérique, selon que l'appareil avec lequel vous travaillez peut être programmé pour envoyer des données :

  • Format d'adaptateur par défaut : Si l'appareil peut être programmé pour envoyer des données dans le format avec lequel vous voulez travailler, créez un adaptateur jumeau numérique sans spécifier inbound-envelope ou inbound-routes. La réponse contiendra des données dans le format par défaut de l'appareil. Si le mappage d'enveloppe est spécifié et contient une valeur timeObserved, receivedTime est utilisé en tant que valeur timeObserved. Pour un exemple spécifique, voir Scénario : Envoi de données structurées dans un format par défaut à l'aide de HTTP.
  • Format d'adaptateur personnalisé : Pour les appareils qui ne peuvent pas être programmés pour envoyer des données, vous pouvez créer un adaptateur jumeau numérique personnalisé en définissant un adaptateur personnalisé inbound-envelope et envelope-mapping en transformant les données utiles et les métadonnées pour obtenir la sortie avec laquelle vous voulez travailler. Pour un exemple spécifique, voir Scénario : Envoi de données structurées dans un format personnalisé à l'aide de HTTP.
  • ID authentification : Lorsque vous créez un adaptateur jumeau numérique si vous connectez un appareil, l'instance jumeau numérique associée doit utiliser un paramètre d'ID authentification, avec un certificat ou une clé secrète pour authentifier l'appareil.
  • Clé externe : Après avoir créé un adaptateur jumeau numérique, vous pouvez mettre à jour l'adaptateur jumeau numérique pour modifier la clé externe d'un appareil. Lorsque vous envoyez des données, utilisez la clé externe comme nom d'utilisateur pour l'appareil.
  • Limite : Le nombre maximal de routes entrantes pour un adaptateur jumeau numérique est de 128.
Exemple d'entrée de données utiles de périphérique, de mappage JSON et de résultat transformé

Vous pouvez essayer le mappage d'adaptateur dans JQ Playground en collant les données utiles en tant qu'entrée d'interrogation, en ajoutant le mappage JSON dans la section JSON, puis en affichant le résultat de sortie.

Exemple JSON de données utiles de l'appareil :

{ "time": "<timestamp>", "temp": 65, "hum": 55 }

Utilisez une expression JQ ou une notation JsonPath pour créer une sortie de mappage JSON de données utiles d'adaptateur.

Cet exemple utilise une expression JQ : 
{ "temperature": ".temp", "humidity": ".hum", "timeObserved": ".time" }
Cet exemple utilise la notation JsonPath pour créer une sortie de mappage JSON de données utiles d'adaptateur :
{ "temperature": "$.temp", "humidity": "$.hum", "timeObserved": "$.time" }
Résultat de sortie transformé :
{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

Pour plus d'exemples, voir Référence : Expressions JQ pour les adaptateurs de jumeau numérique et Scénarios.

  • Si l'appareil envoie ou reçoit des données non structurées, vous n'avez pas besoin de spécifier un adaptateur jumeau numérique.

    1. Dans la page de liste Domaines IdO, sélectionnez le domaine IdO avec lequel vous voulez travailler. Si vous avez besoin d'aide pour trouver la page de liste des domaines IoT, voir Liste des domaines IoT.
    2. Sélectionnez l'onglet Adaptateurs jumeaux numériques, sélectionnez Créer.
    3. Entrez un nom et facultativement une description. Évitez d'entrer des informations confidentielles.
    4. Pour trouver le modèle de jumeau numérique que vous souhaitez associer :
      • Sélectionner un modèle : Pour rechercher le modèle de jumeau numérique par nom.
      • Sélectionner avec l'URI de spécification de modèle : Pour rechercher le modèle jumeau numérique à l'aide du DTMI. Par exemple, dtmi:com:example:iot:demo;1
    5. Dépend du fait que l'appareil avec lequel vous travaillez peut être programmé pour envoyer des données dans des formats spécifiques :
      • Si l'appareil peut être programmé pour envoyer des données dans un format spécifique, vous n'avez pas besoin de spécifier l'enveloppe et les itinéraires de l'adaptateur, l'adaptateur est généré à partir des données utiles de l'appareil.
      • Si l'appareil ne peut pas être programmé pour envoyer des données dans le format souhaité, spécifiez un adaptateur pour traduire les données utiles entrantes dans le format de données avec lequel vous voulez travailler. Activez l'option Spécifier l'enveloppe et les routes entrantes :
        • Charger le fichier .json d'enveloppe entrante : Chargez un fichier .json qui contient l'enveloppe entrante pour cet adaptateur.
        • Coller l'enveloppe entrante JSON : Ajoutez l'enveloppe entrante JSON à cet adaptateur.
    6. Spécification des routes entrantes : Ajoutez une liste de définitions de routes avec des conditions et des mappages de données utiles facultatifs. Les itinéraires sont évalués dans l'ordre.
      • Charger le fichier .json des routes entrantes : Chargez les routes entrantes dans un fichier .json.
      • Coller le JSON des routes entrantes : Ajoutez les routes entrantes au format JSON.
    7. Marqueurs : (Facultatif) Ajoutez un ou plusieurs marqueurs à l'adaptateur jumeau numérique. Si vous êtes autorisé à créer une ressource, vous disposez également des autorisations nécessaires pour appliquer des marqueurs à structure libre à cette ressource. Pour appliquer un marqueur défini, vous devez être autorisé à utiliser l'espace de noms de marqueur. Pour plus d'informations sur le marquage, voir Marqueurs de ressource. Si vous ne savez pas si vous devez appliquer des marqueurs, ignorez cette option ou demandez à un administrateur. Vous pouvez appliquer des marqueurs plus tard.
    8. Sélectionnez Créer.

  • Utilisez la commande oci iot digital-twin-adapter create et les paramètres requis pour créer un adaptateur jumeau numérique.

    Pour créer un adaptateur jumeau numérique pour les données structurées dans un format par défaut : Si l'appareil peut être programmé, vous créez un adaptateur jumeau numérique sans spécifier le inbound-envelope ou le envelope-mapping. Par conséquent, les données par défaut provenant de l'appareil sont acceptées dans la réponse.

    Deux options pour associer le modèle de jumeau numérique :

    • Utilisation de DTMI :

      L'exemple suivant utilise le paramètre URI DTMI pour associer l'adaptateur au modèle jumeau numérique. Remplacez <digital-twin-model-spec-uri> par l'URI DTMI du modèle jumeau numérique associé. 
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>'
    • Utilisation de l'OCID du modèle de jumeau numérique :
      Sinon, l'exemple suivant utilise le paramètre --digital-twin-model-id avec <digital-twin-model-OCID> pour le modèle de jumeau numérique que vous souhaitez associer à un adaptateur de jumeau numérique :
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-id <digital-twin-model-OCID>

    Pour créer un adaptateur jumeau numérique pour les données structurées dans un format personnalisé :

    Utilisez la commande oci iot digital-twin-adapter create et le paramètre --iot-domain-id requis. Pour créer un adaptateur jumeau numérique personnalisé, définissez des valeurs inbound-envelope ou inbound-route spécifiques pour obtenir la sortie avec laquelle vous voulez travailler. Pour ce faire, définissez un mappage de données utiles personnalisé pour votre jumeau numérique à l'aide d'un fichier <file://inbound-envelope.json> et d'un fichier <file://inbound-routes.json> à l'aide d'expressions JQ.

    Remplacez <digital-twin-model-spec-uri> par l'URI DTMI du modèle jumeau numérique associé et remplacez <iot-domain-OCID> par l'OCID du domaine IoT à associer à cet adaptateur jumeau numérique :

    oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>' --inbound-envelope <file://inbound-envelope.json> --inbound-routes <file://inbound-routes.json>

    Pour plus d'informations sur le référencement de fichiers, voir Utilisation d'un fichier JSON pour les entrées complexes.

    Pour la liste complète des paramètres et des valeurs pour les commandes de l'interface de ligne de commande, voir Informations de référence sur les commandes de l'interface de ligne de commande.

  • Exécutez l'opération CreateDigitalTwinAdapter pour créer un adaptateur jumeau numérique dans le domaine IoT spécifié.