Azure Digital Twins-API's en SDK's
Dit artikel bevat een overzicht van de beschikbare Azure Digital Twins-API's en de methoden voor interactie met deze API's. U kunt de REST API's rechtstreeks gebruiken met hun bijbehorende Swaggers (via een hulpprogramma zoals Postman) of via een SDK.
Azure Digital Twins is uitgerust met besturingsvlak-API's, GEGEVENSvlak-API's en SDK's voor het beheren van uw exemplaar en de bijbehorende elementen.
- De API's van het besturingsvlak zijn ARM-API's (Azure Resource Manager) en hebben betrekking op resourcebeheerbewerkingen, zoals het maken en verwijderen van uw exemplaar.
- De API's voor het gegevensvlak zijn Azure Digital Twins-API's en worden gebruikt voor gegevensbeheerbewerkingen, zoals het beheren van modellen, tweelingen en de grafiek.
- De SDK's maken gebruik van de bestaande API's om het ontwikkelen van aangepaste toepassingen te vereenvoudigen door gebruik te maken van Azure Digital Twins.
API's voor besturingsvlak
De API's van het besturingsvlak zijn ARM-API's die worden gebruikt voor het beheren van uw Azure Digital Twins-exemplaar als geheel, zodat ze bewerkingen behandelen, zoals het maken of verwijderen van uw hele exemplaar. U gebruikt deze API's ook om eindpunten te maken en te verwijderen.
Als u de API's rechtstreeks wilt aanroepen, verwijst u naar de meest recente Swagger-map in de Swagger-opslagplaats van het besturingsvlak. Deze map bevat ook een map met voorbeelden waarin het gebruik wordt weergegeven.
Dit zijn de SDK's die momenteel beschikbaar zijn voor de Azure Digital Twins-besturingsvlak-API's.
U kunt ook de besturingsvlak-API's oefenen door te communiceren met Azure Digital Twins via Azure Portal en CLI.
API's voor gegevensvlak
De gegevensvlak-API's zijn de Azure Digital Twins-API's die worden gebruikt om de elementen binnen uw Azure Digital Twins-exemplaar te beheren. Ze omvatten bewerkingen zoals het maken van routes, het uploaden van modellen, het maken van relaties en het beheren van dubbels, 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 uploaden, valideren, ophalen en verwijderen van modellen die zijn geschreven in DTDL.DigitalTwins- De categorie DigitalTwins bevat de API's waarmee ontwikkelaars digitale dubbels en hun relaties in een Azure Digital Twins-exemplaar kunnen maken, wijzigen en verwijderen.Query- Met de categorie Query kunnen ontwikkelaars sets met digitale dubbels vinden in de tweelinggrafiek tussen relaties.Event Routes- De categorie Gebeurtenisroutes bevat API's voor het routeren van gegevens, via het systeem en naar downstreamservices.Import Jobs- Met de API Voor importtaken kunt u een langdurige, asynchrone actie beheren om modellen, tweelingen en relaties bulksgewijs te importeren.Delete Jobs- Met de API Taken verwijderen kunt u een langlopende, asynchrone actie beheren om alle modellen, tweelingen en relaties in een exemplaar te verwijderen.
Als u de API's rechtstreeks wilt aanroepen, verwijst u naar de meest recente Swagger-map in de Swagger-opslagplaats van het gegevensvlak. Deze map bevat ook een map met voorbeelden waarin het gebruik wordt weergegeven. U kunt ook de api-referentiedocumentatie voor het gegevensvlak bekijken.
Dit zijn de SDK's die momenteel beschikbaar zijn voor de Azure Digital Twins-gegevensvlak-API's.
U kunt ook de API's voor het gegevensvlak oefenen door te communiceren met Azure Digital Twins via de CLI.
Opmerkingen bij gebruik en verificatie
Deze sectie bevat gedetailleerdere informatie over het gebruik van de API's en SDK's.
API-notities
Hier volgt enkele algemene informatie voor het rechtstreeks aanroepen van de Azure Digital Twins-API's.
- U kunt een HTTP REST-testprogramma zoals Postman gebruiken om directe aanroepen te doen naar de Azure Digital Twins-API's. Zie De Azure Digital Twins-API's aanroepen met Postman voor meer informatie over dit proces.
- Azure Digital Twins biedt momenteel geen ondersteuning voor Cross-Origin Resource Sharing (CORS). Zie Cross-Origin Resource Sharing (CORS) voor Azure Digital Twins voor meer informatie over de impact- en oplossingsstrategieën.
Hier vindt u meer informatie over verificatie voor API-aanvragen.
- Een manier om een Bearer-token te genereren voor Azure Digital Twins API-aanvragen is met de CLI-opdracht az account get-access-token . Zie Get bearer-token voor gedetailleerde instructies.
- Aanvragen voor de Azure Digital Twins-API's vereisen een gebruiker of service-principal die deel uitmaakt van dezelfde Microsoft Entra ID-tenant waar het Azure Digital Twins-exemplaar bestaat. Om kwaadwillende scans van Azure Digital Twins-eindpunten te voorkomen, krijgen aanvragen met toegangstokens van buiten de oorspronkelijke tenant een foutbericht '404 Subdomein niet gevonden'. Deze fout wordt geretourneerd, zelfs als de gebruiker of service-principal een Azure Digital Twins-gegevenseigenaar of Azure Digital Twins-gegevenslezerrol heeft gekregen via Microsoft Entra B2B-samenwerking . Zie App-verificatiecode schrijven voor meer informatie over het verkrijgen van toegang tot meerdere tenants.
SDK-notities
De onderliggende SDK voor Azure Digital Twins is Azure.Core. Raadpleeg de documentatie voor De Azure-naamruimte voor naslaginformatie over de SDK-infrastructuur en -typen.
Hier vindt u meer informatie over verificatie met de SDK's.
- Begin met het instantiëren van de
DigitalTwinsClientklas. De constructor vereist referenties die kunnen worden verkregen met verschillende soorten verificatiemethoden in hetAzure.Identitypakket. Zie de documentatie voor de naamruimte voor meer informatieAzure.Identity. - U kunt het nuttig vinden tijdens het aan de
InteractiveBrowserCredentialslag gaan, maar er zijn verschillende andere opties, waaronder referenties voor beheerde identiteit, die u waarschijnlijk gebruikt om Azure-functies te verifiëren die zijn ingesteld met MSI voor Azure Digital Twins. Zie de klassedocumentatie voor meer informatieInteractiveBrowserCredential.
Hier vindt u meer informatie over functies en geretourneerde gegevens.
- Alle service-API-aanroepen worden weergegeven als lidfuncties in de
DigitalTwinsClientklasse. - Alle servicefuncties bestaan in synchrone en asynchrone versies.
- Alle servicefuncties genereren een uitzondering voor elke retourstatus van 400 of hoger. Zorg ervoor dat u aanroepen in een
trysectie verpakt en ten minsteRequestFailedExceptionsonderscheppen. Zie de referentiedocumentatie voor meer informatie over dit type uitzondering. - De meeste servicemethoden retourneren
Response<T>of (Task<Response<T>>voor de asynchrone aanroepen), waarbijTde klasse retourobject voor de serviceaanroep is. De antwoordklasse bevat het retourneert de service en geeft retourwaarden weer in hetValueveld. - Servicemethoden met gepaginade resultaten retourneren
Pageable<T>ofAsyncPageable<T>als resultaten. Zie de referentiedocumentatie voor meer informatie over dePageable<T>klasse. Zie de referentiedocumentatie voor meer informatieAsyncPageable<T>. - U kunt gepaginade resultaten herhalen met behulp van een
await foreachlus. Zie Itereren met Async Enumerables in C# 8 voor meer informatie over dit proces. - Servicemethoden retourneren waar mogelijk sterk getypte 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 veel service-API's dubbele gegevens in JSON-indeling en retourneren ze deze.
Serialisatie-helpers in de .NET -SDK (C#)
Serialisatiehelpers zijn helperfuncties die beschikbaar zijn in de .NET-SDK (C#) voor het snel maken of deserialiseren van dubbelgegevens voor toegang tot basisinformatie. Omdat de belangrijkste SDK-methoden standaard dubbelgegevens als JSON retourneren, kan het handig zijn om deze helperklassen te gebruiken om de dubbelgegevens verder op te splitsen.
De beschikbare helperklassen zijn:
BasicDigitalTwin: Algemeen vertegenwoordigt de kerngegevens van een digitale dubbelBasicDigitalTwinComponent: Algemeen vertegenwoordigt een onderdeel in deContentseigenschappen van eenBasicDigitalTwinBasicRelationship: Algemeen vertegenwoordigt de kerngegevens van een relatieDigitalTwinsJsonPropertyName: Bevat de tekenreeksconstanten voor gebruik in JSON-serialisatie en deserialisatie voor aangepaste typen digitale dubbels
Bulksgewijs importeren met de IMPORT Jobs-API
De IMPORT Jobs-API is een gegevensvlak-API waarmee u een set modellen, dubbels en/of relaties in één API-aanroep kunt importeren. Api-bewerkingen voor importtaken zijn ook opgenomen in de CLI-opdrachten en SDK's voor het gegevensvlak. Voor het gebruik van de IMPORT Jobs-API is het gebruik van Azure Blob Storage vereist.
Machtigingen controleren
Als u de IMPORT Jobs-API wilt gebruiken, moet u de machtigingsinstellingen inschakelen die in deze sectie worden beschreven.
Eerst hebt u een door het systeem toegewezen beheerde identiteit nodig voor uw Azure Digital Twins-exemplaar. Zie Beheerde identiteit voor het exemplaar in-/uitschakelen voor instructies voor het instellen van een door het systeem beheerde identiteit voor het exemplaar.
U moet schrijfmachtigingen hebben in uw Azure Digital Twins-exemplaar voor de volgende gegevensactiecategorieën:
Microsoft.DigitalTwins/jobs/*- Alle grafiekelementen die u wilt opnemen in de aanroep Taken. Dit kan zijn
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*en/ofMicrosoft.DigitalTwins/digitaltwins/relationships/*.
De ingebouwde rol die al deze machtigingen biedt, is Azure Digital Twins-gegevenseigenaar. U kunt ook een aangepaste rol gebruiken om gedetailleerde toegang te verlenen tot alleen de gegevenstypen die u nodig hebt. Zie Beveiliging voor Azure Digital Twins-oplossingen voor meer informatie over rollen in Azure Digital Twins.
Notitie
Als u een API-aanroep voor Import Jobs probeert uit te voeren en u schrijfmachtigingen mist voor een van de grafiekelementtypen die u wilt importeren, slaat de taak dat type over en importeert u de andere. Als u bijvoorbeeld schrijftoegang hebt tot modellen en dubbels, maar geen relaties, slaagt een poging om alle drie de typen elementen bulksgewijs te importeren alleen de modellen en dubbels te importeren. De taakstatus geeft een fout weer en het bericht geeft aan welke machtigingen ontbreken.
U moet ook de volgende RBAC-machtigingen verlenen aan de door het systeem toegewezen beheerde identiteit van uw Azure Digital Twins-exemplaar, zodat deze toegang heeft tot invoer- en uitvoerbestanden in de Azure Blob Storage-container:
- Opslagblobgegevenslezer voor de Azure Storage-invoerblobcontainer
- Inzender voor Opslagblobgegevens voor de Azure Storage-uitvoerblobcontainer
Genereer ten slotte een Bearer-token dat kan worden gebruikt in uw aanvragen voor de Taken-API. Zie Bearer-token ophalen voor instructies.
Gegevens indelen
De API accepteert graafgegevensinvoer van een NDJSON-bestand , dat moet worden geüpload naar een Azure Blob Storage-container . Het bestand begint met een Header sectie, gevolgd door de optionele secties Models, Twinsen Relationships. U hoeft niet alle drie de typen grafiekgegevens in het bestand op te nemen, maar alle secties die aanwezig zijn, moeten deze volgorde volgen. Tweelingen en relaties die met deze API zijn gemaakt, kunnen eventueel initialisatie van hun eigenschappen bevatten.
Hier volgt een voorbeeld van een invoergegevensbestand voor de import-API:
{"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}
Tip
Voor een voorbeeldproject waarmee modellen, tweelingen en relaties worden geconverteerd naar de NDJSON die wordt ondersteund door de import-API, raadpleegt u Azure Digital Twins Bulk Import NDJSON Generator. Het voorbeeldproject is geschreven voor .NET en kan worden gedownload of aangepast om u te helpen bij het maken van uw eigen importbestanden.
Zodra het bestand is gemaakt, uploadt u het naar een blok-blob in Azure Blob Storage met behulp van de uploadmethode van uw voorkeur (sommige opties zijn de AzCopy-opdracht, de Azure CLI of Azure Portal). U gebruikt de BLOB Storage-URL van het NDJSON-bestand in de hoofdtekst van de API-aanroep Taken importeren.
De importtaak uitvoeren
U kunt nu doorgaan met het aanroepen van de IMPORT Jobs-API. Zie Modellen, tweelingen en relaties bulksgewijs uploaden met de Import Jobs-API voor gedetailleerde instructies voor het importeren van een volledige grafiek in één API-aanroep. U kunt ook de IMPORT Jobs-API gebruiken om elk resourcetype onafhankelijk te importeren. Zie Import Jobs API-instructies voor modellen, tweelingen en relaties voor meer informatie over het gebruik van de API importtaken met afzonderlijke resourcetypen.
In de hoofdtekst van de API-aanroep geeft u de BLOB Storage-URL van het NDJSON-invoerbestand op. U geeft ook een nieuwe BLOB Storage-URL op om aan te geven waar u het uitvoerlogboek wilt opslaan zodra de service het heeft gemaakt.
Belangrijk
Zorg ervoor dat de door het systeem toegewezen beheerde identiteit van uw Azure Digital Twins-exemplaar de RBAC-machtigingen voor opslagblob heeft die worden beschreven in de sectie Machtigingen controleren.
Wanneer de importtaak wordt uitgevoerd, wordt er een gestructureerd uitvoerlogboek gegenereerd door de service en opgeslagen als een nieuwe toevoeg-blob in uw blobcontainer, op de URL-locatie die u hebt opgegeven voor de uitvoer-blob in de aanvraag. Hier volgt een voorbeeld van een uitvoerlogboek voor het importeren van modellen, tweelingen en relaties voor een geslaagde taak:
{"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"}}
Wanneer de taak is voltooid, kunt u het totale aantal opgenomen entiteiten zien met behulp van de metrische gegevens BulkOperationEntityCount.
Het is ook mogelijk om een actieve importtaak te annuleren met de bewerking Annuleren vanuit de IMPORT Jobs-API. Zodra de taak is geannuleerd en niet meer wordt uitgevoerd, kunt u deze verwijderen.
Limieten en overwegingen
Houd rekening met de volgende overwegingen bij het werken met de API importtaken:
- Importtaken zijn geen atomische bewerkingen. Er is geen terugdraaiactie in het geval van een fout, gedeeltelijke voltooiing van de taak of het gebruik van de bewerking Annuleren.
- Er wordt slechts één bulktaak tegelijk ondersteund binnen een Azure Digital Twins-exemplaar. U kunt deze informatie en andere numerieke limieten van de taak-API's in Azure Digital Twins-limieten bekijken.
Bulksgewijs verwijderen met de TAKEN-API verwijderen
De Delete Jobs-API is een gegevensvlak-API waarmee u alle modellen, tweelingen en relaties in een exemplaar kunt verwijderen met één API-aanroep. Verwijdertaken-API-bewerkingen zijn ook beschikbaar als CLI-opdrachten. Ga naar de API-documentatie om de aanvraagdetails voor het maken van een verwijdertaak te bekijken en de status ervan te controleren.
Als u ervoor wilt zorgen dat alle elementen worden verwijderd, volgt u deze aanbevelingen tijdens het gebruik van de API Taken verwijderen:
- Zie Bearer-token ophalen voor instructies voor het genereren van een Bearer-token voor het verifiëren van API-aanvragen.
- Als u onlangs een groot aantal entiteiten in uw grafiek hebt geïmporteerd, wacht u even en controleert u of alle elementen in uw grafiek zijn gesynchroniseerd voordat u de verwijdertaak start.
- Stop alle bewerkingen op het exemplaar, met name uploadbewerkingen, totdat de verwijdertaak is voltooid.
Afhankelijk van de grootte van de grafiek die wordt verwijderd, kan een verwijdertaak een paar minuten tot meerdere uren duren.
De standaardtime-outperiode voor een verwijdertaak is 12 uur, die kan worden aangepast aan elke waarde tussen 15 minuten en 24 uur met behulp van een queryparameter in de API. Dit is de hoeveelheid tijd die de verwijdertaak uitvoert voordat er een time-out optreedt. Op dat moment probeert de service de taak te stoppen als deze nog niet is voltooid.
Limieten en andere overwegingen
Houd rekening met de volgende overwegingen bij het werken met de DELETE Jobs-API:
- Verwijdertaken zijn geen atomische bewerkingen. Er is geen terugdraaiactie in het geval van een fout, gedeeltelijke taakvoltooiing of time-out van de taak.
- Er wordt slechts één bulktaak tegelijk ondersteund binnen een Azure Digital Twins-exemplaar. U kunt deze informatie en andere numerieke limieten van de taak-API's in Azure Digital Twins-limieten bekijken.
Metrische API-gegevens bewaken
API-metrische gegevens, zoals aanvragen, latentie en foutpercentage, kunnen worden weergegeven in Azure Portal.
Zie Uw exemplaar bewaken voor informatie over het weergeven en beheren van metrische gegevens van Azure Digital Twins. Zie metrische gegevens voor Azure Digital Twins voor een volledige lijst met api-metrische gegevens die beschikbaar zijn voor Azure Digital Twins.
Volgende stappen
Zie hoe u directe aanvragen kunt indienen bij de Azure Digital Twins-API's met behulp van Postman:
U kunt ook oefenen met behulp van de .NET SDK door een client-app te maken met deze zelfstudie: