Creare endpoint in Gemelli digitali di Azure
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.
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.
- 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:
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.
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.
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.
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. 
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.
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.
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.
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.
Creare l'endpoint di messaggi non recapitabili
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.
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.