Cloud-naar-apparaat-berichten verzenden met IoT Hub (.NET)

Azure IoT Hub is een volledig beheerde service die betrouwbare en veilige bidirectionele communicatie tussen miljoenen apparaten en een back-end van een oplossing mogelijk maakt.

In dit artikel leest u informatie over:

• Cloud-naar-apparaat-berichten (C2D) van de back-end van uw oplossing verzenden naar één apparaat via IoT Hub

• Cloud-naar-apparaat-berichten ontvangen op een apparaat

• Ontvangstbevestiging aanvragen (feedback), van de back-end van uw oplossing, voor berichten die vanaf IoT Hub naar een apparaat worden verzonden

Aan het einde van dit artikel voert u twee .NET-console-apps uit.

• MessageReceiveSample: een voorbeeldapparaat-app die is opgenomen in de Microsoft Azure IoT SDK voor .NET, die verbinding maakt met uw IoT-hub en cloud-naar-apparaat-berichten ontvangt.

• SendCloudToDevice: een service-app die een cloud-naar-apparaat-bericht verzendt naar de apparaat-app via IoT Hub en vervolgens de ontvangstbevestiging ontvangt.

Meer informatie over cloud-naar-apparaat-berichten vindt u in D2C en C2D Messaging met IoT Hub.

Vereisten

• Een Azure-abonnement. Als u nog geen abonnement op Azure hebt, maak dan een gratis account aan voordat u begint.

• Een IoT-hub in uw Azure-abonnement. Als u nog geen hub hebt, kunt u de stappen in Een IoT-hub maken volgen.

• Een apparaat dat is geregistreerd in uw IoT-hub. Als u nog geen apparaat hebt geregistreerd, registreert u er een in de Azure Portal.

• In dit artikel wordt voorbeeldcode van de Azure IoT SDK voor C# gebruikt.

  • Download of kloon de SDK-opslagplaats van GitHub naar uw ontwikkelcomputer.
  • Zorg ervoor dat .NET Core 3.0.0 of hoger is geïnstalleerd op uw ontwikkelcomputer. Controleer uw versie door .NET uit te voeren dotnet --version en zo nodig te downloaden .

• Zorg ervoor dat de poort 8883 is geopend in de firewall. Het apparaatvoorbeeld in dit artikel maakt gebruik van het MQTT-protocol, dat communiceert via poort 8883. Deze poort is in sommige netwerkomgevingen van bedrijven en onderwijsinstellingen mogelijk geblokkeerd. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

• Visual Studio.

De verbindingsreeks ophalen

In dit artikel voert u een voorbeeld-app uit die een apparaat simuleert en cloud-naar-apparaat-berichten ontvangt die via uw IoT Hub worden verzonden. De MessageReceiveSample-voorbeeld-app die is opgenomen in de Microsoft Azure IoT SDK voor .NET maakt verbinding met uw IoT-hub en fungeert als uw gesimuleerde apparaat. In het voorbeeld wordt de primaire connection string van het geregistreerde apparaat op uw IoT-hub gebruikt.

Voer de volgende stappen uit om de primaire connection string op te halen voor een apparaat dat is geregistreerd bij uw IoT-hub:

1. Selecteer resourcegroepenin de Azure Portal. Selecteer de resourcegroep waarin uw hub zich bevindt en selecteer vervolgens uw hub in de lijst met resources.

2. Selecteer in het linkerdeelvenster van uw IoT-hub onder Apparaatbeheerde optie Apparaten.

3. Selecteer het juiste apparaat in de lijst met apparaten.

4. Kopieer de Primaire connection string en sla de waarde op.

   

Berichten ontvangen in de apparaat-app

In deze sectie voert u de voorbeeldapparaat-app MessageReceiveSample uit om C2D-berichten te ontvangen die via uw IoT-hub worden verzonden. Open een nieuwe opdrachtprompt en navigeer naar de map azure-iot-sdk-csharp\iothub\device\samples\getting started\MessageReceiveSample , onder de map waarin u de Azure IoT C#-SDK hebt uitgebreid. Voer de volgende opdrachten uit, waarbij u de waarde van de {Your device connection string} tijdelijke aanduiding vervangt door het apparaat connection string u hebt gekopieerd van het geregistreerde apparaat in uw IoT-hub.

dotnet restore
dotnet run --c "{Your device connection string}"

De volgende uitvoer is afkomstig van de voorbeeldapparaat-app nadat deze is gestart en verbinding heeft gemaakt met uw IoT-hub:

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
     
5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.

De voorbeeldapparaat-app peilt naar berichten met behulp van de methoden ReceiveAsync en CompleteAsync . De ReceiveC2dMessagesPollingAndCompleteAsync methode maakt gebruik van de ReceiveAsync methode, die asynchroon het ontvangen bericht retourneert op het moment dat het apparaat het bericht ontvangt. ReceiveAsyncretourneert null na een opgegeven time-outperiode. In dit voorbeeld wordt de standaardwaarde van één minuut gebruikt. Wanneer het apparaat een null ontvangt, moet het blijven wachten op nieuwe berichten. Deze vereiste is de reden waarom de voorbeeld-app het volgende codeblok in de ReceiveC2dMessagesPollingAndCompleteAsync methode opneemt:

   if (receivedMessage == null)
   {
      continue;
   }

De aanroep van de CompleteAsync methode meldt IoT Hub dat het bericht is verwerkt en dat het bericht veilig uit de apparaatwachtrij kan worden verwijderd. Het apparaat moet deze methode aanroepen wanneer de verwerking is voltooid, ongeacht het protocol dat wordt gebruikt.

Met AMQP- en HTTPS-protocollen, maar niet met het MQTT-protocol, kan het apparaat ook het volgende doen:

• Een bericht verwijderen, waardoor IoT Hub het bericht in de apparaatwachtrij wordt bewaard voor toekomstig gebruik.
• Een bericht weigeren, waardoor het bericht definitief uit de apparaatwachtrij wordt verwijderd.

Als er iets gebeurt waardoor het apparaat het bericht niet kan voltooien, afbreken of weigeren, wordt IoT Hub na een vaste time-outperiode het bericht opnieuw in de wachtrij geplaatst voor bezorging. Daarom moet de logica voor berichtverwerking in de apparaat-app idempotent zijn, zodat hetzelfde bericht meerdere keren hetzelfde resultaat oplevert.

Zie Cloud-naar-apparaat-berichten verzenden vanuit een IoT-hub voor meer informatie over de levenscyclus van cloud-naar-apparaat-berichten en hoe IoT Hub cloud-naar-apparaat-berichten verwerkt.

De IoT-hub ophalen connection string

In dit artikel maakt u een back-endservice voor het verzenden van cloud-naar-apparaat-berichten via uw IoT Hub. Als u cloud-naar-apparaat-berichten wilt verzenden, heeft uw service de machtiging serviceverbinding nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent.

Voer de volgende stappen uit om de IoT Hub connection string voor het servicebeleid op te halen:

1. Selecteer resourcegroepenin de Azure Portal. Selecteer de resourcegroep waarin uw hub zich bevindt en selecteer vervolgens uw hub in de lijst met resources.

2. Selecteer In het linkerdeelvenster van uw IoT-hub de optie Beleid voor gedeelde toegang.

3. Selecteer het servicebeleid in de lijst met beleidsregels.

4. Kopieer de Primaire connection string en sla de waarde op.

Zie Toegangsbeheer en machtigingen voor meer informatie over IoT Hub beleid en machtigingen voor gedeelde toegang.

Een cloud-naar-apparaat-bericht verzenden

In deze sectie maakt u een .NET-console-app die cloud-naar-apparaat-berichten verzendt naar de gesimuleerde apparaat-app. U hebt de apparaat-id van uw apparaat en uw IoT-hub nodig connection string.

1. Selecteer in Visual Studio Bestand>Nieuw>Project. Selecteer in Een nieuw project makende optie Console-app (.NET Framework) en selecteer vervolgens Volgende.

2. Geef het project de naam SendCloudToDevice en selecteer Volgende.

   

3. Accepteer de meest recente versie van de .NET Framework. Selecteer Maken om het project te maken.

4. Klik in Solution Explorer met de rechtermuisknop op het nieuwe project en selecteer Vervolgens NuGet-pakketten beheren.

5. Selecteer in NuGet-pakketten beherende optie Bladeren en zoek en selecteer Vervolgens Microsoft.Azure.Devices. Selecteer Installeren.

   In deze stap wordt het NuGet-pakket van de Azure IoT-service-SDK gedownload, geïnstalleerd en toegevoegd.

6. Voeg de volgende using instructie toe boven aan het bestand Program.cs .

   using Microsoft.Azure.Devices;
   

7. Voeg de volgende velden toe aan de klasse Program: Vervang de waarde van de {iot hub connection string} tijdelijke aanduiding door de IoT-hub-connection string u eerder hebt genoteerd in De IoT-hub ophalen connection string. Vervang de waarde van de {device id} tijdelijke aanduiding door de apparaat-id van het geregistreerde apparaat in uw IoT-hub.

   static ServiceClient serviceClient;
   static string connectionString = "{iot hub connection string}";
   static string targetDevice = "{device id}";
   

