Introduzione
La RealityConnect API è l’unica superficie pubblica che consente ai sistemi esterni di interagire con l’ecosistema Prevu3D. Usala per leggere e scrivere contenuti in RealityPlatform, gestire i workspace RealityTwin, gestire la tua organizzazione, caricare file e dataset e molto altro.
Come è organizzata l’API
Sezione intitolata “Come è organizzata l’API”Vale la pena conoscere alcune scelte di progettazione prima di iniziare a sviluppare:
- URL di base regionali. L’API funziona in più regioni (US East, EU Central, Asia North, Canada Central). La tua organizzazione è provisionata esattamente in una di esse. Recupera sempre il tuo URL di base dall’endpoint di discovery invece di codificarlo staticamente. La guida Per iniziare mostra come fare.
- Tutto è nell’ambito della tua organizzazione. Un token vede solo i nodi a cui l’utente di servizio ha ottenuto l’accesso. Le chiamate tra organizzazioni non sono possibili.
- Le risorse vivono in una gerarchia di contenuti. La maggior parte delle operazioni ha come target un nodo identificato da UUID. I nodi formano un albero (organizzazione → divisione → sito → cartella → asset) che puoi navigare con l’endpoint
/nodes/{id}/browse. - Controllo degli accessi a tre livelli. Scope OAuth, accesso ai contenuti e ruoli per nodo devono tutti superare la verifica affinché una richiesta abbia successo. Consulta il Modello di sicurezza per sapere come configurare ciascuno di essi.
- JSON su HTTPS. Ogni endpoint accetta e restituisce JSON, usa l’autenticazione con bearer-token e segue i codici di stato HTTP standard.
Autenticazione OAuth
Sezione intitolata “Autenticazione OAuth”L’autenticazione dell’API si basa sul protocollo OAuth2. Flussi supportati:
| Flusso OAuth | Descrizione | Esempi di casi d’uso |
|---|---|---|
| Client Credentials | Accesso server-to-server senza un utente che ha effettuato l’accesso. Crea un utente di servizio nella tua organizzazione; ne configuri i permessi separatamente. | Script, automazione, integrazioni di backend, test dell’API |
| Native app | Un utente accede tramite il browser e acconsente agli scope. Usa Authorization Code + Native Application con PKCE e un redirect http://localhost. Nessun client secret. | App desktop, strumenti CLI, plugin CAD |
| Authorization Code + redirect HTTPS personalizzato | Applicazioni web con un URL di callback sul tuo dominio. Usa Authorization Code con PKCE e un URI di redirect HTTPS con corrispondenza esatta. | App web, integrazioni SaaS |
Passaggi successivi
Sezione intitolata “Passaggi successivi”- Per iniziare: prerequisiti, accesso di rete, modello di sicurezza e scelta di un flusso OAuth.
- Flusso Client Credentials: configurazione server-to-server dalla creazione dell’app OAuth alla tua prima chiamata all’API.
- Flusso Native Application: accesso utente con PKCE e un redirect localhost.
- Flusso Authorization Code + redirect personalizzato: accesso di app web con PKCE e un callback HTTPS personalizzato sul tuo dominio.
- Riferimento API interattivo: catalogo completo degli endpoint con schemi di richiesta/risposta e un generatore di richieste integrato.
- Snippet di codice: esempi Python copia-incolla per operazioni API comuni.
- Flussi di lavoro dei Data Bundle: creazione di un data bundle, caricamento dei dati, avvio dell’elaborazione, monitoraggio dei progressi e download dei file di input.