Démarrage rapide : Créer un jumeau numérique et envoyer des données

Ce scénario montre comment créer une instance de jumeau numérique et comment tester votre configuration en envoyant des données-échantillons à l'aide de l'authentification de base.

Conditions requises

Un administrateur doit créer des politiques pour que votre utilisateur puisse accéder aux ressources OCI avec lesquelles vous voulez travailler. Les politiques suivantes sont requises pour configurer ce scénario. Pour plus d'informations sur les politiques supplémentaires liées aux autres scénarios IoT, voir Préalables.

Politiques IoT

Utilisez cette politique de famille IoT pour permettre au groupe d'utilisateurs spécifié de gérer n'importe quelle ressource IoT dans un compartiment spécifique ou votre administrateur peut utiliser des politiques IoT pour configurer des politiques spécifiques pour des ressources IoT spécifiques :

Allow group <group-name> to manage iot-family in compartment <your-compartment-name>

Politiques de clé secrète de chambre forte

Lorsque vous utilisez la commande pour l'étape 3 : Créer une instance de jumeau numérique si vous utilisez l'authentification de base, vous devez créer une clé secrète, pour ce faire, vous avez besoin de la politique suivante.

Autoriser un utilisateur IoT à lire des clés secrètes dans un compartiment et une chambre forte spécifiques pour un domaine IoT :

Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}

Étape 1 : Créer un groupe de domaines IoT

Si vous avez un groupe de domaines IoT ou un domaine IoT existant avec lequel vous voulez travailler, ignorez cette étape et utilisez ces OCID pour créer l'instance de jumeau numérique associée. Vous pouvez également effectuer ces étapes pour créer un groupe de domaines IoT et un domaine IoT. Pour obtenir la liste complète des options, voir Création d'un groupe de domaines IoT.

1. Dans la page de liste des groupes de domaines IoT, sélectionnez Créer un groupe de domaines. Si vous avez besoin d'aide pour trouver la page de liste, voir Liste des groupes de domaines IoT.
2. Dans la page Créer un groupe de domaines, entrez un nom convivial pour le nouveau groupe de domaines et une description facultative. Évitez d'entrer des informations confidentielles.
3. Sélectionnez le compartiment dans lequel stocker le nouveau groupe de domaines. Votre groupe de domaines IoT et votre domaine IoT peuvent se trouver dans des compartiments différents. Toutes les ressources IoT doivent se trouver dans la même région.
4. Sélectionnez un type de groupe de domaines. Le développeur est le type par défaut. Vous ne pouvez pas modifier le type de groupe de domaines, mais créer un nouveau groupe de domaines.
  
  Développeur : À utiliser pour le développement et les tests, réduit les coûts et utilise moins de ressources.
  
  Standard : Pour les groupes de domaines de production, désactivez l'option de développement pour ajuster les ressources et activer la haute disponibilité avec un basculement automatique.
  
  Note
  
  Vous ne pouvez pas modifier le type de groupe de domaines, mais créer un nouveau groupe de domaines.
5. Sélectionnez Créer.
Utilisez la commande oci iot domain-group create et le paramètre --compartment-id requis pour créer un groupe de domaines IoT dans un compartiment spécifique. Remplacez la valeur <compartment-OCID> par l'OCID de votre compartiment :
oci iot domain-group create --compartment-id <compartment-OCID>
Option Type :
Si vous ne spécifiez pas --type, le type de groupe de domaines par défaut est lightweight, pour le développement et le test d'un groupe de domaines léger qui coûte moins cher et utilise moins de ressources. Lorsque vous voulez créer un groupe de domaines de production, utilisez l'option standard.
Pour un groupe de domaines de production, utilisez le paramètre --type avec la valeur standard pour créer un groupe de domaines standard qui s'adapte avec une haute disponibilité et un basculement automatique.
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 CreateIotDomainGroup pour créer un groupe de domaines IoT dans un compartiment.

Étape 2 : Créer un domaine IoT

1. Dans la page de liste Domaine IoT, sélectionnez un compartiment dans lequel vous voulez stocker vos domaines IoT. Votre groupe de domaines IoT et votre domaine IoT peuvent se trouver dans des compartiments différents. Vos IoT ressources de jumeau numérique peuvent se trouver dans des compartiments différents et doivent se trouver dans la même région. Si vous avez besoin d'aide pour trouver la page de liste des domaines IoT, voir Liste des domaines IoT.
2. Sélectionnez Créer un domaine.
3. Entrez un nom convivial pour le domaine IoT. Évitez d'entrer des informations confidentielles.
4. (Facultatif) Entrez une description.
5. Sélectionnez le compartiment du groupe de domaines associé, puis sélectionnez le groupe de domaines à associer à ce domaine.
6. Sélectionnez Créer.
7. Voir et copier des points d'extrémité pour l'hôte de l'appareil du domaine IoT, l'hôte de l'appareil affiche l'ID abrégé du domaine. Sélectionnez Copier pour copier ce point d'extrémité à utiliser à l'étape suivante.
  device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com
  
  Pour obtenir la liste complète des options, voir Création d'un domaine IoT.
1. Utilisez la commande oci iot domain create et les paramètres requis pour créer un domaine IoT.
2. Remplacez <iot-domain-group-OCID> par le groupe de domaines IoT que vous voulez associer au domaine IoT. Remplacez <compartment-OCID> par l'OCID du compartiment pour le domaine IoT :
  oci iot domain create --compartment-id <compartment-OCID> --iot-domain-group-id <iot-domain-group-OCID>
  
  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 CreateIotDomain pour créer un domaine IoT.

Étape 3 : Créer une instance de jumeau numérique

Dans cet exemple, l'instance de jumeau numérique n'est pas associée à un modèle de jumeau numérique ou à un adaptateur de jumeau numérique. Vous pouvez utiliser cette méthode si vous testez simplement la configuration d'un jumeau numérique ou si vous configurez une instance de jumeau numérique pour vous connecter à un appareil qui envoie des données non structurées. Pour obtenir la liste complète des options, voir Création d'une instance de jumeau numérique.

Options de clé externe : La clé externe est le nom d'utilisateur de l'appareil lors de la connexion à un appareil pour envoyer des données à l'étape 5. Si vous n'incluez pas de paramètre --external-key, la clé externe est générée dans la réponse. Si vous spécifiez la clé externe, il est recommandé de ne pas utiliser de guillemets avec la valeur de la clé externe.
Options d'authentification : Lorsque vous créez une instance de jumeau numérique, l'authentification est facultative et n'est requise que si vous envoyez des données vers ou depuis un appareil. Ajoutez l'authentification à l'instance de jumeau numérique à l'aide du paramètre --auth-id.

L'exemple suivant utilise une clé secrète pour l'authentification. Vous pouvez utiliser une clé secrète pour un environnement de test. Pour un environnement de production sécurisé, l'instance de jumeau numérique doit utiliser un certificat mTLS pour l'authentification.

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 Instances jumeaux numériques, puis sélectionnez Créer.
3. Entrez un nom et facultativement une description. Évitez d'entrer des informations confidentielles.
4. Facultative. Entrez une clé externe qui est un identificateur unique. Si vous ne spécifiez pas de clé externe, elle est générée lors de l'enregistrement de cette instance de jumeau numérique. Utilisez la clé externe comme nom d'utilisateur de l'appareil lorsque vous connectez ou envoyez des données à l'appareil.
5. Sélectionnez le type :
  Connexion directe : Connectez un appareil ou une entité directement au domaine IdO. Si le périphérique ou l'entité envoie des données structurées, sélectionnez un adaptateur. La sélection d'un adaptateur associe cette instance de jumeau numérique à une couche de transformation qui convertit les données utiles de périphérique entrant dans la structure DTDL du modèle de jumeau numérique associé attendue par l'instance.
  Sélectionner un adaptateur : Activez et sélectionnez un adaptateur jumeau numérique dans la liste pour associer l'adaptateur à cette instance de jumeau numérique. Si vous n'avez pas d'adaptateur, créez un adaptateur jumeau numérique.
  Si le périphérique envoie des données structurées, vous devez sélectionner un adaptateur. Un adaptateur n'est pas requis si l'appareil ou l'entité auquel vous voulez vous connecter envoie des données non structurées ou reçoit des commandes de données non structurées.
  Non connecté : Utilisez cette option pour créer une instance de jumeau numérique réservée à la simulation sans ingestion de données. Un modèle jumeau numérique est requis et ne doit pas contenir de télémétrie ou de propriétés. Après avoir créé cette instance de jumeau numérique, vous pouvez ajouter des relations de jumeau numérique pour simuler votre environnement IdO sans la complexité de l'ingestion ou de l'authentification de données.
  ID authentification : Si l'appareil ou l'entité envoie ou reçoit des données, vous devez spécifier un ID authentification. Pour tester l'ID authentification de la clé secrète de la chambre forte et pour le service de production, créez un certificat mTLS pour l'ID authentification de l'instance de jumeau numérique.
  Sélectionner l'ID authentification : Sélectionnez l'option de clé secrète ou de certificat. Pour une clé secrète, sélectionnez le compartiment de la chambre forte, la chambre forte et la clé secrète. Pour un certificat, sélectionnez le compartiment du certificat, puis le certificat.
  Coller l'OCID de l'authentification : Collez l'OCID du certificat ou de la clé secrète.
  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.
6. Sélectionnez Créer.
1. Utilisez la commande oci iot digital-twin-instance create et ces paramètres pour créer une instance de jumeau numérique.
2. Remplacez <iot-domain-OCID> par le domaine IoT que vous voulez associer à cette instance de jumeau numérique IoT. Remplacez <secret-or-certificate-OCID> par l'OCID de la clé secrète de la chambre forte :
  oci iot digital-twin-instance create --auth-id <secret-OCID> --iot-domain-id <iot-domain-OCID>
Pour obtenir la liste complète des paramètres et des valeurs, voir Informations de référence sur les commandes de l'interface de ligne de commande IoT et Informations de référence sur les commandes de l'interface de ligne de commande.
Exécutez l'opération CreateDigitalTwinInstance pour créer une instance de jumeau numérique.

Étape 4 : Obtenir les détails du domaine IoT

Si vous disposez du point d'extrémité d'hôte de l'appareil pour le domaine IoT à utiliser, ignorez cette étape.

Les détails du domaine IoT contiennent l'hôte de l'appareil, y compris l'ID court du domaine, pour plus de Obtention des détails d'un domaine IoT,

1. Dans la page de liste IoT Domaines, sélectionnez le domaine avec lequel vous voulez travailler. Si vous avez besoin d'aide pour trouver la page de liste des domaines IoT ou les domaines IoT, voir Liste des domaines IoT.
2. Détails : Voir ou modifier le nom du domaine et la description, copier l'OCID, le point d'extrémité hôte de l'appareil, voir le compartiment et l'horodatage de la création du domaine.
  device-host : <domain-short-id>.device.iot.<region>.oci.oraclecloud.com
3. Accédez aux différentes ressources et tâches associées au domaine en sélectionnant les liens ou les onglets. Pour une description des paramètres de domaine, voir Création d'un domaine IoT
Utilisez la commande oci iot domain get et le paramètre requis pour obtenir les détails d'un domaine IoT, notamment l'hôte de l'appareil avec l'ID court de domaine :
oci iot domain get --iot-domain-id <iot-domain-OCID>
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 GetIotDomain pour obtenir les détails d'un domaine.

Étape 5 : Envoyer les données

Envoyez des données-échantillons à l'instance de jumeau numérique créée à l'étape 3 : Créer une instance de jumeau numérique précédente.

Nom d'utilisateur de l'appareil : Utilisez external key de l'instance de jumeau numérique comme nom d'utilisateur de l'appareil.
Mot de passe de l'appareil : Est associé à l'ID authentification de l'instance de jumeau numérique. Si l'instance de jumeau numérique utilise un OCID de clé secrète de chambre forte pour l'authentification, utilisez le contenu de clé secrète en texte brut comme mot de passe de l'appareil, voir Création d'une clé secrète et Obtention du contenu d'une clé secrète. L'utilisation d'une clé secrète de chambre forte comme mot de passe de périphérique est recommandée uniquement pour les tests et non pour la production.

L'exemple suivant utilise une clé secrète pour l'authentification. Sinon, pour la production, l'instance de jumeau numérique doit utiliser un certificat mTLS pour l'authentification.

Utilisation de Curl
Composants de style POSIX : Utilisez cette commande curl lors de l'utilisation de bash, zsh, terminal macOS, Linux ou Git Bash sous Windows.
curl -u '<digital-twin-instance-external-key>:<device-password>' \ -H 'Content-Type: text/plain' \ -d 'sample data 1' \ 'https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic'
Windows Powershell : Utilisez cette commande curl dans cet exemple, utilisez -G pour effectuer une demande GET et ajoutez toutes les données fournies avec --data-urlencode à l'URL en tant que paramètres d'interrogation. Vous pouvez également utiliser les variables environnementales.
```
curl.exe -u "<digital-twin-instance-external-key>:<device-password>" `
  -H "Content-Type: text/plain" `
  -d "sample data 1" `
  "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"
```
Lorsque vous avez terminé l'étape 3 : Créer une instance de jumeau numérique, si vous avez défini la valeur du paramètre de clé externe avec des guillemets, vous devez inclure les guillemets lorsque vous envoyez des données : "external-key". Pour citer les meilleures pratiques, voir Dépannage.
Utilisez n'importe quel client MQTT, cet exemple utilise MQTTX avec les paramètres suivants.
1. Pour télécharger et configurer MQTTX, suivez ces instructions, voir Introduction à MQTTX. Ouvrez MQTTX.
2. Sélectionnez + Nouvelle connexion pour créer une nouvelle connexion.
3. Entrez la valeur <unique-id> de la clé externe dans le champ Nom d'utilisateur. Vous pouvez trouver la clé externe dans la réponse oci iot digital-twin-instance create, à partir de l'étape 3 : Créer une instance de jumeau numérique précédente :
  "external-key": "<unique-id>"
4. Entrez le mot de passe de l'appareil. Si vous testez l'utilisation de la clé secrète de chambre forte, il doit s'agir du contenu de la clé secrète en texte brut. Ou pour un environnement de production sécurisé, utilisez un certificat MTLS.
5. Entrez l'hôte. Sélectionnez le protocole mqtts:// dans la liste déroulante des hôtes et entrez l'hôte de l'appareil : <domain-short-id>.device.iot.<region>.oci.oraclecloud.com dans le domaine IoT.
6. Entrez le port, par exemple : 8883
  Note
  
  Actuellement, MQTT Secure (MQTTS) n'est pris en charge qu'avec le port 8883.
7. Activez l'option SSL/TLS.
8. Activez l'option SSL Secure.
9. Pour le certificat, sélectionnez l'option Certificat de serveur signé par une autorité de certification.
10. Lorsque vous configurez la connexion MQTTX, veillez à vous connecter à l'aide d'un clean session et réglez l'option Last-Will-Retain à false pour permettre la conservation des abonnements clients si l'appareil se déconnecte brièvement.
11. Réglez Dernière volonté QoS à 1.
12. Sélectionnez Connexion.
Une fois ces étapes terminées, vous disposez d'une instance de jumeau numérique dans la plate-forme IoT qui peut recevoir des données à partir d'un appareil.

Que faire ensuite

Consultez les fichiers-échantillons IoT pour configurer les environnements de test et de production.
Configurez APEX pour voir les données de domaine IoT dans APEX, puis installez un exemple d'application d'exploration APEX IoT pour surveiller visuellement vos appareils et messages IoT.
Si vous ne prévoyez pas de conserver les ressources, supprimez les domaines IoT associés au groupe de domaines IoT et supprimez le groupe de domaines IoT.

Documentation sur Oracle Cloud Infrastructure