Kom igång med enhetshantering (Azure CLI)

Artikel
07/17/2024

Serverdelsappar kan använda Azure IoT Hub-primitiver, till exempel enhetstvillingar och direktmetoder, för att fjärrstarta och övervaka enhetshanteringsåtgärder på enheter. Den här artikeln visar hur Azure CLI och en enhet kan arbeta tillsammans för att anropa en direktmetod för en enhet med IoT Hub.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Använd en direkt metod för att initiera enhetshanteringsåtgärder (till exempel omstart, fabriksåterställning och uppdatering av inbyggd programvara) från en Azure CLI-session. Enheten ansvarar för:

Hantera metodbegäran som skickas från IoT Hub.
Initiera motsvarande enhetsspecifika åtgärd på enheten.
Tillhandahålla statusuppdateringar via rapporterade egenskaper till IoT Hub.

Du kan använda Azure CLI för att köra frågor för enhetstvillingar för att rapportera om förloppet för dina enhetshanteringsåtgärder. Mer information om hur du använder direkta metoder finns i Vägledning för kommunikation från moln till enhet.

Den här artikeln visar hur du skapar två Azure CLI-sessioner:

En session som skapar en simulerad enhet. Den simulerade enheten är konfigurerad för att returnera en statuskod och JSON-nyttolast när en direktmetod anropas.
En session som anropar en direktmetod på den simulerade enhet som skapades i den andra sessionen.

Förutsättningar

Azure CLI. Du kan också köra kommandona i den här artikeln med hjälp av Azure Cloud Shell, ett interaktivt CLI-gränssnitt som körs i webbläsaren eller i en app som Windows Terminal. Om du använder Cloud Shell behöver du inte installera något. Om du föredrar att använda CLI lokalt kräver den här artikeln Azure CLI version 2.36 eller senare. Kör az --version för att hitta versionen. Information om hur du installerar eller uppgraderar Azure CLI lokalt finns i Installera Azure CLI.
En IoT-hubb i din Azure-prenumeration. Om du inte har någon hubb ännu kan du följa stegen i Skapa en IoT-hubb.
Kontrollera att port 8883 är öppen i brandväggen. Enhetsexemplet i den här artikeln använder MQTT-protokollet, som kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Ansluta till IoT Hub (MQTT).

Förbereda Cloud Shell

Om du vill använda Azure Cloud Shell måste du först starta och konfigurera det. Om du använder CLI lokalt går du vidare till avsnittet Förbered två CLI-sessioner .

Välj Cloud Shell-ikonen i sidhuvudet i Azure-portalen.

Kommentar

Om det är första gången du använder Cloud Shell uppmanas du att skapa lagring, vilket krävs för att använda Cloud Shell. Välj en prenumeration för att skapa ett lagringskonto och en Microsoft Azure Files-resurs.
Använd miljöväljaren i Cloud Shell-verktygsfältet för att välja önskad CLI-miljö. Den här artikeln använder Bash-miljön. Du kan också använda PowerShell-miljön.

Kommentar

Vissa kommandon kräver olika syntax eller formatering i Bash- och PowerShell-miljöerna. Mer information finns i Tips för att använda Azure CLI.

Förbereda två CLI-sessioner

Därefter måste du förbereda två Azure CLI-sessioner. Om du använder Cloud Shell kör du dessa sessioner på separata Cloud Shell-flikar. Om du använder en lokal CLI-klient kör du separata CLI-instanser. Använd de separata CLI-sessionerna för följande uppgifter:

Den första sessionen simulerar en IoT-enhet som kommunicerar med din IoT-hubb.
Den andra sessionen anropar en direktmetod från din simulerade enhet med hjälp av din IoT-hubb.

Kommentar

Azure CLI kräver att du är inloggad på ditt Azure-konto. Om du använder Cloud Shell loggas du automatiskt in på ditt Azure-konto. Om du använder en lokal CLI-klient måste du logga in på varje CLI-session. All kommunikation mellan azure CLI-gränssnittet och din IoT-hubb autentiseras och krypteras. Därför behöver den här artikeln inte extra autentisering som du använder med en riktig enhet, till exempel en niska veze. Mer information om hur du loggar in med Azure CLI finns i Logga in med Azure CLI.

I den första CLI-sessionen kör du kommandot az extension add . Kommandot lägger till Microsoft Azure IoT-tillägget för Azure CLI i CLI-gränssnittet. Tillägget lägger till specifika kommandon för IoT Hub, IoT Edge och IoT Device Provisioning Service (DPS) i Azure CLI. När du har installerat tillägget behöver du inte installera det igen i någon Cloud Shell-session.
```
az extension add --name azure-iot
```
Kommentar

Den här artikeln använder den senaste versionen av Azure IoT-tillägget med namnet azure-iot. Den äldre versionen kallas azure-cli-iot-ext. Du bör bara ha en version installerad i taget. Du kan använda kommandot az extension list för att verifiera de tillägg som är installerade.

Använd az extension remove --name azure-cli-iot-ext för att ta bort den äldre versionen av tillägget.

Använd az extension add --name azure-iot för att lägga till den nya versionen av tillägget.

Om du vill se vilka tillägg du har installerat använder du az extension list.
Öppna den andra CLI-sessionen. Om du använder Cloud Shell i en webbläsare väljer du ikonen Öppna ny session i verktygsfältet för din första CLI-session. Om du använder CLI lokalt öppnar du en andra CLI-instans.

Skapa och simulera en enhet

I det här avsnittet skapar du en enhetsidentitet för din IoT-hubb i den första CLI-sessionen och simulerar sedan en enhet med den enhetsidentiteten. Den simulerade enheten svarar på de direkta metoder som du anropar i den andra CLI-sessionen.

Så här skapar och startar du en simulerad enhet:

I den första CLI-sessionen kör du kommandot az iot hub device-identity create och ersätter följande platshållare med motsvarande värden. Det här kommandot skapar enhetsidentiteten för den simulerade enheten.

{DeviceName}. Namnet på den simulerade enheten.

{HubName}. Namnet på din IoT-hubb.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
I den första CLI-sessionen kör du kommandot az iot device simulate och ersätter följande platshållare med motsvarande värden. Det här kommandot simulerar en enhet med den enhetsidentitet som du skapade i föregående steg. Den simulerade enheten är konfigurerad för att returnera en statuskod och nyttolast när en direktmetod anropas.

{DeviceName}. Namnet på den simulerade enheten.

{HubName}. Namnet på din IoT-hubb.
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --method-response-code 201 \
                       --method-response-payload '{"result":"Direct method successful"}'
```
Dricks

Som standard skickar kommandot az iot device simulate 100 enhet-till-moln-meddelanden med ett intervall på 3 sekunder mellan meddelanden. Simuleringen avslutas när alla meddelanden har skickats. Om du vill att simuleringen ska köras längre kan du använda parametern --msg-count för att ange fler meddelanden eller parametern --msg-interval för att ange ett längre intervall mellan meddelanden. Du kan också köra kommandot igen för att starta om den simulerade enheten.

Anropa en direktmetod

I det här avsnittet använder du den andra CLI-sessionen för att anropa en direktmetod på den simulerade enhet som körs i den första CLI-sessionen.

Bekräfta att den simulerade enheten i den första CLI-sessionen körs. Annars startar du om det genom att köra kommandot az iot device simulate igen från Skapa och simulera en enhet.
I den andra CLI-sessionen kör du kommandot az iot hub invoke-device-method och ersätter följande platshållare med motsvarande värden. I det här exemplet finns det ingen befintlig metod för enheten. Kommandot anropar ett exempelmetodnamn på den simulerade enheten. Metoden innehåller en statuskod och nyttolast i svaret.

{DeviceName}. Namnet på den simulerade enheten.

{HubName}. Namnet på din IoT-hubb.

{MethodName}. Namnet på din direktmetod. Den simulerade enheten har ingen befintlig metod, så du kan välja vilket namn du vill för det här kommandot.
```
az iot hub invoke-device-method --device-id {DeviceName} --hub-name {HubName} \
                                --method-name {MethodName}
```
I den första CLI-sessionen bekräftar du att utdata visar metodanropet. I följande skärmbild använde SampleDevice vi och SampleMethod för {DeviceName} platshållarna respektive {MethodName} i az iot hub invoke-device-method CLI-kommandot.
I den andra CLI-sessionen bekräftar du att utdata visar statuskoden och nyttolasten som tagits emot från den anropade metoden.

Anropa en direktmetod med en nyttolast

I det här avsnittet använder du den andra CLI-sessionen för att anropa en direktmetod och tillhandahålla en nyttolast till den simulerade enhet som körs i den första CLI-sessionen.

Bekräfta att den simulerade enheten i den första CLI-sessionen körs. Annars startar du om det genom att köra kommandot az iot device simulate igen från Skapa och simulera en enhet.
I den andra CLI-sessionen kör du kommandot az iot hub invoke-device-method och ersätter följande platshållare med motsvarande värden. I det här exemplet finns det ingen befintlig metod för enheten. Kommandot anropar ett exempelmetodnamn på den simulerade enheten och tillhandahåller en nyttolast för den metoden. Metoden innehåller en statuskod och nyttolast i svaret.

{DeviceName}. Namnet på den simulerade enheten.

{HubName}. Namnet på din IoT-hubb.

{MethodName}. Namnet på din direktmetod. Den simulerade enheten har ingen befintlig metod, så du kan välja vilket namn du vill för det här kommandot.
```
az iot hub invoke-device-method --device-id {DeviceName} --hub-name {HubName} \
                                --method-name {MethodName} \
                                --method-payload '{ "SamplePayload": "PayloadValue" }'
```
I den första CLI-sessionen bekräftar du att utdata visar metodanropet. I följande skärmbild använde SampleDevice vi och SampleMethod för {DeviceName} platshållarna respektive {MethodName} i az iot hub invoke-device-method CLI-kommandot.
I den andra CLI-sessionen bekräftar du att utdata visar statuskoden och nyttolasten som tagits emot från den anropade metoden.

Nästa steg

Information om hur du använder Azure CLI för att utöka IoT-lösningen och schemalägga metodanrop på enheter finns i Schemalägga och sända jobb.

Om du vill fortsätta komma igång med IoT Hub- och enhetshanteringsmönster, till exempel bildbaserad uppdatering från slutpunkt till slutpunkt, kan du läsa artikeln Enhetsuppdatering för Azure IoT Hub med hjälp av Raspberry Pi 3 B+-referensbilden.

Dela via