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

Artykuł
04/07/2024

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 Node.js.

Artykuły Wysyłanie danych telemetrycznych z urządzenia do centrum IoT Hub i Wysyłanie komunikatów z chmury do urządzenia przy użyciu usługi IoT Hub pokazują podstawowe funkcje obsługi komunikatów między urządzeniami i chmurą w usłudze IoT Hub. Samouczek Konfigurowanie routingu komunikatów za pomocą usługi IoT Hub przedstawia sposób niezawodnego przechowywania komunikatów z urządzenia do chmury w usłudze Microsoft Azure Blob Storage. 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 potrzebujesz plików 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 Node.js:

FileUpload.js, który przekazuje plik do magazynu przy użyciu identyfikatora URI sygnatury dostępu współdzielonego dostarczonego przez centrum IoT.
FileUploadNotification.js, który odbiera powiadomienia o przekazaniu plików z centrum IoT Hub.

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.
Node.js w wersji 10.0.x lub nowszej. Zalecana jest wersja LTS. Możesz pobrać Node.js z nodejs.org.
Port 8883 powinien być otwarty w zaporze. Przykład urządzenia w tym artykule używa 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:

W obszarze Ustawienia centrum wybierz pozycję Przekazywanie pliku w okienku po lewej stronie centrum IoT Hub.
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 .
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.
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.

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 tej sekcji utworzysz aplikację urządzenia w celu przekazania pliku do centrum IoT Hub. Kod jest oparty na kodzie dostępnym w przykładzie upload_to_blob_advanced.js w przykładzie zestawu SDK usługi Azure IoT Node.js SDK.

Utwórz pusty folder o nazwie fileupload. W folderze fileupload utwórz plik package.json, uruchamiając następujące polecenie w wierszu polecenia. Zaakceptuj wszystkie ustawienia domyślne:
```
npm init
```
W wierszu polecenia w folderze fileupload uruchom następujące polecenie, aby zainstalować zestaw SDK urządzenia azure-iot-device , azure-iot-device-mqtt oraz pakiety @azure/storage-blob :
```
npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save
```

Za pomocą edytora tekstów utwórz plik FileUpload.js w folderze fileupload i skopiuj do niego następujący kod.

'use strict';

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

const {
  AnonymousCredential,
  BlockBlobClient,
  newPipeline
} = require('@azure/storage-blob');

// make sure you set these environment variables prior to running the sample.
const deviceConnectionString = process.env.DEVICE_CONNECTION_STRING;
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);

async function uploadToBlob(localFilePath, client) {
  const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
  if (!blobInfo) {
    throw new errors.ArgumentError('Invalid upload parameters');
  }

  const pipeline = newPipeline(new AnonymousCredential(), {
    retryOptions: { maxTries: 4 },
    telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
    keepAliveOptions: { enable: false }
  });

  // Construct the blob URL to construct the blob client for file uploads
  const { hostName, containerName, blobName, sasToken } = blobInfo;
  const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

  // Create the BlockBlobClient for file upload to the Blob Storage Blob
  const blobClient = new BlockBlobClient(blobUrl, pipeline);

  // Setup blank status notification arguments to be filled in on success/failure
  let isSuccess;
  let statusCode;
  let statusDescription;

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT Hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

  await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);
}

// Create a client device from the connection string and upload the local file to blob storage.
const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

Zapisz i zamknij plik FileUpload.js .
Skopiuj plik obrazu do fileupload folderu i nadaj mu nazwę, taką jak myimage.png.
Dodaj zmienne środowiskowe dla urządzenia parametry połączenia i ścieżkę do pliku, który chcesz przekazać. Urządzenie zostało parametry połączenia po zarejestrowaniu urządzenia w centrum IoT.
- Dla systemu Windows:
```
set DEVICE_CONNECTION_STRING={your device connection string}
set PATH_TO_FILE={your image filepath}
```
- W przypadku systemu Linux/Bash:
```
export DEVICE_CONNECTION_STRING="{your device connection string}"
export PATH_TO_FILE="{your image filepath}"
```

Pobieranie parametry połączenia centrum IoT

W tym artykule utworzysz usługę zaplecza, która będzie odbierać komunikaty powiadomień o przekazaniu plików z utworzonego 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:

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.
W okienku po lewej stronie centrum IoT hub wybierz pozycję Zasady dostępu współdzielonego.
Z listy zasad wybierz zasady usługi .
Skopiuj parametry połączenia podstawową i zapisz wartość.

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ą Node.js, która odbiera komunikaty powiadomień o przekazaniu plików z usługi IoT Hub.

Utwórz pusty folder o nazwie fileuploadnotification. W folderze fileuploadnotification utwórz plik package.json, uruchamiając następujące polecenie w wierszu polecenia. Zaakceptuj wszystkie ustawienia domyślne:
```
npm init
```
W wierszu polecenia w folderze fileuploadnotification uruchom następujące polecenie, aby zainstalować pakiet zestawu SDK azure-iothub :
```
npm install azure-iothub --save
```
Za pomocą edytora tekstów utwórz plik FileUploadNotification.js w folderze fileuploadnotification .
Dodaj następujące require instrukcje na początku pliku FileUploadNotification.js :
```
'use strict';

const Client = require('azure-iothub').Client;
```

Przeczytaj parametry połączenia centrum IoT w środowisku:

const connectionString = process.env.IOT_HUB_CONNECTION_STRING;

Dodaj następujący kod, aby utworzyć klienta usługi na podstawie parametry połączenia:
```
const serviceClient = Client.fromConnectionString(connectionString);
```

Otwórz klienta i użyj funkcji getFileNotificationReceiver , aby otrzymywać aktualizacje stanu.

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
      if (err) {
        console.error('error getting the file notification receiver: ' + err.toString());
      } else {
        receiver.on('message', function (msg) {
          console.log('File upload from device:')
          console.log(msg.getData().toString('utf-8'));
          receiver.complete(msg, function (err) {
            if (err) {
              console.error('Could not finish the upload: ' + err.message);
            } else {
              console.log('Upload complete');
            }
          });
        });
      }
    });
  }
});

Uwaga

Jeśli chcesz otrzymywać powiadomienia o rozłączeniu podczas nasłuchiwania powiadomień przekazywania plików, musisz zarejestrować 'error' się przy użyciu polecenia receiver.on. Aby nadal otrzymywać powiadomienia o przekazaniu plików, należy ponownie wykonać pracę z usługą serviceClient.open IoT Hub przy użyciu metody .

Zapisz i zamknij plik FileUploadNotification.js .
Dodaj zmienną środowiskową dla parametry połączenia usługi IoT Hub. Skopiowano ten ciąg wcześniej w sekcji Pobieranie parametry połączenia centrum IoT Hub.
- Dla systemu Windows:
```
set IOT_HUB_CONNECTION_STRING={your iot hub connection string}
```
- W przypadku systemu Linux/Bash:
```
export IOT_HUB_CONNECTION_STRING="{your iot hub connection string}"
```

Uruchamianie aplikacji

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

W wierszu polecenia w folderze fileuploadnotification uruchom następujące polecenie:

node FileUploadNotification.js

W wierszu polecenia w folderze fileupload uruchom następujące polecenie:

node FileUpload.js

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

uploadStreamToBlockBlob success
notifyBlobUploadStatus success

Następujące przykładowe dane wyjściowe pochodzą z aplikacji FileUploadNotification po zakończeniu przekazywania:

Service client connected
File upload from device:
{"deviceId":"myDeviceId","blobUri":"https://{your storage account name}.blob.core.windows.net/device-upload-container/myDeviceId/image.png","blobName":"myDeviceId/image.png","lastUpdatedTime":"2021-07-23T23:27:06+00:00","blobSizeInBytes":26214,"enqueuedTimeUtc":"2021-07-23T23:27:07.2580791Z"}

Weryfikowanie przekazywania pliku

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

Przejdź do konta magazynu w witrynie Azure Portal.
W lewym okienku konta magazynu wybierz pozycję Kontenery.
Wybierz kontener, do którego został przekazany plik.
Wybierz folder o nazwie po urządzeniu.
Wybierz obiekt blob, do którego został przekazany plik. W tym artykule jest to obiekt blob o takiej samej nazwie jak plik.
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: