Hantera slutpunkter och vägar i Azure Digital Twins (API:er och CLI)

I Azure Digital Twins kan du dirigera händelsemeddelanden till underordnade tjänster eller anslutna beräkningsresurser. Det gör du genom att först konfigurera slutpunkter som kan ta emot händelserna. Du kan sedan skapa händelsevägar som anger vilka händelser som genererats av Azure Digital Twins i Azure som ska levereras till vilka slutpunkter.

Den här artikeln vägleder dig genom processen för att skapa slutpunkter och vägar med REST-API:erna, .NET (C#) SDK och Azure Digital Twins CLI.

Du kan också hantera slutpunkter och vägar med hjälp av Azure Portal. En version av den här artikeln som använder portalen i stället finns i How-to: Manage endpoints and routes (portal)(Så här hanterar du slutpunkter och vägar (portal) .

Förutsättningar

  • Du behöver ett Azure-konto (du kan konfigurera ett kostnadsfritt här)
  • Du behöver en instans Azure Digital Twins Azure-prenumerationen. 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 konfigurationen till hands för senare användning i den här artikeln:
    • Instansnamn
    • Resursgrupp
  • Använd bash-miljön i Azure Cloud Shell.

    Starta Cloud Shell i ett nytt fönster

  • Om du vill kan du i stället installera Azure CLI för att köra CLI-referenskommandon.

    • 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. Fler inloggningsalternativ finns i Logga in med Azure CLI.

    • När du uppmanas till det installerar du Azure CLI-tillägg vid första användning. 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 en slutpunkt för Azure Digital Twins

Det här är de typer av slutpunkter som stöds som du kan skapa för din instans:

Mer information om de olika slutpunktstyperna finns i Välja mellan Azure-meddelandetjänster.

I det här avsnittet beskrivs hur du skapar dessa slutpunkter med hjälp av Azure CLI. Du kan också hantera slutpunkter med DigitalTwinsEndpoint-kontrollplanets API:er.

Förutsättning: skapa slut punkts resurser

Om du vill länka en slut punkt till Azure Digitals-band måste du redan ha installerat Event Grid-ämnet, händelsehubben eller Service Bus ämnet som du använder för slut punkten.

Använd följande diagram för att se vilka resurser som ska ställas in innan du skapar slut punkten.

Slut punkts typ Resurser som krävs (länkade till skapande instruktioner)
Event Grid slut punkt Event Grid-ämne
Event Hubs slut punkt     Namn område för Event Hub

händelsehubben

Valfritt auktoriseringsregel för nyckelbaserad autentisering
Service Bus slut punkt Service Bus namnrymd

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. 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 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 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>

Skapa 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 dessa kommandon är event grid, event hub eller Service Bus-ämnet tillgängliga som en slutpunkt inuti 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 skapar senare i den här artikeln.

Skapa en slutpunkt med identitetsbaserad autentisering

Du kan också skapa en slutpunkt som har identitetsbaserad autentisering för att använda slutpunkten med en hanterad identitet. Det här alternativet är endast tillgängligt för Service Bus slutpunkter av Service Bus (stöds inte för Event Grid).

CLI-kommandot för att skapa den här typen av slutpunkt finns nedan. Du behöver följande värden för att ansluta till platshållarna i kommandot:

  • Azure-resurs-ID för din Azure Digital Twins instans
  • ett slutpunktsnamn
  • en slutpunktstyp
  • slutpunktsresursens namnområde
  • namnet på händelsehubben eller Service Bus ämnet
  • platsen för din Azure Digital Twins instans
az resource create --id <Azure-Digital-Twins-instance-Azure-resource-ID>/endpoints/<endpoint-name> --properties '{\"properties\": { \"endpointType\": \"<endpoint-type>\", \"authenticationType\": \"IdentityBased\", \"endpointUri\": \"sb://<endpoint-namespace>.servicebus.windows.net\", \"entityPath\": \"<name-of-event-hub-or-Service-Bus-topic>\"}, \"location\":\"<instance-location>\" }' --is-full-object

Skapa en slutpunkt med dead lettering

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 harupplevts till ett lagringskonto. Den här processen kallas för "dead-lettering".

Slutpunkter med dead-lettering aktiverat kan konfigureras med hjälp Azure Digital Twins CLI eller kontrollplans-API:er.

Mer information om dead-lettering finns i Begrepp: Händelsevägar. Mer information om hur du ställer in en slutpunkt med dead lettering finns i resten av det här avsnittet.

Konfigurera lagringsresurser

Innan du anger en plats för dead-letter måste du ha ett lagringskonto med en container konfigurerad i ditt Azure-konto.

Du anger URI:en för den här containern när du skapar slutpunkten senare. Platsen för dead-letter anges till slutpunkten som en container-URI med en SAS-token. Denna token behöver write behörighet för målcontainern i lagringskontot. SAS-URI:et med fullständigt format: 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 för att konfigurera slutpunktsanslutningen i nästa avsnitt.

  1. Följ stegen i Skapa ett lagringskonto för att skapa ett lagringskonto i din Azure-prenumeration. Anteckna lagringskontots namn för senare användning.

  2. Följ stegen i Skapa en container för att skapa en container i det nya lagringskontot. Anteckna containernamnet för senare användning.

  3. Skapa sedan en SAS-token för ditt lagringskonto som slutpunkten kan använda för att komma åt den. Börja med att gå till ditt lagringskonto i Azure Portal (du hittar det efter namn i portalens sökfält).

  4. 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.

    Lagringskontosidan i Azure Portal

  5. 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. 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).

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

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

    Lagringskontosidan i Azure Portal visar alla inställningsval för att generera en SAS-token och markera knappen Generera SAS och anslutningssträng

  8. Detta genererar flera SAS- och anslutningssträngvärden längst ned på samma sida, under inställningsinställningarna. Rulla ned 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.

    Kopiera SAS-token som ska användas i hemligheten med dead letter.

Skapa slutpunkten för dead-letter

Om du vill skapa en slutpunkt som har dead-lettering aktiverat lägger du till följande parameter för dead letter i kommandot az dt endpoint create för Azure Digital Twins CLI.

Värdet för parametern är SAS-URI:en med den dead letter 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.

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

Lägg till den här parametern i slutet av kommandona för slutpunktsskapande från avsnittet Skapa slutpunkt tidigare för att skapa en slutpunkt av önskad typ som har dead-lettering aktiverat.

Du kan också skapa slutpunkter för dead letter med hjälp Azure Digital Twins API:er för kontrollplanet i stället för CLI. Det gör du genom att visa DigitalTwinsEndpoint-dokumentationen för att se hur du strukturerar begäran och lägger till parametrarna för dead letter.

Skapa en slutpunkt med slutbokstav med identitetsbaserad autentisering

Du kan också skapa en slutpunkt för dead-lettering som har identitetsbaserad autentisering för att använda slutpunkten med en hanterad identitet. Det här alternativet är endast tillgängligt för Service Bus slutpunkter av Service Bus (stöds inte för Event Grid).

Om du vill skapa den här typen av slutpunkt använder du samma CLI-kommandofrån tidigare för att skapa en slutpunkt med identitetsbaserad autentisering , med ett extra fält i JSON-nyttolasten för deadLetterUri en .

Här är de värden som du behöver för att ansluta till platshållarna i kommandot:

  • Azure-resurs-ID för din Azure Digital Twins instans
  • ett slutpunktsnamn
  • en slutpunktstyp
  • slutpunktsresursens namnområde
  • namnet på händelsehubben eller Service Bus ämnet
  • SAS-URI-information för dead letter: lagringskontonamn, containernamn
  • platsen för din Azure Digital Twins instans
az resource create --id <Azure-Digital-Twins-instance-Azure-resource-ID>/endpoints/<endpoint-name> --properties '{\"properties\": { \"endpointType\": \"<endpoint-type>\", \"authenticationType\": \"IdentityBased\", \"endpointUri\": \"sb://<endpoint-namespace>.servicebus.windows.net\", \"entityPath\": \"<name-of-event-hub-or-Service-Bus-topic>\", \"deadLetterUri\": \"https://<storage-account-name>.blob.core.windows.net/<container-name>\"}, \"location\":\"<instance-location>\" }' --is-full-object

Schema för meddelandelagring

När slutpunkten med dead lettering har ställts in lagras meddelanden med öppna meddelanden i följande format i ditt lagringskonto:

{container}/{endpoint-name}/{year}/{month}/{day}/{hour}/{event-ID}.json

Meddelanden med nya meddelanden matchar schemat för den ursprungliga händelse som var avsedd att levereras till den ursprungliga slutpunkten.

Här är ett exempel på ett meddelande med obokstav för ett meddelande om att skapa 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": "<yourInstance>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": "<yourInstance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Skapa en händelseväg

Förutsättning: Du måste skapa slutpunkter enligt beskrivningen tidigare i den här artikeln innan du kan gå vidare till att skapa en väg. Du kan fortsätta med att skapa en händelseväg när dina slutpunkter har slutfört inställningen.

Anteckning

Om du nyligen har distribuerat slutpunkterna kontrollerar du att distributionen är klar innan du försöker använda dem för en ny händelseväg. Om vägdistributionen misslyckas eftersom slutpunkterna inte är redo väntar du några minuter och försöker igen.

Om du skriptar det här flödet kanske du vill ta hänsyn till detta genom att skapa med 2–3 minuters väntetid för att slutpunktstjänsten ska slutföra distributionen innan du går vidare till vägkonfigurationen.

Om du vill skicka data Azure Digital Twins till en slutpunkt måste du definiera en händelseväg. Händelsevägar används för att ansluta händelseflödet i hela systemet och till underordnade tjänster.

En vägdefinition kan innehålla följande element:

  • Det vägnamn som du vill använda
  • Namnet på den slutpunkt som du vill använda
  • Ett filter som definierar vilka händelser som skickas till slutpunkten

Om det inte finns något vägnamn dirigeras inga meddelanden utanför Azure Digital Twins. Om det finns ett vägnamn och filtret true är dirigeras alla meddelanden till slutpunkten. Om det finns ett vägnamn och ett annat filter läggs till filtreras meddelanden baserat på filtret.

En väg bör tillåta att flera meddelanden och händelsetyper väljs.

Händelsevägar kan skapas med de Azure Digital Twins Api:erna för EventRoutes-dataplanet eller cli-kommandona az dt route. Resten av det här avsnittet går igenom skapandeprocessen.

Skapa vägar med API:er och C# SDK

Ett sätt att definiera händelsevägar är med API:erna för dataplanet. Exemplen i det här avsnittet använder .NET (C#) SDK.

CreateOrReplaceEventRouteAsync är DET SDK-anrop som används för att lägga till en händelseväg. Här är ett exempel på dess användning:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

Tips

Alla SDK-funktioner finns i synkrona och asynkrona versioner.

SDK-kod för exempel på händelseväg

Följande exempelmetod visar hur du skapar, listar och tar bort en händelseväg med C# SDK:

private static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

Skapa vägar med CLI

Vägar kan också hanteras med hjälp av az dt route-kommandon för Azure Digital Twins CLI.

Mer information om hur du använder CLI och vilka kommandon som är tillgängliga finns i Begrepp: Azure Digital Twins CLI-kommandouppsättning.

Filtrera händelser

Utan filtrering tar slutpunkter emot en mängd olika händelser från Azure Digital Twins:

  • Telemetri som uttjänats av digitala tvillingar med hjälp Azure Digital Twins tjänst-API
  • Meddelanden om ändring av tvillingegenskap som uttjänats för egenskapsändringar för en tvilling i Azure Digital Twins instansen
  • Livscykelhändelser som uttjänats när tvillingar eller relationer skapas eller tas bort

Du kan begränsa de händelser som skickas genom att lägga till ett filter för en slutpunkt i händelsevägen.

Anteckning

Filter är fallkänsliga och måste matcha nyttolastfallet.

För telemetrifilter innebär det att höljet måste matcha höljet i telemetrin som skickas av enheten, inte nödvändigtvis det hölje som definierats i tvillingmodellen.

Om du vill lägga till ett filter kan du använda en https://{Your-azure-digital-twins-host-name}/eventRoutes/{event-route-name}?api-version=2020-10-31 PUT-begäran i med följande brödtext:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

Här är flödesfiltren som stöds. Använd information i kolumnen Filtertextschema för att ersätta <filter-text> platshållaren i begärandetexten ovan.

Filternamn Description Filtrera textschema Värden som stöds
Sant/falskt Gör att du kan skapa en väg utan filtrering eller inaktivera en väg så att inga händelser skickas <true/false> true = vägen är aktiverad utan filtrering
false = vägen är inaktiverad
Typ Den typ av händelse som flödar genom din digitala tvillinginstans type = '<eventType>' Här är möjliga värden för händelsetyp:
Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
Microsoft.DigitalTwins.Twin.Update
Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
microsoft.iot.telemetry
Källa Namnet på Azure Digital Twins instansen source = '<host-name>' Här är möjliga värden för värdnamn:
För meddelanden:<yourDigitalTwinInstance>.api.<yourRegion>.digitaltwins.azure.net
För telemetri: <yourDigitalTwinInstance>.api.<yourRegion>.digitaltwins.azure.net/<twinId>
Ämne En beskrivning av händelsen i kontexten för händelsekällan ovan subject = '<subject>' Här är möjliga ämnesvärden:
För meddelanden: Ämnet är <twinid>
eller ett URI-format för ämnen som unikt identifieras av flera delar eller ID:er:
<twinid>/relationships/<relationshipid>
För telemetri: Ämnet är komponentsökvägen (om telemetrin genereras från en tvillingkomponent), till exempel comp1.comp2 . Om telemetrin inte genereras från en komponent är dess ämnesfält tomt.
Dataschema DTDL-modell-ID dataschema = '<model-dtmi-ID>' För telemetri: Dataschemat är modell-ID:t för tvillingen eller komponenten som skickar telemetrin. Till exempel dtmi:example:com:floor4;2
För meddelanden (skapa/ta bort): Dataschemat kan nås i meddelandetexten på $body.$metadata.$model .
För meddelanden (uppdatering): Dataschemat kan nås i meddelandetexten på $body.modelId
Innehållstyp Innehållstyp för datavärde datacontenttype = '<contentType>' Innehållstypen är application/json
Specifikationsversion Den version av händelseschemat som du använder specversion = '<version>' Versionen måste vara 1.0 . Detta anger CloudEvents-schemaversion 1.0
Meddelandetext Referera till en egenskap i data fältet för ett meddelande $body.<property> Exempel på meddelanden finns i Begrepp: Händelseaviseringar. Du kan referera till data valfri egenskap i fältet med hjälp av $body

Följande datatyper stöds som värden som returneras av referenser till data ovan:

Datatyp Exempel
Sträng STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
CONTAINS(subject, '<twinID>')
Integer $body.errorCode > 200
Dubbel $body.temperature <= 5.5
Bool $body.poweredOn = true
Null $body.prop != null

Följande operatorer stöds när du definierar flödesfilter:

Familj Operatorer Exempel
Logiskt AND, OR, ( ) (type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Jämförelse <, <=, >, >=, =, != $body.temperature <= 5.5

Följande funktioner stöds när du definierar flödesfilter:

Funktion Beskrivning Exempel
STARTS_WITH(x,y) Returnerar true om värdet x börjar med strängen y . STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y) Returnerar true om värdet x slutar med strängen y . ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y) Returnerar true om värdet x innehåller strängen y . CONTAINS(subject, '<twinID>')

När du implementerar eller uppdaterar ett filter kan det ta några minuter innan ändringen återspeglas i datapipelinen.

Övervaka händelsevägar

Routningsmått som antal, svarstid och felfrekvens kan visas i Azure Portal.

Från portalens startsida söker du efter din Azure Digital Twins instans för att hämta information om den. Välj alternativet Mått på Azure Digital Twins instansens navigeringsmeny till vänster för att öppna sidan Mått.

Skärmbild som visar måttsidan för Azure Digital Twins.

Härifrån kan du visa måtten för din instans och skapa anpassade vyer.

Mer information om Azure Digital Twins mått finns i How-to: View metrics with Azure Monitor.

Nästa steg

Läs om de olika typerna av händelsemeddelanden som du kan ta emot: