Come usare l'API REST IoT Central per gestire i manifesti di distribuzione
Un manifesto di distribuzione consente di specificare i moduli che il runtime di IoT Edge deve scaricare e configurare. Un dispositivo IoT Edge può scaricare un manifesto di distribuzione quando si connette per la prima volta all'applicazione IoT Central. Questo articolo descrive come gestire i manifesti di distribuzione archiviati nell'applicazione IoT Central usando l'API REST.
Per altre informazioni su IoT Edge e IoT Central, vedere Connettere i dispositivi di Azure IoT Edge a un'applicazione Azure IoT Central.
Ogni chiamata API REST IoT Central richiede un'intestazione di autorizzazione. Per altre informazioni, vedere Come autenticare e autorizzare le chiamate API REST IoT Central.
Per la documentazione di riferimento per l'API REST IoT Central, vedere Informazioni di riferimento sull'API REST di Azure IoT Central.
Suggerimento
È possibile usare Postman per provare le chiamate API REST descritte in questo articolo. Scaricare l'insieme IoT Central Postman e importarlo in Postman. Nella raccolta sarà necessario impostare variabili come il sottodominio dell'app e il token di amministrazione.
Per informazioni su come gestire i manifesti di distribuzione usando l'interfaccia utente di IoT Central, vedere Gestire i manifesti di distribuzione IoT Edge nell'applicazione IoT Central.
API REST dei manifesti di distribuzione
L'API REST di IoT Central consente di:
- Aggiungere un manifesto di distribuzione all'applicazione
- Aggiornare un manifesto di distribuzione nell'applicazione
- Ottenere un elenco dei manifesti di distribuzione nell'applicazione
- Ottenere un manifesto di distribuzione in base all'ID
- Eliminare un manifesto di distribuzione nell'applicazione
Nota
L'API REST del manifesto della distribuzione è attualmente in anteprima.
Aggiungere un manifesto di distribuzione
Usare la richiesta seguente per creare un nuovo manifesto di distribuzione.
PUT https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
Nell'esempio seguente viene illustrato un corpo della richiesta che aggiunge un manifesto di distribuzione che definisce tre moduli:
{
"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
}
}
}
}
}
Il corpo della richiesta include alcuni campi obbligatori:
id
: ID univoco per il manifesto della distribuzione nell'applicazione IoT Central.displayName
: un nome per il manifesto di distribuzione visualizzato nell'interfaccia utente.data
: manifesto di distribuzione IoT Edge.
La risposta a questa richiesta è simile all'esempio seguente:
{
"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\""
}
Ottenere un manifesto di distribuzione
Usare la richiesta seguente per recuperare i dettagli di un manifesto di distribuzione dall'applicazione:
GET https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
È possibile ottenere i deploymentManifestId
valori usando l'API Manifesti di distribuzione elenco .
La risposta a questa richiesta è simile all'esempio seguente:
{
"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\""
}
Aggiornare un manifesto della distribuzione
PATCH https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
Il corpo della richiesta di esempio seguente aggiorna l'impostazione SendInterval
della proprietà desiderata per il SimuatedTemperatureSetting
modulo:
{
"data": {
"modulesContent": {
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendInterval": 30
}
}
}
}
}
La risposta a questa richiesta è simile all'esempio seguente:
{
"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\""
}
Eliminare un manifesto di distribuzione
Usare la richiesta seguente per eliminare un manifesto di distribuzione:
DELETE https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
Elencare i manifesti di distribuzione
Usare la richiesta seguente per recuperare un elenco di manifesti di distribuzione dall'applicazione:
GET https://{your app subdomain}/api/deploymentManifests?api-version=2022-10-31-preview
La risposta a questa richiesta è simile all'esempio seguente:
{
"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
}
]
}
Assegnare un manifesto di distribuzione a un dispositivo
Per usare un manifesto di distribuzione già archiviato nell'applicazione IoT Central, usare innanzitutto l'API Get a deployment manifesto per recuperarla. Usare la richiesta seguente per assegnare un manifesto di distribuzione a un dispositivo IoT Edge nell'applicazione IoT Central:
POST https://{your app subdomain}.azureiotcentral.com/api/devices/{your IoT Edge device ID}/applyDeploymentManifest?api-version=2022-10-31-preview
Il corpo della richiesta di esempio seguente assegna il manifesto di distribuzione 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
}
}
}
}
}
Passaggi successivi
Dopo aver appreso come gestire i manifesti di distribuzione con l'API REST, un passaggio successivo suggerito consiste nell'apprendere come usare l'API REST IoT Central per gestire i dispositivi.