Documentation Oracle Cloud Infrastructure

Création d'un adaptateur jumeau numérique

Créez un adaptateur jumeau numérique pour convertir les charges utiles de 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 mapping.

Concepts

Un adaptateur jumeau numérique est requis lors de 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 le périphérique peut être programmé pour envoyer des données dans le format que vous souhaitez utiliser, créez un adaptateur jumeau numérique sans indiquer inbound-envelope ou inbound-routes. La réponse contiendra des données au format par défaut de l'appareil. Si le mapping d'enveloppe est spécifié et contient une valeur timeObserved, receivedTime est utilisé en tant que valeur timeObserved. Pour obtenir un exemple spécifique, reportez-vous à Scénario : envoi de données structurées au format par défaut à l'aide de HTTP.
  • Format d'adaptateur personnalisé : pour les périphériques 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 inbound-envelope et un envelope-mapping personnalisés transformant la charge utile et les métadonnées pour obtenir la sortie avec laquelle vous souhaitez travailler. Pour obtenir un exemple spécifique, reportez-vous à Scénario : envoi de données structurées dans un format personnalisé à l'aide de HTTP.
  • ID d'authentification : lorsque vous créez un adaptateur jumeau numérique si vous connectez un périphérique, l'instance de jumeau numérique associée doit utiliser un paramètre d'ID d'authentification, avec un certificat ou un secret pour authentifier le périphérique.
  • Clé externe : une fois que vous avez 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 le périphérique.
  • Limite : le nombre maximal de routes entrantes pour un adaptateur jumeau numérique est de 128.
Exemple d'entrée de charge utile d'appareil, de mapping JSON et de résultat transformé

Vous pouvez essayer le mapping d'adaptateur dans JQ Playground en collant la charge utile en tant qu'entrée de requête, en ajoutant le mapping JSON dans la section JSON, puis en affichant le résultat de sortie.

Exemple JSON de charge utile d'appareil :

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

Utilisez une expression JQ ou la notation JsonPath pour créer une sortie de mapping JSON de charge utile 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 mapping JSON de charge utile d'adaptateur :
{ "temperature": "$.temp", "humidity": "$.hum", "timeObserved": "$.time" }
Résultat de la sortie transformée :
{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

Pour plus d'exemples, reportez-vous à Référence : Expressions JQ pour les adaptateurs de jumeaux numériques 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 IoT, sélectionnez le domaine IoT avec lequel vous voulez travailler. Si vous avez besoin d'aide pour trouver la page de liste des domaines IoT, reportez-vous à Liste des domaines IoT.
    2. Sélectionnez l'onglet Adaptateurs de jumeaux numériques, puis Créer.
    3. Entrez un nom et éventuellement une description. Evitez de saisir des informations confidentielles.
    4. Pour trouver le modèle de jumeau numérique que vous voulez associer :
      • Sélectionner un modèle : permet de rechercher le modèle de jumeau numérique par nom.
      • Sélectionner avec l'URI de spécification de modèle : permet de rechercher le modèle de jumeau numérique à l'aide du DTMI. Par exemple, dtmi:com:example:iot:demo;1
    5. Dépend du fait que le périphérique avec lequel vous travaillez peut être programmé pour envoyer des données dans des formats spécifiques :
      • Si le périphérique 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 routages de l'adaptateur, l'adaptateur est généré à partir de la charge utile du périphérique.
      • Si le périphérique ne peut pas programmer l'envoi de données au format souhaité, indiquez un adaptateur pour convertir les données entrantes au format de données que vous souhaitez utiliser. Activez l'option Spécifier l'enveloppe et les routages entrants :
        • Charger le fichier d'enveloppes entrantes .json : chargez un fichier .json contenant l'enveloppe entrante pour cet adaptateur.
        • Coller le JSON de l'enveloppe entrante : ajoutez le JSON de l'enveloppe entrante à cet adaptateur.
    6. Spécification des routages entrants : ajoutez une liste de définitions de routage avec des conditions et des mappings de charge utile facultatifs. Les routages sont évalués dans l'ordre.
      • Télécharger le fichier .json des routages entrants vers le serveur : chargez les routages entrants dans un fichier .json.
      • Coller les routages entrants au format JSON : ajoutez les routages entrants au format JSON.
    7. Balises : (facultatif) ajoutez des balises à l'adaptateur jumeau numérique. Si vous êtes autorisé à créer une ressource, vous disposez également des droits d'accès nécessaires pour lui appliquer des balises à format libre. Pour appliquer une balise définie, vous devez disposer de droits d'accès permettant d'utiliser l'espace de noms de balise. Pour plus d'informations sur le balisage, reportez-vous à Balises de ressource. Si vous n'êtes pas certain d'appliquer des balises, ignorez cette option ou demandez à un administrateur. Vous pouvez appliquer des balises ultérieurement.
    8. Choisissez 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 le périphérique peut être programmé, vous créez un adaptateur jumeau numérique sans spécifier inbound-envelope ou envelope-mapping, de sorte que les données par défaut provenant du périphérique sont acceptées dans la réponse.

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

    • Utilisation du DTMI :

      L'exemple suivant utilise le paramètre URI DTMI pour associer l'adaptateur au modèle de jumeau numérique. Remplacez <digital-twin-model-spec-uri> par l'URI DTMI de votre 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 de modèle de jumeau numérique :
      L'exemple suivant utilise également le paramètre --digital-twin-model-id avec <digital-twin-model-OCID> pour le modèle de jumeau numérique à 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é, procédez comme suit :

    Utilisez la commande oci iot digital-twin-adapter create et le paramètre --iot-domain-id requis. Pour créer un adaptateur de jumeau numérique personnalisé, définissez une valeur inbound-envelope ou inbound-route spécifique afin d'obtenir la sortie à utiliser. Pour ce faire, définissez un mapping de charge utile 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 de votre modèle jumeau numérique associé et remplacez <iot-domain-OCID> par l'OCID de 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, reportez-vous à la section Using a JSON File for Complex Input.

    Pour obtenir la liste complète des paramètres et des valeurs des commandes de la CLI, reportez-vous à Référence des commandes de la CLI.

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