Eindpunten maken in Azure Digital Twins

In dit artikel wordt uitgelegd hoe u een eindpunt maakt voor Azure Digital Twin-gebeurtenissen met behulp van Azure Portal of de Azure CLI. U kunt ook eindpunten beheren met de DigitalTwinsEndpoint-besturingsvlak-API's.

Het routeren van gebeurtenismeldingen van Azure Digital Twins naar downstreamservices of verbonden rekenresources is een proces in twee stappen: eindpunten maken en vervolgens gebeurtenisroutes maken om gegevens naar deze eindpunten te verzenden. In dit artikel wordt de eerste stap besproken, waarbij eindpunten worden ingesteld die de gebeurtenissen kunnen ontvangen. Later kunt u gebeurtenisroutes maken die aangeven welke gebeurtenissen worden gegenereerd door Azure Digital Twins aan welke eindpunten worden geleverd.

Vereisten

• U hebt een Azure-account nodig dat gratis kan worden ingesteld

• U hebt een Azure Digital Twins-exemplaar nodig in uw Azure-abonnement. Als u nog geen exemplaar hebt, kunt u er een maken met behulp van de stappen in Een exemplaar en verificatie instellen. Laat de volgende waarden van de installatie handig zijn om verderop in dit artikel te gebruiken:

  • Exemplaarnaam
  • Resourcegroep

  U vindt deze details in Azure Portal nadat u uw exemplaar hebt ingesteld.

  

Volg vervolgens de onderstaande instructies als u de Azure CLI wilt gebruiken tijdens het volgen van deze handleiding.

De omgeving voorbereiden op de Azure CLI

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.

  

• Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

  • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

  • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

Vereiste resources maken

Deze services zijn de ondersteunde typen eindpunten die u voor uw exemplaar kunt maken:

• Event Grid-onderwerp
  • Voor Event Grid-eindpunten worden alleen Event Grid-onderwerpen ondersteund. Event Grid-domeinen worden niet ondersteund als eindpunten.
• Event Hubs Hubs
• Service Bus-onderwerp

Als u een eindpunt wilt koppelen aan Azure Digital Twins, moet het Event Grid-onderwerp, de Event Hub of het Service Bus-onderwerp dat u gebruikt voor het eindpunt al bestaan.

Gebruik de volgende grafiek om te zien welke resources moeten worden ingesteld voordat u uw eindpunt maakt.

Eindpunttype	Vereiste resources (gekoppeld aan instructies voor maken)
Event Grid-eindpunt	Event Grid-onderwerp *Gebeurtenisschema moet Event Grid-schema of Cloud-gebeurtenisschema v1.0 zijn
Event Hubs-eindpunt	Event Hubs-naamruimte Event Hub (Optioneel) autorisatieregel voor verificatie op basis van sleutels
Service Bus-eindpunt	Service Bus-naamruimte Service Bus-onderwerp (Optioneel) autorisatieregel voor verificatie op basis van sleutels

Het eindpunt maken

Nadat u de eindpuntbronnen hebt gemaakt, kunt u deze gebruiken voor een Azure Digital Twins-eindpunt.

Portal

Als u een nieuw eindpunt wilt maken, gaat u naar de pagina van uw exemplaar in Azure Portal (u kunt het exemplaar vinden door de naam ervan in te voeren in de zoekbalk van de portal).

1. Selecteer Eindpunten in het exemplaarmenu. Selecteer vervolgens op de pagina Eindpunten die volgt de optie + Een eindpunt maken. Als u dit doet, wordt de pagina Een eindpunt maken geopend, waar u de velden in de volgende stappen invult.

   

2. Voer een naam in voor uw eindpunt en kies het eindpunttype.

3. Voltooi de overige details die vereist zijn voor uw eindpunttype, inclusief uw abonnement en de eindpuntbronnen die eerder zijn beschreven.

   1. Alleen voor Event Hubs- en Service Bus-eindpunten moet u een verificatietype selecteren. U kunt verificatie op basis van sleutels gebruiken met een vooraf gemaakte autorisatieregel of een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit. Zie Eindpuntopties: Verificatie op basis van identiteit voor meer informatie over het gebruik van de opties voor identiteitsverificatie.

   

4. Voltooi het maken van uw eindpunt door Opslaan te selecteren.

Nadat u uw eindpunt hebt gemaakt, kunt u controleren of het eindpunt is gemaakt door het meldingspictogram in de bovenste Azure Portal-balk te controleren:

Als het maken van het eindpunt mislukt, bekijkt u het foutbericht en probeert u het na enkele minuten opnieuw.

U kunt ook het eindpunt bekijken dat is gemaakt op de pagina Eindpunten voor uw Azure Digital Twins-exemplaar.

Het Event Grid-onderwerp, event hub of Service Bus-onderwerp is nu beschikbaar als eindpunt in Azure Digital Twins, onder de naam die u voor het eindpunt hebt gekozen. Normaal gesproken gebruikt u die naam als doel van een gebeurtenisroute, die u kunt maken in Routes en filters maken.

CLI

In de volgende voorbeelden ziet u hoe u eindpunten maakt met behulp van de opdracht az dt endpoint create voor de Azure Digital Twins CLI. Vervang de tijdelijke aanduidingen in de opdrachten door de details van uw eigen resources.

Een Event Grid-eindpunt maken:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Een Event Hubs-eindpunt maken (verificatie op basis van sleutels):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Een Service Bus-onderwerpeindpunt maken (verificatie op basis van sleutels):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Nadat deze opdrachten zijn uitgevoerd, is het Event Grid-onderwerp, event hub of Service Bus-onderwerp beschikbaar als eindpunt in Azure Digital Twins, onder de naam die u hebt opgegeven met het --endpoint-name argument. Normaal gesproken gebruikt u die naam als doel van een gebeurtenisroute, die u kunt maken in Routes en filters maken.

Eindpuntopties: verificatie op basis van identiteit

In deze sectie wordt beschreven hoe u een beheerde identiteit gebruikt voor een Azure Digital Twins-exemplaar bij het doorsturen van gebeurtenissen naar ondersteunde routeringsbestemmingen. Het instellen van een beheerde identiteit is niet vereist voor routering, maar het kan het exemplaar helpen om eenvoudig toegang te krijgen tot andere met Microsoft Entra beveiligde resources, zoals Event Hubs, Service Bus-bestemmingen en Azure Storage-container. Beheerde identiteiten kunnen worden toegewezen aan het systeem of aan de gebruiker zijn toegewezen.

De rest van deze sectie doorloopt drie stappen voor het instellen van een eindpunt met een beheerde identiteit.

1. Beheerde identiteit inschakelen voor het exemplaar

Gebruik de onderstaande tabbladen voor instructies die overeenkomen met uw voorkeurservaring.

Portal

Zorg er eerst voor dat u een beheerde identiteit hebt ingeschakeld voor uw Azure Digital Twins-exemplaar.

Zorg er ook voor dat u de rol Gegevenseigenaar van Azure Digital Twins hebt voor het exemplaar. U vindt instructies in Machtigingen voor gebruikerstoegang instellen.

CLI

Zorg er eerst voor dat u een beheerde identiteit hebt ingeschakeld voor uw Azure Digital Twins-exemplaar.

Zorg er ook voor dat u de rol Gegevenseigenaar van Azure Digital Twins hebt voor het exemplaar. U vindt instructies in Machtigingen voor gebruikerstoegang instellen.

2. Azure-rollen toewijzen aan de identiteit

Zodra een beheerde identiteit is gemaakt voor uw Azure Digital Twins-exemplaar, moet u de juiste rollen toewijzen om te verifiëren met verschillende typen eindpunten voor het routeren van gebeurtenissen naar ondersteunde bestemmingen. In deze sectie worden de rolopties beschreven en hoe u deze toewijst aan de beheerde identiteit.

Belangrijk

Zorg ervoor dat u deze stap voltooit. Zonder deze methode heeft de identiteit geen toegang tot uw eindpunten en worden gebeurtenissen niet geleverd.

Hier volgen de minimale rollen die uw Azure Digital Twins-identiteit nodig heeft voor toegang tot een eindpunt, afhankelijk van het type bestemming. Rollen met hogere machtigingen (zoals rollen van gegevenseigenaar) werken ook.

Bestemming	Azure-rol
Azure Event Hubs	Azure Event Hubs-gegevenszender
Azure Service Bus	Afzender van Azure Service Bus-gegevens
Azure Storage-container	Inzender voor opslagblobgegevens

Gebruik de onderstaande tabbladen om de rol toe te wijzen met behulp van uw voorkeurservaring.

Portal

Als u een rol aan de identiteit wilt toewijzen, opent u eerst Azure Portal in een browser.

1. Navigeer naar uw eindpuntresource (uw Event Hub, Service Bus-onderwerp of opslagcontainer) door te zoeken naar de naam in de zoekbalk van de portal.

2. Klik op Toegangsbeheer (IAM) .

3. Selecteer Toevoegen>Roltoewijzing toevoegen om het deelvenster Roltoewijzing toevoegen te openen.

4. Wijs de gewenste rol toe aan de beheerde identiteit van uw Azure Digital Twins-exemplaar met behulp van de onderstaande informatie. Raadpleeg Azure-rollen toewijzen met Azure Portal voor informatie over het toewijzen van rollen.

   Instelling	Weergegeven als
   Role	Selecteer de gewenste rol in de opties.
   Toegang toewijzen aan	Beheerde identiteit
   Leden	Selecteer de door de gebruiker toegewezen of door het systeem toegewezen beheerde identiteit van uw Azure Digital Twins-exemplaar waaraan de rol wordt toegewezen. Een door de gebruiker toegewezen identiteit heeft de naam die u hebt gekozen bij het maken van de identiteit en een door het systeem toegewezen identiteit heeft een naam die overeenkomt met de naam van uw Azure Digital Twins-exemplaar.

   

CLI

U kunt de --scopes parameter toevoegen aan de az dt create opdracht om de identiteit toe te wijzen aan een of meer bereiken met een opgegeven rol. De opdracht met deze parameter kan worden gebruikt bij het maken van het exemplaar of later door de naam door te geven van een exemplaar dat al bestaat.

Hier volgt een voorbeeld waarmee een exemplaar met een door het systeem toegewezen beheerde identiteit wordt gemaakt en die identiteit wordt toegewezen aan een aangepaste rol die wordt aangeroepen MyCustomRole in een Event Hub.

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

Zie de referentiedocumentatie az dt create voor meer voorbeelden van roltoewijzingen met deze opdracht.

U kunt ook de opdrachtgroep az role assignment gebruiken om rollen te maken en te beheren. Deze opdracht kan worden gebruikt ter ondersteuning van andere scenario's waarbij u geen roltoewijzing wilt groeperen met de opdracht maken.

3. Het eindpunt maken met verificatie op basis van identiteit

Nadat u een beheerde identiteit hebt ingesteld voor uw Azure Digital Twins-exemplaar en deze de juiste rol(en) hebt toegewezen, kunt u de eindpunten maken die gebruikmaken van de identiteit voor verificatie. Deze optie is alleen beschikbaar voor Event Hubs- en Service Bus-eindpunten (dit wordt niet ondersteund voor Event Grid).

Notitie

U kunt een eindpunt dat al is gemaakt met een sleutelidentiteit, niet bewerken om over te schakelen op verificatie op basis van identiteit. U moet het verificatietype kiezen wanneer het eindpunt voor het eerst wordt gemaakt.

Gebruik de onderstaande tabbladen om het eindpunt te maken met behulp van uw voorkeurservaring.

Portal

Volg de algemene instructies om een Azure Digital Twins-eindpunt te maken.

Wanneer u de stap voor het voltooien van de vereiste gegevens voor uw eindpunttype hebt bereikt, selecteert u Door het systeem toegewezen of door de gebruiker toegewezen (preview) voor het verificatietype.

Voltooi het instellen van uw eindpunt en selecteer Opslaan.

CLI

Beheerde identiteiten worden toegevoegd aan een eindpunt door parameters toe te voegen aan de az dt endpoint create opdracht die wordt gebruikt om het eindpunt te maken. (Zie de referentiedocumentatie of de algemene instructies voor het maken van een Azure Digital Twins-eindpunt voor meer informatie over deze opdracht.)

Gebruik de onderstaande CLI-opdracht voor het gekozen type beheerde identiteit.

Door het systeem toegewezen identiteit opdracht

Als u een eindpunt wilt maken dat gebruikmaakt van door het systeem toegewezen verificatie, geeft u het IdentityBased verificatietype op met de --auth-type parameter. In het onderstaande voorbeeld ziet u deze functionaliteit voor een Event Hubs-eindpunt.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

Door de gebruiker toegewezen identiteit opdracht

Als u een eindpunt wilt maken dat gebruikmaakt van door de gebruiker toegewezen identiteitsverificatie, geeft u de door de gebruiker toegewezen identiteitsresource-id op met de --user parameter. In het onderstaande voorbeeld ziet u deze functionaliteit voor een Event Hubs-eindpunt.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

Overwegingen voor het uitschakelen van beheerde identiteiten

Omdat een identiteit afzonderlijk wordt beheerd van de eindpunten die deze gebruiken, is het belangrijk om rekening te houden met de effecten die wijzigingen in de identiteit of de bijbehorende rollen kunnen hebben op de eindpunten in uw Azure Digital Twins-exemplaar. Als de identiteit is uitgeschakeld of een benodigde rol voor een eindpunt wordt verwijderd, kan het eindpunt ontoegankelijk worden en wordt de stroom van gebeurtenissen verstoord.

Als u een eindpunt wilt blijven gebruiken dat is ingesteld met een beheerde identiteit die nu is uitgeschakeld, moet u het eindpunt verwijderen en opnieuw maken met een ander verificatietype. Het kan tot een uur duren voordat de levering van gebeurtenissen aan het eindpunt na deze wijziging wordt hervat.

Eindpuntopties: Onbeletterd

Wanneer een eindpunt een gebeurtenis niet binnen een bepaalde periode kan leveren of na een poging om de gebeurtenis een bepaald aantal keren te leveren, kan de niet-bezorgde gebeurtenis naar een opslagaccount worden verzonden. Dit proces staat bekend als dead-lettering.

U kunt de benodigde opslagbronnen instellen met behulp van Azure Portal of de Azure Digital Twins CLI. Als u echter een eindpunt wilt maken waarvoor dead-lettering is ingeschakeld, moet u de Azure Digital Twins CLI of besturingsvlak-API's gebruiken.

Zie Eindpunten en gebeurtenisroutes voor meer informatie over dead-lettering. Ga verder met de rest van deze sectie voor instructies over het instellen van een eindpunt met dode letters.

Opslagbronnen instellen

Voordat u de locatie met een dode letter instelt, moet u een opslagaccount hebben met een container die is ingesteld in uw Azure-account.

U geeft de URI voor deze container op wanneer u het eindpunt later maakt. De locatie van de dode letter wordt aan het eindpunt verstrekt als een container-URI met een SAS-token. Dit token heeft toestemming nodig write voor de doelcontainer binnen het opslagaccount. De volledig gevormde SAS-URI voor dode letters heeft de volgende notatie: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Volg de onderstaande stappen om deze opslagbronnen in te stellen in uw Azure-account om u voor te bereiden op het instellen van de eindpuntverbinding in de volgende sectie.

1. Volg de stappen in Een opslagaccount maken om een opslagaccount te maken in uw Azure-abonnement. Noteer de naam van het opslagaccount om deze later te gebruiken.
2. Volg de stappen in Een container maken om een container te maken in het nieuwe opslagaccount. Noteer de containernaam om deze later te gebruiken.

Een SAS-token maken

Maak vervolgens een SAS-token voor uw opslagaccount dat het eindpunt kan gebruiken om er toegang toe te krijgen.

Portal

1. Navigeer eerst naar uw opslagaccount in Azure Portal (u vindt het op naam met de zoekbalk van de portal).

2. Kies op de pagina opslagaccount de koppeling Shared Access Signature in de linkernavigatiebalk om het SAS-token in te stellen.

   

3. Selecteer op de pagina Shared Access Signature onder Toegestane services en toegestane resourcetypen de gewenste instellingen. U moet ten minste één vak in elke categorie selecteren. Kies onder Toegestane machtigingen schrijven (u kunt desgewenst ook andere machtigingen selecteren).

4. Stel de gewenste waarden in voor de overige instellingen.

5. Wanneer u klaar bent, selecteert u de knop SAS genereren en verbindingsreeks om het SAS-token te genereren.

   

6. Hierdoor worden verschillende SAS- en verbindingsreeks waarden onder aan dezelfde pagina gegenereerd, onder de instellingsselecties. Schuif omlaag om de waarden weer te geven en gebruik het pictogram Kopiëren naar klembord om de SAS-tokenwaarde te kopiëren. Sla het bestand op om later te gebruiken.

CLI

1. Haal uw opslagaccountsleutels op met behulp van de volgende opdracht en kopieer de waarde voor een van uw sleutels:

   az storage account keys list --account-name <storage-account-name>
   

2. Selecteer een vervaldatum en genereer het SAS-token voor uw opslagaccount met behulp van de volgende opdracht:

   az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
   

   De uitvoer van deze opdracht is het SAS-token. Kopieer de SAS-tokenwaarde om later te gebruiken.

   Notitie

   Deze opdracht bevat 'blob', 'file', 'queue'- en 'table' -services, een 'object' -resourcetype; en staat 'write' -machtigingen toe.

   Zie de Azure CLI-verwijzing voor meer informatie over de az storage account generate-sas opdracht en de bijbehorende parameters.

Het eindpunt voor dode letters maken

Portal

Als u een eindpunt wilt maken waarvoor dead-lettering is ingeschakeld, moet u de CLI-opdrachten of besturingsvlak-API's gebruiken om uw eindpunt te maken in plaats van Azure Portal.

Voor instructies over het maken van dit type eindpunt met de Azure CLI schakelt u over naar het CLI-tabblad voor deze sectie.

CLI

Als u een eindpunt wilt maken waarvoor dead-lettering is ingeschakeld, voegt u de --deadletter-sas-uri parameter toe aan de opdracht az dt endpoint create waarmee een eindpunt wordt gemaakt.

De waarde voor de parameter is de SAS-URI voor dode letters die bestaat uit de naam van het opslagaccount, de containernaam en het SAS-token dat u in de vorige sectie hebt verzameld. Met deze parameter wordt het eindpunt gemaakt met verificatie op basis van sleutels. De parameter ziet er als volgt uit:

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Tip

Als u een eindpunt met een dode letter met verificatie op basis van identiteiten wilt maken, voegt u zowel de parameter dead-letter uit deze sectie als de juiste parameter voor beheerde identiteit toe aan dezelfde opdracht.

U kunt ook dode lettereindpunten maken met behulp van de Azure Digital Twins-besturingsvlak-API's in plaats van de CLI. Als u dit wilt doen, bekijkt u de DigitalTwinsEndpoint-documentatie om te zien hoe u de aanvraag structureren en de parameters voor de dode letter toevoegt.

Schema voor berichtopslag

Zodra het eindpunt met 'dead-lettering' is ingesteld, worden berichten met een dode letter opgeslagen in de volgende indeling in uw opslagaccount:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

Niet-geschreven berichten komen overeen met het schema van de oorspronkelijke gebeurtenis die is bedoeld om te worden bezorgd bij uw oorspronkelijke eindpunt.

Hier volgt een voorbeeld van een bericht met een dode letter voor een melding voor het maken van een dubbel:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Volgende stappen

Als u gegevens van Azure Digital Twins daadwerkelijk naar een eindpunt wilt verzenden, moet u een gebeurtenisroute definiëren. Met deze routes kunnen ontwikkelaars gebeurtenisstromen, in het hele systeem en naar downstreamservices, verbinden. Met één route kunnen meerdere meldingen en gebeurtenistypen worden geselecteerd. Ga door met het maken van een gebeurtenisroute naar uw eindpunt in Routes en filters maken.