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 waarmee gegevens naar deze eindpunten worden verzonden. 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.

Vereiste voorwaarden

• Een Azure-account dat u gratis kunt instellen.

• Een Azure Digital Twins-exemplaar in uw Azure-abonnement. Als u geen exemplaar hebt, maakt u er een door de stappen in Een exemplaar en verificatie instellen uit te voeren. Zorg ervoor dat de volgende waarden van de installatie beschikbaar zijn voor gebruik verderop in dit artikel:

  • Instantie-naam
  • Bronnengroep

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

  

Als u de Azure CLI wilt gebruiken tijdens het volgen van deze handleiding, volgt u de instructies in de volgende sectie.

Uw omgeving voorbereiden voor de Azure CLI

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie Aan de slag met Azure Cloud Shell voor meer informatie.

  

• Als u liever CLI-referentieopdrachten lokaal uitvoert, installeert u de Azure CLI. Als je op Windows of macOS werkt, overweeg dan om Azure CLI in een Docker-container te draaien. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij de Azure CLI met behulp van de opdracht az login . Om het authenticatieproces te voltooien, volgt u de stappen die op uw terminal worden weergegeven. Zie Verifiëren bij Azure met behulp van Azure CLI voor andere aanmeldingsopties.

  • Wanneer u daarom wordt gevraagd, installeer de Azure CLI-extensie bij het eerste gebruik. Zie Extensies gebruiken en beheren met de Azure CLI voor meer informatie over extensies.

  • Voer az version uit om de versie en afhankelijke bibliotheken te vinden die zijn geïnstalleerd. Voer az upgrade uit om een upgrade uit te voeren naar de nieuwste versie.

Noodzakelijke bronnen creëren

Deze services zijn de ondersteunde typen eindpunten die u voor uw instantie 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-hub
• Service Bus-onderwerp

Voordat u een eindpunt koppelt aan Azure Digital Twins, moet u het Event Grid-onderwerp, event hub of Service Bus-onderwerp maken dat u voor het eindpunt gebruikt.

Gebruik de volgende grafiek om te zien welke resources u moet instellen voordat u uw eindpunt maakt.

Eindpunttype	Vereiste hulpmiddelen (gekoppeld aan instructies voor het maken van)
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 het Azure Digital Twins-eindpunt maken. Gebruik de volgende tabbladen om uw voorkeurservaring te selecteren.

Portaal

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 Uitvoereindpunten > verbinden in het exemplaarmenu. Selecteer vervolgens op de pagina Eindpuntende optie + Een eindpunt maken. Met deze actie wordt de pagina Een eindpunt maken geopend.

   

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. Selecteer alleen een verificatietype voor Event Hubs en Service Bus-eindpunten. 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. Door het systeem toegewezen identiteit is alleen beschikbaar als u een door het systeem toegewezen identiteit voor het exemplaar hebt ingeschakeld. Zie Eindpuntopties: Verificatie op basis van identiteit verderop in dit artikel 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 is gemaakt door het meldingspictogram in de bovenste Azure-portalbalk 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 u hebt 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 het 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 u deze opdrachten hebt uitgevoerd, is het Event Grid-onderwerp, event hub of Service Bus-onderwerp beschikbaar als eindpunt in Azure Digital Twins. Het eindpunt heeft de naam die u hebt opgegeven met het --endpoint-name argument. Normaal gesproken gebruikt u die naam als het 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 systeemaangewezen of gebruikersaangewezen zijn.

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

1. Beheerde identiteit inschakelen voor de instantie

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

Portaal

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

Zorg er ook voor dat u de rol Gegevenseigenaar van Azure Digital Twins hebt voor het exemplaar. Instructies vind je in Gebruikerstoegangsmachtigingen 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. Zie voor instructies Machtigingen voor gebruikerstoegang instellen.

2. Azure-rollen toewijzen aan de identiteit

Nadat u een beheerde identiteit voor uw Azure Digital Twins-exemplaar hebt gemaakt, wijst u deze de juiste rollen toe 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 dit kunnen identiteiten geen toegang krijgen tot uw eindpunten en worden gebeurtenissen niet afgeleverd.

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 (een cloud-gebaseerde berichtendienst van Microsoft)	Azure Service Bus-gegevenszender
Azure Storage-container	Bijdrager van opslagblobdata

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

Portaal

Als u een rol aan de identiteit wilt toewijzen, opent u 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. Selecteer Toegangsbeheer (IAM).

3. Selecteer Roltoewijzing toevoegen> om de pagina Roltoewijzing toevoegen te openen.

4. Wijs de gewenste rol toe aan de beheerde identiteit van uw Azure Digital Twins-exemplaar. Zie Azure-rollen toewijzen met behulp van Azure Portal voor gedetailleerde stappen.

   Configuratie	Waarde
   Rol	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. Gebruik deze opdracht voor het eerst bij het aanmaken van de instantie, of later door de naam van een bestaande instantie door te geven.

Hier is een voorbeeld dat een instantie met een door het systeem toegewezen beheerde identiteit creëert en die identiteit een aangepaste rol met de naam MyCustomRole toekent 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 az dt create referentiedocumentatie voor meer voorbeelden van roltoewijzingen met deze opdracht.

U kunt ook de opdrachtgroep az role assignment gebruiken om rollen te maken en te beheren. Gebruik deze opdracht om andere scenario's te ondersteunen 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 rollen hebt toegewezen, maakt u de eindpunten 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).

Opmerking

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

Gebruik de volgende secties om het eindpunt te maken met behulp van uw voorkeurservaring.

Portaal

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

Voeg beheerde identiteiten toe aan een eindpunt door parameters toe te voegen aan de az dt endpoint create opdracht. Zie de referentiedocumentatie of de algemene instructies voor het maken van een Azure Digital Twins-eindpunt voor meer informatie over deze opdracht.

Gebruik de volgende 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 volgende 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 volgende 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

Een identiteit wordt afzonderlijk beheerd van de eindpunten die deze gebruiken, dus het is belangrijk om na te gaan hoe wijzigingen in de identiteit of de bijbehorende rollen van invloed kunnen zijn op de eindpunten in uw Azure Digital Twins-exemplaar. Als u de identiteit uitschakelt of een benodigde rol voor een eindpunt verwijdert, wordt het eindpunt ontoegankelijk en wordt de stroom gebeurtenissen onderbroken.

Als u een eindpunt wilt blijven gebruiken dat is ingesteld met een beheerde identiteit die u hebt uitgeschakeld, verwijdert u het eindpunt en maakt u het opnieuw met een ander verificatietype. Het kan een uur duren voordat gebeurtenissen na deze wijziging de levering aan het eindpunt hervatten.

Eindpuntopties: Onbeletterd

Wanneer een eindpunt een gebeurtenis niet binnen een bepaalde periode of aantal pogingen kan 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 controlevlakken-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.

Opslagmiddelen inrichten

Voordat u de locatie voor dode letters instelt, moet u een opslagaccount met een container in uw Azure-account hebben.

Wanneer u het eindpunt maakt, geeft u de URI van deze container op. De locatie van de dode letter wordt aan het eindpunt verstrekt als een container-URI met een SAS-token. Dit token heeft write toestemming nodig 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>.

Als u deze opslagbronnen in uw Azure-account wilt instellen, volgt u de stappen in de volgende sectie. Nadat u de opslagbronnen hebt ingesteld, kunt u de eindpuntverbinding instellen.

1. Als u een opslagaccount in uw Azure-abonnement wilt maken, volgt u de stappen in Een opslagaccount maken. Noteer de naam van het opslagaccount, zodat u deze later kunt gebruiken.
2. Volg de stappen in Een container maken in het nieuwe opslagaccount om een container te maken. Noteer de containernaam zodat u deze later kunt gebruiken.

Een SAS-token maken

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

Portaal

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

2. Kies op de pagina opslagaccount de koppeling Shared Access Signature voor beveiliging en netwerken > 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 Schrijven onder Toegestane machtigingen. U kunt ook andere machtigingen selecteren.

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

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

6. Als u dit proces voltooit, worden verschillende SAS- en verbindingsreekswaarden 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.

   Opmerking

   De voorbeeldset met parameters in de vorige opdracht omvat services zoals 'blob', 'file', 'queue' en 'table' (--services bfqt), een resourcetype 'object' (--resource-types o) en 'schrijf'-machtigingen ().

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

Het eindpunt voor dode letters maken

Portaal

Als u een eindpunt wilt maken waarvoor dead-lettering is ingeschakeld, gebruikt u de CLI-opdrachten of besturingsvlak-API's om uw eindpunt te maken. U kunt dit type eindpunt niet maken in 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>

Aanbeveling

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 u het eindpunt hebt ingesteld met 'dead-lettering', worden de berichten met dode letters opgeslagen in uw opslagaccount in de volgende indeling:

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

De onbestelbare berichten komen overeen met het schema van de oorspronkelijke gebeurtenis die uw oorspronkelijke eindpunt wilde leveren.

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

Nadat u een eindpunt hebt gemaakt, definieert u een gebeurtenisroute om gegevens naar het eindpunt te verzenden. Met gebeurtenisroutes kunt u de gebeurtenisstroom instellen in het hele systeem en naar downstreamservices. Eén route kan meerdere meldingen en gebeurtenistypen toestaan. Maak een gebeurtenisroute naar uw eindpunt met de instructies in Routes en filters maken.