Documentazione di riferimento di Swagger per Gemelli digitali di Azure
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 per il nuovo servizio, visitare la documentazione attiva di Gemelli digitali di Azure.
Ogni istanza di Gemelli digitali di Azure di cui è stato effettuato il provisioning include la propria documentazione di riferimento Swagger generata automaticamente.
Swagger (o OpenAPI) raccoglie complesse informazioni sulle API in una risorsa di riferimento interattiva e indipendente dal linguaggio. Swagger fornisce materiale di riferimento di importanza critica 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, che include:
- Informazioni sull'API e sul modello a oggetti.
- Endpoint API REST che specificano i payload delle richieste, le intestazioni, i parametri, i percorsi di contesto e i metodi HTTP necessari.
- Test delle funzionalità dell'API.
- Informazioni sulla risposta di esempio per la convalida e la conferma delle risposte HTTP.
- Informazioni sui codici di errore.
Swagger è un pratico strumento per semplificare lo sviluppo e i test delle chiamate effettuate all'API Gestione per Gemelli digitali di Azure.
Suggerimento
Viene fornita un'anteprima di prova di Swagger per mostrare il set di funzionalità delle API. L'anteprima è ospitata in docs.westcentralus.azuresmartspaces.net/management/swagger.
È possibile accedere alla propria documentazione di Swagger generata automaticamente dell'API di gestione all'indirizzo:
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| NOME | Sostituire con |
|---|---|
| NOME_ISTANZA_UTENTE | Nome dell'istanza di Gemelli digitali di Azure |
| POSIZIONE_UTENTE | Area del server in cui è ospitata l'istanza |
Materiale di riferimento
Il materiale di riferimento di Swagger generato automaticamente offre una rapida panoramica di concetti importanti, endpoint disponibili dell'API Gestione e una descrizione di ogni modello a oggetti per facilitare sviluppo e test.
Un breve riepilogo descrive l'API.
Sono elencati anche i modelli a oggetti dell'API Gestione.
È possibile selezionare ogni modello a oggetti elencato per visualizzare un riepilogo più dettagliato degli attributi principali.
I modelli a oggetti Swagger generati sono utili per leggere tutti gli oggetti gemelli digitali di Azure disponibili e le API. Gli sviluppatori possono usare questa risorsa quando compilano soluzioni in Gemelli digitali di Azure.
Riepilogo degli endpoint
Swagger fornisce anche una panoramica completa di tutti gli endpoint che compongono l'API Gestione.
Ogni endpoint elencato include anche le informazioni obbligatorie sulla richiesta, tra cui:
- I parametri obbligatori.
- I tipi di dati dei parametri obbligatori.
- Metodo HTTP per l'accesso alla risorsa.
Selezionare ogni risorsa per visualizzare il contenuto aggiuntivo per ottenere una panoramica più dettagliata.
Usare Swagger per testare gli endpoint
Una delle funzionalità più potenti offerte da Swagger è la possibilità di testare un endpoint API direttamente dall'interfaccia utente della documentazione.
Dopo aver selezionato un endpoint specifico, verrà visualizzato il pulsante Prova .
Espandere la sezione per visualizzare i campi di input per ogni parametro obbligatorio e facoltativo. Immettere i valori corretti, quindi selezionare Esegui.
Dopo l'esecuzione del test, è possibile convalidare i dati della risposta.
Dati della 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 i codici di errore per facilitare il debug o migliorare i test non superati.
Autorizzazione OAuth 2.0 di Swagger
Nota
- L'entità utente che ha creato la risorsa gemelli digitali di Azure avrà un'assegnazione di ruolo Amministratore spazio e sarà in grado di creare assegnazioni di ruolo aggiuntive per altri utenti. Tali utenti e i relativi ruoli possono essere autorizzati a chiamare le API.
Seguire la procedura descritta nella guida introduttiva per creare e configurare un'applicazione Azure Active Directory. In alternativa, è possibile riutilizzare una registrazione dell'app esistente.
Aggiungere l'URI di reindirizzamento seguente alla registrazione dell'app Azure Active Directory:
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-htmlNOME Sostituire con Esempio YOUR_SWAGGER_URL URL della documentazione dell'API REST di gestione trovato nel portale https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerSelezionare la casella di controlloToken di accesso di concessione implicitaper consentire l'uso del flusso di concessione > implicito OAuth 2.0. Selezionare Configura, quindi Salva.
Copiare l'ID client dell'app Azure Active Directory.
Dopo aver completato la registrazione di Azure Active Directory:
Selezionare il pulsante Autorizza nella pagina swagger.
Incollare l'ID applicazione nel campo client_id .
Verrà quindi reindirizzato al modale di successo seguente.
Per altre informazioni sulle richieste di test interattive protette da OAuth 2.0, leggere la documentazione ufficiale.
Passaggi successivi
Per altre informazioni sui modelli a oggetti e il grafico di intelligence spaziale di Gemelli digitali di Azure, vedere Informazioni sui modelli a oggetti di Gemelli digitali di Azure.
Per informazioni su come eseguire l'autenticazione con l'API di gestione, vedere Eseguire l'autenticazione con le API.