Documentazione di riferimento Swagger per Azure Digital Twins

Importante

È stata rilasciata una nuova versione del servizio Gemelli digitali di Azure. Alla luce delle funzionalità espanse del nuovo servizio, il servizio Gemelli digitali di Azure originale (descritto in questo set di documentazione) è stato ritirato.

Per visualizzare la documentazione del nuovo servizio, visita la documentazione attiva di Azure Digital Twins.

Ogni istanza provisionata di Gemelli digitali di Azure include la propria documentazione di riferimento Swagger generata automaticamente.

Swaggero OpenAPI, unisce informazioni API complesse in una risorsa di riferimento interattiva e indipendente dal linguaggio. Swagger fornisce materiale di riferimento critico sui payload JSON, i metodi HTTP e gli endpoint specifici da usare per eseguire operazioni su un'API.

Riepilogo di Swagger

Swagger fornisce un riepilogo interattivo dell'API, il quale include:

• Informazioni sull'API e sul modello a oggetti.
• Endpoint dell'API REST che specificano i payload di richiesta necessari, le intestazioni, i parametri, i percorsi di contesto e i metodi HTTP.
• Test delle funzionalità dell'API.
• Informazioni di risposta di esempio usate per convalidare e confermare le risposte HTTP.
• Informazioni sul codice di errore.

Swagger è uno strumento pratico per facilitare lo sviluppo e i test delle chiamate effettuate alle API di gestione di Gemelli digitali di Azure.

Suggerimento

Viene fornita un'anteprima sneak di Swagger per illustrare il set di funzionalità api. È ospitato in docs.westcentralus.azuresmartspaces.net/management/swagger.

È possibile accedere alla propria documentazione Swagger dell'API di gestione generata all'indirizzo:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Nome	Sostituire con
NOME_DELLA_TUA_ISTANZA	Nome della tua istanza di Azure Digital Twins
LA_TUA_POSIZIONE	Area del server in cui è ospitata l'istanza

Materiale di consultazione

Il materiale di riferimento Swagger generato automaticamente fornisce una rapida panoramica di concetti importanti, endpoint API di gestione disponibili e una descrizione di ogni modello a oggetti per facilitare lo sviluppo e il test.

Un riepilogo conciso descrive l'API.

Sono elencati anche i modelli a oggetti dell'API di gestione.

È possibile selezionare ogni modello a oggetti elencato per un riepilogo più dettagliato degli attributi chiave.

I modelli oggetto Swagger generati sono comodi per leggere tutti gli oggetti e le API disponibili dei Gemelli digitali di Azure . Gli sviluppatori possono usare questa risorsa quando creano soluzioni in Gemelli digitali di Azure.

Riepilogo endpoint

Swagger offre anche una panoramica completa di tutti gli endpoint che compongono le API di gestione.

Ogni endpoint elencato include anche le informazioni di richiesta necessarie, ad esempio:

• Parametri obbligatori.
• Tipi di dati dei parametri obbligatori.
• Metodo HTTP per accedere alla risorsa.

Selezionare ogni risorsa per visualizzare il contenuto aggiuntivo per ottenere una panoramica più dettagliata.

Usare Swagger per testare gli endpoint

Una delle potenti funzionalità offerte da Swagger è la possibilità di testare un endpoint API direttamente tramite l'interfaccia utente della documentazione.

Dopo aver selezionato un endpoint specifico, verrà visualizzato il pulsante Prova.

Espandere tale sezione per visualizzare i campi di input per ogni parametro obbligatorio e facoltativo. Immettere i valori corretti e selezionare Esegui.

Dopo aver eseguito il test, è possibile convalidare i dati di risposta.

Dati di risposta di Swagger

Ogni endpoint elencato include anche i dati del corpo della risposta per convalidare lo sviluppo e i test. Questi esempi includono i codici di stato e JSON per le richieste HTTP riuscite.

Gli esempi includono anche codici di errore che consentono di eseguire il debug o migliorare i test non superati.

Autorizzazione di Swagger OAuth 2.0

Nota

• L'entità utente che ha creato la risorsa di Azure Digital Twins avrà un'assegnazione di ruolo Amministratore dello spazio e sarà in grado di creare assegnazioni di ruolo aggiuntive per altri utenti. Questi utenti e i relativi ruoli possono essere autorizzati a chiamare le API.

1. Seguire la procedura descritta in Avvio rapido per creare e configurare un'applicazione Azure Active Directory. In alternativa, è possibile riutilizzare una registrazione dell'app esistente.

2. Aggiungere il seguente URI di reindirizzamento alla registrazione dell'app di Azure Active Directory:

   

   https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
   

   Nome	Sostituire con	Esempio
   YOUR_SWAGGER_URL	L'URL della documentazione dell'API REST di gestione si trova nel portale	https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

3. Selezionare la casella di controllo concessione implicita>token di accesso per consentire l'uso del flusso di concessione implicita di OAuth 2.0. Selezionare Configura, quindi Salva.

4. Copiare l'ID client dell'app Azure Active Directory.

Dopo aver completato la registrazione di Azure Active Directory:

1. Seleziona il pulsante Autorizza nella pagina Swagger.

   

2. Incollare l'ID applicazione nel campo client_id.

   

3. Si verrà quindi reindirizzati alla seguente finestra di successo.

   modal di reindirizzamento Swagger

Per altre informazioni sui test interattivi delle richieste protette da OAuth 2.0, vedere la documentazione ufficiale .

Passaggi successivi

• Per altre informazioni sui modelli a oggetti di Gemelli digitali di Azure e sul grafico di intelligenza spaziale, vedere Informazioni sui modelli a oggetti di Gemelli digitali di Azure.

• Per informazioni su come eseguire l'autenticazione con l'API di gestione, leggere Eseguire l'autenticazione con le API.