Creare endpoint in Gemelli digitali di Azure
Questo articolo illustra come creare un endpoint per gli eventi di Gemelli digitali di Azure usando 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 delle 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 di 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 di eventi che specificano gli eventi generati da Gemelli digitali di Azure recapitati 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. Avere i valori seguenti da configurare a portata di mano da usare più avanti in questo articolo:
- Nome istanza
- Gruppo di risorse
Questi dettagli sono disponibili nella portale di Azure dopo la configurazione dell'istanza.
Seguire quindi 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 per 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 con l'interfaccia della riga di comando di Azure.
Quando richiesto, installare l'estensione dell'interfaccia della riga di comando di Azure al primo uso. 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 di Griglia di eventi sono supportati solo gli argomenti di Griglia di eventi. I domini di Griglia di eventi non sono supportati come endpoint.
- Hub eventi
- Argomento del bus di servizio
Per collegare un endpoint a Gemelli digitali di Azure, l'argomento griglia di eventi, l'hub eventi o bus di servizio argomento 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 di 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 immettendone il nome nella barra di ricerca del portale).
Dal menu dell'istanza selezionare Endpoint. Nella pagina Endpoints (Endpoint) che segue selezionare + Crea un endpoint. In questo modo si aprirà la pagina Crea un endpoint , in cui verranno compilati 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 bus di servizio endpoint, è 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 assegnata 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 controllando l'icona di notifica nella parte superiore portale di Azure barra:
Se la creazione dell'endpoint ha esito negativo, osservare il messaggio di errore e riprovare dopo alcuni minuti.
È anche possibile visualizzare l'endpoint creato di nuovo nella pagina Endpoint per l'istanza di Gemelli digitali di Azure.
Ora l'argomento griglia di eventi, l'hub eventi o bus di servizio argomento è disponibile come endpoint in Gemelli digitali di Azure, con il nome scelto per l'endpoint. In genere si userà tale nome come destinazione di una route di 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, bus di servizio destinazioni e Archiviazione di Azure Contenitore. 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.
Assicurarsi prima di tutto di aver abilitato un'identità gestita per l'istanza di Gemelli digitali di Azure.
Assicurarsi anche di avere il ruolo proprietario dei dati di Gemelli digitali di Azure nell'istanza di . Per istruzioni, vedere Configurare le autorizzazioni di accesso utente.
2. Assegnare i 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. Anche i ruoli con autorizzazioni più elevate (ad esempio i ruoli di proprietario dei dati) funzioneranno.
| Destination | 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, bus di servizio argomento 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 assegnata 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 sull'identità
Dopo aver configurato un'identità gestita per l'istanza di Gemelli digitali di Azure e assegnargli i ruoli appropriati, è possibile creare gli endpoint che usano l'identità per l'autenticazione. Questa opzione è disponibile solo per Hub eventi e 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à. È necessario scegliere il tipo di autenticazione quando viene creato per la prima volta l'endpoint.
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 lo 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 di eventi. Per istruzioni su come configurare un endpoint con messaggi non recapitabili, continuare con il resto di questa sezione.
Configurare le risorse di archiviazione
Prima di impostare la posizione dei messaggi non recapitabili, è necessario avere 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 write l'autorizzazione 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 nella portale di Azure (è possibile trovarla 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 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 (è anche possibile selezionare altre autorizzazioni se si desidera).
Impostare i valori desiderati per le impostazioni rimanenti.
Al termine, selezionare il pulsante Genera firma di accesso condiviso e stringa di connessione per generare il token di firma di accesso condiviso.
In questo modo verranno generati diversi valori di firma di accesso condiviso e stringa di connessione 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 . Salvarlo per usarlo 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 per 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 del gemello:
{
"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 di 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 di eventi all'endpoint in Creare route e filtri.