Creare endpoint in Gemelli digitali di Azure

Articolo
04/06/2023

Questo articolo illustra come creare un endpoint per gli eventi di Gemelli digitali di Azure utilizzando il portale di Azure o l'interfaccia della riga di comando di Azure. È anche possibile gestire gli endpoint con le API del piano di controllo DigitalTwinsEndpoint.

Il routing di notifiche degli eventi da Gemelli digitali di Azure ai servizi downstream o alle risorse di calcolo connesse è un processo in due passaggi: creare endpoint, quindi creare route eventi per inviare dati a tali endpoint. Questo articolo illustra il primo passaggio, la configurazione degli endpoint che possono ricevere gli eventi. Successivamente, è possibile creare route eventi che specificano gli eventi generati da Gemelli digitali di Azure consegnato agli endpoint.

Prerequisiti

È necessario un account Azure, che può essere configurato gratuitamente
È necessaria un'istanza di Gemelli digitali di Azure nella sottoscrizione di Azure. Se non si dispone già di un'istanza, è possibile crearne una seguendo la procedura descritta in Configurare un'istanza e l'autenticazione. Disporre a portata di mano dei seguenti valori di configurazione da utilizzare più avanti in questo articolo:
- Nome istanza
- Gruppo di risorse
Questi dettagli sono disponibili nel portale di Azure dopo aver configurato l'istanza.

Quindi seguire le istruzioni riportate di seguito se si intende usare l'interfaccia della riga di comando di Azure seguendo questa guida.

Preparare l'ambiente per l'interfaccia della riga di comando di Azure

Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.
Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
- Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.
- Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.
- Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Creare le risorse necessarie

Questi servizi sono i tipi supportati di endpoint che è possibile creare per l'istanza:

Argomento di Griglia di eventi
- Per gli endpoint Griglia di eventi sono supportati solo gli argomenti relativi a Griglia di eventi. I domini di Griglia di eventi non sono supportati come endpoint.
Hub Hub eventi
Argomento del bus di servizio

Per collegare un endpoint a Gemelli digitali di Azure, gli argomenti Griglia di eventi, hub eventi o Bus di servizio usato per l'endpoint deve esistere già.

Per vedere quali risorse è necessario configurare prima di creare l'endpoint usare il grafico seguente.

Tipo di endpoint	Risorse necessarie (collegate alle istruzioni di creazione)
Endpoint di Griglia di eventi	Argomento di Griglia di eventi *schema eventi deve essere Schema Griglia di eventi o Schema Eventi cloud v1.0
Endpoint di Hub eventi	Spazio dei nomi Hub eventi Hub eventi (Facoltativo) regola di autorizzazione per l'autenticazione basata su chiave
Endpoint del bus di servizio	Spazio dei nomi bus di servizio: Argomento del bus di servizio (Facoltativo) regola di autorizzazione per l'autenticazione basata su chiave

Creare l'endpoint

Dopo aver creato le risorse dell'endpoint, è possibile usarle per un endpoint di Gemelli digitali di Azure.

Portale
CLI

Per creare un nuovo endpoint, passare alla pagina dell'istanza nel portale di Azure (è possibile trovare l'istanza immettendo il nome nella barra di ricerca del portale).

Dal menu dell'istanza selezionare Endpoint. Poi dalla paginaEndpoints che segue selezionare + Crea un endpoint. In questo modo si aprirà la pagina Crea un endpoint, dove compilare i campi nei passaggi seguenti.
Immettere un nome per l'endpoint e scegliere il tipo di endpoint.
Completare gli altri dettagli necessari per il tipo di endpoint, inclusa la sottoscrizione e le risorse dell'endpoint descritte in precedenza.
1. Solo per Hub eventi e endpoint del bus di servizio, è necessario selezionare un tipo di autenticazione. È possibile usare l'autenticazione basata su chiave con una regola di autorizzazione creata in modo preliminare o un'identità gestita assegnata dal sistema o dall'utente. Per altre informazioni sull'uso delle opzioni di autenticazione delle identità, vedere Opzioni endpoint: autenticazione basata su identità.
Completare la creazione dell'endpoint selezionando Salva.

Dopo aver creato l'endpoint, è possibile verificare che l'endpoint sia stato creato correttamente controllando l'icona di notifica nella barra superiore del portale di Azure:

Screenshot della notifica per verificare la creazione di un endpoint nel portale di Azure.

Se la creazione dell'endpoint ha esito negativo, osservare il messaggio di errore e riprovare dopo alcuni minuti.

Inoltre è possibile visualizzare l'endpoint creato di nuovo nella pagina Endpoint per l'istanza di Gemelli digitali di Azure.

Gli argomenti Griglia di eventi, hub eventi o Bus di servizio ora è disponibile come endpoint in Gemelli digitali di Azure, con il nome scelto per l'endpoint. In genere si usa tale nome come destinazione di una route eventi, che è possibile creare in Creare route e filtri.

Gli esempi seguenti illustrano come creare endpoint usando il comandocreazione endpoint az dt per l'interfaccia della riga di comando di Gemelli digitali di Azure. Sostituire i segnaposto nei comandi con i dettagli delle proprie risorse.

Per creare un endpoint Griglia di eventi:

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>

Per creare un endpoint Hub eventi (autenticazione basata su chiave):

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>

Per creare un endpoint dell'argomento Bus di servizio (autenticazione basata su chiave):

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>

Dopo aver eseguito correttamente questi comandi, gli argomenti Griglia di eventi, hub eventi o Bus di servizio saranno disponibili come endpoint in Gemelli digitali di Azure, con il nome fornito con l'argomento --endpoint-name. In genere si usa tale nome come destinazione di una route eventi, che è possibile creare in Creare route e filtri.

Opzioni dell'endpoint: autenticazione basata su identità

Questa sezione descrive come usare un'identità gestita per un'istanza di Gemelli digitali di Azure durante l'inoltro di eventi alle destinazioni di routing supportate. La configurazione di un'identità gestita non è necessaria per il routing, ma consente all'istanza di accedere facilmente ad altre risorse protette di Microsoft Entra, ad esempio Hub eventi, destinazioni del Bus di servizio e Contenitore di Archiviazione di Azure. Le identità gestite possono essere assegnate dal sistema o assegnate dall'utente.

La parte restante di questa sezione illustra tre passaggi per configurare un endpoint con un'identità gestita.

1. Abilitare l'identità gestita per l'istanza

Usare le schede seguenti per istruzioni che corrispondono all'esperienza preferita.

Portale
CLI

Prima di tutto, assicurarsi di aver abilitato un'identità gestita per l'istanza di Gemelli digitali di Azure.

Inoltre, assicurarsi di avere il ruolo Proprietario dei dati di Gemelli digitali di Azure nell'istanza. Per istruzioni, vedere Configurare le autorizzazioni di accesso utente.

2. Assegnare ruoli di Azure all'identità

Dopo aver creato un'identità gestita per l'istanza di Gemelli digitali di Azure, è necessario assegnare i ruoli appropriati per l'autenticazione con diversi tipi di endpoint per il routing degli eventi alle destinazioni supportate. Questa sezione descrive le opzioni del ruolo e come assegnarle all'identità gestita.

Importante

Assicurarsi di completare questo passaggio. Senza di esso, l'identità non sarà in grado di accedere agli endpoint e gli eventi non verranno recapitati.

Ecco i ruoli minimi necessari all'identità di Gemelli digitali di Azure per accedere a un endpoint, a seconda del tipo di destinazione. Funzionano anche i ruoli con autorizzazioni più elevate (ad esempio ruoli di proprietario dei dati).

Destinazione	Ruolo di Azure
Hub eventi di Azure	Mittente dei dati di Hub eventi di Azure
Bus di servizio di Azure	Mittente dei dati del bus di servizio di Azure
Contenitore di archiviazione di Azure	Collaboratore ai dati del BLOB di archiviazione

Usare le schede seguenti per assegnare il ruolo usando l'esperienza preferita.

Portale
CLI

Per assegnare un ruolo all'identità, iniziare aprendo il portale di Azure in un browser.

Passare alla risorsa endpoint (hub eventi, argomento del bus di servizio o contenitore di archiviazione) cercandone il nome nella barra di ricerca del portale.
Seleziona Controllo di accesso (IAM).
Selezionare Aggiungi>Aggiungi assegnazione di ruolo per aprire la pagina Aggiungi assegnazione di ruolo.

Assegnare il ruolo desiderato all'identità gestita dell'istanza di Gemelli digitali di Azure usando le informazioni seguenti. Per la procedura dettagliata, vedere Assegnare ruoli di Azure usando il portale di Azure.

Impostazione	Valore
Ruolo	Selezionare il ruolo desiderato nelle opzioni.
Assegna accesso a	Identità gestita
Membri	Selezionare l'identità gestita assegnata dall'utente o dal sistema dell'istanza di Gemelli digitali di Azure a cui viene assegnato il ruolo. Un'identità assegnata dall'utente avrà il nome scelto al momento della creazione dell'identità e un'identità assegnata dal sistema avrà un nome che corrisponde al nome dell'istanza di Gemelli digitali di Azure.

È possibile aggiungere il parametro --scopes al comando az dt create per assegnare l'identità a uno o più ambiti con un ruolo specificato. Il comando con questo parametro può essere usato per la prima volta durante la creazione dell'istanza o successivamente passando il nome di un'istanza già esistente.

Ecco un esempio che crea un'istanza con un'identità gestita assegnata dal sistema e assegna tale identità a un ruolo personalizzato chiamato MyCustomRole in un hub eventi.

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

Per altri esempi di assegnazioni di ruolo con questo comando, vedere la documentazione di riferimento creazione az dt.

Inoltre è possibile usare il gruppo del comando assegnazione di ruolo az per creare e gestire i ruoli. Questo comando può essere usato per supportare altri scenari in cui non si vuole raggruppare l'assegnazione di ruolo con il comando create.

3. Creare l'endpoint con l'autenticazione basata su identità

Dopo aver configurato un'identità gestita per l'istanza di Gemelli digitali di Azure e aver assegnato i ruoli appropriati, è possibile creare gli endpoint che usano l'identità per l'autenticazione. Questa opzione è disponibile solo per Hub eventi ed endpoint di tipo Bus di servizio (non è supportato per Griglia di eventi).

Nota

Non è possibile modificare un endpoint già creato con l'identità basata su chiave per passare all'autenticazione basata su identità. Quando viene creato per la prima volta l'endpoint, è necessario scegliere il tipo di autenticazione.

Usare le schede seguenti per creare l'endpoint usando l'esperienza preferita.

Portale
CLI

Iniziare a seguire le istruzioni generali per creare un endpoint di Gemelli digitali di Azure.

Quando si arriva al passaggio del completamento dei dettagli necessari per il tipo di endpoint, selezionare Assegnato dal sistema o Assegnato dall'utente (anteprima) per il tipo di autenticazione.

Completare la configurazione dell'endpoint e selezionare Salva.

Le identità gestite vengono aggiunte a un endpoint aggiungendo parametri al comando az dt endpoint create usato per creare l'endpoint. (Per altre informazioni su questo comando, vedere la documentazione di riferimento o le istruzioni generali per creare un endpoint di Gemelli digitali di Azure.).

Usare il comando dell'interfaccia della riga di comando seguente per il tipo scelto di identità gestita.

Comando identità assegnato dal sistema

Per creare un endpoint che usa l'autenticazione assegnata dal sistema, specificare il tipo di autenticazione IdentityBased con il parametro --auth-type. L'esempio seguente illustra questa funzionalità per un endpoint di Hub eventi.

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

Comando identità assegnato dall'utente

Per creare un endpoint che usa l'autenticazione dell'identità assegnata dall'utente, specificare l'ID risorsa identità assegnata dall'utente con il parametro --user. L'esempio seguente illustra questa funzionalità per un endpoint di Hub eventi.

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>

Considerazioni sulla disabilitazione delle identità gestite

Poiché un'identità viene gestita separatamente dagli endpoint che la usano, è importante considerare gli effetti che le modifiche apportate all'identità o ai relativi ruoli possono avere negli endpoint nell'istanza di Gemelli digitali di Azure. Se l'identità è disabilitata o viene rimosso un ruolo necessario per un endpoint, l'endpoint può diventare inaccessibile e il flusso di eventi verrà interrotto.

Per continuare a usare un endpoint configurato con un'identità gestita che ora è stata disabilitata, è necessario eliminare l'endpoint e ricrearlo con un tipo di autenticazione diverso. Prima che gli eventi riprendano il processo di recapito all'endpoint dopo la modifica, potrebbe trascorrere fino a un'ora.

Opzioni endpoint: messaggi non recapitabili

Quando un endpoint non può recapitare un evento entro un determinato periodo di tempo o dopo aver tentato di recapitare l'evento un determinato numero di volte, può inviare l'evento non recapitato a un account di archiviazione. Questo processo è noto come inserimento nella coda di eventi non recapitabili.

È possibile configurare le risorse di archiviazione necessarie usando il portale di Azure o l'interfaccia della riga di comando di Gemelli digitali di Azure. Tuttavia, per creare un endpoint con messaggi non recapitabili abilitati, è necessario usare l'interfaccia della riga di comando di Gemelli digitali di Azure o le API del piano di controllo.

Per altre informazioni sui messaggi non recapitabili, vedere Endpoint e route eventi. Per istruzioni su come configurare un endpoint con messaggi non recapitabili, continuare a seguire il resto di questa sezione.

Configurare le risorse di archiviazione

Prima di impostare la posizione dei messaggi non recapitabili, è necessario disporre di un account di archiviazione con un contenitore configurato nell'account Azure.

Si fornirà l'URI per questo contenitore durante la creazione dell'endpoint in un secondo momento. Il percorso dei messaggi non recapitabili verrà fornito all'endpoint come URI del contenitore con un token di firma di accesso condiviso. Tale token richiede l'autorizzazione write per il contenitore di destinazione all'interno dell'account di archiviazione. L'URI di firma di accesso condiviso con caratteri non recapitabili completamente formato sarà nel formato: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Seguire questa procedura per configurare queste risorse di archiviazione nell'account Azure, per prepararsi a configurare la connessione all'endpoint nella sezione successiva.

Seguire la procedura descritta in Creare un account di archiviazione, per creare un account di archiviazione nella sottoscrizione di Azure. Prendere nota del nome dell'account di archiviazione da usare in un secondo momento.
Seguire la procedura descritta in Creare un contenitore, per creare un contenitore all'interno del nuovo account di archiviazione. Prendere nota del nome del contenitore per usarlo in un secondo momento.

Creare un token di firma di accesso condiviso

Creare quindi un token di firma di accesso condiviso per l'account di archiviazione che l'endpoint può usare per accedervi.

Portale
CLI

Per iniziare, passare all'account di archiviazione nel portale di Azure (è possibile trovarlo in base al nome con la barra di ricerca del portale).
Nella pagina account di archiviazione scegliere il collegamento Firma di accesso condiviso nella barra di spostamento a sinistra, per avviare la configurazione del token di firma di accesso condiviso.
Nella pagina di firma di accesso condiviso, in Servizi consentiti e Tipi di risorse consentiti, selezionare le impostazioni desiderate. È necessario selezionare almeno una casella in ogni categoria. In Autorizzazioni consentite, scegliere Scrittura (se si desidera, è possibile anche selezionare altre autorizzazioni).
Impostare i valori desiderati per le impostazioni rimanenti.
Al termine, selezionare il pulsante Genera stringa di connessione e firma di accesso condiviso, per generare il token di firma di accesso condiviso.
In questo modo verranno generati diversi valori di stringa di connessione e firma di accesso condiviso nella parte inferiore della stessa pagina, sotto le selezioni delle impostazioni. Scorrere verso il basso per visualizzare i valori e usare l'icona Copia negli Appunti per copiare il valore del token di firma di accesso condiviso. Salvare e usare in un secondo momento.

Recuperare le chiavi dell'account di archiviazione usando il comando seguente e copiare il valore per una delle chiavi:
```
az storage account keys list --account-name <storage-account-name>
```
Selezionare una data di scadenza e generare il token di firma di accesso condiviso per l'account di archiviazione usando il comando seguente:
```
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
```
L'output di questo comando è il token di firma di accesso condiviso. Copiare il valore del token di firma di accesso condiviso da usare in un secondo momento.

Nota

Questo comando include i servizi "blob", "file", "coda" e "tabella"; un tipo di risorsa "oggetto" e consente le autorizzazioni di "scrittura" .

Per altre informazioni sul comando az storage account generate-sas e sui relativi parametri, vedere le informazioni di riferimento dell'interfaccia della riga di comando di Azure.

Creare l'endpoint di messaggi non recapitabili

Portale
CLI

Per creare un endpoint con messaggi non recapitabili abilitati, è necessario usare i comandi dell'interfaccia della riga di comando o le API del piano di controllo per creare l'endpoint, anziché il portale di Azure.

Per istruzioni su come creare questo tipo di endpoint con l'interfaccia della riga di comando di Azure, passare alla scheda dell'interfaccia della riga di comando in questa sezione.

Per creare un endpoint con messaggi non recapitabili abilitati, aggiungere il parametro --deadletter-sas-uri al comando creazione endpoint az dt che crea un endpoint.

Il valore per il parametro è l'URI di firma di accesso condiviso di messaggi non recapitabili costituito dal nome dell'account di archiviazione, dal nome del contenitore e dal token di firma di accesso condiviso raccolti nella sezione precedente. Questo parametro crea l'endpoint con l'autenticazione basata su chiave. Di seguito è riportato l'aspetto del parametro:

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

Suggerimento

Per creare un endpoint di messaggi non recapitabili con l'autenticazione basata su identità, aggiungere sia il parametro di messaggi non recapitabili di questa sezione che il parametro di identità gestito appropriato allo stesso comando.

Inoltre è possibile creare endpoint di messaggi non recapitabili usando le API del piano di controllo di Gemelli digitali di Azure anziché l'interfaccia della riga di comando. A tale scopo, visualizzare la documentazione di DigitalTwinsEndpoint per informazioni su come strutturare la richiesta e aggiungere i parametri dei messaggi non recapitabili.

Schema di archiviazione dei messaggi

Dopo aver configurato l'endpoint con messaggi non recapitabili, i messaggi non recapitabili verranno archiviati nel formato seguente nell'account di archiviazione:

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

I messaggi non recapitabili corrispondono allo schema dell'evento originale che deve essere recapitato all'endpoint originale.

Ecco un esempio di messaggio non recapitato per una notifica di creazione di gemello digitale:

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

Passaggi successivi

Per inviare effettivamente dati da Gemelli digitali di Azure a un endpoint, è necessario definire una route eventi. Queste route consentono agli sviluppatori di collegare il flusso di eventi, attraverso il sistema e fino ai servizi downstream. Una singola route può consentire la selezione di più notifiche e tipi di evento. Continuare a creare una route eventi all'endpoint in Creare route e filtri.

Condividi tramite