Dela via

Självstudie: Distribuera Förhandsversion av Azure Digital Twins och konfigurera en rumslig graf

  • Artikel

Viktigt

En ny version av Azure Digital Twins-tjänsten har släppts. Mot bakgrund av den nya tjänstens utökade funktioner har den ursprungliga Azure Digital Twins-tjänsten (beskrivs i den här dokumentationsuppsättningen) dragits tillbaka.

Om du vill visa dokumentationen för den nya tjänsten går du till den aktiva Azure Digital Twins-dokumentationen.

Du kan använda Azure Digital Twins Preview-tjänsten för att sammanföra personer, platser och enheter i ett sammanhängande rumsligt system. Den här serien med självstudier visar hur du använder Azure Digital Twins för att identifiera rumsbeläggning med optimala förhållanden för temperatur och luftkvalitet.

Dessa självstudier går igenom ett .NET-konsolprogram för att skapa ett scenario för en kontorsbyggnad. Den här byggnaden har flera våningar och rum på varje våning. Rummen innehåller enheter med kopplade sensorer som identifierar rörelse, omgivningstemperatur och luftkvalitet.

Du får lära dig hur du replikerar fysiska områden och enheter i byggnaden som digitala objekt med hjälp av Azure Digital Twins-tjänsten. Du simulerar enhetshändelserna med hjälp av ett annat konsolprogram. Därefter får du lära dig hur du övervakar händelserna som kommer från dessa fysiska områden och enheter i nära realtid.

En kontorsadministratör kan använda den här informationen för att hjälpa en medarbetare som jobbar i den här byggnaden att boka mötesrum med optimala förhållanden. En förvaltningsansvarig kan använda din konfiguration till att få användningstrender för rummen och till att övervaka arbetsförhållanden i underhållssyfte.

I seriens första kurs lär du dig följande:

  • Distribuera Digital Twins.
  • Tilldela behörigheter till appen.
  • Ändra en Digital Twins-exempelapp.
  • Etablera byggnaden.

I de här kurserna används och ändras samma exempel som i snabbstarten för att hitta tillgängliga rum, för en mer detaljerad och djupgående täckning av de här begreppen.

Förutsättningar

  • En Azure-prenumeration. Om du inte har något Azure-konto skapar du ett kostnadsfritt konto.

  • .NET Core SDK. Azure Digital Twins-exemplen som används i dessa självstudier är skrivna i C#. Se till att installera .NET Core SDK version 2.1.403 eller senare på utvecklingsdatorn för att skapa och köra exemplet. Kontrollera att rätt version är installerad på datorn genom att köra dotnet --version i ett kommandofönster.

  • Visual Studio Code för att utforska exempelkoden.

Distribuera Digital Twins

Använd stegen i det här avsnittet för att skapa en ny instans av Azure Digital Twins-tjänsten. Bara en instans kan skapas per prenumeration. Hoppa till nästa avsnitt om du redan har en som körs.

  1. Logga in på Azure-portalen.

  2. Välj startsidan och sedan + Skapa en resurs.

    Expandera startsidan och välj sedan + Skapa en resurs

  3. Sök efter Digital Twins och välj Digital Twins.

    Val för att skapa en ny Digital Twins-instans

    Du kan också välja Sakernas Internet och välja Digital Twins (förhandsversion).

  4. Välj Skapa för att starta distributionsprocessen.

    Skapa och bekräfta distributionen av resursen

  5. I fönstret Digital Twins anger du följande information:

    • Resursnamn: Skapa ett unikt namn på Digital Twins-instansen.

    • Prenumeration: Välj den prenumeration som du vill använda för att skapa Digital Twins-instansen.

    • Resursgrupp: Välj eller skapa en resursgrupp för Digital Twins-instansen.

    • Plats: Välj den plats som är närmast enheten.

      Digital Twins-fönstret med angiven information

  6. Granska din Digital Twins-information och välj sedan Skapa. Det kan ta några minuter för Digital Twins-instansen att skapas. Du kan övervaka förloppet i meddelandefönstret.

  7. Öppna översiktsfönstret för Digital Twins-instansen. Observera länken under Hanterings-API. URL:en för hanterings-API :et formateras som:

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

    Denna URL tar dig till dokumentationen för Azure Digital Twins REST API som gäller för din instans. Läs om hur du använder Azure Digital Twins Swagger för att få reda på hur du läser och använder den här API-dokumentationen. Kopiera och ändra URL:en för hanterings-API :et till det här formatet:

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

    Programmet använder den ändra URL:en som bas-URL för att få åtkomst till instansen. Kopiera denna ändrade URL till en temporär fil. Du behöver URL:en i nästa avsnitt.

    Översikt över API för hantering

Bevilja appen behörigheter

Digital Twins använder Azure Active Directory (Azure AD) för att kontrollera läs-/skrivåtkomst till tjänsten. Alla program som måste ansluta till din Digital Twins-instans måste registreras med Azure AD. Stegen i det här avsnittet visar hur du registrerar din exempelapp.

Om du redan har en appregistrering kan du återanvända den för ditt exempel. Men bläddra igen det här avsnittet för att se till att din appregistrering har konfigurerats på rätt sätt.

Anteckning

Det här avsnittet innehåller anvisningar för Azure AD appregistrering.

  1. I Azure Portal öppnar du Azure Active Directory från den expanderbara vänstra menyn och öppnar sedan fönstret Appregistreringar.

    Välj fönstret Azure Active Directory

  2. Välj knappen + Ny registrering .

    Välj knappen Ny registrering

  3. Ge appregistreringen ett eget namn i rutan Namn.

    1. Under Avsnittet Omdirigerings-URI (valfritt) anger du https://microsoft.com i textrutan.

    2. Kontrollera vilka konton och klientorganisationer som stöds av din Azure Active Directory-app.

    3. Välj Register (Registrera).

    Skapa fönster

  4. Bladet Autentisering anger viktiga konfigurationsinställningar för autentisering.

    1. Lägg till omdirigerings-URI:er och konfigurera åtkomsttoken genom att välja + Lägg till en plattform.

    2. Välj Ja för att ange att appen är en offentlig klient.

    3. Kontrollera vilka konton och klientorganisationer som stöds av din Azure Active Directory-app.

    Konfigurationsinställning för offentlig klient

  5. När du har valt lämplig plattform konfigurerar du dina omdirigerings-URI:er och åtkomsttoken på sidopanelen till höger om användargränssnittet.

    1. Omdirigerings-URI:er måste matcha den adress som anges av autentiseringsbegäran:

      • För appar som finns i en lokal utvecklingsmiljö väljer du Offentlig klient (mobil & skrivbord). Se till att ställa in den offentliga klienten påJa.
      • För Single-Page appar som finns på Azure App Service väljer du Webb.

    2. Avgör om en utloggnings-URL är lämplig.

    3. Aktivera det implicita beviljandeflödet genom att kontrollera åtkomsttoken eller ID-token.

    Konfigurera omdirigerings-URI:er

    Klicka på Konfigurera och sedan på Spara.

  6. Öppna fönstret Översikt i din registrerade app och kopiera värdena för följande entiteter till en tillfällig fil. Du använder dessa värden för att konfigurera exempelprogrammet i följande avsnitt.

    • Program-ID (klient)
    • Katalog-ID (klient)

    ID för Azure Active Directory-programmet

  7. Öppna fönstret API-behörigheter för din appregistrering. Välj + Lägg till en behörighetsknapp . I fönstret Begär API-behörigheter väljer du fliken API:er som min organisation använder och söker sedan efter något av följande:

    1. Azure Digital Twins. Välj Azure Digital Twins-API :et.

      Sök-API eller Azure Digital Twins

    2. Du kan också söka Azure Smart Spaces Serviceefter . Välj Azure Smart Spaces Service-API:et .

      Sök API för Azure Smart Spaces

    Viktigt

    Det Azure AD API-namn och ID som visas beror på din klientorganisation:

    • Testa klient- och kundkonton bör söka Azure Digital Twinsefter .
    • Andra Microsoft-konton bör söka Azure Smart Spaces Serviceefter .

  8. Endera API:et visas som Azure Digital Twins i samma fönster för API-behörigheter för begäran när det har valts. Välj listrutan Läs och markera sedan kryssrutan Läs.Skriv . Välj knappen Lägg till behörigheter .

    Lägga till API-behörigheter

  9. Beroende på organisationens inställningar kan du behöva vidta ytterligare åtgärder för att ge administratörsåtkomst till det här API:et. Kontakta administratören om du vill ha mer information. När administratörsåtkomsten har godkänts visas dina behörigheter i kolumnen Admin Medgivande krävs i fönstret API-behörigheter.

    Admin godkännande av medgivande

    Kontrollera att Azure Digital Twins visas.

Konfigurera Digital Twins-exemplet

Det här avsnittet vägleder dig genom en Azure Digital Twins-app som kommunicerar med Digital Twins REST-API:erna.

Ladda ned exemplet

Om du redan har exemplen för snabbstarten för att hitta tillgängliga rum kan du hoppa över dessa steg.

  1. Ladda ned Digital Twins .Net-exemplen.
  2. Extrahera innehållet i zip-mappen på din dator.

Utforska exemplet

I den extraherade exempelmappen öppnar du filen digital-twins-samples-csharp\digital-twins-samples.code-workspace i Visual Studio Code. Den innehåller två projekt:

  • Du kan använda etableringsexemplet occupancy-quickstart för att konfigurera och etablera en graf med rumslig information. Den här grafen är en digital bild av fysiska utrymmen och resurserna i dem. Den använder en objektmodell som definierar objekt för en smart byggnad. En komplett lista över Digital Twins-objekt och REST-API:er finns i den här REST API-dokumentationen eller den URL för API för hantering som har skapats för din instans.

    Om du vill utforska exemplet för att förstå hur det kommunicerar med digital twins-instansen kan du börja med mappen src\actions . Filerna i den här mallen implementerar kommandon som du vill använda i dessa självstudier:

    • Filen provisionSample.cs visar hur du etablerar din rumsliga graf.
    • Filen getSpaces.cs hämtar information om de etablerade utrymmena.
    • Filen getAvailableAndFreshSpaces.cs hämtar resultatet av en anpassad funktion som kallas för användardefinierad funktion.
    • Filen createEndpoints.cs skapar slutpunkter för att interagera med andra tjänster.

  • Simuleringsexemplet device-connectivity simulerar sensordata och skickar det till den IoT-hubb som har etablerats för din Digital Twin-instans. Du använder det här exemplet i nästa självstudie när du har etablerat den rumsliga grafen. Sensorn och enhetsidentifierarna som du använder för att konfigurera det här exemplet ska vara samma som det du använder för att etablera grafen.

Konfigurera etableringsexemplet

  1. Öppna ett kommandofönster och gå till det nedladdade exemplet. Kör följande kommando:

    cd occupancy-quickstart/src

  2. Återställ beroenden till exempelprojektet genom att köra följande kommando:

    dotnet restore

  3. I Visual Studio Code öppnar du filen appSettings.json i projektet occupancy-quickstart. Uppdatera följande värden:

    • ClientId: Ange program-ID:t för din Azure AD-appregistrering. Du antecknade ID:t i avsnittet där du anger appbehörigheter.
    • Klientorganisation: Ange katalog-ID:t för din Azure AD-klient. Du antecknade även ID:t i avsnittet där du anger appbehörigheter.
    • BaseUrl: Ange URL:en för din Digital Twins-instans. Du kan hämta den här URL:en genom att ersätta platshållarna i den här URL:en med värdena för din instans: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Du kan också hämta URL:en genom att ändra URL:en för API för hantering i distributionsavsnittet. Ersätt swagger/ med api/v1.0/.

  4. Granska en lista över Digital Twins-funktioner som du kan utforska med hjälp av exemplet. Kör följande kommando:

    dotnet run

Förstå etableringsprocessen

I det här avsnittet visas hur exemplet etablerar en rumslig graf över en byggnad.

I Visual Studio Code bläddrar du till mappen occupancy-quickstart\src\actions och öppnar filen provisionSample.cs. Observera följande funktion:

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;
}

Den här funktionen använder provisionSample.yaml i samma mapp. Öppna den här filen och notera hierarkin för en kontorsbyggnad: Venue (Plats), Floor (Våning), Area (Område) och Rooms (Rum). Vilken som helst av dessa fysiska utrymmen kan innehålla devices (enheter) och sensors (sensorer). Varje post har en fördefinierad type– till exempel Golv, Rum.

I yaml-exempelfilen visas en rumslig graf som använder Default Digital Twins-objektmodellen. Den här modellen innehåller allmänna namn för de flesta typer. Allmänna namn är tillräckliga för en byggnad. Exempel är Temperature (Temperatur) för SensorDataType (Sensordatatyp) och Map (Karta) för SpaceBlobType (Utrymmesblobtyp). Ett exempel på utrymmestypen är Room (Rum) med undertyperna FocusRoom (Fokusrum), ConferenceRoom (Konferensrum) och så vidare.

Om du var tvungen att skapa en rumslig graf för en annan typ av plats, till exempel en fabrik, kanske du behöver en annan objektmodell. Du kan få reda på vilka modeller som är tillgängliga att använda genom att köra kommandot dotnet run GetOntologies på kommandoraden för etableringsexemplet.

Mer information om rumsliga grafer och objektmodellerna finns i Förstå Digital Twins-objektmodellen och rumslig graf.

Ändra exemplet på rumslig graf

Filen provisionSample.yaml innehåller följande noder:

  • resources (resurser): Noden resources skapar en Azure IoT Hub-resurs för att kommunicera med enheterna i din konfiguration. En IoT-hugg på rotnoden i grafen kan kommunicera med alla enheterna och sensorerna i din graf.

  • spaces (utrymmen): I Digital Twins-objektmodellen representerar spaces de fysiska platserna. Varje utrymme har en Type– till exempel Region, Plats eller Kund – och en vänlig Name. Utrymmen kan tillhöra andra utrymmen som skapar en hierarkisk struktur. Filen provisionSample.yaml har en rumslig graf av en föreställd byggnad. Observera den logiska kapslingen av utrymmen av typen Floor i Venue, Area på en våning och Room-noderna i ett område.

  • devices (enheter): Utrymmen kan innehålla devices, som är fysiska eller virtuella enheter som hanterar ett antal sensorer. En enhet kan till exempel vara en användares telefon, en Raspberry Pi-sensorpodd eller en gateway. I den föreställda byggnaden i exemplet kan du observera hur rummet med namnet Focus Room innehåller en Raspberry Pi 3 A1-enhet. Varje enhetsnod identifieras med ett unikt hardwareId, som är hårdkodat i exemplet. Om du vill konfigurera det här exemplet för faktisk produktion ersätter du dessa med värden från konfigurationen.

  • sensors (sensorer): en enhet kan innehålla flera sensors. De kan identifiera och registrera fysiska förändringar som temperatur, rörelse och batterinivå. Varje sensornod har unikt identifierats av ett hardwareId, hårdkodat här. För en faktisk app ersätter du dessa med hjälp av de unika identifierarna för sensorerna i konfigurationen. Filen provisionSample.yaml har två sensorer för att registrera Motion (Rörelse) och CarbonDioxide (Koldioxid). Lägg till en annan sensor för att registrera Temperature (Temperatur) genom att lägga till följande rader, nedanför raderna för CarbonDioxide-sensorn (Koldioxidsensorn). Dessa anges i provisionSample.yaml som kommenterade rader. Du kan ta bort kommentaren från dem genom att ta bort tecknet # före varje rad.

            - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE

    Anteckning

    Kontrollera att justeringen av nycklarna dataType och hardwareId är i linje med uttrycken ovanför det här kodavsnittet. Se även till att redigeraren inte ersätter blanksteg med tabbar.

Spara och stäng filen provisionSample.yaml. I nästa självstudie lägger du till mer information i den här filen och etablerar sedan Azure Digital Twins-exempelbyggnaden.

Tips

Du kan visa och ändra ett spatialt diagram med hjälp av Visningsprogrammet för Azure Digital Twins Graph.

Rensa resurser

Om du inte vill utforska Azure Digital Twins nu kan du ta bort resurser som du har skapat i den här självstudien:

  1. På den vänstra menyn i Azure-portalen väljer du Alla resurser, väljer din Digital Twins-resursgrupp och Ta bort.

    Tips

    Om det inträffade problem när du skulle ta bort Digital Twins-instansen finns det nu en tjänstuppdatering som åtgärdar det. Försök att ta bort instansen igen.

  2. Ta bort exempelprogrammet på datorn om det behövs.

Nästa steg

Fortsätt till nästa självstudie i serien för att lära dig hur du implementerar en anpassad logik för att övervaka villkor i exempelbyggnaden:

Självstudie: Etablera byggnaden och övervaka arbetsförhållanden