API-uri si SDK-uri Azure Digital Twins – Azure Digital Twins

• 30.04.2021
• 11 minute de citit

• • b

  • v

In acest articol

Azure Digital Twins este echipat atat cu API-uri de plan de control, cat si cu API-uri de plan de date pentru gestionarea instantei si a elementelor sale.

• API-urile planului de control sunt API-urile Azure Resource Manager (ARM) si acopera operatiunile de gestionare a resurselor, cum ar fi crearea si stergerea instantei.
• API-urile planului de date sunt API-urile pentru gemeni digitali Azure si sunt utilizate pentru operatiuni de gestionare a datelor, cum ar fi gestionarea modelelor, a gemenilor si a graficului.

Acest articol ofera o prezentare generala a API-urilor disponibile si a metodelor de interactiune cu acestea. Puteti utiliza API-urile REST direct cu Swagger-urile lor asociate (printr-un instrument precum Postman), sau printr-un SDK.

Prezentare generala: API-uri de plan de control

API-urile planului de control sunt API-urile ARM utilizate pentru a gestiona instanta Azure Digital Twins ca intreg, deci acopera operatiuni precum crearea sau stergerea intregii instante. De asemenea, le veti utiliza pentru a crea si sterge puncte finale.

Cea mai actuala versiune API a planului de control este 2020-12-01 .

Pentru a utiliza API-urile planului de control:

