Azure Digital Twins-API:er och SDK:er

  • Artikel

Den här artikeln ger en översikt över tillgängliga Azure Digital Twins-API:er och metoderna 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 levereras med API:er för kontrollplan, API:er för dataplanet och SDK:er för att hantera din instans och dess element.

  • API:er för kontrollplan är API:er för Azure Resource Manager (ARM) och omfattar resurshanteringsåtgärder som att skapa och ta bort din instans.
  • API:erna för dataplanet är Azure Digital Twins-API:er och används för datahanteringsåtgärder som att hantera modeller, tvillingar och grafen.
  • SDK:erna utnyttjar de befintliga API:erna för att underlätta utvecklingen av anpassade program som använder Azure Digital Twins.

API:er för kontrollplan

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

Om du vill anropa API:erna direkt refererar du till den senaste Swagger-mappen i kontrollplanets Swagger-lagringsplats. Den här mappen innehåller också en mapp med exempel som visar användningen.

Här är de SDK:er som för närvarande är tillgängliga för Api:erna för Azure Digital Twins-kontrollplanet.

SDK-språk Paketlänk Referensdokumentation Källkod
.NET (C#) Azure.ResourceManager.DigitalTwins på NuGet Referens för Azure DigitalTwins SDK för .NET Microsoft Azure Digital Twins-hanteringsklientbibliotek för .NET på GitHub
Java azure-resourcemanager-digitaltwins på Maven Referens för Resurshantering – Digital Twins Azure Resource Manager AzureDigitalTwins-klientbibliotek för Java på GitHub
JavaScript AzureDigitalTwinsManagement-klientbibliotek för JavaScript på npm AzureDigitalTwinsManagement-klientbibliotek för JavaScript på GitHub
Python azure-mgmt-digitaltwins på PyPI Microsoft Azure SDK för Python på GitHub
Kör azure-sdk-for-go/services/digitaltwins/mgmt Azure SDK för Go på GitHub

Du kan också använda API:er för kontrollplanet genom att interagera med Azure Digital Twins via Azure-portalen och CLI.

API:er för dataplan

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 in i följande kategorier:

Om du vill anropa API:erna direkt refererar du till den senaste Swagger-mappen i dataplanets Swagger-lagringsplats. Den här mappen innehåller också en mapp med exempel som visar användningen. Du kan också visa referensdokumentationen för dataplanets API.

Här är de SDK:er som för närvarande är tillgängliga för Api:er för Azure Digital Twins-dataplanet.

SDK-språk Paketlänk Referensdokumentation Källkod
.NET (C#) Azure.DigitalTwins.Core på NuGet Referens för Azure IoT Digital Twins-klientbibliotek för .NET Azure IoT Digital Twins-klientbibliotek för .NET på GitHub
Java com.azure:azure-digitaltwins-core på Maven Referens för Azure Digital Twins SDK för Java Azure IoT Digital Twins-klientbibliotek för Java på GitHub
JavaScript Azure Azure Digital Twins Core-klientbibliotek för JavaScript på npm Reference for @azure/digital-twins-core Azure Azure Digital Twins Core-klientbibliotek för JavaScript på GitHub
Python Azure Azure Digital Twins Core-klientbibliotek för Python på PyPI Referens för azure-digitaltwins-core Azure Azure Digital Twins Core-klientbibliotek för Python på GitHub

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

Anteckningar om användning och autentisering

Det här avsnittet innehåller mer detaljerad information om hur du använder API:er och SDK:er.

API-anteckningar

Här är lite allmän information för att anropa Azure Digital Twins-API:erna direkt.

Här är lite mer information om autentisering för API-begäranden.

  • Ett sätt att generera en ägartoken för Azure Digital Twins API-begäranden är med CLI-kommandot az account get-access-token . Detaljerade instruktioner finns i Hämta ägartoken.
  • Begäranden till Azure Digital Twins-API:erna kräver en användare eller tjänstens huvudnamn som ingår i samma Microsoft Entra-ID-klientorganisation där Azure Digital Twins-instansen finns. För att förhindra skadlig genomsökning av Azure Digital Twins-slutpunkter returneras felmeddelandet "404 underdomän hittades inte" om begäranden med åtkomsttoken utanför den ursprungliga klientorganisationen. Det här felet returneras även om användaren eller tjänstens huvudnamn fick rollen Azure Digital Twins Data Owner eller Azure Digital Twins Data Reader via Microsoft Entra B2B-samarbete . Information om hur du uppnår åtkomst mellan flera klienter finns i Skriva kod för appautentisering.

SDK-anteckningar

Den underliggande SDK:t för Azure Digital Twins är Azure.Core. Mer information om SDK-infrastrukturen och -typerna finns i dokumentationen för Azure-namnområdet.

Här är lite mer information om autentisering med SDK:erna.

  • Börja med att instansiera DigitalTwinsClient klassen. Konstruktorn kräver autentiseringsuppgifter som kan hämtas med olika typer av autentiseringsmetoder i Azure.Identity paketet. Mer information finns Azure.Identityi 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 InteractiveBrowserCredentialAzure-funktioner som konfigurerats med MSI mot Azure Digital Twins. Mer information om InteractiveBrowserCredentialfinns i dess klassdokumentation.

Här är lite mer information om funktioner och returnerade data.

  • Alla tjänst-API-anrop exponeras som medlemsfunktioner i DigitalTwinsClient klassen.
  • Alla tjänstfunktioner finns i synkrona och asynkrona versioner.
  • Alla tjänstfunktioner utlöser ett undantag för returstatusen 400 eller senare. Se till att omsluta anrop till ett try avsnitt och fånga minst RequestFailedExceptions. Mer information om den här typen av undantag finns i referensdokumentationen.
  • De flesta tjänstmetoder returnerar Response<T> eller (Task<Response<T>> för asynkrona anrop), där T är klassen för returobjektet för tjänstanropet. Klassen Response kapslar in tjänstreturen och visar returvärden i fältet Value .
  • Tjänstmetoder med sidiga resultat returnerar Pageable<T> eller AsyncPageable<T> som resultat. Mer information om klassen finns i referensdokumentationen. Mer information om AsyncPageable<T>finns i referensdokumentationenPageable<T>.
  • Du kan iterera över sidiga resultat med hjälp av en await foreach loop. Mer information om den här processen finns i Iterera med Async Enumerables i C# 8.
  • Tjänstmetoder returnerar starkt typerade objekt där det är möjligt. Men eftersom Azure Digital Twins baseras på modeller som har 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.

Serialiseringshjälpare i .NET (C#) SDK

Serialiseringshjälpare är hjälpfunktioner som är tillgängliga i .NET (C#) SDK för att snabbt skapa eller deserialisera tvillingdata för åtkomst till grundläggande information. Eftersom SDK-kärnmetoderna 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 generellt kärndata för en digital tvilling
  • BasicDigitalTwinComponent: Representerar allmänt en komponent i egenskaperna för Contents en BasicDigitalTwin
  • BasicRelationship: Representerar generellt kärndata för en relation
  • DigitalTwinsJsonPropertyName: Innehåller strängkonstanterna för användning i JSON-serialisering och deserialisering för anpassade typer av digitala tvillingar

Massimport med API:et Importera jobb

API för importjobb är ett API för dataplan som gör att du kan importera en uppsättning modeller, tvillingar och/eller relationer i ett enda API-anrop. API-åtgärder för importjobb ingår också i CLI-kommandona och SDK:erna för dataplanet. Användning av API för importjobb kräver användning av Azure Blob Storage.

Kontrollera behörigheter

Om du vill använda API:et Importera jobb måste du aktivera behörighetsinställningarna som beskrivs i det här avsnittet.

Först behöver du en systemtilldelad hanterad identitet för din Azure Digital Twins-instans. Anvisningar för hur du konfigurerar en systemhanterad identitet för instansen finns i Aktivera/inaktivera hanterad identitet för instansen.

Du måste ha skrivbehörigheter i din Azure Digital Twins-instans för följande kategorier av dataåtgärder:

  • Microsoft.DigitalTwins/jobs/*
  • Alla grafelement som du vill inkludera i jobbanropet. Detta kan inkludera Microsoft.DigitalTwins/models/*, Microsoft.DigitalTwins/digitaltwins/*och/eller Microsoft.DigitalTwins/digitaltwins/relationships/*.

Den inbyggda rollen som ger alla dessa behörigheter är Azure Digital Twins Data Owner. Du kan också använda en anpassad roll för att ge detaljerad åtkomst till endast de datatyper som du behöver. Mer information om roller i Azure Digital Twins finns i Säkerhet för Azure Digital Twins-lösningar.

Kommentar

Om du försöker köra ett API-anrop för importjobb och du saknar skrivbehörighet till någon av de diagramelementtyper som du försöker importera hoppar jobbet över den typen och importerar de andra. Om du till exempel har skrivåtkomst till modeller och tvillingar, men inte relationer, kommer ett försök att massimportera alla tre typerna av element bara att lyckas importera modellerna och tvillingarna. Jobbstatusen återspeglar ett fel och meddelandet anger vilka behörigheter som saknas.

Du måste också bevilja följande RBAC-behörigheter till den systemtilldelade hanterade identiteten för din Azure Digital Twins-instans så att den kan komma åt indata- och utdatafiler i Azure Blob Storage-containern:

Generera slutligen en ägartoken som kan användas i dina begäranden till jobb-API:et. Instruktioner finns i Hämta ägartoken.

Formatera data

API:et accepterar diagraminformationsindata från en NDJSON-fil , som måste laddas upp till en Azure Blob Storage-container . Filen börjar med ett Header avsnitt följt av de valfria avsnitten Models, Twinsoch Relationships. Du behöver inte inkludera alla tre typerna av grafdata i filen, men alla avsnitt som finns måste följa den ordningen. Tvillingar och relationer som skapats med det här API:et kan också inkludera initiering av deras egenskaper.

Här är en exempelindatafil för import-API:et:

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

Dricks

Ett exempelprojekt som konverterar modeller, tvillingar och relationer till NDJSON som stöds av import-API:et finns i Azure Digital Twins Bulk Import NDJSON Generator. Exempelprojektet är skrivet för .NET och kan laddas ned eller anpassas för att hjälpa dig att skapa egna importfiler.

När filen har skapats laddar du upp den till en blockblob i Azure Blob Storage med den uppladdningsmetod du föredrar (vissa alternativ är Kommandot AzCopy, Azure CLI eller Azure-portalen). Du använder bloblagrings-URL:en för NDJSON-filen i brödtexten i API-anropet Importera jobb.

Kör importjobbet

Nu kan du fortsätta med att anropa API:et För importjobb. Detaljerade anvisningar om hur du importerar ett fullständigt diagram i ett API-anrop finns i Ladda upp modeller, tvillingar och relationer i bulk med API:et Importera jobb. Du kan också använda API:et Importera jobb för att importera varje resurstyp oberoende av varandra. Mer information om hur du använder API:et Importera jobb med enskilda resurstyper finns i Importera api-instruktioner för jobb för modeller, tvillingar och relationer.

I api-anropets brödtext anger du bloblagrings-URL:en för NDJSON-indatafilen. Du anger också en ny bloblagrings-URL som anger var du vill att utdataloggen ska lagras när tjänsten skapar den.

Viktigt!

Kontrollera att den systemtilldelade hanterade identiteten för din Azure Digital Twins-instans har de RBAC-behörigheter för lagringsblob som beskrivs i avsnittet Kontrollera behörigheter.

När importjobbet körs genereras en strukturerad utdatalogg av tjänsten och lagras som en ny tilläggsblob i blobcontainern på den URL-plats som du angav för utdatabloben i begäran. Här är ett exempel på utdataloggen för ett lyckat jobb med att importera modeller, tvillingar och relationer:

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

När jobbet är klart kan du se det totala antalet inmatade entiteter med måttet BulkOperationEntityCount.

Det går också att avbryta ett importjobb som körs med åtgärden Avbryt från API:et Importera jobb. När jobbet har avbrutits och inte längre körs kan du ta bort det.

Begränsningar och överväganden

Tänk på följande när du arbetar med API:et importera jobb:

  • Importjobb är inte atomiska åtgärder. Det finns ingen återställning vid fel, partiellt slutförande av jobb eller användning av åtgärden Avbryt.
  • Endast ett massjobb stöds i taget i en Azure Digital Twins-instans. Du kan visa den här informationen och andra numeriska gränser för jobb-API:erna i Azure Digital Twins-gränser.

Massborttagning med API:et Ta bort jobb

API:et Ta bort jobb är ett API för dataplan som gör att du kan ta bort alla modeller, tvillingar och relationer i en instans med ett enda API-anrop. API-åtgärder för att ta bort jobb är också tillgängliga som CLI-kommandon. Gå till API-dokumentationen för att se information om begäran för att skapa ett borttagningsjobb och kontrollera dess status.

Följ dessa rekommendationer när du använder API:et Ta bort jobb för att se till att alla element tas bort:

  • Anvisningar om hur du genererar en ägartoken för att autentisera API-begäranden finns i Hämta ägartoken.
  • Om du nyligen har importerat ett stort antal entiteter till diagrammet väntar du en stund och kontrollerar att alla element synkroniseras i diagrammet innan du påbörjar borttagningsjobbet.
  • Stoppa alla åtgärder på instansen, särskilt uppladdningsåtgärder, tills borttagningsjobbet har slutförts.

Beroende på storleken på diagrammet som tas bort kan ett borttagningsjobb ta allt från några minuter till flera timmar.

Standardtidsgränsen för ett borttagningsjobb är 12 timmar, vilket kan justeras till valfritt värde mellan 15 minuter och 24 timmar med hjälp av en frågeparameter i API:et. Det här är den tid som borttagningsjobbet körs innan tidsgränsen uppnås, då tjänsten försöker stoppa jobbet om det inte har slutförts ännu.

Begränsningar och andra överväganden

Tänk på följande när du arbetar med API:et Ta bort jobb:

  • Ta bort jobb är inte atomiska åtgärder. Det finns ingen återställning vid fel, delvis slutförande av jobb eller tidsgräns för jobbet.
  • Endast ett massjobb stöds i taget i en Azure Digital Twins-instans. Du kan visa den här informationen och andra numeriska gränser för jobb-API:erna i Azure Digital Twins-gränser.

Övervaka API-mått

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

Information om hur du visar och hanterar Azure Digital Twins-mått finns i Övervaka din instans. En fullständig lista över API-mått som är tillgängliga för Azure Digital Twins finns i Azure Digital Twins API-mått för begäran.

Nästa steg

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

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