API e SDK di Gemelli digitali di Azure
Questo articolo offre una panoramica delle API di Gemelli digitali di Azure disponibili e i metodi per interagire con essi. È possibile usare le API REST direttamente con i Swaggers associati (tramite uno strumento come Postman) o tramite un SDK.
Gemelli digitali di Azure è dotato di API del piano di controllo, API del piano dati e SDK per la gestione dell'istanza e dei relativi elementi.
- Le API del piano di controllo sono API di Azure Resource Manager (ARM) e coprono le operazioni di gestione delle risorse come la creazione e l'eliminazione dell'istanza.
- Le API del piano dati sono API di Gemelli digitali di Azure e vengono usate per operazioni di gestione dei dati come la gestione di modelli, gemelli e il grafico.
- Gli SDK sfruttano le API esistenti per semplificare lo sviluppo di applicazioni personalizzate che usano Gemelli digitali di Azure.
API del piano di controllo
Le API del piano di controllo sono API ARM usate per gestire l'istanza di Gemelli digitali di Azure nel suo complesso, in modo da coprire operazioni come la creazione o l'eliminazione dell'intera istanza. Queste API verranno usate anche per creare ed eliminare endpoint.
Per chiamare direttamente le API, fare riferimento alla cartella Swagger più recente nel repository Swagger del piano di controllo. Questa cartella include anche una cartella di esempi che mostrano l'utilizzo.
Ecco gli SDK attualmente disponibili per le API del piano di controllo di Gemelli digitali di Azure.
È anche possibile esercitare le API del piano di controllo interagendo con Gemelli digitali di Azure tramite l'interfaccia della riga di comando e l'portale di Azure.
API del piano dati
Le API del piano dati sono le API di Gemelli digitali di Azure usate per gestire gli elementi all'interno dell'istanza di Gemelli digitali di Azure. Includono operazioni come la creazione di route, il caricamento di modelli, la creazione di relazioni e la gestione dei gemelli e possono essere suddivise in modo ampio nelle categorie seguenti:
DigitalTwinModels- La categoria DigitalTwinModels contiene API per gestire i modelli in un'istanza di Gemelli digitali di Azure. Le attività di gestione includono caricamento, convalida, recupero ed eliminazione di modelli creati in DTDL.DigitalTwins- La categoria DigitalTwins contiene le API che consentono agli sviluppatori di creare, modificare ed eliminare gemelli digitali e le relative relazioni in un'istanza di Gemelli digitali di Azure.Query- La categoria Query consente agli sviluppatori di trovare set di gemelli digitali nel grafico dei gemelli tra le relazioni.Event Routes- La categoria Route di eventi contiene API per instradare i dati, attraverso il sistema e verso i servizi downstream.Import Jobs- L'API Importa processi consente di gestire un'azione asincrona a esecuzione prolungata per importare modelli, gemelli e relazioni in blocco.Delete Jobs- L'API Elimina processi consente di gestire un'azione asincrona a esecuzione prolungata per eliminare tutti i modelli, i gemelli e le relazioni in un'istanza di .
Per chiamare direttamente le API, fare riferimento alla cartella Swagger più recente nel repository Swagger del piano dati. Questa cartella include anche una cartella di esempi che mostrano l'utilizzo. È anche possibile visualizzare la documentazione di riferimento dell'API del piano dati.
Ecco gli SDK attualmente disponibili per le API del piano dati di Gemelli digitali di Azure.
È anche possibile eseguire l'esercizio delle API del piano dati interagendo con Gemelli digitali di Azure tramite l'interfaccia della riga di comando.
Note sull'utilizzo e sull'autenticazione
Questa sezione contiene informazioni più dettagliate sull'uso delle API e degli SDK.
Note API
Ecco alcune informazioni generali per chiamare direttamente le API di Gemelli digitali di Azure.
- È possibile usare uno strumento di test REST HTTP come Postman per effettuare chiamate dirette alle API di Gemelli digitali di Azure. Per altre informazioni su questo processo, vedere Chiamare le API di Gemelli digitali di Azure con Postman.
- Gemelli digitali di Azure attualmente non supporta la condivisione di risorse tra le origini (CORS). Per altre informazioni sulle strategie di impatto e risoluzione, vedere Condivisione di risorse tra le origini (CORS) per Gemelli digitali di Azure.
Ecco altre informazioni sull'autenticazione per le richieste API.
- Un modo per generare un token di connessione per le richieste api di Gemelli digitali di Azure consiste nel comando az account get-access-token dell'interfaccia della riga di comando. Per istruzioni dettagliate, vedere Ottenere il token di connessione.
- Le richieste alle API di Gemelli digitali di Azure richiedono un utente o un'entità servizio che fa parte dello stesso tenant di Microsoft Entra ID in cui è presente l'istanza di Gemelli digitali di Azure. Per impedire l'analisi dannosa degli endpoint di Gemelli digitali di Azure, le richieste con token di accesso dall'esterno del tenant di origine verranno restituiti un messaggio di errore "404 Sub-Domain not found". Questo errore verrà restituito anche se all'utente o all'entità servizio è stato assegnato un ruolo di proprietario dei dati di Gemelli digitali di Azure o lettore dati di Gemelli digitali di Azure tramite Microsoft Entra B2B Collaboration. Per informazioni su come ottenere l'accesso tra più tenant, vedere Scrivere codice di autenticazione dell'app.
Note dell'SDK
L'SDK sottostante per Gemelli digitali di Azure è Azure.Core. Per informazioni di riferimento sull'infrastruttura e sui tipi dell'SDK, vedere la documentazione dello spazio dei nomi di Azure.
Ecco altre informazioni sull'autenticazione con gli SDK.
- Iniziare creando un'istanza della
DigitalTwinsClientclasse . Il costruttore richiede credenziali che possono essere ottenute con diversi tipi di metodi di autenticazione nelAzure.Identitypacchetto. Per altre informazioni suAzure.Identity, vedere la relativa documentazione sullo spazio dei nomi. - Può risultare utile durante l'introduzione
InteractiveBrowserCredential, ma sono disponibili diverse altre opzioni, tra cui le credenziali per l'identità gestita, che probabilmente si userà per autenticare le funzioni di Azure configurate con l'identità del servizio gestito in Gemelli digitali di Azure. Per altre informazioni suInteractiveBrowserCredential, vedere la relativa documentazione della classe.
Ecco altre informazioni sulle funzioni e i dati restituiti.
- Tutte le chiamate API del servizio vengono esposte come funzioni membro nella
DigitalTwinsClientclasse . - Tutte le funzioni del servizio esistono nelle versioni sincrone e asincrone.
- Tutte le funzioni del servizio generano un'eccezione per qualsiasi stato restituito di 400 o superiore. Assicurarsi di eseguire il wrapping delle chiamate in una
trysezione e di intercettare almenoRequestFailedExceptions. Per altre informazioni su questo tipo di eccezione, vedere la relativa documentazione di riferimento. - La maggior parte dei metodi del servizio restituisce
Response<T>o (Task<Response<T>>per le chiamate asincrone), doveTè la classe dell'oggetto restituito per la chiamata al servizio. La classe Response incapsula la restituzione del servizio e presenta i valori restituiti nel relativoValuecampo. - I metodi di servizio con risultati di paging restituiscono
Pageable<T>oAsyncPageable<T>come risultati. Per altre informazioni sulla classe, vedere laPageable<T>relativa documentazione di riferimento. Per altre informazioni suAsyncPageable<T>, vedere la relativa documentazione di riferimento. - È possibile scorrere i risultati di paging usando un
await foreachciclo. Per altre informazioni su questo processo, vedere Iterating with Async Enumerables in C# 8 (Iterating with Async Enumerables in C# 8). - I metodi di servizio restituiscono oggetti fortemente tipizzati laddove possibile. Tuttavia, poiché Gemelli digitali di Azure si basa su modelli configurati dall'utente in fase di esecuzione (tramite modelli DTDL caricati nel servizio), molte API del servizio accettano e restituiscono dati gemelli in formato JSON.
Helper di serializzazione in .NET (C#) SDK
Gli helper di serializzazione sono funzioni helper disponibili in .NET (C#) SDK per creare o deserializzare rapidamente i dati dei gemelli per l'accesso alle informazioni di base. Poiché i metodi dell'SDK di base restituiscono dati gemelli come JSON per impostazione predefinita, può essere utile usare queste classi helper per suddividere ulteriormente i dati del gemello.
Le classi helper disponibili sono:
BasicDigitalTwin: rappresenta in modo generico i dati principali di un gemello digitaleBasicDigitalTwinComponent: rappresenta in modo generico un componente nelleContentsproprietà di un oggettoBasicDigitalTwinBasicRelationship: rappresenta in modo generico i dati principali di una relazioneDigitalTwinsJsonPropertyName: contiene le costanti stringa da usare nella serializzazione JSON e nella deserializzazione per i tipi di gemelli digitali personalizzati
Importazione bulk con l'API Importa processi
L'API Processi di importazione è un'API del piano dati che consente di importare un set di modelli, gemelli e/o relazioni in una singola chiamata API. Le operazioni dell'API Dei processi di importazione sono incluse anche con i comandi dell'interfaccia della riga di comando e gli SDK del piano dati. L'uso dell'API Import Jobs richiede l'uso di Archiviazione BLOB di Azure.
Verificare le autorizzazioni
Per usare l'API Importa processi, è necessario abilitare le impostazioni di autorizzazione descritte in questa sezione.
Prima di tutto, è necessaria un'identità gestita assegnata dal sistema per l'istanza di Gemelli digitali di Azure. Per istruzioni su come configurare un'identità gestita dal sistema per l'istanza, vedere Abilitare/disabilitare l'identità gestita per l'istanza.
È necessario disporre delle autorizzazioni di scrittura nell'istanza di Gemelli digitali di Azure per le categorie di azioni di dati seguenti:
Microsoft.DigitalTwins/jobs/*- Tutti gli elementi del grafo che si desidera includere nella chiamata Processi. Ciò può includere
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*e/oMicrosoft.DigitalTwins/digitaltwins/relationships/*.
Il ruolo predefinito che fornisce tutte queste autorizzazioni è proprietario dei dati di Gemelli digitali di Azure. È anche possibile usare un ruolo personalizzato per concedere l'accesso granulare solo ai tipi di dati necessari. Per altre informazioni sui ruoli in Gemelli digitali di Azure, vedere Security for Azure Digital Twins solutions (Sicurezza per soluzioni di Gemelli digitali di Azure).
Nota
Se si tenta di eseguire una chiamata all'API Import Jobs e si mancano le autorizzazioni di scrittura per uno dei tipi di elemento del grafo che si sta tentando di importare, il processo ignorerà tale tipo e importerà gli altri. Ad esempio, se si ha accesso in scrittura a modelli e gemelli, ma non alle relazioni, un tentativo di importazione bulk di tutti e tre i tipi di elemento avrà esito positivo solo nell'importazione dei modelli e dei gemelli. Lo stato del processo rifletterà un errore e il messaggio indicherà quali autorizzazioni mancano.
Sarà anche necessario concedere le autorizzazioni di controllo degli accessi in base al ruolo seguenti all'identità gestita assegnata dal sistema dell'istanza di Gemelli digitali di Azure in modo che possa accedere ai file di input e output nel contenitore Archiviazione BLOB di Azure:
- Archiviazione lettore di dati BLOB per il contenitore BLOB di input Archiviazione di Azure
- Archiviazione Collaboratore ai dati BLOB per il contenitore BLOB di output Archiviazione di Azure
Infine, generare un token di connessione che può essere usato nelle richieste all'API Processi. Per istruzioni, vedere Ottenere il token di connessione.
Formattare i dati
L'API accetta l'input delle informazioni sul grafo da un file NDJSON , che deve essere caricato in un contenitore di archiviazione BLOB di Azure. Il file inizia con una Header sezione, seguita dalle sezioni Modelsfacoltative , Twinse Relationships. Non è necessario includere tutti e tre i tipi di dati del grafo nel file, ma tutte le sezioni presenti devono seguire tale ordine. I gemelli e le relazioni create con questa API possono includere facoltativamente l'inizializzazione delle relative proprietà.
Ecco un file di dati di input di esempio per l'API di importazione:
{"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}
Suggerimento
Per un progetto di esempio che converte modelli, gemelli e relazioni in NDJSON supportato dall'API di importazione, vedere Importazione bulk di Gemelli digitali di Azure NDJSON Generator. Il progetto di esempio viene scritto per .NET e può essere scaricato o adattato per facilitare la creazione di file di importazione personalizzati.
Dopo aver creato il file, caricarlo in un BLOB in blocchi in Archiviazione BLOB di Azure usando il metodo di caricamento preferito (alcune opzioni sono il comando AzCopy, l'interfaccia della riga di comando di Azure o il portale di Azure). Si userà l'URL di archiviazione BLOB del file NDJSON nel corpo della chiamata ALL'API Import Jobs.
Eseguire il processo di importazione
È ora possibile procedere con la chiamata all'API Importa processi. Per istruzioni dettagliate sull'importazione di un grafico completo in una chiamata API, vedere Caricare modelli, gemelli e relazioni in blocco con l'API Importa processi. È anche possibile usare l'API Importa processi per importare ogni tipo di risorsa in modo indipendente. Per altre informazioni sull'uso dell'API Importa processi con singoli tipi di risorse, vedere Importare istruzioni api processi per modelli, gemelli e relazioni.
Nel corpo della chiamata API si fornirà l'URL di archiviazione BLOB del file di input NDJSON. Si fornirà anche un nuovo URL di archiviazione BLOB per indicare dove archiviare il log di output dopo che il servizio lo crea.
Importante
Assicurarsi che l'identità gestita assegnata dal sistema dell'istanza di Gemelli digitali di Azure disponga delle autorizzazioni di controllo degli accessi in base al ruolo del BLOB di archiviazione descritte nella sezione Controllare le autorizzazioni.
Durante l'esecuzione del processo di importazione, un log di output strutturato viene generato dal servizio e archiviato come nuovo BLOB di accodamento nel contenitore BLOB, nel percorso URL specificato per il BLOB di output nella richiesta. Di seguito è riportato un log di output di esempio per un processo di importazione di modelli, gemelli e relazioni riuscite:
{"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"}}
Al termine del processo, è possibile visualizzare il numero totale di entità inserite usando la metrica BulkOperationEntityCount.
È anche possibile annullare un processo di importazione in esecuzione con l'operazione Annulla dall'API Importa processi. Dopo che il processo è stato annullato e non è più in esecuzione, è possibile eliminarlo.
Limiti e considerazioni
Tenere presenti le considerazioni seguenti durante l'uso dell'API Importa processi:
- I processi di importazione non sono operazioni atomiche. Non esiste alcun rollback in caso di errore, completamento parziale del processo o utilizzo dell'operazione Annulla.
- In un'istanza di Gemelli digitali di Azure è supportato un solo processo in blocco alla volta. È possibile visualizzare queste informazioni e altri limiti numerici delle API processi nei limiti di Gemelli digitali di Azure.
Eliminazione bulk con l'API Elimina processi
L'API Elimina processi è un'API del piano dati che consente di eliminare tutti i modelli, i gemelli e le relazioni in un'istanza con una singola chiamata API. Le operazioni dell'API Elimina processi sono disponibili anche come comandi dell'interfaccia della riga di comando. Visitare la documentazione dell'API per visualizzare i dettagli della richiesta per la creazione di un processo di eliminazione e verificarne lo stato.
Per assicurarsi che tutti gli elementi vengano eliminati, seguire queste indicazioni durante l'uso dell'API Elimina processi:
- Per istruzioni su come generare un token di connessione per autenticare le richieste API, vedere Ottenere il token di connessione.
- Se di recente è stato importato un numero elevato di entità nel grafico, attendere qualche tempo e verificare che tutti gli elementi siano sincronizzati nel grafico prima di iniziare il processo di eliminazione.
- Arrestare tutte le operazioni sull'istanza, in particolare le operazioni di caricamento, fino al completamento del processo di eliminazione.
A seconda delle dimensioni del grafico da eliminare, un processo di eliminazione può richiedere da qualche minuto a più ore.
Il periodo di timeout predefinito per un processo di eliminazione è di 12 ore, che può essere modificato in qualsiasi valore compreso tra 15 minuti e 24 ore usando un parametro di query nell'API. Questo è il tempo di esecuzione del processo di eliminazione prima del timeout, a questo punto il servizio tenterà di arrestare il processo se non è ancora stato completato.
Limiti e altre considerazioni
Tenere presenti le considerazioni seguenti durante l'uso dell'API Elimina processi:
- I processi di eliminazione non sono operazioni atomiche. Non è presente alcun rollback in caso di errore, completamento parziale del processo o timeout del processo.
- In un'istanza di Gemelli digitali di Azure è supportato un solo processo in blocco alla volta. È possibile visualizzare queste informazioni e altri limiti numerici delle API processi nei limiti di Gemelli digitali di Azure.
Monitorare le metriche dell'API
Le metriche api, ad esempio le richieste, la latenza e la frequenza degli errori, possono essere visualizzate nella portale di Azure.
Per informazioni sulla visualizzazione e la gestione delle metriche di Gemelli digitali di Azure, vedere Monitorare l'istanza. Per un elenco completo delle metriche dell'API disponibili per Gemelli digitali di Azure, vedere Metriche delle richieste dell'API di Gemelli digitali di Azure.
Passaggi successivi
Vedere come effettuare richieste dirette alle API di Gemelli digitali di Azure usando Postman:
In alternativa, provare a usare .NET SDK creando un'app client con questa esercitazione: