IoT Hub-eindpunten
Azure IoT Hub maakt verschillende eindpunten beschikbaar ter ondersteuning van de apparaten en services die ermee communiceren.
Notitie
Sommige van de functies die in dit artikel worden genoemd, zoals cloud-naar-apparaat-berichten, apparaatdubbels en apparaatbeheer, zijn alleen beschikbaar in de standaardlaag van IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.
IoT Hub-namen
U vindt de hostnaam van een IoT-hub in Azure Portal in het werkvenster Overzicht van uw IoT-hub. De DNS-naam van een IoT-hub ziet er standaard uit zoals in het volgende voorbeeld:
{your iot hub name}.azure-devices.net
IoT Hub-eindpunten voor ontwikkeling en beheer
Azure IoT Hub is een multitenant-service die de functionaliteit beschikbaar maakt voor verschillende actoren. In het volgende diagram ziet u de verschillende eindpunten die ioT Hub beschikbaar maakt.
In de volgende lijst worden de eindpunten beschreven:
Resourceprovider: een Azure Resource Manager-interface . Met deze interface kunnen eigenaren van Azure-abonnementen IoT-hubs maken en verwijderen en ioT-hubeigenschappen bijwerken. IoT Hub-eigenschappen bepalen beleid voor gedeelde toegang op hubniveau, in tegenstelling tot toegangsbeheer op apparaatniveau en functionele opties voor cloud-naar-apparaat- en apparaat-naar-cloud-berichten. Met de IoT Hub-resourceprovider kunt u ook apparaatidentiteiten exporteren.
Apparaatidentiteitsbeheer: een set HTTPS REST-eindpunten voor het beheren van apparaatidentiteiten (maken, ophalen, bijwerken en verwijderen). Apparaat-id's worden gebruikt voor apparaatverificatie en toegangsbeheer.
Beheer van apparaatdubbels: een set servicegerichte HTTPS REST-eindpunten voor het opvragen en bijwerken van apparaatdubbels (tags en eigenschappen bijwerken).
Takenbeheer: een set servicegerichte HTTPS REST-eindpunten voor het opvragen en beheren van taken.
Apparaateindpunten: een set eindpunten voor elk apparaat in het identiteitsregister. Behalve waar vermeld, worden deze eindpunten weergegeven met behulp van MQTT v3.1.1-, HTTPS 1.1- en AMQP 1.0-protocollen . AMQP en MQTT zijn ook beschikbaar via WebSockets op poort 443. Deze apparaateindpunten zijn onder andere:
Apparaat-naar-cloud-berichten verzenden
Cloud-naar-apparaat-berichten ontvangen
Uploads van bestanden initiëren
Eigenschappen van apparaatdubbel ophalen en bijwerken (HTTPS wordt niet ondersteund)
Aanvragen voor directe methoden ontvangen (HTTPS wordt niet ondersteund)
Service-eindpunten: een set eindpunten voor de back-end van uw oplossing om te communiceren met uw apparaten. Met één uitzondering worden deze eindpunten alleen weergegeven met behulp van de AMQP - en AMQP via WebSockets-protocollen. Het aanroepeindpunt van de directe methode wordt weergegeven via het HTTPS-protocol.
Apparaat-naar-cloud-berichten ontvangen: dit eindpunt is het ingebouwde eindpunt dat wordt besproken in berichtrouteringsconcepten. Een back-endservice kan deze gebruiken om de apparaat-naar-cloud-berichten te lezen die door uw apparaten worden verzonden. U kunt naast dit ingebouwde eindpunt ook aangepaste eindpunten maken op uw IoT-hub.
Cloud-naar-apparaat-berichten verzenden en ontvangstbevestigingen ontvangen
Meldingen voor het uploaden van bestanden ontvangen
Directe methode aanroepen
In het artikel Azure IoT Hub SDK's worden de verschillende manieren beschreven om toegang te krijgen tot deze eindpunten.
Alle IoT Hub-eindpunten maken gebruik van het TLS-protocol en er wordt nooit een eindpunt weergegeven op niet-versleutelde/onbeveiligde kanalen.
Belangrijk
De volgende functionaliteit voor apparaten die X.509-verificatie (CA) gebruiken, is nog niet algemeen beschikbaar en de preview-modus moet zijn ingeschakeld:
- HTTPS, MQTT via WebSockets en AMQP via WebSockets-protocollen.
- Bestandsuploads (alle protocollen).
Deze functies zijn algemeen beschikbaar op apparaten die gebruikmaken van X.509-vingerafdrukverificatie. Zie Ondersteunde X.509-certificaten voor meer informatie over X.509-verificatie met IoT Hub.
Aangepaste eindpunten voor berichtroutering
U kunt bestaande Azure-services in uw Azure-abonnementen koppelen aan uw IoT-hub om te fungeren als eindpunten voor berichtroutering. Deze eindpunten fungeren als service-eindpunten en worden gebruikt als sinks voor berichtroutes. Apparaten kunnen niet rechtstreeks naar deze eindpunten schrijven. Zie IoT Hub-berichtroutering gebruiken om apparaat-naar-cloud-berichten naar verschillende eindpunten te verzenden voor meer informatie over berichtroutering.
IoT Hub ondersteunt momenteel de volgende Azure-services als aangepaste eindpunten:
- Opslagcontainers
- Event Hubs
- Service Bus-wachtrijen
- Service Bus-onderwerpen
- Cosmos DB
Zie Quota en beperking voor de limieten voor eindpunten per hub.
Ingebouwd eindpunt
U kunt standaard Event Hubs-integratie en SDK's gebruiken om apparaat-naar-cloud-berichten te ontvangen van het ingebouwde eindpunt (berichten/gebeurtenissen). Zodra een route is gemaakt, worden gegevens niet meer naar het ingebouwde eindpunt gestroomd, tenzij er een route naar dat eindpunt wordt gemaakt. Zelfs als er geen routes worden gemaakt, moet een terugvalroute worden ingeschakeld om berichten naar het ingebouwde eindpunt te routeren. De terugval is standaard ingeschakeld als u uw hub maakt met behulp van de portal of de CLI.
Azure Storage als een routerings-eindpunt
Er zijn twee opslagservices die IoT Hub kan berichten routeren naar: Azure Blob Storage - en Azure Data Lake Storage Gen2-accounts (ADLS Gen2). Beide gebruiken blobs voor hun opslag.
IoT Hub ondersteunt het schrijven van gegevens naar Azure Storage in de Apache Avro-indeling en de JSON-indeling. De standaardindeling is AVRO. Als u JSON-codering wilt gebruiken, stelt u de eigenschap contentType in op de eigenschap application/json en contentEncoding op UTF-8 in de eigenschappen van het berichtsysteem. Beide waarden zijn hoofdlettergevoelig. Als de inhoudscodering niet is ingesteld, schrijft IoT Hub de berichten in de met base 64 gecodeerde indeling.
De coderingsindeling kan alleen worden ingesteld wanneer het blob-opslageindpunt is geconfigureerd; het kan niet worden bewerkt voor een bestaand eindpunt.
IoT Hub batcheert berichten en schrijft gegevens naar de opslag wanneer de batch een bepaalde grootte bereikt of een bepaalde hoeveelheid tijd is verstreken. IoT Hub is standaard ingesteld op de volgende naamconventie voor bestanden: {iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}.
U kunt elke naamconventie voor bestanden gebruiken, maar u moet alle vermelde tokens gebruiken. IoT Hub schrijft naar een lege blob als er geen gegevens zijn om te schrijven.
We raden u aan de blobs of bestanden weer te geven en deze vervolgens te herhalen, om ervoor te zorgen dat alle blobs of bestanden worden gelezen zonder veronderstellingen over de partitie te maken. Het partitiebereik kan mogelijk veranderen tijdens een door Microsoft geïnitieerde failover of handmatige failover van IoT Hub. U kunt de List Blobs-API gebruiken om de lijst met blobs of De ADLS Gen2-API voor de lijst met bestanden op te sommen. Voorbeeld:
public void ListBlobsInContainer(string containerName, string iothub)
{
var storageAccount = CloudStorageAccount.Parse(this.blobConnectionString);
var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
if (cloudBlobContainer.Exists())
{
var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
foreach (IListBlobItem item in results)
{
Console.WriteLine(item.Uri);
}
}
}
Als u een met Azure Data Lake Gen2 compatibel opslagaccount wilt maken, maakt u een nieuw V2-opslagaccount en selecteert u Hiërarchische naamruimte inschakelen in de sectie Data Lake Storage Gen2 van het tabblad Geavanceerd , zoals wordt weergegeven in de volgende afbeelding:
Service Bus-wachtrijen en Service Bus-onderwerpen als routeringseindpunt
Service Bus-wachtrijen en -onderwerpen die worden gebruikt als IoT Hub-eindpunten mogen geen sessies of dubbele detectie hebben ingeschakeld. Als een van deze opties is ingeschakeld, wordt het eindpunt weergegeven als Onbereikbaar in Azure Portal.
Event Hubs als een routerings-eindpunt
Naast het ingebouwde eindpunt dat compatibel is met Event Hubs, kunt u ook gegevens routeren naar aangepaste eindpunten van het type Event Hubs.
Azure Cosmos DB als routeringseindpunt
U kunt gegevens rechtstreeks vanuit IoT Hub naar Azure Cosmos DB verzenden. IoT Hub biedt ondersteuning voor schrijven naar Cosmos DB in JSON (indien opgegeven in het berichtinhoudstype) of als base 64 gecodeerd binair bestand.
Ter ondersteuning van grootschalige scenario's kunt u synthetische partitiesleutels inschakelen voor het Cosmos DB-eindpunt. Omdat Cosmos DB een hyperscale-gegevensarchief is, moeten alle gegevens/documenten die ernaar worden geschreven een veld bevatten dat een logische partitie vertegenwoordigt. Elke logische partitie heeft een maximale grootte van 20 GB. U kunt de naam van de eigenschap partitiesleutel opgeven in de naam van de partitiesleutel. De eigenschapsnaam van de partitiesleutel wordt gedefinieerd op containerniveau en kan niet worden gewijzigd zodra deze is ingesteld.
U kunt de waarde van de synthetische partitiesleutel configureren door een sjabloon op te geven in de partitiesleutelsjabloon op basis van het geschatte gegevensvolume. In productiescenario's kan bijvoorbeeld worden verwacht dat uw logische partitie de maximale limiet van 20 GB binnen een maand nadert. In dat geval kunt u een synthetische partitiesleutel definiëren als een combinatie van de apparaat-id en de maand. De gegenereerde partitiesleutelwaarde wordt automatisch toegevoegd aan de partitiesleuteleigenschap voor elke nieuwe Cosmos DB-record, zodat logische partities elke maand voor elk apparaat worden gemaakt.
Let op
Als u de door het systeem toegewezen beheerde identiteit gebruikt om te verifiëren bij Cosmos DB, moet u Azure CLI of Azure PowerShell gebruiken om de ingebouwde roldefinitie van Cosmos DB Data Contributor toe te wijzen aan de identiteit. Roltoewijzing voor Cosmos DB wordt momenteel niet ondersteund vanuit Azure Portal. Zie Op rollen gebaseerde toegang configureren voor Azure Cosmos DB voor meer informatie over de verschillende rollen. Zie Azure Cosmos DB SQL-rolbronnen beheren voor meer informatie over het toewijzen van rollen via CLI.
Eindpuntstatus
U kunt de REST API Eindpuntstatus ophalen gebruiken om de status van de eindpunten op te halen. We raden u aan de metrische gegevens voor IoT Hub-routering te gebruiken die betrekking hebben op latentie van routeringsberichten om fouten te identificeren en op te sporen wanneer de eindpuntstatus is dood of beschadigd, omdat we verwachten dat de latentie hoger is wanneer het eindpunt zich in een van deze statussen bevindt. Zie IoT Hub bewaken voor meer informatie over het gebruik van metrische ioT Hub-gegevens.
| Status | Beschrijving |
|---|---|
| Gezonde | Het eindpunt accepteert berichten zoals verwacht. |
| Ongezonde | Het eindpunt accepteert geen berichten en IoT Hub probeert opnieuw berichten naar dit eindpunt te verzenden. |
| onbekend | IoT Hub heeft niet geprobeerd berichten aan dit eindpunt te leveren. |
| Gedegradeerd | Het eindpunt accepteert berichten langzamer dan verwacht of herstelt van een beschadigde status. |
| Dood | IoT Hub levert geen berichten meer aan dit eindpunt. Nieuwe pogingen om berichten naar dit eindpunt te verzenden, zijn mislukt. |
Volgende stappen
Meer informatie over deze onderwerpen: