Azure Digital Twins API's en SDK's

  • Artikel
  • 7 minuten om te lezen

In dit artikel vindt u een overzicht van Azure Digital Twins beschikbare API's en de methoden voor interactie met deze API's. U kunt de REST API's rechtstreeks gebruiken met hun bijbehorende S tools (via een hulpprogramma zoals Postman)of via een SDK.

Azure Digital Twins is uitgerust met API's voor besturingsvlak, API's voor gegevensvlakken en SDK's voor het beheren van uw exemplaar en de elementen ervan.

  • De API's van het besturingsvlak zijn Azure Resource Manager (ARM) API's en omvatten bewerkingen voor resourcebeheer, zoals het maken en verwijderen van uw exemplaar.
  • De gegevensvlak-API's zijn Azure Digital Twins API's en worden gebruikt voor gegevensbeheerbewerkingen zoals het beheren van modellen, tweelingen en de grafiek.
  • De SDK's profiteren van de bestaande API's om de ontwikkeling van aangepaste toepassingen die gebruikmaken van Azure Digital Twins. De SDK's voor het besturingsvlak zijn beschikbaar in .NET (C#) en Javaen de gegevensvlak-SDK's zijn beschikbaar in .NET (C#), Java, JavaScripten Python.

Overzicht: API's voor besturingsvlak

De API's van het besturingsvlak zijn ARM-API's die worden gebruikt om uw Azure Digital Twins-exemplaar als geheel te beheren. Ze hebben dus betrekking op bewerkingen zoals het maken of verwijderen van uw hele exemplaar. U gebruikt deze API's ook om eindpunten te maken en te verwijderen.

De meest recente api-versie van het besturingsvlak is 2020-12-01.

De API's van het besturingsvlak gebruiken:

U kunt ook api's voor besturingsvlak oefenen door te communiceren met Azure Digital Twins via de Azure Portal en CLI.

Overzicht: API's voor gegevensvlak

De gegevensvlak-API's zijn Azure Digital Twins API's die worden gebruikt om de elementen in uw Azure Digital Twins beheren. Ze omvatten bewerkingen zoals het maken van routes, het uploaden van modellen, het maken van relaties en het beheren van tweelingen, en kunnen breed worden onderverdeeld in de volgende categorieën:

  • DigitalTwinModels: de categorie DigitalTwinModels bevat API's voor het beheren van de modellen in een Azure Digital Twins exemplaar. Beheeractiviteiten omvatten het uploaden, valideren, ophalen en verwijderen van modellen die zijn geschreven in DTDL.
  • DigitalTwins: de categorie DigitalTwins bevat de API's die ontwikkelaars digitale tweelingen en hun relaties in een Azure Digital Twins maken, wijzigen en verwijderen.
  • Query: met de categorie Query kunnen ontwikkelaars sets van digitale tweelingen vinden in de tweelinggrafiek tussen relaties.
  • Gebeurtenisroutes: de categorie Gebeurtenisroutes bevat API's om gegevensdoor te geven, via het systeem en naar downstreamservices.

De meest recente api-versie van het gegevensvlak is 2020-10-31.

De gegevensvlak-API's gebruiken:

U kunt ook api's voor datumvlakken oefenen door te communiceren met Azure Digital Twins via de CLI.

.NET (C#) SDK (gegevensvlak)

De Azure Digital Twins .NET -SDK (C#) maakt deel uit van de Azure SDK voor .NET. Het is een open source en is gebaseerd op de api's Azure Digital Twins gegevensvlak.

Notitie

Zie de algemene ontwerpprincipes voor Azure SDK's en de specifieke .NET-ontwerprichtlijnenvoor meer informatie over SDK-ontwerp.

Als u de SDK wilt gebruiken, moet u het NuGet-pakket Azure.DigitalTwins.Core opnemen in uw project. U hebt ook de nieuwste versie van het Azure.Identity-pakket nodig. In Visual Studio kunt u deze pakketten toevoegen met behulp van de NuGet-Pakketbeheer (toegankelijk via Hulpprogramma's > NuGet Pakketbeheer > NuGet-pakketten voor oplossing beheren). U kunt ook het .NET-opdrachtregelprogramma gebruiken met de opdrachten in de onderstaande NuGet-pakketkoppelingen om deze pakketten toe te voegen aan uw project:

Zie Code a client app (Een client-app coden) voor een gedetailleerd overzicht van het gebruik van de API'sin de praktijk.

Helpers voor serialisatie

Serialisatiehulpfuncties zijn helperfuncties die beschikbaar zijn in de SDK voor het snel maken of deserialiseren van tweelinggegevens voor toegang tot basisinformatie. Omdat de belangrijkste SDK-methoden standaard dubbele gegevens retourneren als JSON, kan het handig zijn om deze helperklassen te gebruiken om de tweelinggegevens verder op te delen.

De beschikbare helperklassen zijn:

  • BasicDigitalTwin: In het algemeen worden de kerngegevens van een digitale tweeling vertegenwoordigd
  • BasicDigitalTwinComponent: Algemene vertegenwoordigt een onderdeel in de Contents eigenschappen van een BasicDigitalTwin
  • BasicRelationship: Geeft de kerngegevens van een relatie weer in het algemeen
  • DigitalTwinsJsonPropertyName: Bevat de tekenreeksconstanten voor gebruik in JSON-serialisatie en deserialisatie voor aangepaste digital twin-typen

Algemene gebruiksnotities voor API/SDK

Notitie

Houd er rekening mee Azure Digital Twins momenteel geen ondersteuning biedt voor Cross-Origin Resource Sharing (CORS). Zie de sectie Cross-Origin Resource Sharing (CORS) van Concepten: Beveiliging voor Azure Digital Twins oplossingen voor meer informatie over de impact- en oplossingsstrategieën.

De volgende lijst bevat gedetailleerdere en algemene richtlijnen voor het gebruik van de API's en SDK's.

  • U kunt een HTTP REST-testprogramma zoals Postman gebruiken om directe aanroepen uit te voeren naar Azure Digital Twins API's. Zie API-aanvragen maken met Postman voor meer informatie over dit proces.
  • Als u de SDK wilt gebruiken, maakt u een instantie van de DigitalTwinsClient klasse . De constructor vereist referenties die kunnen worden verkregen met verschillende soorten verificatiemethoden in het Azure.Identity pakket. Zie de documentatie Azure.Identity van de naamruimte voor meer informatieover .
  • Het kan handig zijn om aan de slag te gaan, maar er zijn verschillende andere opties, waaronder referenties voor beheerde identiteit, die u waarschijnlijk gebruikt voor het verifiëren van Azure-functies die zijn ingesteld met InteractiveBrowserCredential MSI op Azure Digital Twins. Zie de InteractiveBrowserCredential klassedocumentatie voor meer informatie over.
  • Voor aanvragen naar Azure Digital Twins API's is een gebruiker of service-principal vereist die deel uitmaakt van dezelfde Azure Active Directory-tenant (Azure AD) waarin het Azure Digital Twins-exemplaar bestaat. Om schadelijke scans van Azure Digital Twins eindpunten te voorkomen, krijgen aanvragen met toegangstokens van buiten de oorspronkelijke tenant het foutbericht '404 Sub-Domain niet gevonden'. Deze fout wordt zelfs geretourneerd als de gebruiker of service-principal de rol Azure Digital Twins Gegevenseigenaar of Azure Digital Twins-gegevenslezer heeft gekregen via Azure AD B2B-samenwerking. Zie App-verificatiecode schrijven voor meer informatie over het verkrijgen van toegang tot meerdere tenants.
  • Alle service-API-aanroepen worden beschikbaar gemaakt als lidfuncties in de DigitalTwinsClient klasse .
  • Alle servicefuncties bestaan in synchrone en asynchrone versies.
  • Alle servicefuncties geven een uitzondering voor een retourstatus van 400 of hoger. Zorg ervoor dat u aanroepen in een try sectie verpakt en ten minste vangt. RequestFailedExceptions Zie de referentiedocumentatie voor meer informatie over dit type uitzondering.
  • De meeste servicemethoden retourneren of ( voor Response<T> Task<Response<T>> de asynchrone aanroepen), waarbij de klasse van T het retourobject is voor de service-aanroep. De klasse Response bevat het retour van de service en presenteert retourwaarden in het Value veld.
  • Servicemethoden met resultaten met pagina's Pageable<T> retourneren of AsyncPageable<T> als resultaten. Zie de referentiedocumentatie voor meer informatie over de klasse . Zie de Pageable<T> AsyncPageable<T> referentiedocumentatie voor meer informatie over.
  • U kunt paginade resultaten herhalen met behulp van een await foreach lus. Zie de relevante documentatie voor meer informatie over dit proces.
  • De onderliggende SDK is Azure.Core . Zie de documentatie voor Azure-naamruimte voor naslag over de infrastructuur en typen van de SDK.

Servicemethoden retourneren waar mogelijk sterk getypeerd objecten. Omdat Azure Digital Twins echter is gebaseerd op modellen die tijdens runtime door de gebruiker zijn geconfigureerd (via DTDL-modellen die zijn geüpload naar de service), nemen en retourneren veel service-API's dubbele gegevens in JSON-indeling.

Metrische API-gegevens bewaken

Metrische API-gegevens, zoals aanvragen, latentie en foutpercentage, kunnen worden bekeken in de Azure Portal.

Zoek op de startpagina van de portal naar uw Azure Digital Twins om de details ervan op te halen. Selecteer de optie Metrische gegevens in Azure Digital Twins menu van het exemplaar om de pagina Metrische gegevens weer te geven.

Schermopname van de pagina met metrische gegevens Azure Digital Twins.

Hier kunt u de metrische gegevens voor uw exemplaar bekijken en aangepaste weergaven maken.

Volgende stappen

Zie hoe u directe aanvragen naar de API's kunt maken met behulp van Postman:

U kunt ook oefenen met het gebruik van de .NET SDK door een client-app te maken met deze zelfstudie: