Wdrażanie i monitorowanie modułów usługi IoT Edge na dużą skalę przy użyciu interfejsu wiersza polecenia platformy Azure

Dotyczy: IoT Edge 1.5 IoT Edge 1.4

Ważne

Obsługiwane są wersje usługi IoT Edge 1.5 LTS i IoT Edge 1.4 LTS. Usługa IoT Edge 1.4 LTS kończy się 12 listopada 2024 r. Jeśli korzystasz z wcześniejszej wersji, zobacz aktualizację Azure IoT Edge.

Utwórz automatyczne wdrażanie usługi Azure IoT Edge przy użyciu interfejsu wiersza polecenia platformy Azure, aby zarządzać trwającymi wdrożeniami dla wielu urządzeń jednocześnie. Wdrożenia automatyczne dla usługi IoT Edge są częścią funkcji zarządzania urządzeniami w usłudze Azure IoT Hub. Wdrożenia to dynamiczne procesy, które umożliwiają wdrażanie wielu modułów na wielu urządzeniach, śledzenie stanu i kondycji modułów oraz wprowadzanie zmian w razie potrzeby.

W tym artykule skonfigurujesz interfejs wiersza polecenia platformy Azure i rozszerzenie IoT. Następnie dowiesz się, jak wdrożyć moduły w zestawie urządzeń usługi IoT Edge i monitorować postęp przy użyciu dostępnych poleceń interfejsu wiersza polecenia.

Wymagania wstępne

• Centrum IoT w ramach subskrypcji platformy Azure.

• Co najmniej jedno urządzenie usługi IoT Edge.

  Jeśli nie masz skonfigurowanego urządzenia usługi IoT Edge, możesz go utworzyć na maszynie wirtualnej platformy Azure. Wykonaj kroki opisane w jednym z następujących artykułów szybki start: Tworzenie wirtualnego urządzenia z systemem Linux lub Tworzenie wirtualnego urządzenia z systemem Windows.

• Interfejs wiersza polecenia platformy Azure w środowisku. Wersja interfejsu wiersza polecenia platformy Azure musi być w wersji 2.0.70 lub nowszej. Użyj polecenia az --version w celu przeprowadzenia weryfikacji. Ta wersja obsługuje polecenia rozszerzenia az i wprowadza platformę poleceń Knack.

• Rozszerzenie IoT dla interfejsu wiersza polecenia platformy Azure.

Konfigurowanie manifestu wdrożenia

Manifest wdrożenia to dokument JSON opisujący moduły do wdrożenia, sposób przepływu danych między modułami i żądane właściwości bliźniaczych reprezentacji modułu. Aby uzyskać więcej informacji, zobacz Dowiedz się, jak wdrażać moduły i ustanawiać trasy w usłudze IoT Edge.

Aby wdrożyć moduły przy użyciu interfejsu wiersza polecenia platformy Azure, zapisz manifest wdrożenia lokalnie jako plik .txt. Ścieżka pliku jest używana w następnej sekcji podczas uruchamiania polecenia w celu zastosowania konfiguracji do urządzenia.

Oto podstawowy manifest wdrożenia z jednym modułem jako przykład:

{
  "content": {
    "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.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Uwaga

Ten przykładowy manifest wdrożenia używa schematu w wersji 1.1 dla agenta i centrum usługi IoT Edge. Wersja schematu 1.1 została wydana wraz z usługą IoT Edge w wersji 1.0.10. Umożliwia ona funkcje, takie jak kolejność uruchamiania modułu i priorytetyzacja tras.

Wdrożenie warstwowe

Wdrożenia warstwowe to typ automatycznego wdrażania, który można stosować nawzajem. Aby uzyskać więcej informacji na temat wdrożeń warstwowych, zobacz Omówienie wdrożeń automatycznych usługi IoT Edge dla pojedynczych urządzeń lub na dużą skalę.

Wdrożenia warstwowe można tworzyć i zarządzać przy użyciu interfejsu wiersza polecenia platformy Azure, takiego jak każde automatyczne wdrożenie, z kilkoma różnicami. Po utworzeniu wdrożenia warstwowego interfejs wiersza polecenia platformy Azure działa dla wdrożeń warstwowych tak samo jak w przypadku dowolnego wdrożenia. Aby utworzyć wdrożenie warstwowe, dodaj flagę --layered do polecenia create.

Druga różnica polega na budowie manifestu wdrożenia. Standardowe automatyczne wdrażanie musi zawierać moduły środowiska uruchomieniowego systemu oprócz wszystkich modułów użytkownika, wdrożenia warstwowe mogą zawierać tylko moduły użytkownika. Wdrożenia warstwowe wymagają również standardowego automatycznego wdrażania na urządzeniu, aby dostarczać wymagane składniki każdego urządzenia usługi IoT Edge, takie jak moduły środowiska uruchomieniowego systemu.

Oto podstawowy manifest wdrożenia warstwowego z jednym modułem jako przykład:

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Uwaga

Ten manifest wdrożenia warstwowego ma nieco inny format niż standardowy manifest wdrożenia. Żądane właściwości modułów środowiska uruchomieniowego są zwinięte i używają notacji kropkowej. To formatowanie jest wymagane, aby witryna Azure Portal rozpoznawała wdrożenie warstwowe. Na przykład:

• properties.desired.modules.<module_name>
• properties.desired.routes.<route_name>

W poprzednim przykładzie pokazano ustawienie properties.desired wdrożenia warstwowego dla modułu. Jeśli to wdrożenie warstwowe dotyczyło urządzenia, na którym zastosowano już ten sam moduł, spowoduje to zastąpienie wszelkich istniejących żądanych właściwości. Aby zaktualizować żądane właściwości zamiast ich zastępowania, możesz zdefiniować nową podsekcję. Na przykład:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

To samo można również wyrazić za pomocą następujących funkcji:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

Uwaga

Obecnie wszystkie wdrożenia warstwowe muszą zawierać edgeAgent obiekt, który ma być uznawany za prawidłowy. Nawet jeśli wdrożenie warstwowe aktualizuje tylko właściwości modułu, uwzględnij pusty obiekt. Na przykład: "$edgeAgent":{}. Wdrożenie warstwowe z pustym edgeAgent obiektem będzie wyświetlane jako docelowe w bliźniaczej reprezentacji modułu edgeAgent , a nie zastosowane.

Podsumowując, aby utworzyć wdrożenie warstwowe:

• Dodaj flagę --layered do polecenia create interfejsu wiersza polecenia platformy Azure.
• Nie dołączaj modułów systemowych.
• Użyj pełnej notacji kropkowej w obszarze $edgeAgent i $edgeHub.

Aby uzyskać więcej informacji na temat konfigurowania bliźniaczych reprezentacji modułów we wdrożeniach warstwowych, zobacz Wdrażanie warstwowe.

Identyfikowanie urządzeń przy użyciu tagów

Przed utworzeniem wdrożenia musisz mieć możliwość określenia, które urządzenia mają mieć wpływ. Usługa Azure IoT Edge identyfikuje urządzenia przy użyciu tagów w bliźniaczej reprezentacji urządzenia.

Każde urządzenie może mieć wiele tagów zdefiniowanych w dowolny sposób, co ma sens dla danego rozwiązania. Jeśli na przykład zarządzasz kampusem inteligentnych budynków, możesz dodać następujące tagi do urządzenia:

"tags":{
  "location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

Aby uzyskać więcej informacji na temat bliźniaczych reprezentacji urządzeń i tagów, zobacz Omówienie bliźniaczych reprezentacji urządzeń i korzystanie z nich w usłudze IoT Hub.

Tworzenie wdrożenia

Moduły są wdrażane na urządzeniach docelowych przez utworzenie wdrożenia, które składa się z manifestu wdrożenia i innych parametrów.

Użyj polecenia az iot edge deployment create, aby utworzyć wdrożenie:

az iot edge deployment create --deployment-id [deployment id] --hub-name [hub name] --content [file path] --labels "[labels]" --target-condition "[target query]" --priority [int]

Użyj tego samego polecenia z flagą --layered , aby utworzyć wdrożenie warstwowe.

Polecenie create dla wdrożenia przyjmuje następujące parametry:

• - warstwowe. Opcjonalna flaga identyfikująca wdrożenie jako wdrożenie warstwowe.
• --deployment-id. Nazwa wdrożenia, które zostanie utworzone w centrum IoT. Nadaj wdrożeniu unikatową nazwę, która zawiera maksymalnie 128 małych liter. Unikaj spacji i następujących nieprawidłowych znaków: & ^ [ ] { } \ | " < > /. Ten parametr jest wymagany.
• --content. Ścieżka pliku do pliku JSON manifestu wdrożenia. Ten parametr jest wymagany.
• --hub-name. Nazwa centrum IoT, w którym zostanie utworzone wdrożenie. Centrum musi znajdować się w bieżącej subskrypcji. Zmień bieżącą subskrypcję przy użyciu az account set -s [subscription name] polecenia .
• --labels. Pary nazw/wartości, które opisują i ułatwiają śledzenie wdrożeń. Etykiety przyjmują formatowanie JSON dla nazw i wartości. Na przykład: {"HostPlatform":"Linux", "Version:"3.0.1"}.
• --target-condition. Warunek określający, które urządzenia będą objęte tym wdrożeniem. Warunek jest oparty na tagach bliźniaczych reprezentacji urządzenia lub zgłoszonych właściwościach bliźniaczej reprezentacji urządzenia i powinien być zgodny z formatem wyrażenia. Na przykład: tags.environment='test' and properties.reported.devicemodel='4000x'. Jeśli warunek docelowy nie zostanie określony, wdrożenie nie zostanie zastosowane do żadnych urządzeń.
• --priority. Dodatnia liczba całkowita. Jeśli co najmniej dwa wdrożenia są przeznaczone dla tego samego urządzenia, wdrożenie o najwyższej wartości liczbowej dla priorytetu zostanie zastosowane.
• --metrics. Metryki, które wysyłają zapytania do zgłoszonych edgeHub właściwości w celu śledzenia stanu wdrożenia. Metryki przyjmują dane wejściowe JSON lub ścieżkę pliku. Na przykład: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Aby monitorować wdrożenie przy użyciu interfejsu wiersza polecenia platformy Azure, zobacz Monitorowanie wdrożeń usługi IoT Edge.

Uwaga

Po utworzeniu nowego wdrożenia usługi IoT Edge może upłynąć do 5 minut, aby usługa IoT Hub przetworzyła nową konfigurację i propagowała nowe żądane właściwości do urządzeń docelowych.

Modyfikowanie wdrożenia

Podczas modyfikowania wdrożenia zmiany są natychmiast replikowane do wszystkich urządzeń docelowych.

Jeśli zaktualizujesz warunek docelowy, wystąpią następujące aktualizacje:

• Jeśli urządzenie nie spełnia starego warunku docelowego, ale spełnia nowy warunek docelowy, a to wdrożenie jest najwyższym priorytetem dla tego urządzenia, to wdrożenie jest stosowane do urządzenia.
• Jeśli urządzenie, na którym jest obecnie uruchomione to wdrożenie, nie spełnia już warunku docelowego, odinstaluje to wdrożenie i podejmie wdrożenie o najwyższym priorytcie.
• Jeśli urządzenie aktualnie uruchomione w tym wdrożeniu nie spełnia już warunku docelowego i nie spełnia warunku docelowego innych wdrożeń, na urządzeniu nie nastąpi żadna zmiana. Urządzenie kontynuuje uruchamianie bieżących modułów w bieżącym stanie, ale nie jest już zarządzane w ramach tego wdrożenia. Gdy urządzenie spełnia warunek docelowy każdego innego wdrożenia, odinstalowuje to wdrożenie i przejmuje nowe.

Nie można zaktualizować zawartości wdrożenia, która zawiera moduły i trasy zdefiniowane w manifeście wdrożenia. Jeśli chcesz zaktualizować zawartość wdrożenia, utwórz nowe wdrożenie przeznaczone dla tych samych urządzeń z wyższym priorytetem. Możesz zmodyfikować niektóre właściwości istniejącego modułu, w tym warunek docelowy, etykiety, metryki i priorytet.

Użyj polecenia az iot edge deployment update, aby zaktualizować wdrożenie:

az iot edge deployment update --deployment-id [deployment id] --hub-name [hub name] --set [property1.property2='value']

Polecenie aktualizacji wdrożenia przyjmuje następujące parametry:

• --deployment-id. Nazwa wdrożenia, które istnieje w centrum IoT Hub.
• --hub-name. Nazwa centrum IoT, w którym istnieje wdrożenie. Centrum musi znajdować się w bieżącej subskrypcji. Przejdź do żądanej subskrypcji przy użyciu polecenia az account set -s [subscription name].
• --set. Zaktualizuj właściwość we wdrożeniu. Możesz zaktualizować następujące właściwości:
  • targetCondition (na przykład targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add. Dodaj nową właściwość do wdrożenia, w tym warunki docelowe lub etykiety.
• --remove. Usuń istniejącą właściwość, w tym warunki docelowe lub etykiety.

Usuwanie wdrożenia

Po usunięciu wdrożenia wszystkie urządzenia biorą udział we wdrożeniu o najwyższym priorytcie. Jeśli urządzenia nie spełniają warunku docelowego innego wdrożenia, moduły nie zostaną usunięte po usunięciu wdrożenia.

Użyj polecenia az iot edge deployment delete, aby usunąć wdrożenie:

az iot edge deployment delete --deployment-id [deployment id] --hub-name [hub name]

Polecenie deployment delete przyjmuje następujące parametry:

• --deployment-id. Nazwa wdrożenia, które istnieje w centrum IoT Hub.
• --hub-name. Nazwa centrum IoT, w którym istnieje wdrożenie. Centrum musi znajdować się w bieżącej subskrypcji. Przejdź do żądanej subskrypcji przy użyciu polecenia az account set -s [subscription name].

Następne kroki

Dowiedz się więcej o wdrażaniu modułów na urządzeniach usługi IoT Edge.