Skapa slutpunkter i Azure Digital Twins

Den här artikeln beskriver hur du skapar en slutpunkt för Azure Digital Twin-händelser med hjälp av Azure-portalen eller Azure CLI. Du kan också hantera slutpunkter med API:erna för DigitalTwinsEndpoint-kontrollplanet.

Routning av händelsemeddelanden från Azure Digital Twins till underordnade tjänster eller anslutna beräkningsresurser är en tvåstegsprocess: skapa slutpunkter och skapa sedan händelsevägar för att skicka data till dessa slutpunkter. Den här artikeln beskriver det första steget och konfigurerar slutpunkter som kan ta emot händelserna. Senare kan du skapa händelsevägar som anger vilka händelser som genereras av Azure Digital Twins som levereras till vilka slutpunkter.

Förutsättningar

• Du behöver ett Azure-konto som kan konfigureras kostnadsfritt

• Du behöver en Azure Digital Twins-instans i din Azure-prenumeration. Om du inte redan har en instans kan du skapa en med hjälp av stegen i Konfigurera en instans och autentisering. Ha följande värden från installationen till hands för senare användning i den här artikeln:

  • Instansnamn
  • Resursgrupp

  Du hittar den här informationen i Azure-portalen när du har konfigurerat din instans.

  

Följ sedan anvisningarna nedan om du tänker använda Azure CLI när du följer den här guiden.

Förbereda din miljö för Azure CLI

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

  • När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.

  • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Skapa nödvändiga resurser

Dessa tjänster är de typer av slutpunkter som stöds som du kan skapa för din instans:

• Event Grid-ämne
  • För Event Grid-slutpunkter stöds endast Event Grid-ämnen. Event Grid-domäner stöds inte som slutpunkter.
• Event Hubs-hubb
• Service Bus-ämne

Om du vill länka en slutpunkt till Azure Digital Twins måste det Event Grid-ämne, händelsehubb eller Service Bus-ämne som du använder för slutpunkten redan finnas.

Använd följande diagram för att se vilka resurser som ska konfigureras innan du skapar slutpunkten.

Slutpunktstyp	Nödvändiga resurser (länkade till skapandeinstruktioner)
Event Grid-slutpunkt	Event Grid-ämne *händelseschemat måste vara Event Grid-schema eller Molnhändelseschema v1.0
Event Hubs-slutpunkt	Event Hubs-namnrymd händelsehubb (Valfritt) auktoriseringsregel för nyckelbaserad autentisering
Service Bus-slutpunkt	Service Bus-namnområde Service Bus-ämne (Valfritt) auktoriseringsregel för nyckelbaserad autentisering

Skapa slutpunkten

När du har skapat slutpunktsresurserna kan du använda dem för en Azure Digital Twins-slutpunkt.

Portal

Om du vill skapa en ny slutpunkt går du till instansens sida i Azure-portalen (du hittar instansen genom att ange dess namn i portalsökningsfältet).

1. På instansmenyn väljer du Slutpunkter. På sidan Slutpunkter som följer väljer du sedan + Skapa en slutpunkt. Om du gör det öppnas sidan Skapa en slutpunkt , där du fyller i fälten i följande steg.

   

2. Ange ett namn för slutpunkten och välj slutpunktstyp.

3. Fyll i den andra information som krävs för din slutpunktstyp, inklusive din prenumeration och de slutpunktsresurser som beskrevs tidigare.

   1. Endast för Event Hubs- och Service Bus-slutpunkter måste du välja en autentiseringstyp. Du kan använda nyckelbaserad autentisering med en i förväg skapad auktoriseringsregel eller en systemtilldelad eller användartilldelad hanterad identitet. Mer information om hur du använder alternativen för identitetsautentisering finns i Slutpunktsalternativ: Identitetsbaserad autentisering.

   

4. Slutför skapandet av slutpunkten genom att välja Spara.

När du har skapat slutpunkten kan du kontrollera att slutpunkten har skapats genom att kontrollera meddelandeikonen i det översta Azure-portalfältet:

Om det inte går att skapa slutpunkten kan du observera felmeddelandet och försöka igen efter några minuter.

Du kan också visa slutpunkten som skapades på sidan Slutpunkter för din Azure Digital Twins-instans.

Nu är Event Grid-ämnet, händelsehubben eller Service Bus-ämnet tillgängligt som en slutpunkt i Azure Digital Twins, under det namn du valde för slutpunkten. Du använder vanligtvis det namnet som mål för en händelseväg, som du kan skapa i Skapa vägar och filter.

CLI

I följande exempel visas hur du skapar slutpunkter med kommandot az dt endpoint create för Azure Digital Twins CLI. Ersätt platshållarna i kommandona med information om dina egna resurser.

Så här skapar du en Event Grid-slutpunkt:

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>

Så här skapar du en Event Hubs-slutpunkt (nyckelbaserad autentisering):

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>

Så här skapar du en Service Bus-ämnesslutpunkt (nyckelbaserad autentisering):

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>

När du har kört de här kommandona kommer event grid-ämnet, händelsehubben eller Service Bus-ämnet att vara tillgängligt som en slutpunkt i Azure Digital Twins, under det namn som du angav med --endpoint-name argumentet. Du använder vanligtvis det namnet som mål för en händelseväg, som du kan skapa i Skapa vägar och filter.

Slutpunktsalternativ: Identitetsbaserad autentisering

Det här avsnittet beskriver hur du använder en hanterad identitet för en Azure Digital Twins-instans när händelser vidarebefordras till routningsmål som stöds. Det krävs inte att du konfigurerar en hanterad identitet för routning, men det kan hjälpa instansen att enkelt komma åt andra Microsoft Entra-skyddade resurser, till exempel Event Hubs, Service Bus-mål och Azure Storage Container. Hanterade identiteter kan vara systemtilldelade eller användartilldelade.

Resten av det här avsnittet går igenom tre steg för att konfigurera en slutpunkt med en hanterad identitet.

1. Aktivera hanterad identitet för instansen

Använd flikarna nedan för instruktioner som matchar din föredragna upplevelse.

Portal

Kontrollera först att du har aktiverat en hanterad identitet för din Azure Digital Twins-instans.

Kontrollera också att du har rollen Som Azure Digital Twins-dataägare på instansen. Du hittar instruktioner i Konfigurera behörigheter för användaråtkomst.

CLI

Kontrollera först att du har aktiverat en hanterad identitet för din Azure Digital Twins-instans.

Kontrollera också att du har rollen Som Azure Digital Twins-dataägare på instansen. Du hittar instruktioner i Konfigurera behörigheter för användaråtkomst.

2. Tilldela Azure-roller till identiteten

När en hanterad identitet har skapats för din Azure Digital Twins-instans måste du tilldela den lämpliga roller för att autentisera med olika typer av slutpunkter för routning av händelser till mål som stöds. I det här avsnittet beskrivs rollalternativen och hur du tilldelar dem till den hanterade identiteten.

Viktigt!

Slutför det här steget. Utan den kommer identiteten inte att kunna komma åt dina slutpunkter och händelser levereras inte.

Här är de minsta roller som din Azure Digital Twins-identitet behöver för att få åtkomst till en slutpunkt, beroende på typ av mål. Roller med högre behörigheter (som dataägarroller) fungerar också.

Mål	Azure-roll
Azure Event Hubs	Azure Event Hubs Data Sender
Azure Service Bus	Azure Service Bus Data Sender
Azure Storage-container	Storage Blob-datadeltagare

Använd flikarna nedan för att tilldela rollen med den upplevelse du föredrar.

Portal

Om du vill tilldela en roll till identiteten börjar du med att öppna Azure-portalen i en webbläsare.

1. Gå till slutpunktsresursen (din händelsehubb, Service Bus-ämne eller lagringscontainer) genom att söka efter dess namn i portalsökningsfältet.

2. Välj Åtkomstkontroll (IAM) .

3. Välj Lägg till>rolltilldelning för att öppna sidan Lägg till rolltilldelning.

4. Tilldela önskad roll till den hanterade identiteten för din Azure Digital Twins-instans med hjälp av informationen nedan. Läs mer om att tilldela roller i Tilldela Azure-roller via Azure Portal.

   Inställning	Värde
   Roll	Välj önskad roll bland alternativen.
   Tilldela åtkomst till	Hanterade identiteter
   Members	Välj den användartilldelade eller systemtilldelade hanterade identiteten för din Azure Digital Twins-instans som tilldelas rollen. En användartilldelad identitet har det namn du valde när du skapade identiteten, och en systemtilldelad identitet har ett namn som matchar namnet på din Azure Digital Twins-instans.

   

CLI

Du kan lägga till parametern --scopes i az dt create kommandot för att tilldela identiteten till ett eller flera omfång med en angiven roll. Kommandot med den här parametern kan användas när du först skapar instansen eller senare genom att skicka in namnet på en instans som redan finns.

Här är ett exempel som skapar en instans med en systemtilldelad hanterad identitet och tilldelar identiteten en anpassad roll som heter MyCustomRole i en händelsehubb.

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

Fler exempel på rolltilldelningar med det här kommandot finns i referensdokumentationen az dt create.

Du kan också använda kommandogruppen az role assignment för att skapa och hantera roller. Det här kommandot kan användas för att stödja andra scenarier där du inte vill gruppera rolltilldelning med kommandot create.

3. Skapa slutpunkten med identitetsbaserad autentisering

När du har konfigurerat en hanterad identitet för din Azure Digital Twins-instans och tilldelat den lämpliga roller kan du skapa de slutpunkter som använder identiteten för autentisering. Det här alternativet är endast tillgängligt för Slutpunkter av Event Hubs- och Service Bus-typ (det stöds inte för Event Grid).

Kommentar

Du kan inte redigera en slutpunkt som redan har skapats med nyckelbaserad identitet för att ändra till identitetsbaserad autentisering. Du måste välja autentiseringstyp när slutpunkten först skapas.

Använd flikarna nedan för att skapa slutpunkten med den upplevelse du föredrar.

Portal

Börja följa de allmänna anvisningarna för att skapa en Azure Digital Twins-slutpunkt.

När du kommer till steget för att slutföra den information som krävs för din slutpunktstyp väljer du antingen Systemtilldelad eller Användartilldelad (förhandsversion) som autentiseringstyp.

Slutför konfigurationen av slutpunkten och välj Spara.

CLI

Hanterade identiteter läggs till i en slutpunkt genom att parametrar läggs till i kommandot az dt endpoint create som används för att skapa slutpunkten. (Mer information om det här kommandot finns i referensdokumentationen eller de allmänna instruktionerna för att skapa en Azure Digital Twins-slutpunkt.).

Använd CLI-kommandot nedan för din valda typ av hanterad identitet.

Systemtilldelad identitetskommando

Om du vill skapa en slutpunkt som använder systemtilldelad autentisering anger du autentiseringstypen IdentityBased med parametern --auth-type . Exemplet nedan illustrerar den här funktionen för en Event Hubs-slutpunkt.

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

Användartilldelad identitetskommando

Om du vill skapa en slutpunkt som använder användartilldelad identitetsautentisering anger du det användartilldelade identitetsresurs-ID:t med parametern --user . Exemplet nedan illustrerar den här funktionen för en Event Hubs-slutpunkt.

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>

Överväganden för att inaktivera hanterade identiteter

Eftersom en identitet hanteras separat från slutpunkterna som använder den är det viktigt att tänka på vilka effekter eventuella ändringar av identiteten eller dess roller kan ha på slutpunkterna i din Azure Digital Twins-instans. Om identiteten är inaktiverad eller om en nödvändig roll för en slutpunkt tas bort från den, kan slutpunkten bli otillgänglig och händelseflödet avbryts.

Om du vill fortsätta använda en slutpunkt som har konfigurerats med en hanterad identitet som nu har inaktiverats måste du ta bort slutpunkten och återskapa den med en annan autentiseringstyp. Det kan ta upp till en timme innan händelser återupptar leveransen till slutpunkten efter den här ändringen.

Slutpunktsalternativ: Obeställbara bokstäver

När en slutpunkt inte kan leverera en händelse inom en viss tidsperiod eller efter att ha försökt leverera händelsen ett visst antal gånger kan den skicka händelsen som inte har levererats till ett lagringskonto. Den här processen kallas för "dead-lettering".

Du kan konfigurera nödvändiga lagringsresurser med hjälp av Azure-portalen eller Azure Digital Twins CLI. Men om du vill skapa en slutpunkt med obeställbara bokstäver aktiverat måste du använda Azure Digital Twins CLI eller kontrollplans-API:er.

Mer information om obeställbara bokstäver finns i Slutpunkter och händelsevägar. Anvisningar om hur du konfigurerar en slutpunkt med obeställbara bokstäver finns i resten av det här avsnittet.

Konfigurera lagringsresurser

Innan du anger platsen för obeställbara bokstäver måste du ha ett lagringskonto med en container konfigurerad i ditt Azure-konto.

Du anger URI:n för den här containern när du skapar slutpunkten senare. Platsen med obeställbara bokstäver kommer att tillhandahållas till slutpunkten som en container-URI med en SAS-token. Den token behöver write behörighet för målcontainern i lagringskontot. Sas-URI:n med den fullständigt formade död bokstaven kommer att vara i formatet: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Följ stegen nedan för att konfigurera dessa lagringsresurser i ditt Azure-konto för att förbereda konfigurationen av slutpunktsanslutningen i nästa avsnitt.

1. Följ stegen i Skapa ett lagringskonto för att skapa ett lagringskonto i din Azure-prenumeration. Anteckna namnet på lagringskontot för att använda det senare.
2. Följ stegen i Skapa en container för att skapa en container i det nya lagringskontot. Anteckna containernamnet för att använda det senare.

Skapa en SAS-token

Skapa sedan en SAS-token för ditt lagringskonto som slutpunkten kan använda för att komma åt den.

Portal

1. Börja med att navigera till ditt lagringskonto i Azure-portalen (du hittar det efter namn i portalens sökfält).

2. På lagringskontosidan väljer du länken Signatur för delad åtkomst i det vänstra navigeringsfältet för att börja konfigurera SAS-token.

   

3. På sidan Signatur för delad åtkomst går du till Tillåtna tjänster och Tillåtna resurstyper och väljer vilka inställningar du vill ha. Du måste välja minst en ruta i varje kategori. Under Tillåtna behörigheter väljer du Skriv (du kan också välja andra behörigheter om du vill).

4. Ange vilka värden du vill ha för de återstående inställningarna.

5. När du är klar väljer du knappen Generera SAS och anslutningssträng för att generera SAS-token.

   

6. Om du gör det genereras flera SAS- och anslutningssträng värden längst ned på samma sida, under inställningsvalen. Rulla nedåt för att visa värdena och använd ikonen Kopiera till Urklipp för att kopiera SAS-tokenvärdet . Spara den om du vill använda den senare.

   

CLI

1. Hämta dina lagringskontonycklar med följande kommando och kopiera värdet för någon av dina nycklar:

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

2. Välj ett förfallodatum och generera SAS-token för ditt lagringskonto med hjälp av följande kommando:

   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
   

   Utdata från det här kommandot är SAS-token. Kopiera SAS-tokenvärdet för senare användning.

   Kommentar

   Det här kommandot innehåller "b lob", "file", "queue" och "table"-tjänster, en "object"-resurstyp och tillåter "write"-behörigheter.

   Mer information om az storage account generate-sas kommandot och dess parametrar finns i Azure CLI-referensen.

Skapa slutpunkten för obeställbara bokstäver

Portal

Om du vill skapa en slutpunkt med obeställbara bokstäver aktiverade måste du använda CLI-kommandon eller API:er för kontrollplanet för att skapa slutpunkten i stället för Azure-portalen.

Instruktioner om hur du skapar den här typen av slutpunkt med Azure CLI finns på fliken CLI för det här avsnittet.

CLI

Om du vill skapa en slutpunkt som har dead-lettering aktiverat lägger du till parametern --deadletter-sas-uri i kommandot az dt endpoint create som skapar en slutpunkt.

Värdet för parametern är SAS-URI:n med obeställbara bokstäver som består av lagringskontots namn, containernamn och SAS-token som du samlade in i föregående avsnitt. Den här parametern skapar slutpunkten med nyckelbaserad autentisering. Så här ser parametern ut:

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

Dricks

Om du vill skapa en slutpunkt med död bokstav med identitetsbaserad autentisering lägger du till både parametern dead-letter från det här avsnittet och lämplig hanterad identitetsparameter i samma kommando.

Du kan också skapa slutpunkter med obeställbara bokstäver med hjälp av API: erna för Azure Digital Twins-kontrollplanet i stället för CLI. Det gör du genom att visa Dokumentationen om DigitalTwinsEndpoint för att se hur du strukturerar begäran och lägger till parametrarna för obeställbara bokstäver.

Schema för meddelandelagring

När slutpunkten med obeställbara bokstäver har konfigurerats lagras meddelanden med obeställbara bokstäver i följande format i ditt lagringskonto:

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

Meddelanden med obeställbara bokstäver matchar schemat för den ursprungliga händelsen som var avsedd att levereras till din ursprungliga slutpunkt.

Här är ett exempel på ett meddelande med obeställbara bokstäver för ett meddelande om att skapa en tvilling:

{
  "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"
}

Nästa steg

Om du vill skicka data från Azure Digital Twins till en slutpunkt måste du definiera en händelseväg. Med de här vägarna kan utvecklare koppla upp händelseflödet, i hela systemet och till underordnade tjänster. En enda väg kan tillåta att flera meddelanden och händelsetyper väljs. Fortsätt för att skapa en händelseväg till slutpunkten i Skapa vägar och filter.