Uso de la API REST de IoT Central para administrar manifiestos de implementación
Un manifiesto de implementación permite especificar los módulos que el entorno de ejecución de IoT Edge debe descargar y configurar. Un dispositivo IoT Edge puede descargar un manifiesto de implementación cuando se conecta por primera vez a la aplicación de IoT Central. En este artículo se describe cómo administrar los manifiestos de implementación almacenados en la aplicación de IoT Central mediante la API REST.
Para más información sobre IoT Edge e IoT Central, consulte Conexión de dispositivos de Azure IoT Edge a una aplicación de Azure IoT Central.
Cada llamada a la API REST de IoT Central requiere un encabezado de autorización. Para obtener más información, vea los procedimientos de autenticación y autorización de llamadas a la API REST de IoT Central.
Para ver la documentación de referencia sobre la API REST de IoT Central, consulte Referencia de la API REST de Azure IoT Central.
Sugerencia
Puede usar Postman para probar las llamadas API REST que se describen en este artículo. Descargue la colección de Postman de IoT Central e impórtela en Postman. En la colección, deberá establecer variables como el subdominio de la aplicación y el token de administrador.
Para obtener información sobre cómo administrar manifiestos de implementación mediante la interfaz de usuario de IoT Central, consulte Administración de manifiestos de implementación de IoT Edge en la aplicación de IoT Central.
API REST de manifiestos de implementación
La API de REST de IoT Central le permite:
- Agregar un manifiesto de implementación a la aplicación
- Actualizar un manifiesto de implementación en la aplicación
- Obtener una lista de los manifiestos de implementación en la aplicación
- Obtener un manifiesto de implementación por identificador
- Eliminar un manifiesto de implementación en la aplicación
Nota:
La API REST de manifiestos de implementación está actualmente en versión preliminar.
Agregar un manifiesto de implementación
Use la siguiente solicitud para crear un nuevo manifiesto de implementación.
PUT https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega un manifiesto de implementación que define tres módulos:
{
"id": "envsensorv1",
"displayName": "Environmental sensor deployment manifest",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.0",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.0",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
}
}
El cuerpo de la solicitud tiene algunos campos obligatorios:
id: un identificador único para el manifiesto de implementación en la aplicación de IoT Central.displayName: un nombre para el manifiesto de implementación que se muestra en la interfaz de usuario.data: el manifiesto de implementación de IoT Edge.
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"id": "envsensorv1",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.1",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.1",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
},
"displayName": "Environmental sensor deployment manifest",
"etag": "\"0500f164-0000-1100-0000-637cf09c0000\""
}
Obtener un manifiesto de implementación
Use la siguiente solicitud para recuperar los detalles de un manifiesto de implementación de la aplicación:
GET https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
Puede obtener los deploymentManifestId valores usando la API Enumerar manifiestos de implementación.
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"id": "envsensor",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.1",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.1",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
},
"displayName": "Environmental sensor deployment manifest",
"etag": "\"0500f663-0000-1100-0000-637cec590000\""
}
Actualización de un manifiesto de implementación
PATCH https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
El cuerpo de la solicitud de ejemplo siguiente actualiza la SendInterval configuración de la propiedad deseada para el SimuatedTemperatureSetting módulo:
{
"data": {
"modulesContent": {
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendInterval": 30
}
}
}
}
}
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"id": "envsensorv1",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.1",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.2",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.1",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 30
}
}
}
},
"displayName": "Environmental sensor deployment manifest",
"etag": "\"05003065-0000-1100-0000-637cf1b00000\""
}
Eliminar un manifiesto de implementación
Use la siguiente solicitud para eliminar un manifiesto de implementación:
DELETE https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
Enumerar manifiestos de implementación
Use la siguiente solicitud para recuperar una lista de manifiestos de implementación de la aplicación:
GET https://{your app subdomain}/api/deploymentManifests?api-version=2022-10-31-preview
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"value": [
{
"id": "envsensor",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.1",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.1",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
},
"displayName": "Environmental sensor deployment manifest",
"etag": "\"0500f663-0000-1100-0000-637cec590000\""
},
{
// More deployment manifests
}
]
}
Asignar un manifiesto de implementación a un dispositivo
Para usar un manifiesto de implementación ya almacenado en la aplicación de IoT Central, use primero la API Obtener un manifiesto de implementación para capturarlo. Use la siguiente solicitud para asignar un manifiesto de implementación a un dispositivo IoT Edge en la aplicación de IoT Central:
POST https://{your app subdomain}.azureiotcentral.com/api/devices/{your IoT Edge device ID}/applyDeploymentManifest?api-version=2022-10-31-preview
El siguiente cuerpo de solicitud de ejemplo asigna el manifiesto de implementación al dispositivo IoT Edge:
{
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.0",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.0",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
}
}
Pasos siguientes
Ahora que ha aprendido a administrar manifiestos de implementación con la API DE REST, se recomienda aprender a Usar la API de REST de IoT Central para administrar dispositivos.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de