Condividi tramite

Esercitazione: Distribuire l'anteprima di Gemelli digitali di Azure e configurare un grafico spaziale

  • Articolo

Importante

È stata rilasciata una nuova versione del servizio Gemelli digitali di Azure. Alla luce delle funzionalità espanse del nuovo servizio, il servizio Gemelli digitali di Azure originale (descritto in questo set di documentazione) è stato ritirato.

Per visualizzare la documentazione per il nuovo servizio, vedere la documentazione attiva di Gemelli digitali di Azure.

È possibile usare il servizio di Anteprima di Gemelli digitali di Azure per riunire persone, luoghi e dispositivi in un sistema spaziale coerente. Questa serie di esercitazioni illustra come usare Gemelli digitali di Azure per determinare l'occupazione di una stanza con condizioni ottimali di temperatura e qualità dell'aria.

Queste esercitazioni illustrano in modo dettagliato un'applicazione console .NET per creare uno scenario costituito da un palazzo di uffici, con più piani e stanze su ogni piano. Le stanze contengono dispositivi, con sensori collegati che rilevano il movimento, la temperatura ambiente e la qualità dell'aria.

Si apprenderà come replicare le entità e le aree fisiche nell'edificio come oggetti digitali usando il servizio Gemelli digitali di Azure. Verranno simulati gli eventi dei dispositivi usando un'altra applicazione console. Quindi, si apprenderà come monitorare gli eventi provenienti da tali entità e aree fisiche quasi in tempo reale.

Un amministratore di un ufficio può usare queste informazioni per aiutare un dipendente che lavora in questo edifico a prenotare le sale riunioni con condizioni ottimali. Un responsabile delle strutture dell'ufficio può usare la configurazione per ottenere le tendenze di utilizzo delle stanze e monitorare le condizioni lavorative a scopo di manutenzione.

Nella prima esercitazione di questa serie si apprenderà come:

  • Distribuire Gemelli digitali
  • Concedere autorizzazioni all'app
  • Modificare un'app di esempio di Gemelli digitali
  • Effettuare il provisioning dell'edificio

Queste esercitazioni usano e modificano gli stessi esempi usati nella guida introduttiva alla ricerca di stanze disponibili per fornire informazioni più dettagliate e approfondite sui concetti.

Prerequisiti

  • Una sottoscrizione di Azure. Se non si ha un account Azure, creare un account gratuito.

  • .NET Core SDK. Gli esempi di Gemelli digitali di Azure usati in queste esercitazioni sono scritti in C#. Assicurarsi di installare .NET Core SDK versione 2.1.403 o successiva nel computer di sviluppo per compilare ed eseguire l'esempio. Controllare se nel computer è installata la versione corretta eseguendo dotnet --version in una finestra di comando.

  • Visual Studio Code per esplorare il codice di esempio.

Distribuire Gemelli digitali

Usare i passaggi in questa sezione per creare una nuova istanza del servizio Gemelli digitali di Azure. Per ogni sottoscrizione può essere creata solo un'istanza. Se c'è già un'istanza in esecuzione, passare alla sezione successiva.

  1. Accedere al portale di Azure.

  2. Selezionare la barra laterale Home, quindi + Crea una risorsa.

    Espandere la barra laterale home, quindi selezionare + Crea una risorsa

  3. Cercare gemelli digitali e selezionare Gemelli digitali.

    Selezioni per la creazione di una nuova istanza di Gemelli digitali

    In alternativa, selezionare Internet delle cose e Gemelli digitali (anteprima).

  4. Selezionare Crea per avviare il processo di distribuzione.

    Creare e confermare la distribuzione della risorsa

  5. Nel riquadro Gemelli digitali immettere le informazioni seguenti:

    • Nome risorsa: creare un nome univoco per l'istanza di Gemelli digitali.

    • Sottoscrizione: scegliere la sottoscrizione da usare per creare questa istanza di Gemelli digitali.

    • Gruppo di risorse: selezionare o creare un gruppo di risorse per l'istanza di Gemelli digitali.

    • Località: selezionare la posizione più vicina ai dispositivi.

      Riquadro Gemelli digitali con informazioni immesse

  6. Rivedere le informazioni relative a Gemelli digitali e quindi selezionare Crea. La creazione dell'istanza di Gemelli digitali può richiedere qualche minuto. È possibile monitorare lo stato di avanzamento nel riquadro Notifiche.

  7. Aprire il riquadro Panoramica dell'istanza di Gemelli digitali. Si noti il collegamento sotto API Gestione. Il formato dell'URL dell'API di gestione è:

    https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

    Questo URL consente di passare alla documentazione dell'API REST di Gemelli digitali di Azure appropriata per l'istanza. Per informazioni su come leggere e usare la documentazione di questa API, leggere How to use Azure Digital Twins Swagger (Come usare Swagger di Gemelli digitali). Copiare e modificare il formato dell'URL dell'API di gestione in questo modo:

    https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/

    L'applicazione userà l'URL modificato come URL di base per l'accesso all'istanza. Copiare l'URL modificato in un file temporaneo. Questo URL servirà nella sezione successiva.

    Panoramica dell'API di gestione

Concedere autorizzazioni all'app

Gemelli digitali usa Azure Active Directory (Azure AD) per controllare l'accesso in lettura/scrittura al servizio. Qualsiasi applicazione che deve connettersi con l'istanza di Gemelli digitali deve essere registrata con Azure AD. I passaggi in questa sezione illustrano come registrare l'app di esempio.

Se si ha già una registrazione dell'app, è possibile riutilizzarla per l'esempio. Esaminare tuttavia questa sezione per assicurarsi che la registrazione dell'app sia configurata correttamente.

Nota

Questa sezione fornisce istruzioni relative alla registrazione app di Azure AD.

  1. Nel portale di Azure aprire Azure Active Directory dal menu sinistro espandibile e quindi aprire il riquadro Registrazioni app.

    Selezionare il riquadro Azure Active Directory

  2. Selezionare il pulsante + Nuova registrazione.

    Selezionare il pulsante Nuova registrazione

  3. Assegnare un nome descrittivo a questa registrazione app nella casella Nome.

    1. Nella sezione URI di reindirizzamento (facoltativo) immettere https://microsoft.com nella casella di testo.

    2. Verificare quali account e tenant sono supportati dall'app Azure Active Directory.

    3. Selezionare Registra.

    Riquadro Crea

  4. Il pannello Autenticazione specifica importanti impostazioni di configurazione dell'autenticazione.

    1. Aggiungere gli URI di reindirizzamento e configurare i Token di accesso selezionando + Aggiungi una piattaforma.

    2. Selezionare Sì per specificare che l'app è un client pubblico.

    3. Verificare quali account e tenant sono supportati dall'app Azure Active Directory.

    Impostazione di configurazione del client pubblico

  5. Dopo aver selezionato la piattaforma appropriata, configurare gli URI di reindirizzamento e i Token di accesso nel pannello laterale a destra dell'interfaccia utente.

    1. È necessario che quanto specificato per URI di reindirizzamento corrisponda all'indirizzo fornito dalla richiesta di autenticazione:

      • Per le app ospitate in un ambiente di sviluppo locale, selezionare Client pubblico (per dispositivi mobili e desktop) . Assicurarsi di impostare client pubblico su Sì.
      • Per le app a pagina singola ospitate nel servizio app di Azure, selezionare Web.

    2. Determinare se è appropriato impostare un URL di disconnessione.

    3. Abilitare il flusso di concessione implicita selezionando Token di accesso o Token ID.

    Configurare gli URI di reindirizzamento

    Fare clic su Configura e quindi su Salva.

  6. Aprire il riquadroPanoramica dell'app registrata e copiare i valori delle entità seguenti in un file temporaneo. Questi valori verranno usati per configurare l'applicazione di esempio nelle sezioni seguenti.

    • ID applicazione (client)
    • ID directory (tenant)

    ID dell'applicazione Azure Active Directory

  7. Aprire il riquadro Autorizzazioni API per la app registrazione app. Selezionare il pulsante + Aggiungi un'autorizzazione. Nel riquadro Richiedi le autorizzazioni dell'API selezionare la scheda API usate dall'organizzazione e quindi cercare uno degli elementi seguenti:

    1. Azure Digital Twins. Selezionare l'API Gemelli digitali di Azure.

      API di ricerca o Gemelli digitali di Azure

    2. In alternativa, cercare Azure Smart Spaces Service. Selezionare l'API Azure Smart Spaces Service (Servizio Spazi intelligenti Azure).

      Api di ricerca per Azure Smart Spaces

    Importante

    Il nome e l'ID dell'API di Azure AD che verranno visualizzati dipendono dal tenant:

    • Gli account dei clienti e dei tenant di test devono cercare Azure Digital Twins.
    • Gli altri account Microsoft devono cercare Azure Smart Spaces Service.

  8. Una volta selezionata, l'API verrà visualizzata come Gemelli digitali di Azure nello stesso riquadro Richiedi le autorizzazioni dell'API. Selezionare l'opzione a discesa Lettura e quindi la casella di controllo Read.Write. Selezionare il pulsante Aggiungi autorizzazioni.

    Aggiungere autorizzazioni API

  9. A seconda delle impostazioni dell'organizzazione, potrebbe essere necessario eseguire passaggi aggiuntivi per concedere l'accesso amministratore a questa API. Contattare l'amministratore per altre informazioni. Una volta approvato l'accesso amministratore, la colonna Consenso amministratore obbligatorio nel riquadro Autorizzazioni API mostra le autorizzazioni.

    Amministrazione approvazione del consenso

    Verificare che venga visualizzato Gemelli digitali di Azure.

Configurare l'esempio di Gemelli digitali

Questa sezione descrive in modo dettagliato un'applicazione di Gemelli digitali di Azure che comunica con le API REST di Gemelli digitali.

Scaricare l'esempio

Se sono già stati scaricati gli esempi per la guida introduttiva alla ricerca di stanze disponibili, è possibile ignorare questi passaggi.

  1. Scaricare gli esempi .NET di Gemelli digitali.
  2. Estrarre il contenuto della cartella ZIP nel computer.

Esaminare l'esempio

Nella cartella degli esempi estratta, aprire il file digital-twins-samples-csharp\digital-twins-samples.code-workspace in Visual Studio Code. La cartella contiene due progetti:

  • È possibile usare l'esempio di provisioning occupazione-quickstart per configurare ed eseguire il provisioning di un grafico di intelligenza spaziale. Questo grafico è l'immagine digitalizzata degli spazi fisici e delle risorse in essi contenuti. Viene usato un modello a oggetti che definisce gli oggetti per un edificio intelligente. Per un elenco completo delle API REST e degli oggetti di Gemelli digitali, vedere la documentazione delle API REST o l'URL dell'API Gestione creato per l'istanza in uso.

    Per esaminare l'esempio e capire come avviene la comunicazione con l'istanza di Gemelli digitali, è possibile iniziare dalla cartella src\actions. I file in questa cartella implementano i comandi che verranno usati in queste esercitazioni:

    • Il file provisionSample.cs mostra come effettuare il provisioning del grafico spaziale.
    • Il file getSpaces.cs ottiene informazioni sugli spazi di cui è stato effettuato il provisioning.
    • Il file getAvailableAndFreshSpaces.cs ottiene i risultati di una funzione personalizzata detta funzione definita dall'utente.
    • Il file createEndpoints.cs crea gli endpoint per l'interazione con altri servizi.

  • L'esempio di simulazione device-connectivity simula i dati dei sensori e li invia all'hub IoT di cui è stato effettuato il provisioning per l'istanza di Gemelli digitali. L'esempio verrà usato nell'esercitazione successiva dopo avere effettuato il provisioning del grafico spaziale. Gli identificatori di sensori e dispositivi usati per configurare questo esempio devono corrispondere a quelli usati per il provisioning del grafico.

Configurare l'esempio di provisioning

  1. Aprire una finestra di comando e passare all'esempio scaricato. Eseguire il comando seguente:

    cd occupancy-quickstart/src

  2. Ripristinare le dipendenze dal progetto di esempio eseguendo questo comando:

    dotnet restore

  3. In Visual Studio Code aprire il file appSettings.json del progetto occupancy-quickstart. Aggiornare i valori seguenti:

    • ClientId: immettere l'ID applicazione della registrazione dell'app Azure AD. Questo ID è stato annotato nella sezione relativa all'impostazione delle autorizzazioni dell'app.
    • Tenant: immettere l'ID directory del tenant di Azure AD. Anche questo ID è stato annotato nella sezione relativa all'impostazione delle autorizzazioni dell'app.
    • BaseUrl: immettere l'URL dell'istanza di Gemelli digitali. Per ottenere questo URL, sostituire i segnaposto nell'URL con i valori per l'istanza: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. È anche possibile ottenere l'URL modificando l'URL dell'API Gestione della sezione relativa alla distribuzione. Sostituire swagger/ con api/v1.0/.

  4. Esaminare un elenco di funzionalità di Gemelli digitali che è possibile esplorare usando l'esempio. Eseguire il comando seguente:

    dotnet run

Informazioni sul processo di provisioning

Questa sezione illustra in che modo l'esempio effettua il provisioning di un grafico spaziale di un edificio.

In Visual Studio Code passare alla cartella occupancy-quickstart\src\actions e aprire il file provisionSample.cs. Osservare la funzione seguente:

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

Questa funzione usa il file provisionSample.yaml nella stessa cartella. Aprire questo file e osservare la gerarchia di un palazzo di uffici, costituita da sede, piano, area e stanze (oggetti Venue, Floor, Area e Rooms). Ognuno di questi spazi fisici può contenere dispositivi e sensori (oggetti devices e sensors). Ogni voce ha un valore predefinito type, ad esempio Floor, Room.

Il file yaml di esempio mostra un grafico spaziale che usa il modello a oggetti Default di Gemelli digitali. Questo modello fornisce nomi generici per la maggior parte dei tipi. I nomi generici sono sufficienti per un edificio. Alcuni esempi sono Temperatura per SensorDataType e Mappa per SpaceBlobType. Un tipo di spazio di esempio è Room con dei sottotipi FocusRoom ConferenceRoom e così via.

Se fosse necessario creare un grafico spaziale per una sede di diverso tipo, ad esempio una fabbrica, potrebbe essere necessario un modello a oggetti diverso. Per visualizzare i modelli disponibili, eseguire il comando dotnet run GetOntologies alla riga di comando per l'esempio di provisioning.

Per altre informazioni sui grafici spaziali e sui modelli a oggetti, vedere Informazioni sui modelli a oggetti di Gemelli digitali e sul grafico di intelligenza spaziale.

Modificare il grafico spaziale di esempio

Il file provisionSample.yaml contiene i nodi seguenti:

  • resources: il nodo resources crea una risorsa dell'hub IoT di Azure per comunicare con i dispositivi configurati. Un hub IoT nel nodo radice del grafico può comunicare con tutti i dispositivi e i sensori nel grafico.

  • spaces: nel modello a oggetti di Gemelli digitali spaces rappresenta i luoghi fisici. Ogni spazio ha un Typeoggetto , ad esempio Region, Venue o Customer, e un'amichevole Name. Gli spazi possono appartenere ad altri spazi e viene così creata una struttura gerarchica. Il file provisionSample.yaml include un grafico spaziale di un edificio immaginario. Si noti l'annidamento logico degli spazi di tipo Floor all'interno di Venue, Area in un oggetto Floor e nodi Room in un oggetto Area.

  • devices: gli spazi possono contenere oggetti devices, che sono entità fisiche o virtuali che gestiscono diversi sensori. Ad esempio, un dispositivo potrebbe essere un telefono dell'utente, un pod del sensore Raspberry Pi o un gateway. Nell'edificio immaginario di esempio osservare che la stanza denominata Focus Room contiene un dispositivo Raspberry Pi 3 A1. Ogni nodo di un dispositivo è identificato da un valore hardwareId univoco, che è hardcoded nell'esempio. Per configurare questo esempio per un ambiente di produzione reale, sostituire questi valori con quelli della configurazione in uso.

  • sensors: un dispositivo può contenere più oggetti sensors. Possono rilevare e registrare i cambiamenti fisici, ad esempio per quanto riguarda temperatura, movimento e livello delle batterie. Ogni nodo di un sensore è identificato da un valore hardwareId univoco hardcoded. Per un'applicazione reale, sostituire questi valori con gli identificatori univoci dei sensori nella configurazione in uso. Il file provisionSample.yaml include due sensori per la registrazione dei valori di Motion e CarbonDioxide. Un altro sensore registra i valori di Temperature, aggiungendo le righe seguenti sotto a quelle per il sensore relativo a CarbonDioxide. Vengono fornite in provisionSample.yaml come righe commentate. Per rimuovere il commento, rimuovere il carattere # all'inizio di ogni riga.

            - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE

    Nota

    Assicurarsi che le chiavi dataType e hardwareId siano allineate con le istruzioni sopra questo frammento di codice. Assicurarsi inoltre che l'editor non sostituisca gli spazi con tabulazioni.

Salvare e chiudere il file provisionSample.yaml. Nella prossima esercitazione verranno aggiunte altre informazioni a questo file e quindi si effettuerà il provisioning dell'edificio di esempio di Gemelli digitali di Azure.

Suggerimento

È possibile visualizzare e modificare il grafo spaziale con il Visualizzatore di Microsoft Azure Active Directory Graph.

Pulire le risorse

Se si non si vuole esplorare ulteriormente Gemelli digitali di Azure, è possibile eliminare le risorse create in questa esercitazione:

  1. Nel portale di Azure selezionare Tutte le risorse nel menu a sinistra, selezionare il gruppo di risorse di Gemelli digitali e quindi fare clic su Elimina.

    Suggerimento

    Se si sono riscontrati problemi durante l'eliminazione dell'istanza di Gemelli digitali, è stato reso disponibile un aggiornamento del servizio con la correzione. Riprovare a eliminare l'istanza.

  2. Se necessario, eliminare l'applicazione di esempio nel computer di lavoro.

Passaggi successivi

Per informazioni su come implementare una logica personalizzata per il monitoraggio delle condizioni nell'edificio di esempio, passare alla prossima esercitazione della serie:

Esercitazione: Effettuare il provisioning dell'edificio e monitorare le condizioni di lavoro