Share via

Utilisation de l’API REST IoT Central pour gérer des manifestes de déploiement

  • Article

Un manifeste de déploiement vous permet de spécifier les modules que le runtime IoT Edge doit télécharger et configurer. Un appareil IoT Edge peut télécharger un manifeste de déploiement quand il se connecte pour la première fois à votre application IoT Central. Cet article explique comment gérer des manifestes de déploiement stockés dans votre application IoT Central à l’aide de l’API REST.

Pour en savoir plus sur IoT Edge et IoT Central, consultez Connecter des appareils Azure IoT Edge à une application Azure IoT Central.

Chaque appel d’API REST IoT Central nécessite un en-tête d’autorisation. Pour plus d’informations, consultez Comment authentifier et autoriser les appels d’API REST d’IoT Central.

Pour obtenir la documentation de référence sur l’API REST IoT Central, consultez Informations de référence sur l’API REST d’Azure IoT Central.

Conseil

Vous pouvez utiliser Postman pour tester les appels d’API REST décrits dans cet article. Téléchargez la collection IoT Central Postman et importez-la dans Postman. Dans la collection, vous devez définir des variables telles que votre sous-domaine d’application et le jeton d’administrateur.

Pour savoir comment gérer des manifestes de déploiement à l’aide de l’IU IoT Central, veuillez consulter la rubrique Gérer des manifestes de déploiement IoT Edge dans votre application IoT Central.

API REST de manifestes de déploiement

L’API REST d’IoT Central vous permet de :

  • Ajouter un manifeste de déploiement à votre application
  • Mettre à jour un manifeste de déploiement dans votre application
  • Obtenir une liste des manifestes de déploiement dans l’application
  • Obtenir un manifeste de déploiement par ID
  • Supprimer un manifeste de déploiement dans votre application

Remarque

L’API REST de manifestes de déploiement est actuellement en préversion.

Ajouter un manifeste de déploiement

Utilisez la requête suivante pour créer un manifeste de déploiement.

PUT https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview

L’exemple suivant montre un corps de requête qui ajoute un manifeste de déploiement définissant trois modules :

{
  "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
        }
      }
    }
  }
}

Le corps de la demande contient des champs obligatoires :

  • id : ID unique du manifeste de déploiement dans l’application IoT Central.
  • displayName : nom du manifeste de déploiement affiché dans l’IU.
  • data : manifeste de déploiement IoT Edge.

La réponse à cette demande ressemble à l’exemple suivant :

{
  "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\""
}

Obtenir un manifeste de déploiement

Utilisez la requête suivante pour récupérer les détails d’un manifeste de déploiement depuis votre application :

GET https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview

Vous pouvez obtenir les valeurs deploymentManifestId à l’aide de l’API Lister les manifestes de déploiement.

La réponse à cette demande ressemble à l’exemple suivant :

{
  "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\""
}

Mettre à jour un manifeste de déploiement

PATCH https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview

L’exemple de corps de requête suivant met à jour le paramètre de propriété souhaité SendInterval pour le module SimuatedTemperatureSetting :

{
  "data": {
    "modulesContent": {
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendInterval": 30
        }
      }
    }
  }
}

La réponse à cette demande ressemble à l’exemple suivant :

{
  "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\""
}

Supprimer un manifeste de déploiement

Utilisez la requête suivante pour supprimer un manifeste de déploiement :

DELETE https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview

Lister les manifestes de déploiement

Utilisez la requête suivante pour récupérer une liste de manifestes de déploiement depuis votre application :

GET https://{your app subdomain}/api/deploymentManifests?api-version=2022-10-31-preview

La réponse à cette demande ressemble à l’exemple suivant :

{
  "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
    }
  ]
}

Attribuer un manifeste de déploiement à un appareil

Pour utiliser un manifeste de déploiement déjà stocké dans votre application IoT Central, utilisez d’abord l’API Obtenir un manifeste de déploiement pour l’extraire. Utilisez la requête suivante pour attribuer un manifeste de déploiement à un appareil IoT Edge dans votre application IoT Central :

POST https://{your app subdomain}.azureiotcentral.com/api/devices/{your IoT Edge device ID}/applyDeploymentManifest?api-version=2022-10-31-preview

L’exemple de corps de requête suivant attribue le manifeste de déploiement à l’appareil 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
        }
      }
    }
  }
}

Étapes suivantes

Maintenant que vous savez comment gérer les manifestes de déploiement avec l’API REST, l’étape suivante suggérée consiste à apprendre à utiliser l’API REST IoT Central pour gérer les appareils.