Dağıtım bildirimlerini yönetmek için IoT Central REST API'sini kullanma

  • Makale

Dağıtım bildirimi, IoT Edge çalışma zamanının indirip yapılandırması gereken modülleri belirtmenize olanak tanır. IoT Edge cihazı, IoT Central uygulamanıza ilk bağlandığında bir dağıtım bildirimi indirebilir. Bu makalede, REST API kullanarak IoT Central uygulamanızda depolanan dağıtım bildirimlerinin nasıl yönetileceğini açıklar.

IoT Edge ve IoT Central hakkında daha fazla bilgi edinmek için bkz. Azure IoT Edge cihazlarını Azure IoT Central uygulamasına Bağlan.

Her IoT Central REST API çağrısı bir yetkilendirme üst bilgisi gerektirir. Daha fazla bilgi edinmek için bkz . IoT Central REST API çağrılarının kimliğini doğrulama ve yetkilendirme.

IoT Central REST API'sinin başvuru belgeleri için bkz . Azure IoT Central REST API başvurusu.

İpucu

Postman'i kullanarak bu makalede açıklanan REST API çağrılarını deneyebilirsiniz. IoT Central Postman koleksiyonunu indirin ve Postman'a aktarın. Koleksiyonda, uygulamanızın alt etki alanı ve yönetici belirteci gibi değişkenleri ayarlamanız gerekir.

IoT Central kullanıcı arabirimini kullanarak dağıtım bildirimlerini yönetmeyi öğrenmek için bkz . IoT Central uygulamanızda IoT Edge dağıtım bildirimlerini yönetme.

Dağıtım bildirimleri REST API

IoT Central REST API şunları yapmanızı sağlar:

  • Uygulamanıza dağıtım bildirimi ekleme
  • Uygulamanızda dağıtım bildirimini güncelleştirme
  • Uygulamadaki dağıtım bildirimlerinin listesini alma
  • Kimliğine göre dağıtım bildirimi alma
  • Uygulamanızdaki dağıtım bildirimini silme

Not

Dağıtım bildirimleri REST API şu anda önizleme aşamasındadır.

Dağıtım bildirimi ekleme

Yeni bir dağıtım bildirimi oluşturmak için aşağıdaki isteği kullanın.

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

Aşağıdaki örnekte, üç modülü tanımlayan bir dağıtım bildirimi ekleyen bir istek gövdesi gösterilmektedir:

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

İstek gövdesinde bazı gerekli alanlar vardır:

  • id: IoT Central uygulamasında dağıtım bildirimi için benzersiz bir kimlik.
  • displayName: Kullanıcı arabiriminde görüntülenen dağıtım bildiriminin adı.
  • data: IoT Edge dağıtım bildirimi.

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Dağıtım bildirimi alma

Uygulamanızdan bir dağıtım bildiriminin ayrıntılarını almak için aşağıdaki isteği kullanın:

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

Liste dağıtım bildirimleri API'sini kullanarak değerleri alabilirsinizdeploymentManifestId.

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Dağıtım bildirimini güncelleştirme

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

Aşağıdaki örnek istek gövdesi modül için SimuatedTemperatureSetting istenen özellik ayarını güncelleştirirSendInterval:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Dağıtım bildirimini silme

Dağıtım bildirimini silmek için aşağıdaki isteği kullanın:

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

Dağıtım bildirimlerini listeleme

Uygulamanızdan dağıtım bildirimlerinin listesini almak için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Cihaza dağıtım bildirimi atama

IoT Central uygulamanızda zaten depolanan bir dağıtım bildirimini kullanmak için önce Dağıtım bildirimi alma API'sini kullanarak bunu getirin. IoT Central uygulamanızdaki bir IoT Edge cihazına dağıtım bildirimi atamak için aşağıdaki isteği kullanın:

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

Aşağıdaki örnek istek gövdesi, dağıtım bildirimini IoT Edge cihazına atar:

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

Sonraki adımlar

Rest API ile dağıtım bildirimlerini yönetmeyi öğrendiğinize göre, önerilen bir sonraki adım IoT Central REST API'sini cihazları yönetmek için kullanma hakkında bilgi edinmektir.