8. Voeg de volgende methode toe aan de klasse Program om een bericht naar uw apparaat te verzenden.

   private async static Task SendCloudToDeviceMessageAsync()
   {
        var commandMessage = new
         Message(Encoding.ASCII.GetBytes("Cloud to device message."));
        await serviceClient.SendAsync(targetDevice, commandMessage);
   }
   

9. Voeg ten slotte de volgende regels toe aan de methode Main .

   Console.WriteLine("Send Cloud-to-Device message\n");
   serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
   
   Console.WriteLine("Press any key to send a C2D message.");
   Console.ReadLine();
   SendCloudToDeviceMessageAsync().Wait();
   Console.ReadLine();
   

10. Druk op F5 om uw voorbeeldservice-app te starten. Selecteer het venster SendCloudToDevice en druk op Enter. U ziet het bericht dat is ontvangen door de voorbeeldapparaat-app, zoals wordt weergegeven in het volgende uitvoervoorbeeld.

    5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
    
    5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
    5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
    5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.
    5/22/2023 11:15:18 AM> Polling using ReceiveAsync() - received message with Id=
    5/22/2023 11:15:18 AM> Received message: [Cloud to device message.]
            Content type:
    
    5/22/2023 11:15:18 AM> Completed C2D message with Id=.
    

Feedback over bezorging ontvangen

Het is mogelijk om ontvangstbevestigingen (of vervaldatum) van IoT Hub aan te vragen voor elk cloud-naar-apparaat-bericht. Met deze optie kan de back-end van de oplossing eenvoudig informatie geven, opnieuw proberen of compensatielogica gebruiken. Zie D2C- en C2D-berichten met IoT Hub voor meer informatie over cloud-naar-apparaat-feedback.

In deze sectie wijzigt u de voorbeeldservice-app SendCloudToDevice om feedback aan te vragen en deze te ontvangen van de IoT-hub.

1. Voeg in Visual Studio in het project SendCloudToDevice de volgende methode toe aan de klasse Program .

   private async static void ReceiveFeedbackAsync()
   {
        var feedbackReceiver = serviceClient.GetFeedbackReceiver();
   
        Console.WriteLine("\nReceiving c2d feedback from service");
        while (true)
        {
            var feedbackBatch = await feedbackReceiver.ReceiveAsync();
            if (feedbackBatch == null) continue;
   
            Console.ForegroundColor = ConsoleColor.Yellow;
            Console.WriteLine("Received feedback: {0}",
              string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
            Console.ResetColor();
   
            await feedbackReceiver.CompleteAsync(feedbackBatch);
        }
    }
   

   Houd er rekening mee dat dit ontvangstpatroon hetzelfde is dat wordt gebruikt voor het ontvangen van cloud-naar-apparaat-berichten van de apparaat-app.

2. Voeg de volgende regel toe in de methode Main , direct na serviceClient = ServiceClient.CreateFromConnectionString(connectionString).

   ReceiveFeedbackAsync();
   

3. Als u feedback wilt aanvragen voor de levering van uw cloud-naar-apparaat-bericht, moet u een eigenschap opgeven in de methode SendCloudToDeviceMessageAsync . Voeg de volgende regel toe, direct na de var commandMessage = new Message(...); regel.

   commandMessage.Ack = DeliveryAcknowledgement.Full;
   

4. Zorg ervoor dat de voorbeeldapparaat-app wordt uitgevoerd en voer vervolgens de voorbeeldservice-app uit door op F5 te drukken. Selecteer het consolevenster SendCloudToDevice en druk op Enter. U ziet dat het bericht wordt ontvangen door de voorbeeldapparaat-app en na een paar seconden het feedbackbericht dat wordt ontvangen door uw SendCloudToDevice-toepassing . In de volgende uitvoer ziet u het feedbackbericht dat is ontvangen door de voorbeeldservice-app:

   Send Cloud-to-Device message
   
   
   Receiving c2d feedback from service
   Press any key to send a C2D message.
   
   Received feedback: Success
   

Volgende stappen

In dit artikel hebt u geleerd hoe u cloud-naar-apparaat-berichten kunt verzenden en ontvangen.

• Zie Cloud-naar-apparaat-berichten verzenden vanuit een IoT-hub voor meer informatie over cloud-naar-apparaat-berichten.

• Zie IoT Hub berichten maken en lezen voor meer informatie over IoT Hub berichtindelingen.