Przekazywanie plików z urządzenia do chmury za pomocą usługi Azure IoT Hub (.NET)

  • Artykuł

W tym artykule pokazano, jak przekazywać pliki możliwości przekazywania plików w usłudze IoT Hub do usługi Azure Blob Storage przy użyciu zestawów SDK urządzeń i usług platformy Azure IoT .NET.

W artykule Wysyłanie danych telemetrycznych z urządzenia do centrum IoT Hub i Wysyłanie komunikatów z chmury do urządzenia za pomocą usługi IoT Hub przedstawiono podstawowe funkcje obsługi komunikatów z urządzenia do chmury i chmury w usłudze IoT Hub. Artykuł Configure Message Routing with IoT Hub (Konfigurowanie routingu komunikatów za pomocą usługi IoT Hub ) przedstawia sposób niezawodnego przechowywania komunikatów z urządzenia do chmury w magazynie obiektów blob platformy Microsoft Azure. Jednak w niektórych scenariuszach nie można łatwo mapować danych wysyłanych przez urządzenia do stosunkowo małych komunikatów z urządzenia do chmury akceptowanych przez usługę IoT Hub. Na przykład:

  • Filmy wideo
  • Duże pliki zawierające obrazy
  • Próbkowane dane drgań o wysokiej częstotliwości
  • Niektóre formy wstępnie przetworzonych danych

Te pliki są zwykle przetwarzane wsadowo w chmurze przy użyciu narzędzi, takich jak usługa Azure Data Factory lub stos usługi Hadoop . Jeśli musisz przekazać pliki z urządzenia, nadal możesz korzystać z zabezpieczeń i niezawodności usługi IoT Hub. W tym artykule pokazano, jak to zrobić.

Na końcu tego artykułu uruchomisz dwie aplikacje konsolowe platformy .NET:

  • FileUploadSample. Ta aplikacja urządzenia przekazuje plik do magazynu przy użyciu identyfikatora URI sygnatury dostępu współdzielonego udostępnionego przez centrum IoT. Ten przykład pochodzi z repozytorium zestawu SDK języka C# usługi Azure IoT pobranego w wymaganiach wstępnych.

  • ReadFileUploadNotification. Ta aplikacja usługi odbiera powiadomienia o przekazaniu plików z centrum IoT Hub. Utworzysz tę aplikację.

Uwaga

Usługa IoT Hub obsługuje wiele platform urządzeń i języków (w tym C, Java, Python i JavaScript) za pośrednictwem zestawów SDK urządzeń usługi Azure IoT. Zapoznaj się z centrum deweloperów usługi Azure IoT, aby dowiedzieć się, jak połączyć urządzenie z usługą Azure IoT Hub.

Ważne

Funkcje przekazywania plików na urządzeniach korzystających z uwierzytelniania urzędu certyfikacji X.509 są w publicznej wersji zapoznawczej, a tryb podglądu musi być włączony. Jest ona ogólnie dostępna na urządzeniach korzystających z uwierzytelniania odcisku palca X.509 lub zaświadczania certyfikatu X.509 za pomocą usługi Azure Device Provisioning Service. Aby dowiedzieć się więcej na temat uwierzytelniania X.509 w usłudze IoT Hub, zobacz Obsługiwane certyfikaty X.509.

Wymagania wstępne

  • Centrum IoT. Utwórz go za pomocą interfejsu wiersza polecenia lub witryny Azure Portal.

  • Zarejestrowane urządzenie. Zarejestruj je w witrynie Azure Portal.

  • Przykładowe aplikacje uruchamiane w tym artykule są napisane przy użyciu języka C# z platformą .NET Core.

    Pobierz zestaw .NET Core SDK dla wielu platform z platformy .NET.

    Sprawdź bieżącą wersję zestawu .NET Core SDK na maszynie dewelopera przy użyciu następującego polecenia:

    dotnet --version

  • Pobierz zestaw SDK języka C# usługi Azure IoT z sekcji Pobierz przykład i wyodrębnij archiwum ZIP.

  • Port 8883 powinien być otwarty w zaporze. W przykładzie w tym artykule użyto protokołu MQTT, który komunikuje się za pośrednictwem portu 8883. Ten port może zostać zablokowany w niektórych środowiskach sieci firmowych i edukacyjnych. Aby uzyskać więcej informacji i sposobów obejścia tego problemu, zobacz Połączenie do usługi IoT Hub (MQTT).

Kojarzenie konta usługi Azure Storage z usługą IoT Hub

Aby przekazać pliki z urządzenia, musisz mieć konto usługi Azure Storage i kontener usługi Azure Blob Storage skojarzony z centrum IoT. Po skojarzeniu konta magazynu i kontenera z centrum IoT Hub centrum IoT hub może podać elementy identyfikatora URI sygnatury dostępu współdzielonego w przypadku żądania przez urządzenie. Następnie urządzenie może użyć tych elementów do skonstruowania identyfikatora URI sygnatury dostępu współdzielonego używanego do uwierzytelniania w usłudze Azure Storage i przekazywania plików do kontenera obiektów blob.

Aby skojarzyć konto usługi Azure Storage z centrum IoT:

  1. W obszarze Ustawienia centrum wybierz pozycję Przekazywanie pliku w okienku po lewej stronie centrum IoT Hub.

    Zrzut ekranu przedstawiający wybieranie ustawień przekazywania plików z portalu.

  2. W okienku Przekazywanie plików wybierz pozycję Kontener usługi Azure Storage. W tym artykule zaleca się, aby twoje konto magazynu i usługa IoT Hub znajdowały się w tym samym regionie.

    • Jeśli masz już konto magazynu, którego chcesz użyć, wybierz je z listy.

    • Aby utworzyć nowe konto magazynu, wybierz pozycję +Konto magazynu. Podaj nazwę konta magazynu i upewnij się, że lokalizacja jest ustawiona na ten sam region co centrum IoT, a następnie wybierz przycisk OK. Nowe konto jest tworzone w tej samej grupie zasobów co centrum IoT Hub. Po zakończeniu wdrażania wybierz konto magazynu z listy.

    Po wybraniu konta magazynu zostanie otwarte okienko Kontenery .

  3. W okienku Kontenery wybierz kontener obiektów blob.

    • Jeśli masz już kontener obiektów blob, którego chcesz użyć, wybierz go z listy i kliknij pozycję Wybierz.

    • Aby utworzyć nowy kontener obiektów blob, wybierz pozycję + Kontener. Podaj nazwę nowego kontenera. Na potrzeby tego artykułu można pozostawić wszystkie inne pola domyślnie. Wybierz pozycję Utwórz. Po zakończeniu wdrażania wybierz kontener z listy i kliknij pozycję Wybierz.

  4. Wróć do okienka Przekazywanie pliku, upewnij się, że powiadomienia o plikach są ustawione na włączone. Wszystkie inne ustawienia można pozostawić w ustawieniach domyślnych. Wybierz pozycję Zapisz i poczekaj na ukończenie ustawień przed przejściem do następnej sekcji.

    Przechwytywanie ekranu przedstawiające potwierdzanie ustawień przekazywania plików w portalu.

Aby uzyskać bardziej szczegółowe instrukcje dotyczące tworzenia konta usługi Azure Storage, zobacz Tworzenie konta magazynu. Aby uzyskać bardziej szczegółowe instrukcje dotyczące kojarzenia konta magazynu i kontenera obiektów blob z centrum IoT Hub, zobacz Konfigurowanie przekazywania plików przy użyciu witryny Azure Portal.

Przekazywanie pliku z aplikacji urządzenia

W tym artykule użyto przykładu z repozytorium zestawu SDK języka C# usługi Azure IoT, które pobrano wcześniej jako aplikację urządzenia. Możesz otworzyć poniższe pliki przy użyciu wybranego programu Visual Studio, programu Visual Studio Code lub edytora tekstów.

Przykład znajduje się w folderze azure-iot-sdk-csharp/iothub/device/samples/getting started/FileUploadSample w folderze, w którym wyodrębniono zestaw SDK języka C# usługi Azure IoT.

Sprawdź kod w FileUpLoadSample.cs. Ten plik zawiera główną logikę przykładu. Po utworzeniu klienta urządzenia usługi IoT Hub jest zgodna ze standardową trzyczęściową procedurą przekazywania plików z urządzenia:

  1. Kod wywołuje metodę GetFileUploadSasUriAsync na kliencie urządzenia, aby uzyskać identyfikator URI sygnatury dostępu współdzielonego z centrum IoT:

    var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

