Przekazywanie plików za pomocą usługi IoT Hub

  • Artykuł

Istnieje wiele scenariuszy, w których nie można łatwo mapować danych urządzenia na stosunkowo małe komunikaty z urządzenia do chmury akceptowane przez usługę IoT Hub. Na przykład wysyłanie dużych plików multimedialnych, takich jak wideo; lub, wysyłając duże partie telemetrii, przekazywane przez sporadycznie podłączone urządzenia lub agregowane i skompresowane w celu zaoszczędzenia przepustowości.

Jeśli musisz przekazać duże pliki z urządzenia, nadal możesz korzystać z zabezpieczeń i niezawodności usługi IoT Hub. Zamiast brokerować komunikaty za pośrednictwem samego siebie, usługa IoT Hub działa jednak jako dyspozytor do skojarzonego konta usługi Azure Storage. Usługa IoT Hub może również wysyłać powiadomienia do usług zaplecza po zakończeniu przekazywania pliku przez urządzenie.

Jeśli potrzebujesz pomocy przy podejmowaniu decyzji, kiedy używać zgłaszanych właściwości, komunikatów z urządzenia do chmury lub przekazywania plików, zobacz Wskazówki dotyczące komunikacji urządzenie-chmura.

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.

Omówienie przekazywania plików

Centrum IoT ułatwia przekazywanie plików z połączonych urządzeń, zapewniając im identyfikatory URI sygnatury dostępu współdzielonego (SAS) na podstawie przekazywania dla kontenera obiektów blob i konta usługi Azure Storage, które zostały wstępnie skonfigurowane z centrum. Istnieją trzy części korzystania z przekazywania plików w usłudze IoT Hub: wstępne konfigurowanie konta usługi Azure Storage i kontenera obiektów blob w centrum IoT, przekazywanie plików z urządzeń oraz, opcjonalnie, powiadamianie usług zaplecza o ukończonych przekazach plików.

Aby można było użyć funkcji przekazywania plików, musisz skojarzyć konto usługi Azure Storage i kontener obiektów blob z centrum IoT Hub. Możesz również skonfigurować ustawienia kontrolujące sposób uwierzytelniania usługi IoT Hub w usłudze Azure Storage, czas wygaśnięcia (TTL) identyfikatorów URI sygnatury dostępu współdzielonego, które centrum IoT Hub przekazuje do urządzeń i wysyła powiadomienia do usług zaplecza. Aby dowiedzieć się więcej, zobacz Kojarzenie konta usługi Azure Storage z usługą IoT Hub.

Urządzenia są zgodne z trzyetapowym procesem przekazywania pliku do skojarzonego kontenera obiektów blob:

  1. Urządzenie inicjuje przekazywanie pliku za pomocą centrum IoT Hub. Przekazuje nazwę obiektu blob w żądaniu i pobiera identyfikator URI sygnatury dostępu współdzielonego oraz identyfikator korelacji w zamian. Identyfikator URI sygnatury dostępu współdzielonego zawiera token SAS dla usługi Azure Storage, który przyznaje urządzeniu uprawnienie do odczytu i zapisu w żądanym obiekcie blob w kontenerze obiektów blob. Aby uzyskać więcej informacji, zobacz Device: Initialize a file upload (Urządzenie: inicjowanie przekazywania plików).

  2. Urządzenie używa identyfikatora URI sygnatury dostępu współdzielonego do bezpiecznego wywoływania interfejsów API usługi Azure Blob Storage w celu przekazania pliku do kontenera obiektów blob. Aby uzyskać więcej informacji, zobacz Device: Upload file using Azure Storage APIs (Urządzenie: przekazywanie pliku przy użyciu interfejsów API usługi Azure Storage).

  3. Po zakończeniu przekazywania pliku urządzenie powiadamia centrum IoT o stanie ukończenia przy użyciu identyfikatora korelacji otrzymanego z usługi IoT Hub po zainicjowaniu przekazywania. Aby uzyskać więcej informacji, zobacz Device: Notify IoT Hub of a completed file upload (Urządzenie: powiadamianie usługi IoT Hub o ukończonym przekazaniu pliku).

Usługi zaplecza mogą subskrybować powiadomienia dotyczące przekazywania plików w punkcie końcowym powiadomień przekazywania plików centrum IoT Hub. Jeśli te powiadomienia zostały włączone w centrum IoT Hub, dostarcza je w tym punkcie końcowym za każdym razem, gdy urządzenie powiadomi centrum o zakończeniu przekazywania plików. Usługi mogą używać tych powiadomień do wyzwalania dalszego przetwarzania danych obiektu blob. Aby uzyskać więcej informacji, zobacz Service: File upload notifications (Usługa: powiadomienia o przekazaniu plików).

Przekazywanie plików jest w pełni obsługiwane przez zestawy SDK urządzeń i usług azure IoT. Aby uzyskać więcej informacji, zobacz Przekazywanie plików przy użyciu zestawu SDK.

Limity przydziału i limity przekazywania plików

Usługa IoT Hub nakłada ograniczenia przepustowości na liczbę przekazywanych plików, które może zainicjować w danym okresie. Próg jest oparty na jednostce SKU i liczbie jednostek centrum IoT. Ponadto każde urządzenie jest ograniczone do 10 współbieżnych aktywnych plików przekazywanych jednocześnie. Aby uzyskać więcej informacji, zobacz IoT Hub quotas and throttling (Limity przydziału i ograniczanie przepustowości usługi IoT Hub).

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

Aby korzystać z funkcji przekazywania plików, musisz skojarzyć konto usługi Azure Storage i kontener obiektów blob z centrum IoT Hub. Wszystkie pliki przekazywane z urządzeń zarejestrowanych w centrum IoT zostaną przekazane do tego kontenera. Aby skonfigurować konto magazynu i kontener obiektów blob w centrum IoT Hub, zobacz Konfigurowanie przekazywania plików usługi IoT Hub przy użyciu witryny Azure Portal, Konfigurowanie przekazywania plików usługi IoT Hub przy użyciu interfejsu wiersza polecenia platformy Azure lub Konfigurowanie przekazywania plików usługi IoT Hub przy użyciu programu PowerShell. Interfejsy API zarządzania usługi IoT Hub umożliwiają również programowe konfigurowanie przekazywania plików.

Jeśli używasz portalu, możesz utworzyć konto magazynu i kontener podczas konfigurowania. W przeciwnym razie, aby utworzyć konto magazynu, zobacz Tworzenie konta magazynu w dokumentacji usługi Azure Storage. Po utworzeniu konta magazynu możesz zobaczyć, jak utworzyć kontener obiektów blob w przewodnikach Szybki start usługi Azure Blob Storage. Domyślnie usługa Azure IoT Hub używa uwierzytelniania opartego na kluczach do nawiązywania połączenia i autoryzacji za pomocą usługi Azure Storage. Można również skonfigurować tożsamości zarządzane przypisane przez użytkownika lub przypisane przez system w celu uwierzytelniania usługi Azure IoT Hub za pomocą usługi Azure Storage. Tożsamości zarządzane zapewniają usługom platformy Azure automatycznie zarządzaną tożsamość w usłudze Microsoft Entra ID w bezpieczny sposób. Aby dowiedzieć się, jak skonfigurować tożsamości zarządzane, zobacz sekcję Konfigurowanie przekazywania plików za pomocą tożsamości zarządzanych w usłudze IoT Hub obsługi tożsamości zarządzanych.

Przekazywanie plików podlega ustawieniom zapory usługi Azure Storage. Na podstawie konfiguracji uwierzytelniania należy upewnić się, że urządzenia mogą komunikować się z usługą Azure Storage.

Istnieje kilka innych ustawień, które kontrolują zachowanie przekazywania plików i powiadomień o przekazaniu plików. W poniższych sekcjach wymieniono wszystkie dostępne ustawienia. W zależności od tego, czy używasz witryny Azure Portal, interfejsu wiersza polecenia platformy Azure, programu PowerShell, czy interfejsów API zarządzania do konfigurowania przekazywania plików, niektóre z tych ustawień mogą być niedostępne. Pamiętaj, aby ustawić ustawienie enableFileUploadNotifications , jeśli chcesz, aby powiadomienia wysyłane do usług zaplecza po zakończeniu przekazywania pliku.

Ustawienia magazynu i uwierzytelniania usługi Iot Hub

Poniższe ustawienia kojarzą konto magazynu i kontener z centrum IoT Hub i kontrolują sposób uwierzytelniania centrum w usłudze Azure Storage. Te ustawienia nie mają wpływu na sposób uwierzytelniania urządzeń w usłudze Azure Storage. Urządzenia zawsze uwierzytelniają się przy użyciu tokenu SAS przedstawionego w identyfikatorze URI sygnatury dostępu współdzielonego pobranym z usługi IoT Hub.

Właściwości opis Zakres i wartość domyślna
storageEndpoints.$default.authenticationType Określa sposób uwierzytelniania usługi IoT Hub w usłudze Azure Storage. Możliwe wartości to keyBased i identityBased. Wartość domyślna: keyBased.
storageEndpoints.$default.connectionString Parametry połączenia do konta usługi Azure Storage do użycia na potrzeby przekazywania plików. Ustawienie domyślne: Pusty ciąg.
storageEndpoints.$default.containerName Nazwa kontenera do przekazania plików. Ustawienie domyślne: Pusty ciąg.
storageEndpoints.$default.identity Tożsamość zarządzana do użycia na potrzeby uwierzytelniania opartego na tożsamościach. Możliwe wartości dotyczą [system] tożsamości zarządzanej przypisanej przez system lub identyfikatora zasobu dla tożsamości zarządzanej przypisanej przez użytkownika. Wartość nie jest używana do uwierzytelniania opartego na kluczach. Wartość domyślna: null.

Ustawienia przekazywania plików

Następujące ustawienia kontrolują przekazywanie plików z urządzenia.

Właściwości opis Zakres i wartość domyślna
storageEndpoints.$default.ttlAsIso8601 Domyślny czas wygaśnięcia dla identyfikatorów URI sygnatur dostępu współdzielonego generowanych przez usługę IoT Hub. ISO_8601 interwał do 48 godzin (minimum jedną minutę). Ustawienie domyślne: jedna godzina.

Ustawienia powiadomień przekazywania plików

Następujące ustawienia kontrolują powiadomienia dotyczące przekazywania plików do usług zaplecza.

Właściwości opis Zakres i wartość domyślna
enableFileUploadNotifications Określa, czy powiadomienia przekazywania plików są zapisywane w punkcie końcowym powiadomień o plikach. Bool. Wartość domyślna: Fałsz.
fileNotifications.ttlAsIso8601 Domyślny czas wygaśnięcia dla powiadomień o przekazaniu plików. ISO_8601 interwał do 48 godzin (minimum jedną minutę). Ustawienie domyślne: jedna godzina.
fileNotifications.lockDuration Zablokuj czas trwania kolejki powiadomień przekazywania plików. Od 5 do 300 sekund. Ustawienie domyślne: 60 sekund.
fileNotifications.maxDeliveryCount Maksymalna liczba dostaw dla kolejki powiadomień o przekazaniu pliku. Od 1 do 100. Wartość domyślna: 10.

Przekazywanie plików przy użyciu zestawu SDK

Poniższe przewodniki z instrukcjami zawierają kompletne instrukcje krok po kroku dotyczące przekazywania plików przy użyciu zestawów SDK urządzeń i usług Azure IoT. W przewodnikach pokazano, jak za pomocą witryny Azure Portal skojarzyć konto magazynu z centrum IoT Hub. Przewodniki zawierają również fragmenty kodu lub odwołują się do przykładów prowadzących przez przekazywanie.

Przewodnik z instrukcjami Przykład zestawu SDK urządzenia Przykład zestawu SDK usługi
.NET Tak Tak
Java Tak Tak
Node.js Tak Tak
Python Tak Nie (nieobsługiwane)

Uwaga

Zestaw SDK urządzenia C używa pojedynczego wywołania klienta urządzenia do przekazywania plików. Aby uzyskać więcej informacji, zobacz IoTHubDeviceClient_UploadToBlobAsync() i IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Te funkcje wykonują wszystkie aspekty przekazywania plików w jednym wywołaniu: inicjowanie przekazywania, przekazywanie pliku do usługi Azure Storage i powiadamianie usługi IoT Hub po zakończeniu. Ta interakcja oznacza, że oprócz dowolnego protokołu używanego przez urządzenie do komunikowania się z usługą IoT Hub urządzenie musi również mieć możliwość komunikowania się za pośrednictwem protokołu HTTPS z usługą Azure Storage, ponieważ te funkcje tworzą wywołania do interfejsów API usługi Azure Storage.

Urządzenie: inicjowanie przekazywania plików

Urządzenie wywołuje interfejs API REST tworzenia identyfikatora URI sygnatury dostępu współdzielonego przekazywania plików lub równoważny interfejs API w jednym z zestawów SDK urządzenia w celu zainicjowania przekazywania pliku.

Obsługiwane protokoły: HTTPS
Punkt końcowy: {iot hub}.azure-devices.net/devices/{deviceId}/files
Metoda: POST

{
    "blobName":"myfile.txt"
}
Właściwości opis
BlobName Nazwa obiektu blob do wygenerowania identyfikatora URI sygnatury dostępu współdzielonego dla.

Usługa IoT Hub odpowiada za pomocą identyfikatora korelacji i elementów identyfikatora URI sygnatury dostępu współdzielonego, których urządzenie może używać do uwierzytelniania w usłudze Azure Storage. Ta odpowiedź podlega limitom ograniczania przepustowości i limitom przekazywania dla poszczególnych urządzeń docelowego centrum IoT.

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}
Właściwości opis
correlationId Identyfikator urządzenia do użycia podczas wysyłania pełnego powiadomienia o przekazaniu pliku do usługi IoT Hub.
Nazwa hosta Nazwa hosta konta usługi Azure Storage dla konta magazynu skonfigurowanego w centrum IoT Hub
containerName Nazwa kontenera obiektów blob skonfigurowanych w centrum IoT.
BlobName Lokalizacja, w której obiekt blob będzie przechowywany w kontenerze. Nazwa ma następujący format: {device ID of the device making the request}/{blobName in the request}
sasToken Token SAS, który udziela dostępu do odczytu i zapisu w obiekcie blob za pomocą usługi Azure Storage. Token jest generowany i podpisany przez usługę IoT Hub.

Po odebraniu odpowiedzi urządzenie:

  • Zapisuje identyfikator korelacji do uwzględnienia w przesłaniu pliku pełne powiadomienie do centrum IoT Hub po zakończeniu przekazywania.

  • Używa innych właściwości do konstruowania identyfikatora URI sygnatury dostępu współdzielonego dla obiektu blob używanego do uwierzytelniania w usłudze Azure Storage. Identyfikator URI sygnatury dostępu współdzielonego zawiera identyfikator URI zasobu dla żądanego obiektu blob i token sygnatury dostępu współdzielonego. Ma następującą formę: https://{hostName}/{containerName}/{blobName}{sasToken} ( sasToken Właściwość w odpowiedzi zawiera wiodący znak "?"). Nawiasy klamrowe nie są uwzględniane.

    Na przykład w przypadku wartości zwróconych w poprzednim przykładzie identyfikator URI sygnatury dostępu współdzielonego to, https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw

    Aby uzyskać więcej informacji na temat identyfikatora URI sygnatury dostępu współdzielonego i tokenu SAS, zobacz Tworzenie sygnatury dostępu współdzielonego usługi w dokumentacji usługi Azure Storage.

Urządzenie: przekazywanie pliku przy użyciu interfejsów API usługi Azure Storage

Urządzenie używa interfejsów API REST usługi Azure Blob Storage lub równoważnych interfejsów API zestawu AZURE Storage SDK do przekazania pliku do obiektu blob w usłudze Azure Storage.

Obsługiwane protokoły: HTTPS

W poniższym przykładzie pokazano żądanie Put Blob w celu utworzenia lub zaktualizowania małego blokowego obiektu blob . Zwróć uwagę, że identyfikator URI używany dla tego żądania to identyfikator URI sygnatury dostępu współdzielonego zwrócony przez usługę IoT Hub w poprzedniej sekcji. Nagłówek x-ms-blob-type wskazuje, że to żądanie dotyczy blokowego obiektu blob. Jeśli żądanie zakończy się pomyślnie, usługa Azure Storage zwróci wartość 201 Created.

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

Praca z interfejsami API usługi Azure Storage wykracza poza zakres tego artykułu. Oprócz interfejsów API REST usługi Azure Blob Storage połączonych wcześniej w tej sekcji możesz zapoznać się z następującą dokumentacją, aby ułatwić rozpoczęcie pracy:

  • Aby dowiedzieć się więcej na temat pracy z obiektami blob w usłudze Azure Storage, zobacz dokumentację usługi Azure Blob Storage.

  • Aby uzyskać informacje na temat używania zestawów SDK klienta usługi Azure Storage do przekazywania obiektów blob, zobacz Dokumentacja interfejsu API usługi Azure Blob Storage.

Urządzenie: powiadamianie centrum IoT Hub o ukończonym przekazaniu pliku

Urządzenie wywołuje interfejs API REST przekazywania pliku aktualizacji lub równoważny interfejs API w jednym z zestawów SDK urządzenia po zakończeniu przekazywania pliku. Urządzenie powinno zaktualizować stan przekazywania pliku za pomocą usługi IoT Hub niezależnie od tego, czy przekazywanie zakończy się powodzeniem, czy niepowodzeniem.

Obsługiwane protokoły: HTTPS
Punkt końcowy: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Metoda: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
Właściwości opis
correlationId Identyfikator korelacji odebrany w początkowym żądaniu identyfikatora URI sygnatury dostępu współdzielonego.
isSuccess Wartość logiczna wskazująca, czy przekazywanie pliku zakończyło się pomyślnie.
statusCode Liczba całkowita reprezentująca kod stanu przekazywania pliku. Zazwyczaj trzy cyfry; na przykład 200 lub 201.
Statusdescription Opis stanu przekazywania pliku.

Po odebraniu pełnego powiadomienia o przekazaniu pliku z urządzenia usługa IoT Hub:

  • Wyzwala powiadomienie o przekazaniu pliku do usług zaplecza, jeśli skonfigurowano powiadomienia dotyczące przekazywania plików.

  • Zwalnia zasoby skojarzone z przekazywaniem pliku. Jeśli usługa IoT Hub nie otrzyma powiadomienia, zachowa zasoby do momentu wygaśnięcia (TTL) identyfikatora URI sygnatury dostępu współdzielonego skojarzonego z przekazywaniem.

Usługa: powiadomienia o przekazaniu plików

Jeśli powiadomienia o przekazaniu plików są włączone w centrum IoT Hub, centrum generuje komunikat powiadomienia dla usług zaplecza po otrzymaniu powiadomienia z urządzenia, które zostało ukończone. Usługa IoT Hub dostarcza te powiadomienia dotyczące przekazywania plików za pośrednictwem punktu końcowego dostępnego dla usługi. Semantyka odbierania powiadomień o przekazaniu plików jest taka sama jak w przypadku komunikatów z chmury do urządzenia i ma ten sam cykl życia komunikatu. Zestawy SDK usługi udostępniają interfejsy API do obsługi powiadomień dotyczących przekazywania plików.

Obsługiwane protokoły AMQP, AMQP-WS
Punkt końcowy: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Metoda GET

Każdy komunikat pobrany z punktu końcowego powiadomienia przekazywania pliku jest rekordem JSON:

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}
Właściwości opis
enqueuedTimeUtc Sygnatura czasowa wskazująca, kiedy powiadomienie zostało utworzone.
deviceId Identyfikator urządzenia, który przesłał plik.
Identyfikator blobUri Identyfikator URI przekazanego pliku.
BlobName Nazwa przekazanego pliku. Nazwa ma następujący format: {device ID of the device}/{name of the blob}
lastUpdatedTime Sygnatura czasowa wskazująca, kiedy plik został ostatnio zaktualizowany.
blobSizeInBytes Liczba całkowita reprezentująca rozmiar przekazanego pliku w bajtach.

Usługi mogą używać powiadomień do zarządzania przekazywaniem. Mogą na przykład wyzwolić własne przetwarzanie danych obiektu blob, wyzwolić przetwarzanie danych obiektu blob przy użyciu innych usług platformy Azure lub zarejestrować powiadomienie o przekazaniu pliku w celu późniejszego przejrzenia.

Następne kroki