Vytváření koncových bodů ve službě Azure Digital Twins

Tento článek vysvětluje, jak vytvořit koncový bod pro události Azure Digital Twin pomocí webu Azure Portal nebo Azure CLI. Koncové body můžete spravovat také pomocí rozhraní API řídicí roviny DigitalTwinsEndpoint.

Směrování oznámení událostí z Azure Digital Twins do podřízených služeb nebo připojených výpočetních prostředků je dvoustupňový proces: vytvoření koncových bodů a následné vytvoření tras událostí pro odesílání dat do těchto koncových bodů. Tento článek popisuje první krok nastavení koncových bodů, které můžou přijímat události. Později můžete vytvořit trasy událostí, které určují, které události vygenerované službou Azure Digital Twins se doručí do koncových bodů.

Předpoklady

• Budete potřebovat účet Azure, který si můžete zdarma nastavit.

• Ve svém předplatném Azure budete potřebovat instanci Azure Digital Twins. Pokud ještě instanci nemáte, můžete ji vytvořit pomocí kroků v části Nastavení instance a ověřování. Můžete použít následující hodnoty z nastavení, které můžete použít dále v tomto článku:

  • Název instance
  • Skupina prostředků

  Tyto podrobnosti najdete na webu Azure Portal po nastavení instance.

  

V dalším kroku postupujte podle následujících pokynů, pokud chcete použít Azure CLI a postupujte podle této příručky.

Příprava prostředí pro rozhraní příkazového řádku Azure

• Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.

  

• Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

  • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.

  • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.

  • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Vytvoření požadovaných prostředků

Tyto služby jsou podporované typy koncových bodů, které můžete vytvořit pro svou instanci:

• Téma Event Gridu
  • U koncových bodů Event Gridu se podporují jenom témata event Gridu. Domény Event Gridu nejsou podporované jako koncové body.
• Centrum Event Hubs
• Téma služby Service Bus

Pokud chcete propojit koncový bod se službou Azure Digital Twins, tématem Event Gridu, centrem událostí nebo tématem služby Service Bus, které používáte pro koncový bod, už musí existovat.

Následující graf vám ukáže, jaké prostředky by se měly nastavit před vytvořením koncového bodu.

Typ koncového bodu	Požadované prostředky (propojené s pokyny k vytvoření)
Koncový bod Event Gridu	Téma Event Gridu *Schéma událostí musí být schéma event Gridu nebo schéma cloudové události verze 1.0.
Koncový bod služby Event Hubs	Obor názvů služby Event Hubs Centrum událostí (Volitelné) autorizační pravidlo pro ověřování na základě klíčů
Koncový bod služby Service Bus	Obor názvů služby Service Bus Téma služby Service Bus (Volitelné) autorizační pravidlo pro ověřování na základě klíčů

Vytvoření koncového bodu

Po vytvoření prostředků koncového bodu je můžete použít pro koncový bod Azure Digital Twins.

Azure Portal

Pokud chcete vytvořit nový koncový bod, přejděte na stránku vaší instance na webu Azure Portal (instanci najdete zadáním jejího názvu do panelu hledání na portálu).

1. V nabídce instance vyberte Koncové body. Potom na následující stránce Koncové body vyberte + Vytvořit koncový bod. Tím se otevře stránka Vytvořit koncový bod , kde vyplníte pole v následujících krocích.

   

2. Zadejte název koncového bodu a zvolte typ koncového bodu.

3. Dokončete další podrobnosti potřebné pro váš typ koncového bodu, včetně vašeho předplatného a prostředků koncového bodu popsaných výše.

   1. Pouze pro koncové body služby Event Hubs a Service Bus musíte vybrat typ ověřování. Ověřování na základě klíčů můžete použít s předem vytvořeným autorizačním pravidlem nebo spravovanou identitou přiřazenou systémem nebo přiřazenou uživatelem. Další informace o použití možností ověřování identit najdete v tématu Možnosti koncového bodu: Ověřování na základě identity.

   

4. Dokončete vytváření koncového bodu výběrem možnosti Uložit.

Po vytvoření koncového bodu můžete ověřit, že se koncový bod úspěšně vytvořil, a to tak, že zkontrolujete ikonu oznámení na horním panelu webu Azure Portal:

Pokud se vytvoření koncového bodu nezdaří, podívejte se na chybovou zprávu a zkuste to znovu za několik minut.

Můžete si také prohlédnout koncový bod, který byl vytvořen zpět na stránce Koncové body pro vaši instanci služby Azure Digital Twins.

Teď je téma Event Gridu, centrum událostí nebo téma služby Service Bus dostupné jako koncový bod ve službě Azure Digital Twins pod názvem, který jste zvolili pro koncový bod. Tento název obvykle použijete jako cíl trasy události, kterou můžete vytvořit v části Vytvořit trasy a filtry.

Rozhraní příkazového řádku

Následující příklady ukazují, jak vytvořit koncové body pomocí příkazu az dt endpoint create pro Azure Digital Twins CLI. Zástupné symboly v příkazech nahraďte podrobnostmi o vlastních prostředcích.

Vytvoření koncového bodu Event Gridu:

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>

Vytvoření koncového bodu služby Event Hubs (ověřování založené na klíči):

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>

Vytvoření koncového bodu tématu služby Service Bus (ověřování založené na klíči):

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>

Po úspěšném spuštění těchto příkazů bude téma Event Gridu, centrum událostí nebo téma služby Service Bus dostupné jako koncový bod ve službě Azure Digital Twins pod názvem, který jste zadali s argumentem --endpoint-name . Tento název obvykle použijete jako cíl trasy události, kterou můžete vytvořit v části Vytvořit trasy a filtry.

Možnosti koncového bodu: Ověřování na základě identity

Tato část popisuje, jak používat spravovanou identitu pro instanci služby Azure Digital Twins při předávání událostí do podporovaných cílů směrování. Nastavení spravované identity se pro směrování nevyžaduje, ale může pomoct instanci snadno přistupovat k dalším prostředkům chráněným Microsoft Entra, jako jsou Event Hubs, cíle služby Service Bus a kontejner Azure Storage. Spravované identity můžou být přiřazené systémem nebo uživatelem.

Zbývající část této části vás provede třemi kroky pro nastavení koncového bodu se spravovanou identitou.

1. Povolení spravované identity pro instanci

Následující karty vám použijí pokyny, které odpovídají vašemu preferovanému prostředí.

Azure Portal

Nejprve se ujistěte, že jste pro instanci služby Azure Digital Twins povolili spravovanou identitu .

Ujistěte se také, že máte v instanci roli Vlastník dat Služby Azure Digital Twins. Pokyny najdete v tématu Nastavení uživatelských přístupových oprávnění.

Rozhraní příkazového řádku

Nejprve se ujistěte, že jste pro instanci služby Azure Digital Twins povolili spravovanou identitu .

Ujistěte se také, že máte v instanci roli Vlastník dat Služby Azure Digital Twins. Pokyny najdete v tématu Nastavení uživatelských přístupových oprávnění.

2. Přiřazení rolí Azure k identitě

Po vytvoření spravované identity pro vaši instanci Azure Digital Twins budete muset přiřadit příslušné role k ověření s různými typy koncových bodů pro směrování událostí do podporovaných cílů. Tato část popisuje možnosti role a způsob jejich přiřazení ke spravované identitě.

Důležité

Nezapomeňte tento krok dokončit. Bez ní nebude identita mít přístup ke koncovým bodům a události se nedoručí.

Tady jsou minimální role, které vaše identita Azure Digital Twins potřebuje pro přístup ke koncovému bodu v závislosti na typu cíle. Role s vyššími oprávněními (jako jsou role vlastníka dat) budou fungovat také.

Cíl	Role Azure
Azure Event Hubs	Odesílatel dat služby Azure Event Hubs
Azure Service Bus	Odesílatel dat Azure Service Bus
Kontejner úložiště Azure	Přispěvatel dat objektů blob úložiště

Pomocí karet níže přiřaďte roli podle svého preferovaného prostředí.

Azure Portal

Pokud chcete k identitě přiřadit roli, začněte otevřením webu Azure Portal v prohlížeči.

1. Přejděte k prostředku koncového bodu (centrum událostí, téma služby Service Bus nebo kontejner úložiště) tak, že na panelu hledání na portálu vyhledáte jeho název.

2. Vyberte Řízení přístupu (IAM) .

3. Výběrem možnosti Přidat>přiřazení role otevřete stránku Přidat přiřazení role.

4. Pomocí následujících informací přiřaďte požadovanou roli ke spravované identitě vaší instance služby Azure Digital Twins. Podrobný postup najdete v tématu Přiřazování rolí Azure s využitím webu Azure Portal.

   Nastavení	Hodnota
   Role	V možnostech vyberte požadovanou roli.
   Přiřadit přístup k	Spravovaná identita
   Členové	Vyberte spravovanou identitu přiřazenou uživatelem nebo systémem přiřazenou vaší instanci služby Azure Digital Twins, která má přiřazenou roli. Identita přiřazená uživatelem bude mít název, který jste zvolili při vytváření identity, a identita přiřazená systémem bude mít název, který odpovídá názvu vaší instance služby Azure Digital Twins.

   

Rozhraní příkazového řádku

Parametr můžete přidat --scopes do az dt create příkazu a přiřadit identitu k jednomu nebo více oborům se zadanou rolí. Příkaz s tímto parametrem lze použít při prvním vytvoření instance nebo později předáním názvu instance, která již existuje.

Tady je příklad, který vytvoří instanci se spravovanou identitou přiřazenou systémem a přiřadí ji vlastní roli volanou MyCustomRole v centru událostí.

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

Další příklady přiřazení rolí pomocí tohoto příkazu najdete v referenční dokumentaci az dt create.

K vytváření a správě rolí můžete také použít skupinu příkazů az role assignment . Tento příkaz lze použít k podpoře jiných scénářů, kdy nechcete seskupit přiřazení role pomocí příkazu create.

3. Vytvoření koncového bodu s ověřováním na základě identity

Po nastavení spravované identity pro vaši instanci Azure Digital Twins a jeho přiřazení odpovídajících rolí můžete vytvořit koncové body, které používají identitu k ověřování. Tato možnost je dostupná jenom pro koncové body služby Event Hubs a Service Bus (nepodporuje se pro Event Grid).

Poznámka:

Nelze upravit koncový bod, který už byl vytvořen s identitou založenou na klíči, aby se změnil na ověřování založené na identitě. Při prvním vytvoření koncového bodu musíte zvolit typ ověřování.

Pomocí karet níže vytvořte koncový bod s použitím preferovaného prostředí.

Azure Portal

Začněte podle obecných pokynů k vytvoření koncového bodu Azure Digital Twins.

Když se dostanete k kroku dokončení podrobností požadovaných pro váš typ koncového bodu, vyberte typ ověřování přiřazený systémem nebo přiřazený uživatelem (Preview ).

Dokončete nastavení koncového bodu a vyberte Uložit.

Rozhraní příkazového řádku

Spravované identity se přidají do koncového bodu přidáním parametrů do az dt endpoint create příkazu, který se používá k vytvoření koncového bodu. (Další informace o tomto příkazu najdete v referenční dokumentaci nebo obecných pokynech k vytvoření koncového bodu Azure Digital Twins.)

Pro zvolený typ spravované identity použijte následující příkaz rozhraní příkazového řádku.

Příkaz identity přiřazené systémem

Pokud chcete vytvořit koncový bod, který používá ověřování přiřazené systémem, zadejte IdentityBased typ ověřování pomocí parametru --auth-type . Následující příklad ukazuje tuto funkci pro koncový bod služby Event Hubs.

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

Příkaz identity přiřazené uživatelem

Pokud chcete vytvořit koncový bod, který používá ověřování identit přiřazené uživatelem, zadejte ID prostředku identity přiřazené uživatelem pomocí parametru --user . Následující příklad ukazuje tuto funkci pro koncový bod služby Event Hubs.

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>

Důležité informace o zákazu spravovaných identit

Vzhledem k tomu, že se identita spravuje odděleně od koncových bodů, které ji používají, je důležité zvážit účinky, které můžou mít všechny změny identity nebo jejích rolí na koncových bodech ve vaší instanci Azure Digital Twins. Pokud je identita zakázaná nebo se z něj odebere nezbytná role, může se koncový bod stát nepřístupným a tok událostí se přeruší.

Pokud chcete dál používat koncový bod, který se nastavil se spravovanou identitou, která je teď zakázaná, musíte koncový bod odstranit a vytvořit ho znovu s jiným typem ověřování. Obnovení doručování událostí do koncového bodu po této změně může trvat až 1 hodinu.

Možnosti koncového bodu: Nedoručované dopisy

Pokud koncový bod nemůže událost doručit během určitého časového období nebo po pokusu o doručení události určitou dobu, může odeslat nedoručenou událost do účtu úložiště. Tento proces se označuje jako nedoručených dopisů.

Potřebné prostředky úložiště můžete nastavit pomocí webu Azure Portal nebo azure Digital Twins CLI. Pokud ale chcete vytvořit koncový bod s povoleným nedoručováním, budete muset použít rozhraní příkazového řádku Azure Digital Twins nebo rozhraní API řídicí roviny.

Další informace o nedoručených dopisech najdete v tématu Koncové body a trasy událostí. Pokyny k nastavení koncového bodu s nedoručenými dopisy najdete ve zbývající části této části.

Nastavení prostředků úložiště

Před nastavením umístění nedoručených dopisů musíte mít účet úložiště s kontejnerem nastaveným ve vašem účtu Azure.

Při pozdějším vytvoření koncového bodu zadáte identifikátor URI pro tento kontejner. Umístění nedoručených dopisů se koncovému bodu poskytne jako identifikátor URI kontejneru s tokenem SAS. Tento token potřebuje write oprávnění pro cílový kontejner v rámci účtu úložiště. Identifikátor URI SAS s úplným formátem nedoručených písmen bude ve formátu: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Pomocí následujícího postupu nastavte tyto prostředky úložiště ve svém účtu Azure a připravte se na nastavení připojení koncového bodu v další části.

1. Podle pokynů v části Vytvoření účtu úložiště vytvořte účet úložiště ve vašem předplatném Azure. Poznamenejte si název účtu úložiště, abyste ho mohli použít později.
2. Postupujte podle kroků v části Vytvoření kontejneru a vytvořte kontejner v rámci nového účtu úložiště. Poznamenejte si název kontejneru, abyste ho mohli použít později.

Vytvoření tokenu SAS

Dále vytvořte token SAS pro svůj účet úložiště, který koncový bod může použít pro přístup k němu.

Azure Portal

1. Začněte tím, že přejdete na svůj účet úložiště na webu Azure Portal (najdete ho podle názvu pomocí vyhledávacího panelu portálu).

2. Na stránce účtu úložiště zvolte odkaz sdílený přístupový podpis na levém navigačním panelu a začněte nastavovat token SAS.

   

3. Na stránce Se sdíleným přístupovým podpisem v části Povolené služby a Povolené typy prostředků vyberte požadovaná nastavení. Budete muset vybrat aspoň jedno pole v každé kategorii. V části Povolená oprávnění zvolte Zapisovat (můžete také vybrat další oprávnění, pokud chcete).

4. Nastavte požadované hodnoty pro zbývající nastavení.

5. Až budete hotovi, vyberte tlačítko Generovat SAS a připojovací řetězec a vygenerujte token SAS.

   

6. Tím se vygeneruje několik hodnot SAS a připojovací řetězec v dolní části stejné stránky pod výběry nastavení. Posuňte se dolů, abyste zobrazili hodnoty a pomocí ikony Kopírovat do schránky zkopírujte hodnotu tokenu SAS. Uložte ho, abyste ho mohli použít později.

   

Rozhraní příkazového řádku

1. Pomocí následujícího příkazu načtěte klíče účtu úložiště a zkopírujte hodnotu jednoho z vašich klíčů:

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

2. Vyberte datum vypršení platnosti a pomocí následujícího příkazu vygenerujte token SAS pro váš účet úložiště:

   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
   

   Výstupem tohoto příkazu je token SAS. Zkopírujte hodnotu tokenu SAS, abyste ji mohli použít později.

   Poznámka:

   Tento příkaz zahrnuje služby "b lob", "file", "queue" a "table", typ prostředku "object" a povolí oprávnění "write".

   Další informace o az storage account generate-sas příkazu a jeho parametrech najdete v referenčních informacích k Azure CLI.

Vytvoření koncového bodu nedoručených písmen

Azure Portal

Pokud chcete vytvořit koncový bod s povoleným nedoručováním, musíte místo webu Azure Portal použít příkazy rozhraní příkazového řádku nebo rozhraní API řídicí roviny .

Pokyny k vytvoření tohoto typu koncového bodu pomocí Azure CLI najdete v této části na kartě rozhraní příkazového řádku.

Rozhraní příkazového řádku

Pokud chcete vytvořit koncový bod s povoleným nedoručováním, přidejte --deadletter-sas-uri parametr do příkazu az dt endpoint create , který vytvoří koncový bod.

Hodnota parametru je identifikátor URI SAS nedoručených písmen tvořený názvem účtu úložiště, názvem kontejneru a tokenem SAS, který jste shromáždili v předchozí části. Tento parametr vytvoří koncový bod s ověřováním na základě klíče. Takto vypadá parametr:

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

Tip

Pokud chcete vytvořit koncový bod nedoručených dopisů s ověřováním založeným na identitě, přidejte parametr nedoručených písmen z této části i příslušný parametr spravované identity do stejného příkazu.

Koncové body nedoručených písmen můžete vytvořit také pomocí rozhraní API řídicí roviny služby Azure Digital Twins místo rozhraní příkazového řádku. Pokud to chcete udělat, podívejte se do dokumentace k DigitalTwinsEndpointu, kde se dozvíte, jak strukturovat požadavek a přidat parametry nedoručených písmen.

Schéma úložiště zpráv

Po nastavení koncového bodu s nedoručovanými dopisy budou zprávy s nedoručovanými dopisy uložené v následujícím formátu ve vašem účtu úložiště:

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

Nedoručené zprávy budou odpovídat schématu původní události, která byla určena k doručení do původního koncového bodu.

Tady je příklad zprávy o nedoručených zprávách pro oznámení o vytvoření dvojčete:

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

Další kroky

Pokud chcete skutečně odesílat data z Azure Digital Twins do koncového bodu, budete muset definovat trasu události. Tyto trasy umožňují vývojářům připojit tok událostí v celém systému a do podřízených služeb. Jedna trasa může povolit výběr více oznámení a typů událostí. Pokračujte vytvořením trasy události do koncového bodu v části Vytvoření tras a filtrů.