// Lines removed for clarity

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
Uri uploadUri = sasUri.GetBlobUri();

  2. Kod używa identyfikatora URI sygnatury dostępu współdzielonego do przekazania pliku do usługi Azure Storage. W tym przykładzie użyto identyfikatora URI sygnatury dostępu współdzielonego do utworzenia klienta blokowego obiektu blob usługi Azure Storage i przekazania pliku:

    var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());

  3. Kod powiadamia centrum IoT o zakończeniu przekazywania. Informuje to centrum IoT, że może zwolnić zasoby skojarzone z przekazywaniem (identyfikator URI sygnatury dostępu współdzielonego). Jeśli powiadomienia dotyczące przekazywania plików są włączone, centrum IoT wysyła komunikat powiadomienia do usług zaplecza.

    var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
{
    // Mandatory. Must be the same value as the correlation id returned in the sas uri response
    CorrelationId = sasUri.CorrelationId,

    // Mandatory. Will be present when service client receives this file upload notification
    IsSuccess = true,

    // Optional, user defined status code. Will be present when service client receives this file upload notification
    StatusCode = 200,

    // Optional, user-defined status description. Will be present when service client receives this file upload notification
    StatusDescription = "Success"
};

await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

Jeśli zbadasz plik parameter.cs , zobaczysz, że:

  • Przykład wymaga przekazania parametru p, który przyjmuje urządzenie parametry połączenia.

  • Domyślnie przykład urządzenia używa protokołu MQTT do komunikowania się z usługą IoT Hub. Możesz użyć parametru t , aby zmienić ten protokół transportu. Niezależnie od tego wyboru klient obiektów blob platformy Azure zawsze używa protokołu HTTPS do przekazania pliku usługi Azure Storage.

Pobieranie parametry połączenia centrum IoT

W tym artykule utworzysz usługę zaplecza w celu odbierania komunikatów powiadomień o przekazaniu plików z centrum IoT. Aby otrzymywać komunikaty z powiadomieniem o przekazaniu plików, usługa wymaga uprawnienia do połączenia z usługą. Domyślnie każde centrum IoT Hub jest tworzone przy użyciu zasad dostępu współdzielonego o nazwie usługa , która przyznaje to uprawnienie.

Aby uzyskać parametry połączenia usługi IoT Hub dla zasad usługi, wykonaj następujące kroki:

  1. W witrynie Azure Portal wybierz pozycję Grupy zasobów. Wybierz grupę zasobów, w której znajduje się centrum, a następnie wybierz centrum z listy zasobów.

  2. W okienku po lewej stronie centrum IoT hub wybierz pozycję Zasady dostępu współdzielonego.

  3. Z listy zasad wybierz zasady usługi .

  4. Skopiuj parametry połączenia podstawową i zapisz wartość.

Zrzut ekranu przedstawiający sposób pobierania parametry połączenia z usługi IoT Hub w witrynie Azure Portal.

Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego i uprawnień usługi IoT Hub, zobacz Kontrola dostępu i uprawnienia.

Otrzymywanie powiadomienia o przekazaniu pliku

W tej sekcji utworzysz aplikację konsolową języka C#, która odbiera komunikaty powiadomień o przekazaniu plików z centrum IoT Hub.

  1. Otwórz okno polecenia i przejdź do folderu, w którym chcesz utworzyć projekt. Utwórz folder o nazwie ReadFileUploadNotifications i zmień katalogi na ten folder.

    mkdir ReadFileUploadNotification
cd ReadFileUploadNotification

  2. Uruchom następujące polecenie, aby utworzyć projekt konsoli języka C#. Po uruchomieniu polecenia folder będzie zawierać plik Program.cs i plik ReadFileUploadNotification.csproj .

    dotnet new console --language c#

  3. Uruchom następujące polecenie, aby dodać pakiet Microsoft.Azure.Devices do pliku projektu. Ten pakiet jest zestawem SDK usługi .NET platformy Azure IoT.

    dotnet add package Microsoft.Azure.Devices

  4. Otwórz plik Program.cs i dodaj następującą instrukcję w górnej części pliku:

    using Microsoft.Azure.Devices;

  5. Dodaj następujące pola do klasy Program: Zastąp wartość symbolu {iot hub connection string} zastępczego parametry połączenia centrum IoT Hub skopiowaną wcześniej w sekcji Pobieranie parametry połączenia centrum IoT:

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

  6. Dodaj następującą metodę do klasy Program:

    private async static void ReceiveFileUploadNotificationAsync()
{
    var notificationReceiver = serviceClient.GetFileNotificationReceiver();
    Console.WriteLine("\nReceiving file upload notification from service");
    while (true)
    {
        var fileUploadNotification = await notificationReceiver.ReceiveAsync();
        if (fileUploadNotification == null) continue;
        Console.ForegroundColor = ConsoleColor.Yellow;
        Console.WriteLine("Received file upload notification: {0}", 
          string.Join(", ", fileUploadNotification.BlobName));
        Console.ResetColor();
        await notificationReceiver.CompleteAsync(fileUploadNotification);
    }
}

    Należy pamiętać, że ten wzorzec odbierania jest taki sam, jak używany do odbierania komunikatów z chmury do urządzenia z aplikacji urządzenia.

  7. Na koniec zastąp wiersze w metodzie Main następującymi elementami:

    Console.WriteLine("Receive file upload notifications\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
ReceiveFileUploadNotificationAsync();
Console.WriteLine("Press Enter to exit\n");
Console.ReadLine();

Uruchamianie aplikacji

Teraz możesz przystąpić do uruchamiania aplikacji.

  1. Najpierw uruchom aplikację usługi, aby otrzymywać powiadomienia o przekazaniu plików z centrum IoT. W wierszu polecenia w folderze ReadFileUploadNotification uruchom następujące polecenia:

    dotnet restore
dotnet run

    Aplikacja uruchamia się i czeka na powiadomienie o przekazaniu pliku z centrum IoT:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

  2. Następnie uruchom aplikację urządzenia, aby przekazać plik do usługi Azure Storage. Otwórz nowy wiersz polecenia i zmień foldery na azure-iot-sdk-csharp\iothub\device\samples\getting started\FileUploadSample w folderze, w którym rozwinięto zestaw SDK języka C# usługi Azure IoT. Uruchom następujące polecenia. Zastąp {Your device connection string} wartość symbolu zastępczego w drugim poleceniu urządzeniem parametry połączenia, które zostało wyświetlone podczas rejestrowania urządzenia w centrum IoT.

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

    Następujące dane wyjściowe pochodzą z aplikacji urządzenia po zakończeniu przekazywania:

      Uploading file TestPayload.txt
  Getting SAS URI from IoT Hub to use when uploading the file...
  Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub
  Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication
  Successfully uploaded the file to Azure Storage
  Notified IoT Hub that the file upload succeeded and that the SAS URI can be freed.
  Time to upload file: 00:00:01.5077954.
  Done.

  3. Zwróć uwagę, że aplikacja usługi pokazuje, że otrzymał powiadomienie o przekazaniu pliku:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

Received file upload notification: myDeviceId/TestPayload.txt

Weryfikowanie przekazywania pliku

Za pomocą portalu możesz wyświetlić przekazany plik w skonfigurowanym kontenerze magazynu:

  1. Przejdź do konta magazynu w witrynie Azure Portal.

  2. W lewym okienku konta magazynu wybierz pozycję Kontenery.

  3. Wybierz kontener, do którego został przekazany plik.

  4. Wybierz folder o nazwie po urządzeniu.

  5. Wybierz obiekt blob, do którego został przekazany plik. W tym artykule jest to obiekt blob o nazwie TestPayload.txt.

    Zrzut ekranu przedstawiający wybieranie przekazanego pliku w witrynie Azure Portal.

  6. Wyświetl właściwości obiektu blob na stronie, która zostanie otwarta. Możesz wybrać pozycję Pobierz , aby pobrać plik i wyświetlić jego zawartość lokalnie.

Następne kroki

W tym artykule przedstawiono sposób użycia funkcji przekazywania plików usługi IoT Hub w celu uproszczenia przekazywania plików z urządzeń. Możesz kontynuować eksplorowanie tej funkcji, wykonując następujące artykuły: