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

Artykuł
12/19/2024

W tym artykule pokazano, jak:

Użyj możliwości przekazywania plików usługi IoT Hub, aby przekazać plik do usługi Azure Blob Storage przy użyciu zestawów SDK urządzeń i usług Azure IoT.
Powiadom usługę IoT Hub o pomyślnym przekazaniu pliku i utworzeniu usługi zaplecza w celu odbierania powiadomień o przekazaniu plików z usługi IoT Hub przy użyciu zestawów SDK usługi Azure IoT.

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. Możliwości przekazywania plików w usłudze IoT Hub umożliwiają przenoszenie dużych lub złożonych danych do chmury. 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ć.

Ten artykuł ma na celu uzupełnienie przykładów zestawu SDK z możliwością uruchamiania, do których odwołuje się ten artykuł.

Aby uzyskać więcej informacji, zobacz:

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. Niektóre wywołania zestawu SDK wymagają parametry połączenia podstawowej usługi IoT Hub, dlatego zanotuj parametry połączenia.
Zarejestrowane urządzenie. Niektóre wywołania zestawu SDK wymagają parametry połączenia podstawowego urządzenia, dlatego zanotuj parametry połączenia.
Uprawnienie IoT Hub Service Connect — aby otrzymywać komunikaty powiadomień o przekazaniu plików, usługa zaplecza musi mieć uprawnienie Service Connect . 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ć więcej informacji, zobacz Nawiązywanie połączenia z centrum IoT Hub.
Skonfiguruj przekazywanie plików w centrum IoT, łącząc konto usługi Azure Storage i kontener usługi Azure Blob Storage. Można je skonfigurować przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell.

Omówienie

Ten instrukcje zawiera dwie sekcje:

Przekazywanie pliku z aplikacji urządzenia
Odbieranie powiadomienia o przekazaniu pliku w aplikacji zaplecza

Przekazywanie pliku z aplikacji urządzenia

W tej sekcji opisano sposób przekazywania pliku z urządzenia do centrum IoT przy użyciu klasy DeviceClient w zestawie SDK usługi Azure IoT dla platformy .NET.

Wykonaj tę procedurę, aby przekazać plik z urządzenia do centrum IoT:

Nawiązywanie połączenia z centrum IoT
Uzyskiwanie identyfikatora URI sygnatury dostępu współdzielonego z centrum IoT Hub
Przekazywanie pliku do usługi Azure Storage
Powiadamianie centrum IoT o stanie przekazywania pliku

Łączenie urządzenia z usługą IoT Hub

Aplikacja urządzenia może uwierzytelniać się w usłudze IoT Hub przy użyciu następujących metod:

Certyfikat X.509
Klucz dostępu współdzielonego

Uwierzytelnianie przy użyciu certyfikatu X.509

Aby połączyć urządzenie z usługą IoT Hub przy użyciu certyfikatu X.509:

Użyj elementu DeviceAuthenticationWithX509Certificate , aby utworzyć obiekt zawierający informacje o urządzeniu i certyfikacie. DeviceAuthenticationWithX509Certificate parametr jest przekazywany jako drugi parametr do DeviceClient.Create (krok 2).
Użyj elementu DeviceClient.Create , aby połączyć urządzenie z usługą IoT Hub przy użyciu certyfikatu X.509.

W tym przykładzie informacje o urządzeniu i certyfikacie są wypełniane w obiekcie przekazywanym auth DeviceAuthenticationWithX509Certificate do DeviceClient.Createobiektu .

W tym przykładzie przedstawiono wartości parametrów wejściowych certyfikatu jako zmienne lokalne w celu zapewnienia przejrzystości. W systemie produkcyjnym przechowuj poufne parametry wejściowe w zmiennych środowiskowych lub innej bezpieczniejszej lokalizacji przechowywania. Na przykład użyj polecenia Environment.GetEnvironmentVariable("HOSTNAME") , aby odczytać zmienną środowiskową nazwy hosta.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

Aby uzyskać więcej informacji na temat uwierzytelniania certyfikatów, zobacz:

Przykłady kodu

Aby zapoznać się z przykładami pracy uwierzytelniania certyfikatu X.509 urządzenia, zobacz:

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Wywołaj metodę CreateFromConnectionString , aby nawiązać połączenie z urządzeniem. Przekaż podstawowe parametry połączenia urządzenia.

AMQP jest domyślnym protokołem transportu.

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

Uzyskiwanie identyfikatora URI sygnatury dostępu współdzielonego z centrum IoT Hub

Wywołaj metodę GetFileUploadSasUriAsync , aby uzyskać szczegóły przekazywania pliku. Identyfikator URI sygnatury dostępu współdzielonego jest używany w następnym kroku do przekazywania pliku z urządzenia do usługi Blob Storage.

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

Przekazywanie pliku do usługi Azure Storage

Aby przekazać plik do usługi Azure Storage:

Utwórz obiekt blockBlobClient, przekazując identyfikator URI przekazywania pliku.
Użyj metody UploadAsync, aby przekazać plik do usługi Blob Storage, przekazując identyfikator URI sygnatury dostępu współdzielonego. Opcjonalnie możesz dodać opcje przekazywania obiektów blob i parametry tokenu anulowania.

Klient usługi Azure Blob zawsze używa protokołu HTTPS do przekazania pliku do usługi Azure Storage.

W tym przykładzie przekazano identyfikator URI sygnatury dostępu współdzielonego w BlockBlobClient celu utworzenia klienta blokowego obiektu blob usługi Azure Storage i przekazania pliku:

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

Powiadamianie centrum IoT o stanie przekazywania pliku

Użyj metody CompleteFileUploadAsync , aby powiadomić centrum IoT Hub o zakończeniu przekazywania przez klienta urządzenia, przekazując obiekt FileUploadCompletionNotification . Flaga IsSuccess wskazuje, czy przekazywanie zakończyło się pomyślnie. Po powiadomieniu centrum IoT będzie zwalniać zasoby skojarzone z przekazywaniem (identyfikator URI sygnatury dostępu współdzielonego).

Jeśli powiadomienia o przekazaniu plików są włączone, usługa IoT Hub wysyła komunikat powiadomienia o przekazaniu pliku do usług zaplecza skonfigurowanych na potrzeby powiadamiania o przekazaniu plików.

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);

Przykład przekazywania pliku zestawu SDK

Zestaw SDK zawiera ten przykład przekazywania plików.

Odbieranie powiadomienia o przekazaniu pliku w aplikacji zaplecza

Możesz utworzyć usługę zaplecza, aby odbierać komunikaty powiadomień o przekazaniu plików z centrum IoT Hub.

Klasa ServiceClient zawiera metody, których usługi mogą używać do odbierania powiadomień o przekazaniu plików.

Dodawanie pakietu NuGet usługi

Aplikacje usługi zaplecza wymagają pakietu NuGet Microsoft.Azure.Devices .

Nawiązywanie połączenia z centrum IoT

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

Zasady dostępu współdzielonego
Microsoft Entra

Ważne

Ten artykuł zawiera kroki nawiązywania połączenia z usługą przy użyciu sygnatury dostępu współdzielonego. Ta metoda uwierzytelniania jest wygodna do testowania i oceny, ale uwierzytelnianie w usłudze przy użyciu identyfikatora Entra firmy Microsoft lub tożsamości zarządzanych jest bardziej bezpieczne. Aby dowiedzieć się więcej, zobacz Security best practices Cloud security (Najlepsze rozwiązania > dotyczące zabezpieczeń w chmurze).

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Połącz aplikację zaplecza z urządzeniem przy użyciu polecenia CreateFromConnectionString. Aplikacja potrzebuje uprawnień połączenia z usługą. Podaj te zasady dostępu współdzielonego parametry połączenia jako parametr do fromConnectionString. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

Na przykład:

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{Shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aplikacja zaplecza korzystająca z usługi Microsoft Entra musi pomyślnie uwierzytelnić się i uzyskać poświadczenia tokenu zabezpieczającego przed nawiązaniem połączenia z usługą IoT Hub. Ten token jest przekazywany do metody połączenia usługi IoT Hub. Aby uzyskać ogólne informacje na temat konfigurowania i używania usługi Microsoft Entra dla usługi IoT Hub, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu identyfikatora Microsoft Entra.

Konfigurowanie aplikacji Microsoft Entra

Musisz skonfigurować aplikację Firmy Microsoft Entra skonfigurowaną dla preferowanych poświadczeń uwierzytelniania. Aplikacja zawiera parametry, takie jak klucz tajny klienta, który jest używany przez aplikację zaplecza do uwierzytelniania. Dostępne konfiguracje uwierzytelniania aplikacji to:

Klucz tajny klienta
Certyfikat
Poświadczenia tożsamości federacyjnej

Aplikacje Firmy Microsoft Entra mogą wymagać określonych uprawnień roli w zależności od wykonywanych operacji. Na przykład współautor bliźniaczej reprezentacji usługi IoT Hub jest wymagany do włączenia dostępu do odczytu i zapisu na urządzeniu usługi IoT Hub i bliźniaczych reprezentacjach modułów. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do usługi IoT Hub przy użyciu przypisania roli RBAC platformy Azure.

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Najprostszym sposobem użycia usługi Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie wartości DefaultAzureCredential, ale zaleca się użycie innej metody w środowisku produkcyjnym, w tym określonej TokenCredential lub pared-down ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu i DefaultAzureCredential klucz tajny klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z usługi , zobacz Wskazówki dotyczące użycia DefaultAzureCredentialdla elementu DefaultAzureCredential.

DefaultAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczeń na podstawie środowiska, w których jest wykonywany. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.

Firma Microsoft Entra wymaga tych pakietów NuGet i odpowiednich using instrukcji:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

W tym przykładzie klucz tajny klienta rejestracji aplikacji Firmy Microsoft, identyfikator klienta i identyfikator dzierżawy są dodawane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia firmy Microsoft Entra jest poświadczenie tokenu zabezpieczającego przekazywane do metody połączenia usługi IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Wynikowy tokenCredential można następnie przekazać do metody łączenia z usługą IoT Hub dla dowolnego klienta zestawu SDK, który akceptuje poświadczenia firmy Microsoft Entra:

W tym przykładzie TokenCredential parametr jest przekazywany do , aby ServiceClient.Create utworzyć obiekt połączenia ServiceClient .

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

W tym przykładzie TokenCredential parametr jest przekazywany do RegistryManager.Create , aby utworzyć obiekt RegistryManager .

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Przykład kodu

Aby zapoznać się z roboczym przykładem uwierzytelniania usługi Entra firmy Microsoft, zobacz Przykład uwierzytelniania opartego na rolach.

Otrzymywanie powiadomienia o przekazaniu pliku

Aby otrzymać powiadomienie o przekazaniu pliku:

Utwórz element CancellationToken.
Wywołaj metodę GetFileNotificationReceiver , aby utworzyć odbiornik powiadomień.
Użyj pętli z funkcją ReceiveAsync , aby poczekać na powiadomienie o przekazaniu pliku.

Na przykład:

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    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);
}

Przykład przekazywania pliku zestawu SDK dla odbiorcy

Zestaw SDK zawiera ten przykład odbiorcy przekazywania plików.

Omówienie

Ten instrukcje zawiera dwie sekcje:

Przekazywanie pliku z aplikacji urządzenia
Odbieranie powiadomienia o przekazaniu pliku w aplikacji zaplecza

Przekazywanie pliku z aplikacji urządzenia

W tej sekcji opisano sposób przekazywania pliku z urządzenia do centrum IoT przy użyciu klasy DeviceClient z zestawu SDK usługi Azure IoT dla języka Java.

Wykonaj tę procedurę, aby przekazać plik z urządzenia do centrum IoT:

Łączenie urządzenia z usługą IoT Hub
Uzyskiwanie identyfikatora URI sygnatury dostępu współdzielonego z centrum IoT Hub
Przekazywanie pliku do usługi Azure Storage
Wysyłanie powiadomienia o stanie przekazywania pliku do centrum IoT Hub

Łączenie urządzenia z usługą IoT Hub

Aplikacja urządzenia może uwierzytelniać się w usłudze IoT Hub przy użyciu następujących metod:

Certyfikat X.509
Klucz dostępu współdzielonego

Uwierzytelnianie przy użyciu certyfikatu X.509

Aby połączyć urządzenie z usługą IoT Hub przy użyciu certyfikatu X.509:

Skompiluj obiekt SSLContext przy użyciu polecenia buildSSLContext.
SSLContext Dodaj informacje do obiektu ClientOptions.
Wywołaj element DeviceClient przy użyciu informacji, ClientOptions aby utworzyć połączenie z urządzeniem do usługi IoT Hub.

W tym przykładzie przedstawiono wartości parametrów wejściowych certyfikatu jako zmienne lokalne w celu zapewnienia przejrzystości. W systemie produkcyjnym przechowuj poufne parametry wejściowe w zmiennych środowiskowych lub innej bezpieczniejszej lokalizacji przechowywania. Na przykład użyj polecenia Environment.GetEnvironmentVariable("PUBLICKEY") , aby odczytać zmienną środowiskową ciągu certyfikatu klucza publicznego.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

Aby uzyskać więcej informacji na temat uwierzytelniania certyfikatów, zobacz:

Przykłady kodu

Aby zapoznać się z przykładami pracy uwierzytelniania certyfikatu X.509 urządzenia, zobacz:

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Operacje przekazywania plików zawsze używają protokołu HTTPS, ale element DeviceClient może definiować element IotHubClientProtocol dla innych usług, takich jak telemetria, metoda urządzenia i bliźniacze reprezentacje urządzenia.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

DeviceClient Utwórz wystąpienie elementu , aby nawiązać połączenie z urządzeniem przy użyciu podstawowego parametry połączenia urządzenia.

String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Uzyskiwanie identyfikatora URI sygnatury dostępu współdzielonego z centrum IoT Hub

Wywołaj metodę getFileUploadSasUri, aby uzyskać obiekt FileUploadSasUriResponse.

FileUploadSasUriResponse zawiera te metody i wartości zwracane. Wartości zwracane można przekazać do metod przekazywania plików.

Method	Wartość zwracana
`getCorrelationId()`	Identyfikator korelacji
`getContainerName()`	Nazwa kontenera
`getBlobName()`	Nazwa obiektu blob
`getBlobUri()`	Blob URI

Na przykład:

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

Przekazywanie pliku do usługi Azure Storage

Przekaż punkt końcowy identyfikatora URI obiektu blob do obiektu BlobClientBuilder.buildclient , aby utworzyć obiekt BlobClient .

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

Wywołaj metodę uploadFromFile , aby przekazać plik do usługi Blob Storage.

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

Wysyłanie powiadomienia o stanie przekazywania pliku do centrum IoT Hub

Wyślij powiadomienie o stanie przekazywania do centrum IoT Po próbie przekazania pliku.

Utwórz obiekt FileUploadCompletionNotification. Przekaż stan powodzenia correlationId przekazywania plików i isSuccess . isSuccess true Przekaż wartość, gdy przekazywanie pliku zakończyło się pomyślnie, false jeśli nie.

FileUploadCompletionNotification musi być wywoływana nawet wtedy, gdy przekazywanie pliku zakończy się niepowodzeniem. Usługa IoT Hub ma stałą liczbę identyfikatorów URI sygnatur dostępu współdzielonego, która może być aktywna w danym momencie. Po zakończeniu przekazywania pliku należy zwolnić identyfikator URI sygnatury dostępu współdzielonego, aby można było wygenerować inny identyfikator URI sygnatury dostępu współdzielonego. Jeśli identyfikator URI sygnatury dostępu współdzielonego nie jest zwalniany za pośrednictwem tego interfejsu API, zwalnia się w końcu na podstawie tego, jak długo identyfikatory URI sygnatur dostępu współdzielonego są skonfigurowane do działania w centrum IoT.

Ten przykład przekazuje stan powodzenia.

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

Zamykanie klienta

Zwolnij client zasoby.

client.closeNow();

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób odbierania powiadomienia o przekazaniu pliku w aplikacji zaplecza.

Klasa ServiceClient zawiera metody, których usługi mogą używać do odbierania powiadomień o przekazaniu plików.

Dodawanie instrukcji importu

Dodaj te instrukcje importowania , aby użyć zestawu SDK java usługi Azure IoT i procedury obsługi wyjątków.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Nawiązywanie połączenia z usługą IoT Hub

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

Zasady dostępu współdzielonego
Microsoft Entra

Ważne

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Definiowanie protokołu połączenia

Użyj elementu IotHubServiceClientProtocol , aby zdefiniować protokół warstwy aplikacji używany przez klienta usługi do komunikowania się z usługą IoT Hub.

IotHubServiceClientProtocol akceptuje tylko wyliczenie AMQPS lub AMQPS_WS .

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Tworzenie obiektu ServiceClient

Utwórz obiekt ServiceClient, podając parametry połączenia i protokół usługi Iot Hub.

Aby przekazać plik na urządzeniu do usługi IoT Hub, twoja usługa wymaga uprawnień 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.

Jako parametr ServiceClient konstruktora podaj zasady dostępu współdzielonego usługi . Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
private static final ServiceClient serviceClient (iotHubConnectionString, protocol);

Otwieranie połączenia między aplikacją a usługą IoT Hub

Otwórz połączenie nadawcy protokołu AMQP. Ta metoda tworzy połączenie między aplikacją a usługą IoT Hub.

serviceClient.open();

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aby zapoznać się z omówieniem uwierzytelniania zestawu Java SDK, zobacz Uwierzytelnianie platformy Azure przy użyciu języka Java i tożsamości platformy Azure.

Dla uproszczenia ta sekcja koncentruje się na opisywaniu uwierzytelniania przy użyciu klucza tajnego klienta.

Konfigurowanie aplikacji Microsoft Entra

Klucz tajny klienta
Certyfikat
Poświadczenia tożsamości federacyjnej

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Najprostszym sposobem użycia usługi Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie wartości DefaultAzureCredential, ale zaleca się użycie innej metody w środowisku produkcyjnym, w tym określonej TokenCredential lub pared-down ChainedTokenCredential. Aby uzyskać więcej informacji na temat zalet i wad używania programu DefaultAzureCredential, zobacz Łańcuchy poświadczeń w bibliotece klienta tożsamości platformy Azure dla języka Java.

Ustawienie domyślneAzureCredential obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczeń na podstawie środowiska, w których jest wykonywany. Próbuje użyć wielu typów poświadczeń w kolejności, dopóki nie znajdzie działającego poświadczenia.

Możesz uwierzytelnić poświadczenia aplikacji Microsoft Entra przy użyciu polecenia DefaultAzureCredentialBuilder. Zapisz parametry połączenia, takie jak identyfikator dzierżawy klucza tajnego klienta, identyfikator klienta i wartości wpisów tajnych klienta jako zmienne środowiskowe. Po utworzeniu TokenCredential elementu przekaż go do elementu ServiceClient lub innego konstruktora jako parametru "credential".

W tym przykładzie DefaultAzureCredentialBuilder próbuje uwierzytelnić połączenie z listy opisanej w artykule DefaultAzureCredential. Wynikiem pomyślnego uwierzytelnienia firmy Microsoft Entra jest poświadczenie tokenu zabezpieczającego przekazywane do konstruktora takiego jak ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Uwierzytelnianie przy użyciu elementu ClientSecretCredentialBuilder

Aby utworzyć poświadczenia przy użyciu informacji o kluczu tajnym klienta, możesz użyć elementu ClientSecretCredentialBuilder . Jeśli ta metoda powiedzie się, zwraca wartość TokenCredential , która może zostać przekazana do klasy ServiceClient lub innego konstruktora jako parametru "credential".

W tym przykładzie do zmiennych środowiskowych dodano wartości klucza tajnego klienta rejestracji aplikacji Firmy Microsoft, identyfikatora klienta i identyfikatora dzierżawy. Te zmienne środowiskowe są używane przez ClientSecretCredentialBuilder program do kompilowania poświadczeń.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Inne klasy uwierzytelniania

Zestaw JAVA SDK zawiera również te klasy, które uwierzytelniają aplikację zaplecza za pomocą usługi Microsoft Entra:

Przykłady kodu

Aby zapoznać się z roboczymi przykładami uwierzytelniania usługi Entra firmy Microsoft, zobacz Przykład uwierzytelniania opartego na rolach.

Sprawdzanie stanu przekazywania pliku

Aby sprawdzić stan przekazywania pliku:

Utwórz obiekt getFileUploadNotificationReceiver.
Użyj polecenia open , aby nawiązać połączenie z centrum IoT Hub.
Wywołaj metodę odbierania , aby sprawdzić stan przekazywania pliku. Ta metoda zwraca obiekt fileUploadNotification . Jeśli otrzymasz powiadomienie o przekazaniu, możesz wyświetlić pola stanu przekazywania przy użyciu metod fileUploadNotification .

Na przykład:

FileUploadNotificationReceiver receiver = serviceClient.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

Przykłady przekazywania plików zestawu SDK

Istnieją dwa przykłady przekazywania plików Java.

Instalowanie pakietów

Przed wywołaniem dowolnego powiązanego kodu należy zainstalować bibliotekę azure-iot-device.

pip install azure-iot-device

Pakiet azure.storage.blob służy do przekazywania pliku.

pip install azure.storage.blob

Przekazywanie pliku z aplikacji urządzenia

W tej sekcji opisano sposób przekazywania pliku z urządzenia do centrum IoT przy użyciu klasy IoTHubDeviceClient z zestawu SDK usługi Azure IoT dla języka Python.

Importowanie bibliotek

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

Łączenie urządzenia z usługą IoT Hub

Aplikacja urządzenia może uwierzytelniać się w usłudze IoT Hub przy użyciu następujących metod:

Certyfikat X.509
Klucz dostępu współdzielonego

Uwierzytelnianie przy użyciu certyfikatu X.509

Aby połączyć urządzenie z usługą IoT Hub przy użyciu certyfikatu X.509:

Użyj create_from_x509_certificate , aby dodać parametry certyfikatu X.509
Wywołanie połączenia w celu nawiązania połączenia z klientem urządzenia

W tym przykładzie przedstawiono wartości parametrów wejściowych certyfikatu jako zmienne lokalne w celu zapewnienia przejrzystości. W systemie produkcyjnym przechowuj poufne parametry wejściowe w zmiennych środowiskowych lub innej bezpieczniejszej lokalizacji przechowywania. Na przykład użyj polecenia os.getenv("HOSTNAME") , aby odczytać zmienną środowiskową nazwy hosta.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

Aby uzyskać więcej informacji na temat uwierzytelniania certyfikatów, zobacz:

Przykłady kodu

Aby zapoznać się z przykładami pracy uwierzytelniania certyfikatu X.509 urządzenia, zobacz przykłady, których nazwy plików kończą się na x509 w scenariuszach centrum asynchronicznego.

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Aby połączyć urządzenie z usługą IoT Hub:

Wywołaj create_from_connection_string, aby dodać parametry połączenia podstawowego urządzenia.
Wywołaj połączenie , aby nawiązać połączenie z klientem urządzenia.

Na przykład:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Uzyskiwanie informacji o usłudze Blob Storage

Wywołaj get_storage_info_for_blob , aby uzyskać informacje z centrum IoT Hub o połączonym koncie usługi Azure Storage. Te informacje obejmują nazwę hosta, nazwę kontenera, nazwę obiektu blob i token SAS. Metoda get_storage_info_for_blob zwraca również metodę correlation_id, która jest używana w metodzie notify_blob_upload_status . Jest correlation_id to sposób oznaczania obiektów blob, nad którymi pracujesz.

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

Przekazywanie pliku do usługi Blob Storage

Aby przekazać plik do usługi Blob Storage:

Użyj from_blob_url , aby utworzyć obiekt BlobClient na podstawie adresu URL obiektu blob.
Wywołaj upload_blob , aby przekazać plik do usługi Blob Storage.

Ten przykład analizuje blob_info strukturę w celu utworzenia adresu URL używanego do zainicjowania obiektu BlobClient. Następnie wywołuje metodę upload_blob przekazywania pliku do usługi Blob Storage.

try:
    sas_url = "https://{}/{}/{}{}".format(
        blob_info["hostName"],
        blob_info["containerName"],
        blob_info["blobName"],
        blob_info["sasToken"]
    )

    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

    # Upload the specified file
    with BlobClient.from_blob_url(sas_url) as blob_client:
        with open(file_name, "rb") as f:
            result = blob_client.upload_blob(f, overwrite=True)
            return (True, result)

except FileNotFoundError as ex:
    # catch file not found and add an HTTP status code to return in notification to IoT hub
    ex.status_code = 404
    return (False, ex)

except AzureError as ex:
    # catch Azure errors that might result from the upload operation
    return (False, ex)

Powiadamianie centrum IoT o stanie przekazywania

Użyj notify_blob_upload_status , aby powiadomić centrum IoT o stanie operacji usługi Blob Storage. Przekaż metodę uzyskaną correlation_id przez metodę get_storage_info_for_blob . Element correlation_id jest używany przez centrum IoT do powiadamiania dowolnej usługi, która może nasłuchiwać powiadomienia dotyczące stanu zadania przekazywania plików.

Ten przykład powiadamia centrum IoT o pomyślnym przekazaniu pliku:

device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)

Zamykanie klienta urządzenia

Zamknij klienta. Po wywołaniu tej metody każda próba dalszego wywołania klienta spowoduje wywołanie błędu ClientError .

device_client.shutdown()

Przykłady przekazywania plików zestawu SDK

Zestaw SDK zawiera dwa przykłady przekazywania plików:

Omówienie

W tym artykule opisano sposób użycia zestawu SDK usługi Azure IoT dla Node.js w celu utworzenia aplikacji urządzenia w celu przekazania pliku i aplikacji usługi zaplecza do odbierania powiadomień o przekazaniu plików.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób przekazywania pliku z urządzenia do centrum IoT przy użyciu pakietu azure-iot-device w zestawie SDK usługi Azure IoT dla Node.js.

Instalowanie pakietów zestawu SDK

Uruchom to polecenie, aby zainstalować zestaw SDK urządzenia azure-iot-device , azure-iot-device-mqtt oraz pakiety @azure/storage-blob na maszynie dewelopera:

npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

Pakiet azure-iot-device zawiera obiekty interfejsu z urządzeniami IoT.

Wykonaj tę procedurę, aby przekazać plik z urządzenia do centrum IoT:

Łączenie urządzenia z usługą IoT Hub
Uzyskiwanie tokenu sygnatury dostępu współdzielonego (SAS) obiektu blob z usługi IoT Hub
Przekazywanie pliku do usługi Azure Storage
Wysyłanie powiadomienia o stanie przekazywania pliku do centrum IoT Hub

Tworzenie modułów

Utwórz moduły klient, protokół, błędy i ścieżki przy użyciu zainstalowanych pakietów.

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

Łączenie urządzenia z usługą IoT Hub

Aplikacja urządzenia może uwierzytelniać się w usłudze IoT Hub przy użyciu następujących metod:

Certyfikat X.509
Klucz dostępu współdzielonego

Uwierzytelnianie przy użyciu certyfikatu X.509

Certyfikat X.509 jest dołączony do transportu połączeń device-to-IoT Hub.

Aby skonfigurować połączenie urządzenia z usługą IoT Hub przy użyciu certyfikatu X.509:

Wywołaj metodę fromConnectionString, aby dodać urządzenie parametry połączenia i typ transportu. Dodaj x509=true do urządzenia parametry połączenia, aby wskazać, że certyfikat został dodany do DeviceClientOptionselementu . Na przykład: HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true.
Skonfiguruj zmienną JSON ze szczegółami certyfikatu i przekaż ją do elementu DeviceClientOptions.
Wywołaj metodę setOptions , aby dodać certyfikat I klucz X.509 (i opcjonalnie hasło) do transportu klienta.
Wywołaj połączenie otwarte , aby otworzyć połączenie z urządzenia do usługi IoT Hub.

W tym przykładzie przedstawiono informacje o konfiguracji certyfikatu w zmiennej JSON. Konfiguracja options certyfikacji jest przekazywana do setOptions programu i połączenie jest otwierane przy użyciu polecenia open.

var options = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }
 client.setOptions(options, callback);
 client.open(connectCallback);

Aby uzyskać więcej informacji na temat uwierzytelniania certyfikatów, zobacz:

Przykład kodu

Aby zapoznać się z roboczym przykładem uwierzytelniania certyfikatu X.509 urządzenia, zobacz Simple sample device X.509 (Proste przykładowe urządzenie X.509).

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Wybieranie protokołu transportowego

Obiekt Client obsługuje następujące protokoły:

Amqp
Http — W przypadku korzystania z Httpusługi Client wystąpienie sprawdza komunikaty z usługi IoT Hub rzadko (co najmniej co 25 minut).
Mqtt
MqttWs
AmqpWs

Zainstaluj wymagane protokoły transportu na maszynie dewelopera.

Na przykład to polecenie instaluje Amqp protokół:

npm install azure-iot-device-amqp --save

Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTPS, zobacz Wskazówki dotyczące komunikacji między chmurą a urządzeniem i Wybieranie protokołu komunikacyjnego.

Tworzenie obiektu klienta

Client Utwórz obiekt przy użyciu zainstalowanego pakietu.

Na przykład:

const Client = require('azure-iot-device').Client;

Tworzenie obiektu protokołu

Utwórz Protocol obiekt przy użyciu zainstalowanego pakietu transportowego.

W tym przykładzie przypisywany jest protokół AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;

Dodawanie protokołu parametry połączenia urządzenia i transportu

Wywołaj metodę fromConnectionString, aby podać parametry połączenia urządzenia:

connStr — parametry połączenia urządzenia.
transportCtor — protokół transportowy.

W tym przykładzie użyto Amqp protokołu transportu:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Otwieranie połączenia z usługą IoT Hub

Użyj metody open, aby otworzyć połączenie między urządzeniem IoT i usługą IoT Hub.

Na przykład:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Uzyskiwanie tokenu SAS z centrum IoT Hub

Użyj polecenia getBlobSharedAccessSignature , aby uzyskać połączony token SAS konta magazynu z centrum IoT.

Na przykład:

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

Przekazywanie pliku do centrum IoT

Aby przekazać plik z urządzenia do usługi IoT Hub:

Tworzenie potoku strumienia
Konstruowanie adresu URL obiektu blob
Tworzenie obiektu BlockBlobClient na potrzeby przekazywania plików do usługi Blob Storage
Wywołaj metodę uploadFile , aby przekazać plik do usługi Blob Storage
Wywołaj metodę notifyBlobUploadStatus , aby powiadomić centrum IoT o pomyślnym lub nieudanym przekazaniu

Na przykład:

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

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

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

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

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

  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);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

Przekazywanie pliku lokalnego do magazynu obiektów blob

Plik lokalny można przekazać do magazynu obiektów blob z komputera

const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

Przykład przekazywania pliku zestawu SDK

Zestaw SDK zawiera zaawansowany przykład przekazywania do obiektów blob.

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób odbierania powiadomień o przekazaniu plików w aplikacji zaplecza.

Klasa ServiceClient zawiera metody, których usługi mogą używać do odbierania powiadomień o przekazaniu plików.

Instalowanie pakietu zestawu SDK usługi

Uruchom to polecenie, aby zainstalować usługę azure-iothub na maszynie deweloperskiej:

npm install azure-iothub --save

Nawiązywanie połączenia z centrum IoT

Usługę zaplecza można połączyć z usługą IoT Hub przy użyciu następujących metod:

Zasady dostępu współdzielonego
Microsoft Entra

Ważne

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Użyj polecenia fromConnectionString , aby nawiązać połączenie z centrum IoT.

Aby przekazać plik z urządzenia, usługa wymaga uprawnień 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.

Jako parametr CreateFromConnectionStringparametru podaj parametry połączenia zasad dostępu współdzielonego usługi. Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Aby zapoznać się z omówieniem uwierzytelniania zestawu NODE.JS SDK, zobacz:

Konfigurowanie aplikacji Microsoft Entra

Klucz tajny klienta
Certyfikat
Poświadczenia tożsamości federacyjnej

Aby uzyskać więcej informacji na temat konfigurowania aplikacji Microsoft Entra, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Najprostszym sposobem użycia usługi Microsoft Entra do uwierzytelniania aplikacji zaplecza jest użycie wartości DefaultAzureCredential, ale zaleca się użycie innej metody w środowisku produkcyjnym, w tym określonej TokenCredential lub pared-down ChainedTokenCredential. Dla uproszczenia w tej sekcji opisano uwierzytelnianie przy użyciu i DefaultAzureCredential klucz tajny klienta. Aby uzyskać więcej informacji na temat zalet i wad korzystania z usługi DefaultAzureCredential, zobacz Łańcuchy poświadczeń w bibliotece klienta tożsamości platformy Azure dla języka JavaScript

Firma Microsoft Entra wymaga tego pakietu:

npm install --save @azure/identity

W tym przykładzie klucz tajny klienta rejestracji aplikacji Firmy Microsoft, identyfikator klienta i identyfikator dzierżawy zostały dodane do zmiennych środowiskowych. Te zmienne środowiskowe są używane przez DefaultAzureCredential program do uwierzytelniania aplikacji. Wynikiem pomyślnego uwierzytelnienia firmy Microsoft Entra jest poświadczenie tokenu zabezpieczającego przekazywane do metody połączenia usługi IoT Hub.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Wynikowy token poświadczeń można następnie przekazać do elementu fromTokenCredential w celu nawiązania połączenia z usługą IoT Hub dla dowolnego klienta zestawu SDK, który akceptuje poświadczenia firmy Microsoft Entra:

fromTokenCredential wymaga dwóch parametrów:

Adres URL usługi platformy Azure — adres URL usługi platformy Azure powinien być w formacie {Your Entra domain URL}.azure-devices.net bez prefiksu https:// . Na przykład MyAzureDomain.azure-devices.net.
Token poświadczeń platformy Azure

W tym przykładzie poświadczenia platformy Azure są uzyskiwane przy użyciu polecenia DefaultAzureCredential. Następnie podano adres URL domeny i poświadczenia platformy Azure w celu Registry.fromTokenCredential utworzenia połączenia z usługą IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Przykłady kodu

Aby zapoznać się z przykładami pracy uwierzytelniania usługi Microsoft Entra, zobacz Przykłady tożsamości platformy Azure.

Tworzenie odbiornika wywołania zwrotnego powiadomienia o przekazaniu pliku

Aby utworzyć odbiornik wywołania zwrotnego powiadomień przekazywania pliku:

Wywołaj metodę getFileNotificationReceiver. Podaj nazwę metody przekazywania pliku wywołania zwrotnego, która jest wywoływana po odebraniu komunikatów powiadomień.
Przetwarzanie powiadomień przekazywania plików w metodzie wywołania zwrotnego.

W tym przykładzie skonfigurowaliśmy odbiornik wywołania zwrotnego receiveFileUploadNotification powiadomień. Odbiorca interpretuje informacje o stanie przekazywania pliku i wyświetla komunikat o stanie do konsoli programu .

//Set up the receiveFileUploadNotification notification message callback receiver
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');
      }
    });
  });
}

Przykład powiadomienia o przekazaniu pliku zestawu SDK

Zestaw SDK zawiera przykład przekazywania plików.

Udostępnij za pośrednictwem

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

Wymagania wstępne

Omówienie

Przekazywanie pliku z aplikacji urządzenia

Łączenie urządzenia z usługą IoT Hub

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykłady kodu

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Uzyskiwanie identyfikatora URI sygnatury dostępu współdzielonego z centrum IoT Hub

Przekazywanie pliku do usługi Azure Storage

Powiadamianie centrum IoT o stanie przekazywania pliku

Przykład przekazywania pliku zestawu SDK

Odbieranie powiadomienia o przekazaniu pliku w aplikacji zaplecza

Dodawanie pakietu NuGet usługi

Nawiązywanie połączenia z centrum IoT

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Przykład kodu

Otrzymywanie powiadomienia o przekazaniu pliku

Przykład przekazywania pliku zestawu SDK dla odbiorcy

Omówienie

Przekazywanie pliku z aplikacji urządzenia

Łączenie urządzenia z usługą IoT Hub

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykłady kodu

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Uzyskiwanie identyfikatora URI sygnatury dostępu współdzielonego z centrum IoT Hub

Przekazywanie pliku do usługi Azure Storage

Wysyłanie powiadomienia o stanie przekazywania pliku do centrum IoT Hub

Zamykanie klienta

Tworzenie aplikacji zaplecza

Dodawanie instrukcji importu

Nawiązywanie połączenia z usługą IoT Hub

Nawiązywanie połączenia przy użyciu zasad dostępu współdzielonego

Definiowanie protokołu połączenia

Tworzenie obiektu ServiceClient

Otwieranie połączenia między aplikacją a usługą IoT Hub

Nawiązywanie połączenia przy użyciu usługi Microsoft Entra

Konfigurowanie aplikacji Microsoft Entra

Uwierzytelnianie przy użyciu wartości DefaultAzureCredential

Uwierzytelnianie przy użyciu elementu ClientSecretCredentialBuilder

Inne klasy uwierzytelniania

Przykłady kodu

Sprawdzanie stanu przekazywania pliku

Przykłady przekazywania plików zestawu SDK

Instalowanie pakietów

Przekazywanie pliku z aplikacji urządzenia

Importowanie bibliotek

Łączenie urządzenia z usługą IoT Hub

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykłady kodu

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Uzyskiwanie informacji o usłudze Blob Storage

Przekazywanie pliku do usługi Blob Storage

Powiadamianie centrum IoT o stanie przekazywania

Zamykanie klienta urządzenia

Przykłady przekazywania plików zestawu SDK

Omówienie

Tworzenie aplikacji urządzenia

Instalowanie pakietów zestawu SDK

Tworzenie modułów

Łączenie urządzenia z usługą IoT Hub

Uwierzytelnianie przy użyciu certyfikatu X.509

Przykład kodu

Uwierzytelnianie przy użyciu klucza dostępu współdzielonego

Wybieranie protokołu transportowego

Tworzenie obiektu klienta

Tworzenie obiektu protokołu

Dodawanie protokołu parametry połączenia urządzenia i transportu

Otwieranie połączenia z usługą IoT Hub

Uzyskiwanie tokenu SAS z centrum IoT Hub

Przekazywanie pliku do centrum IoT

Przekazywanie pliku lokalnego do magazynu obiektów blob

Przykład przekazywania pliku zestawu SDK

Tworzenie aplikacji zaplecza

Instalowanie pakietu zestawu SDK usługi

Nawiązywanie połączenia z centrum IoT