Bestanden uploaden van een apparaat naar de cloud met Azure IoT Hub
Artikel
In dit artikel wordt uitgelegd hoe u het volgende kunt doen:
Gebruik mogelijkheden voor het uploaden van bestanden van IoT Hub om een bestand te uploaden naar Azure Blob Storage met behulp van een Azure IoT-apparaat en service-SDK's.
Informeer IoT Hub dat het bestand is geüpload en maak een back-endservice voor het ontvangen van uploadmeldingen van IoT Hub met behulp van de Sdk's van de Azure IoT-service.
In sommige scenario's kunt u de gegevens die uw apparaten verzenden niet eenvoudig toewijzen aan de relatief kleine apparaat-naar-cloud-berichten die IoT Hub accepteert. Met de mogelijkheden voor het uploaden van bestanden in IoT Hub kunt u grote of complexe gegevens naar de cloud verplaatsen. Voorbeeld:
Video's
Grote bestanden die afbeeldingen bevatten
Voorbeeld van trillingsgegevens met hoge frequentie
Een vorm van vooraf verwerkte gegevens
Deze bestanden worden doorgaans in batches verwerkt in de cloud, met behulp van hulpprogramma's zoals Azure Data Factory of de Hadoop-stack . Wanneer u bestanden van een apparaat wilt uploaden, kunt u nog steeds de beveiliging en betrouwbaarheid van IoT Hub gebruiken. In dit artikel wordt uitgelegd hoe u dit doet.
Dit artikel is bedoeld als aanvulling op runnable SDK-voorbeelden waarnaar in dit artikel wordt verwezen.
De functionaliteit voor het uploaden van bestanden op apparaten die X.509-verificatie (CA) gebruiken, is in openbare preview en de preview-modus moet zijn ingeschakeld. Het is algemeen beschikbaar op apparaten die gebruikmaken van X.509-vingerafdrukverificatie of X.509-certificaatattestation met Azure Device Provisioning Service. Zie Ondersteunde X.509-certificaten voor meer informatie over X.509-verificatie met IoT Hub.
Vereisten
Een IoT-hub. Voor sommige SDK-aanroepen is de primaire ioT Hub-verbindingsreeks vereist, dus noteer de verbindingsreeks.
Een geregistreerd apparaat. Voor sommige SDK-aanroepen is het primaire verbindingsreeks van het apparaat vereist, dus noteer de verbindingsreeks.
Machtiging voor IoT Hub Service Connect : als u meldingsberichten voor het uploaden van bestanden wilt ontvangen, heeft uw back-endservice de machtiging Service Connect nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent. Zie Verbinding maken met een IoT-hub voor meer informatie.
Configureer het uploaden van bestanden in uw IoT-hub door een Azure Storage-account en Een Azure Blob Storage-container te koppelen. U kunt deze configureren met behulp van Azure Portal, Azure CLI of Azure PowerShell.
Overzicht
Deze procedure bevat twee secties:
Een bestand uploaden vanuit een apparaattoepassing
Melding voor het uploaden van bestanden ontvangen in een back-endtoepassing
Een bestand uploaden vanuit een apparaattoepassing
In deze sectie wordt beschreven hoe u een bestand uploadt van een apparaat naar een IoT-hub met behulp van de DeviceClient-klasse in de Azure IoT SDK voor .NET.
Volg deze procedure om een bestand van een apparaat naar IoT Hub te uploaden:
Verbinding maken met IoT Hub
Een SAS-URI ophalen uit IoT-hub
Het bestand uploaden naar Azure Storage
IoT Hub informeren over de uploadstatus van het bestand
Een apparaat verbinden met IoT Hub
Een apparaat-app kan worden geverifieerd met IoT Hub met behulp van de volgende methoden:
X.509-certificaat
Gedeelde toegangssleutel
Verifiëren met behulp van een X.509-certificaat
Een apparaat verbinden met IoT Hub met behulp van een X.509-certificaat:
Gebruik DeviceAuthenticationWithX509Certificate om een object te maken dat apparaat- en certificaatgegevens bevat.
DeviceAuthenticationWithX509Certificate wordt doorgegeven als de tweede parameter aan DeviceClient.Create (stap 2).
Gebruik DeviceClient.Create om het apparaat te verbinden met IoT Hub met behulp van een X.509-certificaat.
In dit voorbeeld worden apparaat- en certificaatgegevens ingevuld in het authDeviceAuthenticationWithX509Certificate object waarnaar wordt doorgegeven DeviceClient.Create.
In dit voorbeeld ziet u waarden voor certificaatinvoerparameter als lokale variabelen voor duidelijkheid. Sla in een productiesysteem gevoelige invoerparameters op in omgevingsvariabelen of een andere veiligere opslaglocatie. Gebruik Environment.GetEnvironmentVariable("HOSTNAME") bijvoorbeeld om de omgevingsvariabele hostnaam te lezen.
Roep GetFileUploadSasUriAsync aan om details over het uploaden van bestanden op te halen. De SAS-URI wordt in de volgende stap gebruikt om een bestand van een apparaat naar Blob Storage te uploaden.
C#
conststring filePath = "TestPayload.txt";
usingvar 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();
Gebruik de methode UploadAsync om een bestand te uploaden naar Blob Storage, waarbij de SAS-URI wordt doorgegeven. U kunt desgewenst opties voor blobuploads en annuleringstokenparameters toevoegen.
De Azure Blob-client gebruikt altijd HTTPS als protocol om het bestand te uploaden naar Azure Storage.
In dit voorbeeld BlockBlobClient wordt de SAS-URI doorgegeven om een Azure Storage-blok-blobclient te maken en het bestand te uploaden:
C#
var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, null, null);
IoT Hub informeren over de uploadstatus van het bestand
Gebruik CompleteFileUploadAsync om De IoT-hub op de hoogte te stellen dat de apparaatclient het uploaden heeft voltooid, waarbij een FileUploadCompletionNotification-object wordt doorgegeven. De IsSuccess vlag geeft aan of het uploaden wel of niet is gelukt. Na een melding geeft IoT Hub resources vrij die zijn gekoppeld aan het uploaden (de SAS-URI).
Als meldingen voor het uploaden van bestanden zijn ingeschakeld, verzendt IoT Hub een meldingsbericht voor het uploaden van bestanden naar back-endservices die zijn geconfigureerd voor melding over het uploaden van bestanden.
C#
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);
Een melding voor het uploaden van bestanden ontvangen in een back-endtoepassing
U kunt een back-endservice maken om meldingsberichten over het uploaden van bestanden van IoT Hub te ontvangen.
De ServiceClient-klasse bevat methoden die services kunnen gebruiken om meldingen over het uploaden van bestanden te ontvangen.
Service NuGet-pakket toevoegen
Voor back-endservicetoepassingen is het NuGet-pakket Microsoft.Azure.Devices vereist.
Verbinding maken met IoT Hub
U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:
Beleid voor gedeelde toegang
Microsoft Entra
Belangrijk
Dit artikel bevat stappen voor het maken van verbinding met een service met behulp van een handtekening voor gedeelde toegang. Deze verificatiemethode is handig voor testen en evalueren, maar verificatie bij een service met Microsoft Entra ID of beheerde identiteiten is een veiligere benadering. Zie Best practices > voor beveiliging voor cloudbeveiliging voor meer informatie.
Verbinding maken met behulp van een beleid voor gedeelde toegang
Een back-endtoepassing verbinden met een apparaat met createFromConnectionString. Uw toepassing heeft een serviceverbindingsmachtiging nodig. Geef dit beleid voor gedeelde toegang op verbindingsreeks als parameter aan fromConnectionString. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.
Een back-end-app die gebruikmaakt van Microsoft Entra, moet een beveiligingstokenreferentie verifiëren en verkrijgen voordat u verbinding maakt met IoT Hub. Dit token wordt doorgegeven aan een IoT Hub-verbindingsmethode. Zie Toegang tot IoT Hub beheren met behulp van Microsoft Entra ID voor algemene informatie over het instellen en gebruiken van Microsoft Entra voor IoT Hub.
Microsoft Entra-app configureren
U moet een Microsoft Entra-app instellen die is geconfigureerd voor uw voorkeursverificatiereferenties. De app bevat parameters zoals het clientgeheim dat door de back-endtoepassing wordt gebruikt om te verifiëren. De beschikbare configuraties voor app-verificatie zijn:
Clientgeheim
Certificaat
Referenties voor federatieve identiteit
Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. IoT Hub Twin-inzender is bijvoorbeeld vereist om lees- en schrijftoegang tot een IoT Hub-apparaat en moduledubbels in te schakelen. Zie Toegang tot IoT Hub beheren met behulp van Azure RBAC-roltoewijzing voor meer informatie.
De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing ChainedTokenCredentialte verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om een andere methode te gebruiken in een productieomgeving, inclusief een specifieke TokenCredential of geparseerde toepassing. Ter vereenvoudiging beschrijft deze sectie verificatie met behulp van DefaultAzureCredential en clientgeheim. Zie Gebruiksrichtlijnen voor DefaultAzureCredential voor meer informatie over de voor- en nadelen van het gebruik.DefaultAzureCredential
DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.
Microsoft Entra vereist deze NuGet-pakketten en bijbehorende using instructies:
Azure.Core
Azure.Identity
C#
using Azure.Core;
using Azure.Identity;
In dit voorbeeld worden clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om DefaultAzureCredential de toepassing te verifiëren. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een IoT Hub-verbindingsmethode.
De resulterende TokenCredential kan vervolgens worden doorgegeven aan een verbinding met de IoT Hub-methode voor elke SDK-client die Microsoft Entra-referenties accepteert:
Een bestand uploaden vanuit een apparaattoepassing
Melding voor het uploaden van bestanden ontvangen in een back-endtoepassing
Een bestand uploaden vanuit een apparaattoepassing
In deze sectie wordt beschreven hoe u een bestand uploadt van een apparaat naar een IoT-hub met behulp van de DeviceClient-klasse van de Azure IoT SDK voor Java.
Volg deze procedure om een bestand van een apparaat naar IoT Hub te uploaden:
Het apparaat verbinden met IoT Hub
Een SAS-URI ophalen uit IoT-hub
Het bestand uploaden naar Azure Storage
Statusmelding voor het uploaden van bestanden verzenden naar IoT Hub
Een apparaat verbinden met IoT Hub
Een apparaat-app kan worden geverifieerd met IoT Hub met behulp van de volgende methoden:
X.509-certificaat
Gedeelde toegangssleutel
Verifiëren met behulp van een X.509-certificaat
Een apparaat verbinden met IoT Hub met behulp van een X.509-certificaat:
Roep DeviceClient aan met behulp van de ClientOptions informatie om de apparaat-naar-IoT Hub-verbinding te maken.
In dit voorbeeld ziet u waarden voor certificaatinvoerparameter als lokale variabelen voor duidelijkheid. Sla in een productiesysteem gevoelige invoerparameters op in omgevingsvariabelen of een andere veiligere opslaglocatie. Gebruik Environment.GetEnvironmentVariable("PUBLICKEY") bijvoorbeeld om een omgevingsvariabele met een openbare sleutelcertificaattekenreeks te lezen.
Verifiëren met behulp van een gedeelde toegangssleutel
Bestandsuploadbewerkingen maken altijd gebruik van HTTPS, maar DeviceClient kan het IotHubClientProtocol definiëren voor andere services, zoals telemetrie, apparaatmethode en apparaatdubbel.
BlobClient blobClient =
new BlobClientBuilder()
.endpoint(sasUriResponse.getBlobUri().toString())
.buildClient();
Roep uploadFromFile aan om het bestand te uploaden naar Blob Storage.
Java
String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);
Statusmelding voor het uploaden van bestanden verzenden naar IoT Hub
Verzend een uploadstatusmelding naar IoT Hub na een poging om een bestand te uploaden.
Maak een FileUploadCompletionNotification-object . Geef de geslaagde status van het uploaden van isSuccess bestanden correlationId door. Geef een isSuccesstrue waarde door wanneer het uploaden van bestanden is geslaagd, false wanneer dat niet het resultaat is.
FileUploadCompletionNotification moet worden aangeroepen, zelfs wanneer het uploaden van het bestand mislukt. IoT Hub heeft een vast aantal SAS-URI's dat op elk gewenst moment actief mag zijn. Zodra u klaar bent met het uploaden van het bestand, moet u uw SAS-URI vrijmaken, zodat andere SAS-URI's kunnen worden gegenereerd. Als een SAS-URI niet via deze API wordt vrijgemaakt, wordt deze uiteindelijk vrijgemaakt op basis van hoe lang SAS-URI's zijn geconfigureerd voor live op een IoT-hub.
In dit voorbeeld wordt een geslaagde status doorgegeven.
Java
FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);
Sluit de client
Maak de client resources vrij.
Java
client.closeNow();
Een back-endtoepassing maken
In deze sectie wordt beschreven hoe u een melding voor het uploaden van bestanden ontvangt in een back-endtoepassing.
De ServiceClient-klasse bevat methoden die services kunnen gebruiken om meldingen over het uploaden van bestanden te ontvangen.
Importinstructies toevoegen
Voeg deze importinstructies toe om de Azure IoT Java SDK en uitzonderingshandler te gebruiken.
U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:
Beleid voor gedeelde toegang
Microsoft Entra
Belangrijk
Dit artikel bevat stappen voor het maken van verbinding met een service met behulp van een handtekening voor gedeelde toegang. Deze verificatiemethode is handig voor testen en evalueren, maar verificatie bij een service met Microsoft Entra ID of beheerde identiteiten is een veiligere benadering. Zie Best practices > voor beveiliging voor cloudbeveiliging voor meer informatie.
Verbinding maken met behulp van een beleid voor gedeelde toegang
Het verbindingsprotocol definiëren
Gebruik IotHubServiceClientProtocol om het toepassingslaagprotocol te definiëren dat door de serviceclient wordt gebruikt om te communiceren met een IoT Hub.
IotHubServiceClientProtocol accepteert alleen de AMQPS of AMQPS_WS opsomming.
Maak het ServiceClient-object en geef het Iot Hub-verbindingsreeks en protocol op.
Als u een bestand op een apparaat wilt uploaden naar IoT Hub, heeft uw service de machtiging voor serviceverbinding nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent.
Als parameter voor de ServiceClient constructor levert u het beleid voor gedeelde toegang van de service . Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.
De verbinding tussen de toepassing en IoT Hub openen
Open de AMQP-afzenderverbinding. Met deze methode maakt u de verbinding tussen de toepassing en IoT Hub.
Java
serviceClient.open();
Verbinding maken met Microsoft Entra
Een back-end-app die gebruikmaakt van Microsoft Entra, moet een beveiligingstokenreferentie verifiëren en verkrijgen voordat u verbinding maakt met IoT Hub. Dit token wordt doorgegeven aan een IoT Hub-verbindingsmethode. Zie Toegang tot IoT Hub beheren met behulp van Microsoft Entra ID voor algemene informatie over het instellen en gebruiken van Microsoft Entra voor IoT Hub.
Ter vereenvoudiging richt deze sectie zich op het beschrijven van verificatie met behulp van clientgeheim.
Microsoft Entra-app configureren
U moet een Microsoft Entra-app instellen die is geconfigureerd voor uw voorkeursverificatiereferenties. De app bevat parameters zoals het clientgeheim dat door de back-endtoepassing wordt gebruikt om te verifiëren. De beschikbare configuraties voor app-verificatie zijn:
Clientgeheim
Certificaat
Referenties voor federatieve identiteit
Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. IoT Hub Twin-inzender is bijvoorbeeld vereist om lees- en schrijftoegang tot een IoT Hub-apparaat en moduledubbels in te schakelen. Zie Toegang tot IoT Hub beheren met behulp van Azure RBAC-roltoewijzing voor meer informatie.
De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing ChainedTokenCredentialte verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om een andere methode te gebruiken in een productieomgeving, inclusief een specifieke TokenCredential of geparseerde toepassing.
Zie Referentieketens in de Azure Identity-clientbibliotheek voor Java voor meer informatie over de voor- en nadelen van het gebruik.DefaultAzureCredential
DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.
U kunt microsoft Entra-app-referenties verifiëren met behulp van DefaultAzureCredentialBuilder. Sla verbindingsparameters zoals tenantID, client-id en clientgeheimwaarden op als omgevingsvariabelen. Zodra de server TokenCredential is gemaakt, geeft u deze door aan ServiceClient of een andere opbouwfunctie als de parameter referentie.
In dit voorbeeld DefaultAzureCredentialBuilder wordt geprobeerd een verbinding te verifiëren vanuit de lijst die wordt beschreven in DefaultAzureCredential. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een constructor zoals ServiceClient.
Java
TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Verifiëren met ClientSecretCredentialBuilder
U kunt ClientSecretCredentialBuilder gebruiken om een referentie te maken met behulp van clientgeheiminformatie. Als dit lukt, retourneert deze methode een TokenCredential die kan worden doorgegeven aan ServiceClient of een andere opbouwfunctie als de parameter referentie.
In dit voorbeeld zijn clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om ClientSecretCredentialBuilder de referentie te bouwen.
Open gebruiken om verbinding te maken met IoT Hub.
Oproep ontvangen om te controleren op de status van het uploaden van bestanden. Met deze methode wordt een fileUploadNotification-object geretourneerd. Als er een uploadmelding wordt ontvangen, kunt u uploadstatusvelden weergeven met behulp van fileUploadNotification-methoden .
In deze sectie wordt beschreven hoe u een bestand uploadt van een apparaat naar een IoT-hub met behulp van de IoTHubDeviceClient-klasse van de Azure IoT SDK voor Python.
Bibliotheken importeren
Python
import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient
Een apparaat verbinden met IoT Hub
Een apparaat-app kan worden geverifieerd met IoT Hub met behulp van de volgende methoden:
X.509-certificaat
Gedeelde toegangssleutel
Verifiëren met behulp van een X.509-certificaat
Een apparaat verbinden met IoT Hub met behulp van een X.509-certificaat:
Verbinding maken aanroepen om de apparaatclient te verbinden
In dit voorbeeld ziet u waarden voor certificaatinvoerparameter als lokale variabelen voor duidelijkheid. Sla in een productiesysteem gevoelige invoerparameters op in omgevingsvariabelen of een andere veiligere opslaglocatie. Gebruik os.getenv("HOSTNAME") bijvoorbeeld om de omgevingsvariabele hostnaam te lezen.
Python
# 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 Hubawait device_client.connect()
Zie voor meer informatie over certificaatverificatie:
Roep get_storage_info_for_blob aan om informatie op te halen uit een IoT-hub over een gekoppeld Azure Storage-account. Deze informatie omvat de hostnaam, containernaam, blobnaam en een SAS-token. De get_storage_info_for_blob methode retourneert ook een correlation_id, die wordt gebruikt in de notify_blob_upload_status methode. Het correlation_id is de manier waarop IoT Hub markeert aan welke blob u werkt.
Python
# 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)
Roep upload_blob aan om het bestand te uploaden naar de Blob Storage.
In dit voorbeeld wordt de blob_info structuur geparseerd om een URL te maken die wordt gebruikt om een BlobClient te initialiseren. Vervolgens wordt het aanroepen upload_blob om het bestand te uploaden naar Blob Storage.
Python
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 filewith 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 = 404return (False, ex)
except AzureError as ex:
# catch Azure errors that might result from the upload operationreturn (False, ex)
IoT Hub informeren over de uploadstatus
Gebruik notify_blob_upload_status om IoT Hub op de hoogte te stellen van de status van de Blob Storage-bewerking. Geef de correlation_id verkregen door de get_storage_info_for_blob methode door. De correlation_id service wordt door IoT Hub gebruikt om een service op de hoogte te stellen die mogelijk luistert naar een melding met betrekking tot de status van de bestandsuploadtaak.
In dit voorbeeld wordt de IoT-hub op de hoogte gemaakt van een geslaagde bestandsupload:
In dit artikel wordt beschreven hoe u de Azure IoT SDK voor Node.js gebruikt om een apparaat-app te maken voor het uploaden van bestanden en back-endservicetoepassingen die een melding over het uploaden van bestanden ontvangen.
Een apparaattoepassing maken
In deze sectie wordt beschreven hoe u een bestand uploadt van een apparaat naar een IoT-hub met behulp van het azure-iot-device-pakket in de Azure IoT SDK voor Node.js.
SDK-pakketten installeren
Voer deze opdracht uit om de SDK voor azure-iot-device device, azure-iot-device-mqtt en de @azure/storage-blob-pakketten op uw ontwikkelcomputer te installeren:
Een apparaat-app kan worden geverifieerd met IoT Hub met behulp van de volgende methoden:
X.509-certificaat
Gedeelde toegangssleutel
Verifiëren met behulp van een X.509-certificaat
Het X.509-certificaat is gekoppeld aan het apparaat-naar-IoT Hub-verbindingstransport.
Een apparaat-naar-IoT Hub-verbinding configureren met behulp van een X.509-certificaat:
Roep fromConnectionString aan om het apparaat of de identiteitsmodule toe te voegen verbindingsreeks en het transporttype aan het Client object toe te voegen. Voeg x509=true toe aan de verbindingsreeks om aan te geven dat een certificaat wordt toegevoegd aan DeviceClientOptions. Voorbeeld:
Configureer een JSON-variabele met certificaatgegevens en geef deze door aan DeviceClientOptions.
Roep setOptions aan om een X.509-certificaat en -sleutel (en eventueel een wachtwoordzin) toe te voegen aan het clienttransport.
Roep open om de verbinding van het apparaat naar IoT Hub te openen.
In dit voorbeeld ziet u informatie over certificaatconfiguratie in een JSON-variabele. De certificeringsconfiguratie clientOptions wordt doorgegeven aan setOptionsen de verbinding wordt geopend met behulp van open.
JavaScript
const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`const client = Client.fromConnectionString(connectionString, Protocol);
var clientOptions = {
cert: myX509Certificate,
key: myX509Key,
passphrase: passphrase,
http: {
receivePolicy: {
interval: 10
}
}
}
client.setOptions(clientOptions);
client.open(connectCallback);
Zie voor meer informatie over certificaatverificatie:
client.open(function(err) {
if (err) {
console.error('error connecting to hub: ' + err);
process.exit(1);
}
})
Een SAS-token ophalen uit IoT Hub
Gebruik getBlobSharedAccessSignature om het SAS-token voor het gekoppelde opslagaccount op te halen uit de IoT-hub.
Voorbeeld:
JavaScript
// 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) {
thrownew errors.ArgumentError('Invalid upload parameters');
}
Het bestand uploaden naar IoT Hub
Een bestand uploaden van een apparaat naar IoT Hub:
De SDK bevat een upload naar een geavanceerd blobvoorbeeld.
Een back-endtoepassing maken
In deze sectie wordt beschreven hoe u meldingen voor het uploaden van bestanden ontvangt in een back-endtoepassing.
De ServiceClient-klasse bevat methoden die services kunnen gebruiken om meldingen over het uploaden van bestanden te ontvangen.
Service SDK-pakket installeren
Voer deze opdracht uit om azure-iothub te installeren op uw ontwikkelcomputer:
cmd/sh
npm install azure-iothub --save
Verbinding maken met IoT Hub
U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:
Beleid voor gedeelde toegang
Microsoft Entra
Belangrijk
Dit artikel bevat stappen voor het maken van verbinding met een service met behulp van een handtekening voor gedeelde toegang. Deze verificatiemethode is handig voor testen en evalueren, maar verificatie bij een service met Microsoft Entra ID of beheerde identiteiten is een veiligere benadering. Zie Best practices > voor beveiliging voor cloudbeveiliging voor meer informatie.
Verbinding maken met behulp van een beleid voor gedeelde toegang
Als u een bestand vanaf een apparaat wilt uploaden, heeft uw service de machtiging voor serviceverbinding nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent.
Als parameter voor CreateFromConnectionStringhet leveren van het beleid voor gedeelde toegang van de service verbindingsreeks. Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.
JavaScript
var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);
Verbinding maken met Microsoft Entra
Een back-end-app die gebruikmaakt van Microsoft Entra, moet een beveiligingstokenreferentie verifiëren en verkrijgen voordat u verbinding maakt met IoT Hub. Dit token wordt doorgegeven aan een IoT Hub-verbindingsmethode. Zie Toegang tot IoT Hub beheren met behulp van Microsoft Entra ID voor algemene informatie over het instellen en gebruiken van Microsoft Entra voor IoT Hub.
Zie voor een overzicht van Node.js SDK-verificatie:
U moet een Microsoft Entra-app instellen die is geconfigureerd voor uw voorkeursverificatiereferenties. De app bevat parameters zoals het clientgeheim dat door de back-endtoepassing wordt gebruikt om te verifiëren. De beschikbare configuraties voor app-verificatie zijn:
Clientgeheim
Certificaat
Referenties voor federatieve identiteit
Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. IoT Hub Twin-inzender is bijvoorbeeld vereist om lees- en schrijftoegang tot een IoT Hub-apparaat en moduledubbels in te schakelen. Zie Toegang tot IoT Hub beheren met behulp van Azure RBAC-roltoewijzing voor meer informatie.
De eenvoudigste manier om Microsoft Entra te gebruiken om een back-endtoepassing ChainedTokenCredentialte verifiëren, is door DefaultAzureCredential te gebruiken, maar het wordt aanbevolen om een andere methode te gebruiken in een productieomgeving, inclusief een specifieke TokenCredential of geparseerde toepassing. Ter vereenvoudiging beschrijft deze sectie verificatie met behulp van DefaultAzureCredential en clientgeheim.
Zie Referentieketens in de Azure Identity-clientbibliotheek voor JavaScript voor meer informatie over de voor- en nadelen van het gebruik DefaultAzureCredential
DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.
Microsoft Entra vereist dit pakket:
shell
npm install --save @azure/identity
In dit voorbeeld zijn clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om DefaultAzureCredential de toepassing te verifiëren. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een IoT Hub-verbindingsmethode.
JavaScript
import { DefaultAzureCredential } from"@azure/identity";
// Azure SDK clients accept the credential as a parameterconst credential = new DefaultAzureCredential();
Het resulterende referentietoken kan vervolgens worden doorgegeven aan fromTokenCredential om verbinding te maken met IoT Hub voor elke SDK-client die Microsoft Entra-referenties accepteert:
De URL van de Azure-service: de Azure-service-URL moet de indeling {Your Entra domain URL}.azure-devices.net hebben zonder voorvoegsel https:// . Bijvoorbeeld: MyAzureDomain.azure-devices.net.
Het Azure-referentietoken
In dit voorbeeld wordt de Azure-referentie verkregen met behulp van DefaultAzureCredential. De URL en referentie van het Azure-domein worden vervolgens opgegeven om Registry.fromTokenCredential de verbinding met IoT Hub te maken.
JavaScript
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 objectconst credential = new DefaultAzureCredential()
// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);
Een callback-ontvanger voor het uploaden van een bestand maken
Een callback-ontvanger voor het uploaden van een bestand maken:
Roep getFileNotificationReceiver aan. Geef de naam op van een callback-methode voor het uploaden van bestanden die wordt aangeroepen wanneer meldingsberichten worden ontvangen.
Meldingen voor het uploaden van bestanden verwerken in de callback-methode.
In dit voorbeeld wordt een ontvanger voor het terugbellen van meldingen receiveFileUploadNotification ingesteld. De ontvanger interpreteert de statusinformatie voor het uploaden van bestanden en drukt een statusbericht af op de console.
JavaScript
//Set up the receiveFileUploadNotification notification message callback receiver
serviceClient.getFileNotificationReceiver(functionreceiveFileUploadNotification(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');
}
});
});
}
Voorbeeld van een melding voor het uploaden van SDK-bestanden
De SDK bevat een voorbeeld van het uploaden van bestanden.
In dit artikel wordt beschreven hoe u de functie voor het uploaden van bestanden van IoT Hub gebruikt om bestanden van een apparaat te uploaden naar een Azure Storage-blobcontainer.
Azure Portal gebruiken om uw IoT-hub te configureren om bestandsuploads van verbonden apparaten in te schakelen. Bevat informatie over het configureren van het Azure-doelopslagaccount.
Cloud-naar-apparaat-berichten verzenden vanuit een back-end-app en deze ontvangen op een apparaat-app met behulp van de Azure IoT SDK's voor C#, Python, Java en Node.js.
In dit artikel wordt beschreven hoe u berichtroutering gebruikt om apparaat-naar-cloud-berichten te verzenden. Bevat informatie over het verzenden van zowel telemetrie- als niet-telemetriegegevens.
Deze zelfstudie laat ontwikkelaars zien hoe ze een apparaat veilig kunnen verbinden met Azure IoT Hub. U gebruikt een Azure IoT-apparaat-SDK voor C, C#, Python, Node.js of Java om een apparaatclient te bouwen voor Windows, Linux of Raspberry Pi (Raspbian). Vervolgens maakt u verbinding en verzendt u telemetrie.