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 exemples de données à l'aide de l'authentification de base.

Prérequis

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

Stratégies IoT

Utilisez cette stratégie de famille IoT pour permettre au groupe d'utilisateurs indiqué de gérer n'importe quelle ressource IoT dans un compartiment spécifique ou l'administrateur peut utiliser des stratégies IoT pour configurer des stratégies spécifiques pour des ressources IoT spécifiques :

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

Stratégies de clé secrète de coffre

Lorsque vous utilisez la commande pour Etape 3 : création d'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 stratégie suivante.

Autorisez tout utilisateur IoT à lire les clés secrètes dans un compartiment et un coffre 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>'}

Etape 1 : création d'un groupe de domaines IoT

Si vous disposez d'un groupe de domaines IoT ou d'un domaine IoT existant à utiliser, 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, reportez-vous à Création d'un groupe de domaines IoT.

1. Sur 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, reportez-vous à Liste des groupes de domaines IoT.
2. Sur la page Créer un groupe de domaines, entrez un nom convivial pour le nouveau groupe de domaines et une description facultative. Evitez de saisir des informations confidentielles.
3. Sélectionnez le compartiment dans lequel stocker le nouveau groupe de domaines. Le groupe de domaines IoT et le domaine IoT peuvent se trouver dans différents compartiments. Toutes les ressources IoT doivent se trouver dans la même région.
4. Sélectionnez un type de groupe de domaines. Le Developer est le type par défaut. Vous ne pouvez pas modifier le type de groupe de domaines au lieu de créer un 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éveloppeur pour redimensionner les ressources et activer la haute disponibilité avec le basculement automatique.
  
  Remarque
  
  Vous ne pouvez pas modifier le type de groupe de domaines, mais créer un groupe de domaines.
5. Sélectionnez Create (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 compartiment :
oci iot domain-group create --compartment-id <compartment-OCID>
Option de type :
Si vous n'indiquez pas de valeur --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égers 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 évolue avec la haute disponibilité et le basculement automatique.
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 CreateIotDomainGroup pour créer un groupe de domaines IoT dans un compartiment.

Etape 2 : création d'un domaine IoT

1. Sur la page de liste Domaine IoT, sélectionnez le compartiment dans lequel stocker les domaines IoT. Le groupe de domaines IoT et le domaine IoT peuvent se trouver dans différents compartiments. Vos ressources de jumeaux numériques IoT 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, reportez-vous à Liste des domaines IoT.
2. Sélectionnez Créer un domaine.
3. Entrez un nom convivial pour le domaine IoT. Evitez de saisir des informations confidentielles.
4. (Facultatif) Saisissez une description.
5. Sélectionnez le compartiment de groupe de domaines associé, puis le groupe de domaines à associer à ce domaine.
6. Sélectionnez Create (Créer).
7. Affichez et copiez les adresses de l'hôte de périphérique du domaine IoT. L'hôte de périphérique affiche l'ID abrégé de domaine. Sélectionnez Copier pour copier cette adresse à utiliser à l'étape suivante.
  device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com
  
  Pour obtenir la liste complète des options, reportez-vous à 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 à associer au domaine IoT. Remplacez <compartment-OCID> par l'OCID de compartiment du domaine IoT :
  oci iot domain create --compartment-id <compartment-OCID> --iot-domain-group-id <iot-domain-group-OCID>
  
  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 CreateIotDomain pour créer un domaine IoT.

Etape 3 : création d'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 de votre 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, reportez-vous à Création d'une instance de jumeau numérique.

Options de clé externe : la clé externe est le nom utilisateur de l'appareil lorsque vous vous vous connectez à 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 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 une authentification à l'instance de jumeau numérique à l'aide du paramètre --auth-id.

L'exemple suivant utilise un secret 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 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 Instances de jumeaux numériques, puis sélectionnez Créer.
3. Entrez un nom et éventuellement une description. Evitez de saisir des informations confidentielles.
4. Facultatif. Entrez une clé externe qui est un identificateur unique. Si vous n'indiquez pas de clé externe, elle est générée lorsque vous enregistrez cette instance de jumeau numérique. Utilisez la clé externe comme nom d'utilisateur du périphérique lorsque vous connectez ou envoyez des données au périphérique.
5. Sélectionnez le type :
  Connecté directement : connectez un appareil ou une entité directement au domaine IoT. 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 charges utiles des périphériques entrants en 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 le périphérique ou l'entité que vous souhaitez 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 de simulation uniquement 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 IoT sans la complexité de l'ingestion ou de l'authentification des données.
  ID d'authentification : si le périphérique ou l'entité envoie ou reçoit des données, vous devez indiquer un ID d'authentification. Pour tester l'ID d'authentification de création d'une clé secrète de coffre et pour la production, créez un certificat MTLS pour l'ID d'authentification de l'instance de jumeau numérique.
  Sélectionner un ID d'authentification : sélectionnez l'option de clé secrète ou de certificat. Pour une clé secrète, sélectionnez le compartiment de coffre, le coffre et la clé secrète. Pour un certificat, sélectionnez le compartiment de certificat, puis le certificat.
  Coller l'OCID d'authentification : collez l'OCID du certificat ou de la clé secrète.
  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.
6. Choisissez 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 à associer à cette instance de jumeau numérique IoT. Remplacez <secret-or-certificate-OCID> par l'OCID de clé secrète du coffre :
  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, reportez-vous à la section IoT CLI command Reference, and CLI Command Reference.
Exécutez l'opération CreateDigitalTwinInstance pour créer une instance de jumeau numérique.

Etape 4 : obtention des détails du domaine IoT

Si vous disposez de l'adresse d'hôte de périphérique pour le domaine IoT à utiliser, ignorez cette étape.

Les détails du domaine IoT contiennent l'hôte du périphérique, y compris l'ID abrégé du domaine, pour plus d'informations sur l'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, reportez-vous à Liste des domaines IoT.
2. Détails : affichez ou modifiez le nom du domaine et la description, copiez l'OCID, l'adresse d'hôte de périphérique, visualisez 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 obtenir une description des paramètres de domaine, reportez-vous à 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, y compris l'hôte de périphérique avec l'ID abrégé de domaine :
oci iot domain get --iot-domain-id <iot-domain-OCID>
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 GetIotDomain pour obtenir les détails d'un domaine.

Etape 5 : Envoyer des données

Envoyez des exemples de données à l'instance de jumeau numérique créée lors de l'étape 3 précédente : création d'une instance de jumeau numérique.

Nom utilisateur de l'appareil : utilisez l'option external key de l'instance de jumeau numérique comme nom utilisateur de l'appareil.
Mot de passe de l'appareil : est associé à l'ID d'authentification de l'instance de jumeau numérique. Si l'instance de jumeau numérique utilise un OCID de clé secrète de coffre pour l'authentification, utilisez le contenu de clé secrète en texte brut comme mot de passe d'appareil. Reportez-vous à Création d'une clé secrète et à Obtention du contenu d'une clé secrète. L'utilisation d'une clé secrète de coffre en tant que 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. Pour la production, l'instance de jumeau numérique doit également utiliser un certificat mTLS pour l'authentification.

Utiliser Curl
Shells de type POSIX : utilisez cette commande curl lorsque vous utilisez bash, zsh, macOS Terminal, 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: Use this curl command in this example use -G to make a GET request and append any data supplied with --data-urlencode to the URL as query parameters. 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éation d'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 les données : "external-key". Pour citer les meilleures pratiques, reportez-vous à Dépannage.
Utilisez n'importe quel client MQTT, cet exemple utilise MQTTX avec les paramètres suivants.
1. Téléchargez et configurez MQTTX en suivant ces instructions. Reportez-vous à la rubrique Introduction à MQTTX. Ouvrez MQTTX.
2. Sélectionnez Nouveau point de connexion pour créer une connexion.
3. Entrez la valeur <unique-id> de la clé externe en tant que nom utilisateur. La clé externe se trouve dans la réponse oci iot digital-twin-instance create, à partir de l'étape 3 précédente : création d'une instance de jumeau numérique :
  "external-key": "<unique-id>"
4. Saisissez le mot de passe du périphérique. Si vous testez l'utilisation d'une clé secrète de coffre, 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 périphérique : <domain-short-id>.device.iot.<region>.oci.oraclecloud.com à partir du domaine IoT.
6. Entrez le port (par exemple, 8883).
  Remarque
  
  Actuellement, MQTT Secure (MQTTS) est uniquement pris en charge à l'aide du port 8883.
7. Activez l'option SSL/TLS.
8. Activez l'option SSL Secure.
9. Pour le certificat, sélectionnez l'option Certificat du serveur signé par l'autorité de certification.
10. Lorsque vous configurez la connexion MQTTX, veillez à vous connecter à l'aide d'un élément clean session et définissez l'option Last-Will-Retain sur false pour permettre la conservation des abonnements client si le périphérique se déconnecte brièvement.
11. Définissez le dernier testament QoS sur 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 d'un appareil.

Que faire ensuite ?

Consultez les exemples de fichiers IoT pour configurer les environnements de test et de production.
Configurez APEX pour vous afficher les données de domaine IoT dans APEX, puis installez un exemple d'application APEX IoT Explorer pour surveiller visuellement vos périphériques 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 Oracle Cloud Infrastructure