• Puteti apela API-urile direct facand referire la cel mai recent folder Swagger din planul de control Swagger repo. Acest folder include, de asemenea, un folder cu exemple care arata utilizarea.
• Puteti accesa in prezent SDK-uri pentru API-urile de control din …
  • .NET (C #) (referinta [generat automat]) (sursa)
  • Java (referinta [generat automat]) (sursa)
  • JavaScript (sursa)
  • Python (sursa)
  • Du-te (sursa)

De asemenea, puteti exercita API-uri de plan de control interactionand cu Azure Digital Twins prin portalul Azure si CLI.

Prezentare generala: API-uri pentru planul de date

API-urile pentru planul de date sunt API-urile Azure Digital Twins utilizate pentru a gestiona elementele din instanta dvs. Azure Digital Twins. Acestea includ operatiuni precum crearea de rute, incarcarea de modele, crearea de relatii si gestionarea gemenilor. Ele pot fi impartite in general in urmatoarele categorii:

• DigitalTwinModels – categoria DigitalTwinModels contine API-uri pentru a gestiona modelele intr-o instanta Azure Digital Twins. Activitatile de gestionare includ incarcarea, validarea, recuperarea si stergerea modelelor create in DTDL.
• DigitalTwins – categoria DigitalTwins contine API-urile care permit dezvoltatorilor sa creeze, sa modifice si sa stearga gemeni digitali si relatiile lor intr-o instanta Azure Digital Twins.
• Interogare – categoria Interogare permite dezvoltatorilor sa gaseasca seturi de gemeni digitali in graficul gemene intre relatii.
• Rute eveniment – categoria Rute eveniment contine API-uri pentru rutarea datelor, prin sistem si catre serviciile din aval.

Cea mai recenta versiune API a planului de date este 2020-10-31 .

Pentru a utiliza API-urile planului de date:

• Puteti apela API-urile direct, prin …
  • facand referire la cel mai recent folder Swagger din planul de date Swagger repo. Acest folder include, de asemenea, un folder cu exemple care arata utilizarea.
  • vizualizarea documentatiei de referinta API.
• Puteti utiliza SDK- ul .NET (C #) . Pentru a utiliza .NET SDK …
  • puteti vizualiza si adauga pachetul din NuGet: Azure.DigitalTwins.Core.
  • puteti vizualiza documentatia de referinta SDK.
  • puteti gasi sursa SDK, inclusiv un folder de mostre, in GitHub: biblioteca client Azure IoT Digital Twins pentru .NET.
  • puteti vedea informatii detaliate si exemple de utilizare continuand la sectiunea .NET (C #) SDK (plan de date) din acest articol.
• Puteti utiliza SDK-ul Java . Pentru a utiliza SDK-ul Java …
  • puteti vizualiza si instala pachetul de la Maven: com.azure:azure-digitaltwins-core
  • puteti vizualiza documentatia de referinta SDK
  • puteti gasi sursa SDK in GitHub: biblioteca client Azure IoT Digital Twins pentru Java
• Puteti utiliza SDK-ul JavaScript . Pentru a utiliza kitul SDK JavaScript …
  • puteti vizualiza si instala pachetul de la npm: biblioteca client Azure Azure Digital Twins Core pentru JavaScript.
  • puteti vizualiza documentatia de referinta SDK.
  • puteti gasi sursa SDK in GitHub: biblioteca client Azure Azure Digital Twins Core pentru JavaScript
• Puteti utiliza SDK-ul Python . Pentru a utiliza SDK-ul Python …
  • puteti vizualiza si instala pachetul din PyPi: biblioteca client Azure Azure Digital Twins Core pentru Python.
  • puteti vizualiza documentatia de referinta SDK.
  • puteti gasi sursa SDK in GitHub: Azure Azure Digital Twins Core client client pentru Python

De asemenea, puteti exercita API-urile planului de data prin interactiunea cu Azure Digital Twins prin CLI.

.NET (C #) SDK (plan de date)

SDK Azure Digital Twins .NET (C #) face parte din SDK Azure pentru .NET. Este open source si se bazeaza pe API-urile planului de date Azure Digital Twins.

Pentru a utiliza SDK, includeti pachetul NuGet Azure.DigitalTwins.Core cu proiectul dvs. De asemenea, veti avea nevoie de cea mai recenta versiune a pachetului Azure.Identity . In Visual Studio, puteti adauga aceste pachete utilizand NuGet Package Manager (accesat prin Instrumente> NuGet Package Manager> Gestionati pachetele NuGet pentru solutie ). Alternativ, puteti utiliza instrumentul de linie de comanda .NET cu comenzile gasite in link-urile de pachete NuGet de mai jos pentru a le adauga la proiect:

• Azure.DigitalTwins.Core. Acesta este pachetul pentru SDK Azure Digital Twins pentru .NET.
• Azure.Identitate. Aceasta biblioteca ofera instrumente pentru a ajuta la autentificarea impotriva Azure.

Pentru o prezentare detaliata a utilizarii API-urilor in practica, consultati Tutorialul: Codificati o aplicatie client.

Exemple de utilizare .NET SDK

Iata cateva exemple de cod care ilustreaza utilizarea SDK-ului .NET.

Autentificati-va impotriva serviciului:

// Autentificati-va impotriva serviciului si creati un sir de clienti adtInstanceUrl = “https: // <your-Azure-Digital-Twins-instance-hostName>”; var credential = new DefaultAzureCredential (); Client DigitalTwinsClient = nou DigitalTwinsClient (nou Uri (adtInstanceUrl), acreditari);

Incarcati un model:

// „client” este o instanta a DigitalTwinsClient // Cititi fisierul model in sir (nu face parte din SDK) sir dtdl = new File.ReadAllText („MyModelFile.json”); asteapta client.CreateModelsAsync (nou [] {dtdl});

Listeaza modele:

// „client” este un obiect DigitalTwinsClient valid // Obtineti un singur model, metadate si date Raspuns <DigitalTwinsModelData> md1 = asteapta client.GetModelAsync (id); DigitalTwinsModelData model1 = md1.Value; // Obtineti o lista cu metadatele tuturor modelelor disponibile; tipariti-le numele de afisare si ID-urile AsyncPageable <DigitalTwinsModelData> md2 = client.GetModelsAsync (); await foreach (DigitalTwinsModelData md in md2) {Console.WriteLine ($ “Introduceti numele: {md.DisplayName}: {md.Id}”); } // Obtineti modele si metadate pentru un ID de model, inclusiv toate dependentele (modele de la care mosteneste, componente la care face referinta) AssyncPageable <DigitalTwinsModelData> md3 = client.GetModelsAsync (new GetModelsOptions {IncludeModelDefinition = true});

Creati gemeni:

sir twinId = “ID-ul meuTwin”; var initData = new BasicDigitalTwin {Id = twinId, Metadata = {ModelId = “dtmi: example: Room; 1”}, // Initializati proprietati Continut = {{“Temperatura”, 25.0}, {“Umiditate”, 50.0},} ,}; asteapta client.CreateOrReplaceDigitalTwinAsync <BasicDigitalTwin> (twinId, initData);

Interogati gemeni si parcurgeti rezultatele:

AsyncPageable <string> result = client.QueryAsync (“Select * From DigitalTwins”); incercati {await foreach (BasicDigitalTwin twin in result) {// Puteti include propria logica pentru a imprima rezultatul // Logica de mai jos tipareste ID-ul si continutul gemenei Console.WriteLine ($ “Twin ID: {twin.Id} \ nTwin date”); foreach (KeyValuePair <sir, obiect> kvp in twin.Contents) {Console.WriteLine ($ “{kvp.Key} {kvp.Value}”); }}} catch (RequestFailedException ex) {Console.WriteLine ($ “Error {ex.Status}, {ex.ErrorCode}, {ex.Message}”); arunca; }

Consultati Tutorialul: codificati o aplicatie client pentru o parcurgere a acestui exemplu de cod de aplicatie.

De asemenea, puteti gasi mostre suplimentare in repo GitHub pentru SDK-ul .NET (C #).

Ajutoare pentru serializare

Ajutoarele de serializare sunt functii de asistenta disponibile in SDK pentru crearea sau deserializarea rapida a datelor gemene pentru accesul la informatiile de baza. Deoarece metodele SDK de baza returneaza datele twin ca JSON in mod implicit, poate fi util sa utilizati aceste clase de ajutor pentru a descompune mai departe datele twin.

Clasele de ajutor disponibile sunt:

• BasicDigitalTwin: reprezinta in mod generic datele de baza ale unui geaman digital
• BasicDigitalTwinComponent: reprezinta in mod generic o componenta in proprietatile Continutului unui BasicDigitalTwin
• Relatie de baza: reprezinta in mod generic datele de baza ale unei relatii
• DigitalTwinsJsonPropertyName: Contine constantele de sir pentru a fi utilizate in serializarea si deserializarea JSON pentru tipurile twin personalizate digitale

Deserializati un geaman digital

Puteti oricand deserializa date gemene folosind biblioteca JSON la alegere, cum ar fi System.Text.Json sau Newtonsoft.Json. Pentru accesul de baza la un geaman, clasele de ajutor pot face acest lucru mai convenabil.

Clasa de asistenta BasicDigitalTwin va ofera, de asemenea, acces la proprietatile definite pe jumatate, printr-un dictionar <sir, obiect>. Pentru a enumera proprietatile gemenei, puteti utiliza:

Twin TwinDigitalTwin; Raspuns <BasicDigitalTwin> twinResponse = asteapta client.GetDigitalTwinAsync <BasicDigitalTwin> (twinId); twin = twinResponse.Value; Console.WriteLine ($ “ID model: {twin.Metadata.ModelId}”); foreach (string prop in twin.Contents.Keys) {if (twin.Contents.TryGetValue (prop, out object value)) Console.WriteLine ($ “Property ‘{prop}’: {value}”); }

Creati un geaman digital

Folosind clasa BasicDigitalTwin, puteti pregati date pentru crearea unei instante gemene:

sir twinId = “ID-ul meuTwin”; var initData = new BasicDigitalTwin {Id = twinId, Metadata = {ModelId = “dtmi: example: Room; 1”}, // Initializati proprietati Continut = {{“Temperatura”, 25.0}, {“Umiditate”, 50.0},} ,}; asteapta client.CreateOrReplaceDigitalTwinAsync <BasicDigitalTwin> (twinId, initData);

Codul de mai sus este echivalent cu urmatoarea varianta „manuala”:

// Definiti un tip de model personalizat pentru clasa twin care va fi creata CustomDigitalTwin {[JsonPropertyName (DigitalTwinsJsonPropertyNames.DigitalTwinId)] sir public Id {get; a stabilit; } [JsonPropertyName (DigitalTwinsJsonPropertyNames.DigitalTwinETag)] sir public ETag {get; a stabilit; } [JsonPropertyName (DigitalTwinsJsonPropertyNames.DigitalTwinMetadata)] public MyCustomDigitalTwinMetadata Metadate {get; a stabilit; } = new MyCustomDigitalTwinMetadata (); [JsonPropertyName (“temperature”)] public double Temperature {get; a stabilit; } [JsonPropertyName (“umiditate”)] public double Umiditate {get; a stabilit; }} clasa MyCustomDigitalTwinMetadata {[JsonPropertyName (DigitalTwinsJsonPropertyNames.MetadataModel)] sir public ModelId {get; a stabilit; } [JsonPropertyName (“temperature”)] public DigitalTwinPropertyMetadata Temperature {get; a stabilit; } [JsonPropertyName (“umiditate”)] public DigitalTwinPropertyMetadata Umiditate {get; a stabilit; }} // Initializati proprietatile duble var myTwin = new MyCustomDigitalTwin {Metadate = {ModelId = “dtmi: example: Room; 1”}, Temperatura = 25,0, Umiditate = 50,0,}; // Creati raspunsul twin <BasicDigitalTwin> raspuns = asteapta clientul.CreateOrReplaceDigitalTwinAsync (twinId, myTwin); Console.WriteLine ($ “Temperatura actualizata ultima data la {response.Value.Metadata.Temperature.LastUpdatedOn}”) CreateOrReplaceDigitalTwinAsync (twinId, myTwin); Console.WriteLine ($ “Temperatura actualizata ultima data la {response.Value.Metadata.Temperature.LastUpdatedOn}”) CreateOrReplaceDigitalTwinAsync (twinId, myTwin); Console.WriteLine ($ “Temperatura actualizata ultima data la {response.Value.Metadata.Temperature.LastUpdatedOn}”)

Deserializati o relatie

Puteti deserializa oricand datele relatiei la un tip la alegere. Pentru accesul de baza la o relatie, utilizati tipul BasicRelationship.

AsyncPageable <BasicRelationship> rels = client.GetRelationshipsAsync <BasicRelationship> (dtId);

Clasa de ajutor BasicRelationship va ofera, de asemenea, acces la proprietatile definite in relatie, printr-un IDictionary <sir, obiect>. Pentru a lista proprietatile, puteti utiliza:

var res = await client.GetRelationshipAsync <BasicRelationship> (twinId, relId); Console.WriteLine ($ “Nume relatie: {rel.Name}”); foreach (string prop in rel.Contents.Keys) {if (twin.Contents.TryGetValue (prop, out object value)) {Console.WriteLine ($ “Property ‘{prop}’: {value}”); }}

Creati o relatie

Folosind clasa BasicRelationship, puteti pregati, de asemenea, date pentru crearea de relatii pe o instanta dubla:

var rel = new BasicRelationship {TargetId = “myTargetTwin”, Name = “contine”, // o relatie cu acest nume trebuie definita in model // Initializati proprietatile Proprietati = {{“active”, adevarat},},}; asteapta client.CreateOrReplaceRelationshipAsync (“mySourceTwin”, “rel001”, rel);

Creati un patch pentru actualizarea twin

Actualizarea apelurilor pentru gemeni si relatii utilizeaza structura JSON Patch. Pentru a crea liste de operatiuni JSON Patch, puteti utiliza JsonPatchDocument asa cum se arata mai jos.

var updateTwinData = new JsonPatchDocument (); updateTwinData.AppendAdd (“/ Temperatura”, 25.0); updateTwinData.AppendAdd (“/ myComponent / Property”, “Hello”); // Anulati o proprietate updateTwinData.AppendRemove (“/ Umiditate”); asteapta client.UpdateDigitalTwinAsync (“myTwin”, updateTwinData);

Note generale privind utilizarea API-ului / SDK-ului

Urmatoarea lista ofera detalii suplimentare si indrumari generale pentru utilizarea API-urilor si SDK-urilor.

• Puteti utiliza un instrument de testare REST HTTP, cum ar fi Postman, pentru a efectua apeluri directe catre API-urile Azure Digital Twins. Pentru mai multe informatii despre acest proces, consultati Proceduri: faceti cereri cu Postman.
• Pentru a utiliza SDK-ul, instantiati clasa DigitalTwinsClient. Constructorul necesita acreditari care pot fi obtinute cu o varietate de metode de autentificare in pachetul Azure.Identity. Pentru mai multe informatii despre Azure.Identity, consultati documentatia spatiului sau de nume.
• Puteti gasi InteractiveBrowserCredential util in timp ce incepeti, dar exista mai multe alte optiuni, inclusiv acreditari pentru identitatea gestionata, pe care probabil le veti utiliza pentru a autentifica functiile Azure configurate cu MSI impotriva Azure Digital Twins. Pentru mai multe informatii despre InteractiveBrowserCredential, consultati documentatia clasei sale.
• Cererile catre API-urile Azure Digital Twins necesita un utilizator sau un director de serviciu care face parte din acelasi chirias Azure Active Directory (Azure AD) in care se afla instanta Azure Digital Twins. Pentru a preveni scanarea rau intentionata a punctelor finale Azure Digital Twins, solicitarilor cu jetoane de acces din afara chiriasului de origine li se va returna un mesaj de eroare „Subdomeniu 404 nu a fost gasit”. Aceasta eroare va fi returnata chiar daca utilizatorul sau directorul de serviciu a primit un rol de proprietar de date Azure Digital Twins sau Azure Digital Twins Data Reader prin colaborarea Azure AD B2B. Pentru informatii despre cum sa obtineti accesul catre mai multi chiriasi, consultati Proceduri: Scrieti codul de autentificare a aplicatiei.
• Toate apelurile API de serviciu sunt expuse ca functii membre pe clasa DigitalTwinsClient.
• Toate functiile de serviciu exista in versiuni sincrone si asincrone.
• Toate functiile de serviciu fac exceptie pentru orice stare de returnare de 400 sau mai mare. Asigurati-va ca incadrati apelurile intr-o sectiune de incercare si cautati cel putin RequestFailedExceptions. Pentru mai multe informatii despre acest tip de exceptie, consultati documentatia de referinta.
• Majoritatea metodelor de serviciu returneaza Raspuns <T> sau (Sarcina <Raspuns <T>> pentru apelurile asincrone), unde T este clasa obiectului de retur pentru apelul de serviciu. Clasa Response incapsuleaza returnarea serviciului si prezinta valorile returnate in campul Value.
• Metodele de service cu rezultate paginate returneaza Pageable <T> sau AsyncPageable <T> ca rezultate. Pentru mai multe informatii despre clasa Pageable <T>, consultati documentatia de referinta; pentru mai multe despre AsyncPageable <T>, consultati documentatia de referinta.
• Puteti itera rezultatele paginate utilizand o bucla await foreach. Pentru mai multe informatii despre acest proces, consultati documentatia relevanta.
• SDK-ul de baza este Azure.Core. Consultati documentatia Azure namespace pentru referinta cu privire la infrastructura si tipurile SDK.

Metodele de service returneaza obiecte puternic tastate ori de cate ori este posibil. Cu toate acestea, deoarece Azure Digital Twins se bazeaza pe modele personalizate configurate de utilizator in timpul rularii (prin modele DTDL incarcate in serviciu), multe API-uri de serviciu iau si returneaza date gemene in format JSON.

Monitorizati valorile API

Valorile API, cum ar fi cererile, latenta si rata de esec, pot fi vizualizate in portalul Azure.

Din pagina de pornire a portalului, cautati instanta dvs. Azure Digital Twins pentru a extrage detaliile sale. Selectati optiunea Metrics din meniul instantei Azure Digital Twins pentru a afisa pagina Metrics .

De aici, puteti vizualiza valorile pentru instanta dvs. si puteti crea vizualizari personalizate.

Pasii urmatori

Vedeti cum sa efectuati cereri directe catre API-uri folosind Postman:

• Instructiuni: faceti solicitari cu Postman

Sau, practicati utilizarea SDK-ului .NET prin crearea unei aplicatii client cu acest tutorial:

• Tutorial: codificati o aplicatie client