Bien démarrer avec l’identité de module et le jumeau de module IoT Hub (C)
Les identités de module et les jumeaux de module sont similaires aux identités d’appareil et aux jumeaux d’appareil Azure IoT Hub, mais offrent un plus grand niveau de détail. Contrairement à l’identité d’appareil et au jumeau d’appareil Azure IoT Hub qui permettent à l’application back-end de configurer un appareil et d’obtenir une visibilité sur les conditions de l’appareil, une identité de module et un jumeau de module fournissent ces capacités pour les composants individuels d’un appareil. Sur les appareils compatibles qui intègrent plusieurs composants, par exemple des appareils avec système d’exploitation ou des appareils avec un microprogramme, ils permettent d’isoler la configuration et les conditions de chacun de ces composants.
Notes
Les fonctionnalités décrites dans cet article sont uniquement disponibles au niveau Standard d’IoT Hub. Pour plus d’informations sur les niveaux de base et standard/gratuit d’IoT Hub, consultez Choisir le niveau IoT Hub correspondant à votre solution.
À la fin de cet article, vous disposez de deux applications C :
CreateIdentities : crée une identité d’appareil, une identité de module et une clé de sécurité associée pour connecter votre appareil et vos clients de module.
UpdateModuleTwinReportedProperties : envoie à votre IoT Hub les propriétés à jour de votre jumeau de module.
Notes
Pour plus d’informations sur les outils SDK disponibles pour créer des applications d’appareil et de back-end, consultez les SDK Azure IoT.
Prérequis
Un IoT Hub. Créez-en un avec l’interface CLI ou le portail Azure.
Le dernier Kit de développement logiciel (SDK) C Azure IoT.
Obtenir la chaîne de connexion du hub IoT
Dans cet article, vous allez créer un service back-end qui ajoute un appareil dans le registre des identités, puis ajoute un module à cet appareil. Votre service a besoin de l’autorisation Écriture du registre. Par défaut, chaque hub IoT est créé avec une stratégie d’accès partagé nommée registryReadWrite qui accorde cette autorisation.
Pour obtenir la chaîne de connexion IoT Hub pour la stratégie registryReadWrite, procédez comme suit :
Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet de gauche de votre hub, sélectionnez Stratégies d’accès partagé.
Dans la liste des stratégies, sélectionnez la stratégie registryReadWrite.
Copiez la Chaîne de connexion principale, puis enregistrez la valeur.
Pour plus d’informations sur les autorisations et les stratégies d’accès partagé IoT Hub, consultez Contrôle d’accès et autorisations.
Créer une identité d’appareil et une identité de module dans IoT Hub
Dans cette section, vous allez créer une application C qui crée une identité d’appareil et une identité de module dans le registre des identités de votre hub IoT. Un appareil ou un module ne peut se connecter à un hub IoT que s’il a une entrée dans le registre des identités. Pour plus d’informations, consultez Comprendre le registre des identités dans votre IoT Hub. En exécutant cette application console, une clé et un ID uniques sont générés pour chaque appareil et module. Votre appareil et le module utilisent ces valeurs pour s’identifier lorsqu’ils envoient des messages d’appareil-à-cloud à IoT Hub. Les ID sont sensibles à la casse.
Ajoutez le code suivant à votre fichier C :
#include <stdio.h>
#include <stdlib.h>
#include "azure_c_shared_utility/crt_abstractions.h"
#include "azure_c_shared_utility/threadapi.h"
#include "azure_c_shared_utility/platform.h"
#include "iothub_service_client_auth.h"
#include "iothub_registrymanager.h"
static const char* hubConnectionString ="[your hub's connection string]"; // modify
static void createDevice(IOTHUB_REGISTRYMANAGER_HANDLE
iotHubRegistryManagerHandle, const char* deviceId)
{
IOTHUB_REGISTRY_DEVICE_CREATE_EX deviceCreateInfo;
IOTHUB_REGISTRYMANAGER_RESULT result;
(void)memset(&deviceCreateInfo, 0, sizeof(deviceCreateInfo));
deviceCreateInfo.version = 1;
deviceCreateInfo.deviceId = deviceId;
deviceCreateInfo.primaryKey = "";
deviceCreateInfo.secondaryKey = "";
deviceCreateInfo.authMethod = IOTHUB_REGISTRYMANAGER_AUTH_SPK;
IOTHUB_DEVICE_EX deviceInfoEx;
memset(&deviceInfoEx, 0, sizeof(deviceInfoEx));
deviceInfoEx.version = 1;
// Create device
result = IoTHubRegistryManager_CreateDevice_Ex(iotHubRegistryManagerHandle,
&deviceCreateInfo, &deviceInfoEx);
if (result == IOTHUB_REGISTRYMANAGER_OK)
{
(void)printf("IoTHubRegistryManager_CreateDevice: Device has been created successfully: deviceId=%s, primaryKey=%s\n", deviceInfoEx.deviceId, deviceInfoEx.primaryKey);
}
else if (result == IOTHUB_REGISTRYMANAGER_DEVICE_EXIST)
{
(void)printf("IoTHubRegistryManager_CreateDevice: Device already exists\n");
}
else if (result == IOTHUB_REGISTRYMANAGER_ERROR)
{
(void)printf("IoTHubRegistryManager_CreateDevice failed\n");
}
// You will need to Free the returned device information after it was created
IoTHubRegistryManager_FreeDeviceExMembers(&deviceInfoEx);
}
static void createModule(IOTHUB_REGISTRYMANAGER_HANDLE iotHubRegistryManagerHandle, const char* deviceId, const char* moduleId)
{
IOTHUB_REGISTRY_MODULE_CREATE moduleCreateInfo;
IOTHUB_REGISTRYMANAGER_RESULT result;
(void)memset(&moduleCreateInfo, 0, sizeof(moduleCreateInfo));
moduleCreateInfo.version = 1;
moduleCreateInfo.deviceId = deviceId;
moduleCreateInfo.moduleId = moduleId;
moduleCreateInfo.primaryKey = "";
moduleCreateInfo.secondaryKey = "";
moduleCreateInfo.authMethod = IOTHUB_REGISTRYMANAGER_AUTH_SPK;
IOTHUB_MODULE moduleInfo;
memset(&moduleInfo, 0, sizeof(moduleInfo));
moduleInfo.version = 1;
// Create module
result = IoTHubRegistryManager_CreateModule(iotHubRegistryManagerHandle, &moduleCreateInfo, &moduleInfo);
if (result == IOTHUB_REGISTRYMANAGER_OK)
{
(void)printf("IoTHubRegistryManager_CreateModule: Module has been created successfully: deviceId=%s, moduleId=%s, primaryKey=%s\n", moduleInfo.deviceId, moduleInfo.moduleId, moduleInfo.primaryKey);
}
else if (result == IOTHUB_REGISTRYMANAGER_DEVICE_EXIST)
{
(void)printf("IoTHubRegistryManager_CreateModule: Module already exists\n");
}
else if (result == IOTHUB_REGISTRYMANAGER_ERROR)
{
(void)printf("IoTHubRegistryManager_CreateModule failed\n");
}
// You will need to Free the returned module information after it was created
IoTHubRegistryManager_FreeModuleMembers(&moduleInfo);
}
int main(void)
{
(void)platform_init();
const char* deviceId = "myFirstDevice";
const char* moduleId = "myFirstModule";
IOTHUB_SERVICE_CLIENT_AUTH_HANDLE iotHubServiceClientHandle = NULL;
IOTHUB_REGISTRYMANAGER_HANDLE iotHubRegistryManagerHandle = NULL;
if ((iotHubServiceClientHandle = IoTHubServiceClientAuth_CreateFromConnectionString(hubConnectionString)) == NULL)
{
(void)printf("IoTHubServiceClientAuth_CreateFromConnectionString failed\n");
}
else if ((iotHubRegistryManagerHandle = IoTHubRegistryManager_Create(iotHubServiceClientHandle)) == NULL)
{
(void)printf("IoTHubServiceClientAuth_CreateFromConnectionString failed\n");
}
else
{
createDevice(iotHubRegistryManagerHandle, deviceId);
createModule(iotHubRegistryManagerHandle, deviceId, moduleId);
}
if (iotHubRegistryManagerHandle != NULL)
{
(void)printf("Calling IoTHubRegistryManager_Destroy...\n");
IoTHubRegistryManager_Destroy(iotHubRegistryManagerHandle);
}
if (iotHubServiceClientHandle != NULL)
{
(void)printf("Calling IoTHubServiceClientAuth_Destroy...\n");
IoTHubServiceClientAuth_Destroy(iotHubServiceClientHandle);
}
platform_deinit();
return 0;
}
Cette application crée une identité d’appareil avec l’ID myFirstDevice et une identité de module avec l’ID myFirstModule sous l’appareil myFirstDevice. (si cet ID de module existe déjà dans le registre d’identité, le code récupère simplement les informations existantes du module.) L’application affiche ensuite la clé primaire pour cette identité. Vous utilisez cette clé dans l’application de module simulé pour vous connecter à votre IoT Hub.
Notes
Le registre des identités IoT Hub stocke uniquement les identités des appareils et des modules pour permettre un accès sécurisé à IoT Hub. Le registre des identités stocke les ID et les clés d’appareil à utiliser en tant qu’informations d’identification de sécurité. Il stocke également un indicateur activé/désactivé pour chaque appareil pouvant être utilisé pour désactiver l’accès de cet appareil. Si votre application a besoin de stocker d’autres métadonnées spécifiques aux appareils, elle doit utiliser un magasin spécifique aux applications. Il n’y a aucun indicateur d’activation/désactivation pour les identités de module. Pour plus d’informations, reportez-vous au Guide du développeur IoT Hub.
Mettre à jour le jumeau de module à l’aide du SDK d’appareil C
Dans cette section, vous allez créer sur votre appareil simulé une application C qui met à jour les propriétés signalées du jumeau de module.
Obtenez la chaîne de connexion de votre module. Dans le Portail Azure, accédez à votre hub IoT, puis sélectionnez Appareils IoT. Recherchez et ouvrez myFirstDevice pour vérifier que myFirstModule a bien été créé. Copiez la chaîne de connexion du module. Vous en aurez besoin à l’étape suivante.
Créer l’application UpdateModuleTwinReportedProperties
Ajoutez ce qui suit à votre fichier C :
#include <stdio.h> #include <stdlib.h> #include "azure_c_shared_utility/crt_abstractions.h" #include "azure_c_shared_utility/threadapi.h" #include "azure_c_shared_utility/platform.h" #include "iothub_service_client_auth.h" #include "iothub_devicetwin.h" const char* deviceId = "bugbash-test-2"; const char* moduleId = "module-id-1"; static const char* hubConnectionString ="[your hub's connection string]"; // modify const char* testJson = "{\"properties\":{\"desired\":{\"integer_property\": b-1234, \"string_property\": \"abcd\"}}}"; int main(void) { (void)platform_init(); IOTHUB_SERVICE_CLIENT_AUTH_HANDLE iotHubServiceClientHandle = NULL; IOTHUB_SERVICE_CLIENT_DEVICE_TWIN_HANDLE iothubDeviceTwinHandle = NULL; if ((iotHubServiceClientHandle = IoTHubServiceClientAuth_CreateFromConnectionString(moduleConnectionString)) == NULL) { (void)printf("IoTHubServiceClientAuth_CreateFromConnectionString failed\n"); } else if ((iothubDeviceTwinHandle = IoTHubDeviceTwin_Create(iotHubServiceClientHandle)) == NULL) { (void)printf("IoTHubServiceClientAuth_CreateFromConnectionString failed\n"); } else { char *result = IoTHubDeviceTwin_UpdateModuleTwin(iothubDeviceTwinHandle, deviceId, moduleId, testJson); printf("IoTHubDeviceTwin_UpdateModuleTwin returned %s\n", result); } if (iothubDeviceTwinHandle != NULL) { (void)printf("Calling IoTHubDeviceTwin_Destroy...\n"); IoTHubDeviceTwin_Destroy(iothubDeviceTwinHandle); } if (iotHubServiceClientHandle != NULL) { (void)printf("Calling IoTHubServiceClientAuth_Destroy...\n"); IoTHubServiceClientAuth_Destroy(iotHubServiceClientHandle); } platform_deinit(); return 0; }
Cet exemple de code vous montre comment récupérer le jumeau de module et mettre à jour les propriétés signalées.
Recevoir les mises à jour du côté appareil
En plus du code précédent, vous pouvez ajouter le bloc de code suivant pour recevoir le message de mise à jour du jumeau sur votre appareil :
#include <stdio.h>
#include <stdlib.h>
#include "azure_c_shared_utility/crt_abstractions.h"
#include "azure_c_shared_utility/macro_utils.h"
#include "azure_c_shared_utility/threadapi.h"
#include "azure_c_shared_utility/platform.h"
#include "iothub_module_client_ll.h"
#include "iothub_client_options.h"
#include "iothub_message.h"
// The protocol you wish to use should be uncommented
//
//#define SAMPLE_MQTT
//#define SAMPLE_MQTT_OVER_WEBSOCKETS
#define SAMPLE_AMQP
//#define SAMPLE_AMQP_OVER_WEBSOCKETS
//#define SAMPLE_HTTP
#ifdef SAMPLE_MQTT
#include "iothubtransportmqtt.h"
#endif // SAMPLE_MQTT
#ifdef SAMPLE_MQTT_OVER_WEBSOCKETS
#include "iothubtransportmqtt_websockets.h"
#endif // SAMPLE_MQTT_OVER_WEBSOCKETS
#ifdef SAMPLE_AMQP
#include "iothubtransportamqp.h"
#endif // SAMPLE_AMQP
#ifdef SAMPLE_AMQP_OVER_WEBSOCKETS
#include "iothubtransportamqp_websockets.h"
#endif // SAMPLE_AMQP_OVER_WEBSOCKETS
#ifdef SAMPLE_HTTP
#include "iothubtransporthttp.h"
#endif // SAMPLE_HTTP
/* Paste in the your iothub connection string */
static const char* connectionString = "[Fill in connection string]";
static bool g_continueRunning;
#define DOWORK_LOOP_NUM 3
static void deviceTwinCallback(DEVICE_TWIN_UPDATE_STATE update_state, const unsigned char* payLoad, size_t size, void* userContextCallback)
{
(void)userContextCallback;
printf("Device Twin update received (state=%s, size=%zu): %s\r\n",
MU_ENUM_TO_STRING(DEVICE_TWIN_UPDATE_STATE, update_state), size, payLoad);
}
static void reportedStateCallback(int status_code, void* userContextCallback)
{
(void)userContextCallback;
printf("Device Twin reported properties update completed with result: %d\r\n", status_code);
g_continueRunning = false;
}
void iothub_module_client_sample_device_twin_run(void)
{
IOTHUB_CLIENT_TRANSPORT_PROVIDER protocol;
IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle;
g_continueRunning = true;
// Select the Protocol to use with the connection
#ifdef SAMPLE_MQTT
protocol = MQTT_Protocol;
#endif // SAMPLE_MQTT
#ifdef SAMPLE_MQTT_OVER_WEBSOCKETS
protocol = MQTT_WebSocket_Protocol;
#endif // SAMPLE_MQTT_OVER_WEBSOCKETS
#ifdef SAMPLE_AMQP
protocol = AMQP_Protocol;
#endif // SAMPLE_AMQP
#ifdef SAMPLE_AMQP_OVER_WEBSOCKETS
protocol = AMQP_Protocol_over_WebSocketsTls;
#endif // SAMPLE_AMQP_OVER_WEBSOCKETS
#ifdef SAMPLE_HTTP
protocol = HTTP_Protocol;
#endif // SAMPLE_HTTP
if (platform_init() != 0)
{
(void)printf("Failed to initialize the platform.\r\n");
}
else
{
if ((iotHubModuleClientHandle = IoTHubModuleClient_LL_CreateFromConnectionString(connectionString, protocol)) == NULL)
{
(void)printf("ERROR: iotHubModuleClientHandle is NULL!\r\n");
}
else
{
bool traceOn = true;
const char* reportedState = "{ 'device_property': 'new_value'}";
size_t reportedStateSize = strlen(reportedState);
(void)IoTHubModuleClient_LL_SetOption(iotHubModuleClientHandle, OPTION_LOG_TRACE, &traceOn);
// Check the return of all API calls when developing your solution. Return checks omitted for sample simplification.
(void)IoTHubModuleClient_LL_SetModuleTwinCallback(iotHubModuleClientHandle, deviceTwinCallback, iotHubModuleClientHandle);
(void)IoTHubModuleClient_LL_SendReportedState(iotHubModuleClientHandle, (const unsigned char*)reportedState, reportedStateSize, reportedStateCallback, iotHubModuleClientHandle);
do
{
IoTHubModuleClient_LL_DoWork(iotHubModuleClientHandle);
ThreadAPI_Sleep(1);
} while (g_continueRunning);
for (size_t index = 0; index < DOWORK_LOOP_NUM; index++)
{
IoTHubModuleClient_LL_DoWork(iotHubModuleClientHandle);
ThreadAPI_Sleep(1);
}
IoTHubModuleClient_LL_Destroy(iotHubModuleClientHandle);
}
platform_deinit();
}
}
int main(void)
{
iothub_module_client_sample_device_twin_run();
return 0;
}
Étapes suivantes
Pour continuer la prise en main de IoT Hub et explorer les autres scénarios IoT, consultez les articles suivants :
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour