Azure Digital Twins-API:er och -API:er

  • Artikel
  • 7 minuter för att läsa

Den här artikeln ger en översikt över Azure Digital Twins TILLGÄNGLIGA API:er och metoder för att interagera med dem. Du kan antingen använda REST-API:erna direkt med deras associerade Swaggers (via ett verktyg som Postman) eller via ett SDK.

Azure Digital Twins har API:er för kontrollplan, API:er för dataplanet och API:er för att hantera din instans och dess element.

  • API:erna för kontrollplanet är Azure Resource Manager(ARM)-API:er och täcker resurshanteringsåtgärder som att skapa och ta bort din instans.
  • API:erna för dataplanet Azure Digital Twins API:er och används för datahanteringsåtgärder som att hantera modeller, tvillingar och grafen.
  • MED HJÄLP av de befintliga API:erna kan du enkelt utveckla anpassade program som använder Azure Digital Twins. Kontrollplans-SDK:erna är tillgängliga i .NET (C#) och Java,och dataplans-SDK:erna är tillgängliga i .NET (C#), Java, JavaScriptoch Python.

Översikt: API:er för kontrollplan

API:erna för kontrollplanet är ARM-API:er som används för att hantera Azure Digital Twins instansen som helhet, så de täcker åtgärder som att skapa eller ta bort hela instansen. Du kommer också att använda dessa API:er för att skapa och ta bort slutpunkter.

Den senaste API-versionen för kontrollplanet är 2020-12-01.

Så här använder du API:er för kontrollplanet:

Du kan också använda API:er för kontrollplan genom att interagera Azure Digital Twins via Azure Portal och CLI.

Översikt: API:er för dataplanet

API:erna för dataplanet är de Azure Digital Twins API:er som används för att hantera elementen i din Azure Digital Twins instans. De omfattar åtgärder som att skapa vägar, ladda upp modeller, skapa relationer och hantera tvillingar och kan delas upp i följande kategorier:

  • DigitalTwinModels – Kategorin DigitalTwinModels innehåller API:er för att hantera modeller i en Azure Digital Twins instans. Hanteringsaktiviteter omfattar överföring, verifiering, hämtning och borttagning av modeller som har redigerats i DTDL.
  • DigitalTwins – Kategorin DigitalTwins innehåller API:er som gör att utvecklare kan skapa, ändra och ta bort digitala tvillingar och deras relationer i en Azure Digital Twins instans.
  • Fråga – Kategorin Fråga gör att utvecklare kan hitta uppsättningar av digitala tvillingar i tvillingdiagrammet över relationer.
  • Händelsevägar – Kategorin Händelsevägar innehåller API:er för att dirigera data, via systemet och till underordnade tjänster.

Den senaste API-versionen för dataplanet är 2020-10-31.

Så här använder du API:er för dataplanet:

Du kan också använda API:er för datumplan genom att interagera Azure Digital Twins via CLI.

.NET (C#) SDK (dataplan)

Den Azure Digital Twins .NET (C#) SDK är en del av Azure SDK för .NET. Den har öppen källkod och baseras på de Azure Digital Twins API:erna för dataplanet.

Anteckning

Mer information om SDK-design finns i de allmänna designprinciperna för Azure SDK:er och de specifika riktlinjerna för .NET-design.

Om du vill använda SDK:n inkluderar du NuGet-paketet Azure.DigitalTwins.Core med ditt projekt. Du behöver också den senaste versionen av Azure.Identity-paketet. I Visual Studio kan du lägga till dessa paket med hjälp av NuGet Package Manager (nås via Tools > NuGet Package Manager > Manage NuGet Packages for Solution). Du kan också använda .NET-kommandoradsverktyget med kommandona i NuGet-paketlänkarna nedan för att lägga till dessa paket i projektet:

En detaljerad genomgång av hur du använder API:erna i praktiken finns i Koda en klientapp.

Serialiseringshjälpare

Serialiseringshjälpfunktioner är hjälpfunktioner som är tillgängliga i SDK:n för att snabbt skapa eller deserialisera tvillingdata för åtkomst till grundläggande information. Eftersom de grundläggande SDK-metoderna returnerar tvillingdata som JSON som standard kan det vara bra att använda dessa hjälpklasser för att dela upp tvillingdata ytterligare.

De tillgängliga hjälpklasserna är:

  • BasicDigitalTwin: Representerar huvuddata för en digital tvilling
  • BasicDigitalTwinComponent: Representerar en komponent i egenskaperna för Contents en BasicDigitalTwin
  • BasicRelationship: Representerar grundläggande data i en relation
  • DigitalTwinsJsonPropertyName: Innehåller strängkonstanterna för användning i JSON-serialisering och deserialisering för anpassade digitala tvillingtyper

Allmän information om API/SDK-användning

Anteckning

Observera att Azure Digital Twins inte stöder resursdelning för korsande ursprung (CORS). Mer information om effekt- och lösningsstrategier finns i avsnittet Resursdelning för korsande ursprung (CORS) i Begrepp: Säkerhet för Azure Digital Twins lösningar.

Följande lista innehåller mer detaljerad information och allmänna riktlinjer för att använda API:er och SDK:er.

  • Du kan använda ett HTTP REST-testverktyg som Postman för att göra direkta anrop till Azure Digital Twins API:er. Mer information om den här processen finns i Göra API-begäranden med Postman.
  • Om du vill använda SDK:n instansierar du DigitalTwinsClient klassen . Konstruktorn kräver autentiseringsuppgifter som kan hämtas med olika typer av autentiseringsmetoder i Azure.Identity paketet. Mer information om Azure.Identity finns i dokumentationen om namnområdet.
  • Det kan vara användbart när du kommer igång, men det finns flera andra alternativ, inklusive autentiseringsuppgifter för hanterad identitet , som du förmodligen använder för att autentisera Azure-funktioner som har ställts in med InteractiveBrowserCredential MSI mot Azure Digital Twins. Mer information om InteractiveBrowserCredential finns i dess klassdokumentation.
  • Begäranden till Azure Digital Twins-API:er kräver en användare eller tjänstens huvudnamn som är en del av samma Azure Active Directory-klientorganisation (Azure AD) där Azure Digital Twins-instansen finns. För att förhindra skadlig genomsökning Azure Digital Twins slutpunkter returneras begäranden med åtkomsttoken utanför den ursprungliga klienten ett felmeddelande om att "404 Sub-Domain kunde inte hittas". Det här felet returneras även om användarens eller tjänstens huvudnamn har fått rollen Azure Digital Twins dataägare eller Azure Digital Twins dataläsare via Azure AD B2B-samarbete. Information om hur du uppnår åtkomst över flera klienter finns i Skriva kod för appautentisering.
  • Alla tjänst-API-anrop exponeras som medlemsfunktioner i DigitalTwinsClient klassen .
  • Alla tjänstfunktioner finns i synkrona och asynkrona versioner.
  • Alla tjänstfunktioner returnerar ett undantag för returstatusen 400 eller högre. Se till att omsluta anrop try i ett avsnitt och fånga minst RequestFailedExceptions . Mer information om den här typen av undantag finns i referensdokumentationen.
  • De flesta tjänstmetoder Response<T> returnerar eller ( Task<Response<T>> för asynkrona anrop), där T är klassen för returobjektet för tjänstanropet. Svarsklassen kapslar in tjänstretur och visar returvärden i Value fältet.
  • Tjänstmetoder med sidindelade resultat Pageable<T> returnerar AsyncPageable<T> eller som resultat. Mer information om Pageable<T> klassen finns i dess referensdokumentation. Mer information finns AsyncPageable<T> i dess referensdokumentation.
  • Du kan iterera över sidindelade resultat med hjälp av en await foreach loop. Mer information om den här processen finns i relevant dokumentation.
  • Den underliggande SDK:n är Azure.Core . Se Azure-namnområdesdokumentationen för referens om SDK-infrastruktur och -typer.

Tjänstmetoder returnerar starkt typifierade objekt där det är möjligt. Men eftersom Azure Digital Twins baseras på modeller som konfigurerats av användaren vid körning (via DTDL-modeller som laddats upp till tjänsten), tar många tjänst-API:er och returnerar tvillingdata i JSON-format.

Övervaka API-mått

API-mått som begäranden, svarstid och felfrekvens kan visas i Azure Portal .

Från portalens startsida söker du efter din Azure Digital Twins instans för att hämta information om den. Välj alternativet Mått på Azure Digital Twins instansens meny för att öppna sidan Mått.

Skärmbild som visar måttsidan för Azure Digital Twins.

Härifrån kan du visa måtten för din instans och skapa anpassade vyer.

Nästa steg

Se hur du gör direkta begäranden till API:erna med Postman:

Eller öva på att använda .NET SDK genom att skapa en klientapp med den här självstudien: