Zelfstudie: Azure Digital Twins Preview implementeren en een ruimtelijke grafiek configureren

Artikel
01/10/2020

Belangrijk

Er is een nieuwe versie van de Azure Digital Twins-service uitgebracht. In het licht van de uitgebreide mogelijkheden van de nieuwe service is de oorspronkelijke Azure Digital Twins-service (beschreven in deze documentatieset) buiten gebruik gesteld.

Als u de documentatie voor de nieuwe service wilt bekijken, gaat u naar de actieve Documentatie voor Azure Digital Twins.

U kunt de Azure Digital Twins Preview-service gebruiken om personen, plaatsen en apparaten samen te brengen in een coherent ruimtelijk systeem. Deze reeks zelfstudies laat zien hoe u Azure Digital Twins gebruikt voor het detecteren van ruimtebezetting met optimale omstandigheden qua temperatuur- en luchtkwaliteit.

In deze zelfstudies leert u een .NET-consoletoepassing te maken om een scenario op te bouwen voor een kantoorgebouw. Het gebouw heeft meerdere verdiepingen en verschillende ruimten per verdieping. De ruimten bevatten apparaten waaraan bewegings-, temperatuur- en luchtkwaliteitssensoren zijn gekoppeld.

U leert hoe u de fysieke gebieden en entiteiten in het gebouw kunt repliceren als digitale objecten met behulp van de Azure Digital Twins-service. U simuleert apparaatgebeurtenissen met een andere consoletoepassing. Vervolgens leert u hoe u de gebeurtenissen die afkomstig zijn van deze fysieke gebieden en entiteiten bijna in realtime kunt bewaken.

Een office manager kan deze informatie gebruiken om werknemers in het gebouw te helpen bij het boeken van vergaderruimten met optimale omstandigheden. Een facilitair manager kan uw instellingen gebruiken voor het detecteren van trends in het gebruik van de ruimten en voor het bewaken van werkomstandigheden voor onderhoudswerkzaamheden.

In de eerste zelfstudie van deze reeks leert u het volgende:

Digital Twins implementeren.
Machtigingen verlenen aan uw app.
Een voorbeeld-app van Digital Twins wijzigen.
Het gebouw inrichten.

In deze zelfstudies worden dezelfde voorbeelden gebruikt en aangepast als in de snelstart voor het vinden van beschikbare ruimten, voor een meer gedetailleerde en uitgebreide uitleg van de concepten.

Vereisten

Een Azure-abonnement. Als u geen Azure-account hebt, maakt u een gratis account.
De .NET Core-SDK. De Azure Digital Twins-voorbeelden in deze zelfstudies zijn geschreven in C#. Installeer .NET Core SDK-versie 2.1.403 of hoger op een ontwikkelcomputer om het voorbeeld te bouwen en uit te voeren. Controleer of de juiste versie op uw computer is geïnstalleerd door dotnet --version uit te voeren in een opdrachtvenster.
Visual Studio Code om de voorbeeldcode mee te verkennen.

Azure Digital Twins implementeren

Maak een nieuw exemplaar van de Azure Digital Twins-service met behulp van de stappen in deze sectie. Per abonnement kan slechts één exemplaar worden gemaakt. Ga naar de volgende sectie als u al een actief exemplaar hebt.

Meld u aan bij de Azure-portal.
Selecteer de zijbalk start en vervolgens + Een resource maken.
Zoek naar Digital Twins en selecteer Digital Twins.

U kunt ook Internet of Things selecteren en Digital Twins (preview) selecteren.
Selecteer Maken om het implementatieproces te starten.
In het deelvenster Digital Twins voert u de volgende informatie in:
- Resourcenaam: geef uw instantie van Digital Twins een unieke naam.
- Abonnement: kies het abonnement dat u wilt gebruiken om deze instantie van Digital Twins te maken.
- Resourcegroep: selecteer of maak een resourcegroep voor de instantie van Digital Twins.
- Locatie: selecteer de locatie die het dichtst bij uw apparaten ligt.
Controleer uw Digital Twins-gegevens en selecteer Maken. Het kan een paar minuten duren voordat uw instantie van Digital Twins is gemaakt. U kunt de voortgang bewaken via het deelvenster Meldingen.
Open het deelvenster Overzicht van de instantie van Digital Twins. Zoals u ziet, wordt er een koppeling weergegeven onder Beheer API. De URL van de Management-API is opgemaakt als:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
```
Deze URL leidt u naar de documentatie van de REST API van Azure Digital Twins, die van toepassing is op uw instantie. Zie Het gebruik van Azure Digital Twins Swagger voor informatie over hoe u deze API-documentatie dient te lezen en gebruiken. Kopieer en wijzig de URL van de Management API in deze indeling:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
```
Uw toepassing gebruikt de aangepaste URL als de basis-URL voor toegang tot uw instantie. Kopieer deze gewijzigde URL naar een tijdelijk bestand. U hebt deze URL nodig in de volgende sectie.

Machtigingen verlenen aan uw app

Digital Twins maakt gebruik van Azure Active Directory (Azure AD) voor het beheren van de lees-/schrijftoegang tot de service. Elke toepassing die moet worden verbonden met uw exemplaar van Digital Twins, moet worden geregistreerd bij Azure AD. In de stappen in deze sectie wordt uitgelegd hoe u de voorbeeld-app registreert.

Als u al over een app-registratie beschikt, kunt u deze opnieuw gebruiken voor uw voorbeeld. Neem deze sectie echter wel door om te controleren of de registratie van uw app juist is geconfigureerd.

Notitie

In deze sectie vindt u instructies voor Azure AD app-registratie.

Open in de Azure PortalAzure Active Directory vanuit het uitvouwbare menu links en open vervolgens het deelvenster App-registraties.
Selecteer de knop + Nieuwe registratie .
Geef een beschrijvende naam voor deze app-registratie op in het vak Naam.
1. Voer https://microsoft.com in het tekstvak in onder de sectie Omleidings-URI (optioneel).
2. Controleer welke accounts en tenants worden ondersteund door uw Azure Active Directory-app.
3. Selecteer Registreren.
Op de blade Verificatie worden belangrijke configuratie-instellingen voor verificatie opgegeven.
1. Voeg omleidings-URI's toe en configureer toegangstokens door + Een platform toevoegen te selecteren.
2. Selecteer Ja om op te geven dat de app een openbare client is.
3. Controleer welke accounts en tenants worden ondersteund door uw Azure Active Directory-app.
Nadat u het juiste platform hebt geselecteerd, configureert u uw omleidings-URI's en toegangstokens in het zijpaneel rechts van de gebruikersinterface.
1. Omleidings-URI's moeten overeenkomen met het adres dat is opgegeven door de verificatieaanvraag:
  - Selecteer Openbare client (mobiel & desktop) voor apps die worden gehost in een lokale ontwikkelomgeving. Zorg ervoor dat openbare client is ingesteld op Ja.
  - Selecteer Web voor Single-Page Apps die worden gehost op Azure App Service.
2. Bepaal of een afmeldings-URL geschikt is.
3. Schakel de impliciete toekenningsstroom in door toegangstokens of id-tokens te controleren.
Klik op Configureren en vervolgens op Opslaan.
Open het deelvenster Overzicht van uw geregistreerde app en kopieer de waarden van de volgende entiteiten naar een tijdelijk bestand. U gebruikt deze waarden om uw voorbeeldtoepassing in de volgende secties te configureren.
- (Client-)id van de app
- (Tenant-)id van de map
Open het deelvenster API-machtigingen voor uw app-registratie. Selecteer de knop + Een machtiging toevoegen . Selecteer in het deelvenster API-machtigingen aanvragen het tabblad API's die mijn organisatie gebruikt en zoek vervolgens naar een van de volgende opties:
1. Azure Digital Twins. Selecteer de Azure Digital Twins-API .
2. U kunt ook zoeken naar Azure Smart Spaces Service. Selecteer de Service-API van Azure Smart Spaces .
Belangrijk

De Azure AD API-naam en -id die worden weergegeven, is afhankelijk van uw tenant:
- Testtenant en klantaccounts moeten zoeken naar Azure Digital Twins.
- Andere Microsoft-accounts moeten zoeken Azure Smart Spaces Servicenaar .
Een van beide API's wordt weergegeven als Azure Digital Twins in hetzelfde deelvenster Api-machtigingen aanvragen zodra deze is geselecteerd. Selecteer de vervolgkeuzelijst Lezen en schakel vervolgens het selectievakje Read.Write in. Selecteer de knop Toestemmingen toevoegen.
Afhankelijk van de instellingen van uw organisatie moet u mogelijk extra stappen uitvoeren om beheerderstoegang tot deze API te verlenen. Neem contact op met de beheerder voor meer informatie. Zodra de beheerderstoegang is goedgekeurd, worden uw machtigingen weergegeven in de kolom Beheer Toestemming vereist in het deelvenster API-machtigingen.

Controleer of Azure Digital Twins wordt weergegeven.

Het Digital Twins-voorbeeld configureren

In deze sectie ziet u hoe een Azure Digital Twins-toepassing communiceert met de REST-API's van Digital Twins.

Het voorbeeld downloaden

Als u de voorbeelden voor de snelstart voor het vinden van beschikbare ruimten al hebt gedownload, kunt u deze stappen overslaan.

Download de .NET-voorbeelden van Digital Twins.
Pak de inhoud van de gecomprimeerde map uit op uw computer.

Het voorbeeld verkennen

Open het bestand digital-twins-samples-csharp\digital-twins-samples.code-workspace uit de uitgepakte voorbeeldmap in Visual Studio Code. Dit bestand bevat twee projecten:

U kunt het inrichtingsvoorbeeld occupancy-quickstart gebruiken voor het configureren en inrichten van een ruimtelijke informatiegrafiek. Deze grafiek is de digitale kopie van uw fysieke ruimten en de resources in die ruimten. Het maakt gebruik van een objectmodel, waarmee objecten voor een slim gebouw worden gedefinieerd. Ga voor een volledige lijst van objecten en REST-API's van Digital Twins naar deze REST API-documentatie of de URL van de Beheer API die is gemaakt voor uw exemplaar.

Als u het voorbeeld wilt verkennen om te begrijpen hoe het communiceert met uw Digital Twins-exemplaar, kunt u beginnen met de map src\actions . De bestanden in deze map implementeren de opdrachten die u in deze zelfstudies gaat gebruiken:
- Het bestand provisionSample.cs laat zien hoe u uw ruimtelijke grafiek inricht.
- Het bestand getSpaces.cs krijgt informatie over de ingerichte ruimten.
- Het bestand getAvailableAndFreshSpaces.cs haalt de resultaten op van een aangepaste (door de gebruiker gedefinieerde) functie op.
- Het bestand createEndpoints.cs maakt eindpunten voor interactie met andere services.
Het simulatievoorbeeld device-connectivity simuleert sensorgegevens en verzendt deze naar de IoT-hub die is ingericht voor uw exemplaar van Digital Twins. U gebruikt dit voorbeeld in de volgende zelfstudie nadat u de ruimtelijke grafiek hebt ingericht. De sensor- en apparaat-id's die u gebruikt voor het configureren van dit voorbeeld moeten gelijk zijn aan de id's die u gebruikt voor het inrichten van de grafiek.

Het inrichtingsvoorbeeld configureren

Open een opdrachtvenster en ga naar het gedownloade voorbeeld. Voer de volgende opdracht uit:
```
cd occupancy-quickstart/src
```
Herstel afhankelijkheden van het voorbeeldproject met deze opdracht:
```
dotnet restore
```
Open in Visual Studio Code het bestand appSettings.json van het project occupancy-quickstart. Werk de volgende waarden bij:
- ClientId: voer de toepassings-id van uw Azure AD-app-registratie in. U hebt deze id genoteerd in de sectie voor het instellen van app-machtigingen.
- Tenant: voer de map-id van uw Azure AD-tenant in. U hebt deze id ook genoteerd in de sectie voor het instellen van app-machtigingen.
- BaseUrl: voer de URL van uw exemplaar van Digital Twins in. Hiertoe vervangt u de tijdelijke aanduidingen in deze URL door de waarden voor uw exemplaar: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. U kunt deze URL ook verkrijgen door de URL van de Beheer API uit de implementatiesectie te wijzigen. Vervang swagger/ door api/v1.0/.
Bekijk een lijst met Digital Twins-functies die u kunt verkennen met behulp van het voorbeeld. Voer de volgende opdracht uit:
```
dotnet run
```

Inzicht in het inrichtingsproces

In deze sectie wordt beschreven hoe u met het voorbeeld een ruimtelijke grafiek van een gebouw inricht.

Ga in Visual Studio Code naar de map occupancy-quickstart\src\actions en open het bestand provisionSample.cs. Let op de volgende functie:

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

Deze functie maakt gebruik van het bestand provisionSample.yaml in dezelfde map. Open dit bestand en bekijk de hiërarchie van een kantoorgebouw, bestaande uit: locatie, verdieping, gebied en ruimten. Elk van deze fysieke ruimten kan devices en sensors bevatten. Elk item heeft een vooraf gedefinieerde typewaarde, bijvoorbeeld Verdieping, Kamer.

Het yaml-voorbeeldbestand bevat een ruimtelijke grafiek die gebruikmaakt van het Digital Twins-objectmodel Default. Dit model bevat algemene namen voor de meeste typen. Algemene namen zijn voldoende voor een gebouw. Voorbeelden hiervan zijn Temperatuur voor SensorDataType en Toewijzen voor SpaceBlobType. Een voorbeeld van een type ruimte is Ruimte met de subtypen Concentratieruimte, Vergaderruimte, enzovoort.

Als u een ruimtelijke grafiek voor een ander type locatie wilt maken (zoals een fabriek) hebt u wellicht een ander objectmodel nodig. Als u wilt weten welke modellen beschikbaar zijn, voert u de opdracht dotnet run GetOntologies uit vanaf de opdrachtregel voor het inrichtingsvoorbeeld.

Lees voor meer informatie over ruimtelijke grafieken en de objectmodellen Inzicht in Digital Twins-objectmodellen en ruimtelijke informatiegrafiek.

Het voorbeeld van de ruimtelijke grafiek wijzigen

Het bestand provisionSample.yaml bevat de volgende knooppunten:

resources: het knooppunt resources maakt een IoT Hub-resource om te communiceren met de apparaten in uw installatie. Een IoT-hub in het hoofdknooppunt van uw grafiek kan communiceren met alle apparaten en sensoren in uw grafiek.
spaces: in het Digital Twins-objectmodel worden de fysieke locaties vertegenwoordigd door spaces. Elke ruimte heeft een Type, bijvoorbeeld Regio, Locatie of Klant, en een beschrijvende Name. Ruimten kunnen deel uitmaken van andere ruimten in een hiërarchische structuur. Het bestand provisionSample.yaml bevat een ruimtelijke grafiek van een denkbeeldig gebouw. Merk op dat ruimten van het type Floor logisch genest zijn in Venue, Area in een verdieping, en Room-knooppunten in een gebied.
devices: ruimten kunnen devices bevatten. Dat zijn fysieke of virtuele entiteiten waarmee een aantal sensoren wordt beheerd. Een apparaat kan bijvoorbeeld de telefoon van een gebruiker, een Raspberry Pi-sensorpod of een gateway zijn. In het denkbeeldige gebouw uit het voorbeeld bevat de ruimte Focus Room bijvoorbeeld het apparaat Raspberry Pi 3 A1. Elk apparaatknooppunt wordt geïdentificeerd door een unieke hardwareId, die is vastgelegd in het voorbeeld. Als u dit voorbeeld wilt configureren in een productieomgeving, moet u deze waarden vervangen door de waarden van uw installatie.
sensoren: een apparaat kan meerdere sensors bevatten. Hiermee kunnen fysieke wijzigingen (bijvoorbeeld in temperatuur, beweging of accuniveau) worden gedetecteerd en vastgelegd. Elk sensorknooppunt wordt geïdentificeerd door een unieke hardwareId, die hier is vastgelegd. Voor een werkelijke toepassing moet u deze vervangen door de unieke id's van de sensoren in uw installatie. Het bestand provisionSample.yaml bevat twee sensoren: een bewegingssensor (Motion) en een CO2-sensor (CarbonDioxide). Voeg, onder de regels voor de CO2-sensor, de volgende regels toe om een temperatuursensor (Temperature) toe te voegen. Deze worden opgegeven in provisionSample.yaml als regels met opmerkingen. U kunt er coderegels van maken door het teken # aan het begin van elke regel te verwijderen.
```
        - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE
```
Notitie

Zorg ervoor dat de sleutels dataType en hardwareId in overeenstemming zijn met de instructies boven dit fragment. Zorg er ook voor dat in uw editor spaties niet worden vervangen door tabs.

Sla het bestand provisionSample.yaml op en sluit het. In de volgende zelfstudie gaat u meer gegevens aan dit bestand toevoegen en het voorbeeldgebouw inrichten in Azure Digital Twins.

Tip

U kunt de ruimtelijke grafiek bekijken en aanpassen met de Graph Viewer voor Azure Digital Twins.

Resources opschonen

Als u Azure Digital Twins niet verder wilt verkennen, kunt u de resources die in deze zelfstudie zijn gemaakt, gerust verwijderen:

Klik in het linkermenu in de Azure-portal op Alle resources, selecteer de Digital Twins-resourcegroep en selecteer Verwijderen.

Tip

Als u problemen hebt bij het verwijderen van uw Digital Twins-exemplaar, is er een service-update met de oplossing hiervoor beschikbaar. Probeer opnieuw of u het exemplaar kunt verwijderen.
Verwijder zo nodig de voorbeeldtoepassing van uw werkcomputer.

Volgende stappen

Ga voor meer informatie over het implementeren van aangepaste logica voor het bewaken van de omstandigheden in uw voorbeeldgebouw naar de volgende zelfstudie in de reeks:

Zelfstudie: Uw gebouw inrichten en uw werkomstandigheden controleren

Delen via