Requisiti di rete

L’uso della RealityConnect API richiede l’accesso HTTPS in uscita agli host elencati di seguito. Questa pagina copre l’intero percorso di rete: cosa deve essere raggiungibile, come proxy e ispezione TLS influiscono sulle connessioni, e come distinguere un problema di rete da un problema di autenticazione.

Riepilogo dei requisiti

Solo in uscita, su HTTPS (porta 443). Non è richiesta alcuna porta in ingresso, regola del firewall o NAT. Vedi Accesso in ingresso.
Consenti l’HTTPS in uscita verso gli hostname indicati di seguito.
Un forward proxy aziendale standard funziona in modo trasparente, anche uno che richiede autenticazione. Vedi Proxy in uscita.
Un proxy di ispezione TLS interromperà le connessioni, a meno che il suo certificato radice non sia attendibile per l’ambiente di runtime dell’integrazione. Vedi Proxy di ispezione TLS.

Accesso in ingresso

Non è necessario aprire nulla in ingresso per usare la RealityConnect API. La tua integrazione avvia sempre la connessione in uscita verso Prevu3D; Prevu3D non apre mai una connessione di ritorno verso la tua rete. Non c’è alcun webhook, URL di callback o listener da registrare, né alcuna regola del firewall in ingresso da creare.

Accesso in uscita

La tua integrazione deve poter raggiungere tre tipi di host tramite HTTPS in uscita:

OAuth e discovery dell’API: https://cloud-api.prevu3d.com
Il tuo host regionale della RealityConnect API (esattamente uno tra):
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
Trasferimenti di file: https://cdn.prevu3d.com (download) e Amazon S3, *.amazonaws.com (URL di upload prefirmati)

Qual è la mia regione?

La tua organizzazione è provisionata in esattamente una regione, quindi non è necessario consentire tutti e quattro gli hostname. Invece di indovinare o chiedere al supporto, fai in modo che la tua integrazione chiami l’endpoint di discovery (GET /oauth/api-info, descritto in ogni guida al flusso OAuth) una volta ottenuto un token: il campo apiUrl della risposta indica quale host regionale usa effettivamente la tua organizzazione. Consenti solo quell’hostname; puoi ignorare gli altri tre.

Proxy in uscita

La RealityConnect API è un’API HTTPS/JSON standard. Non richiede nulla di insolito dal percorso di rete e non fa nulla (come il certificate pinning) che impedirebbe il suo funzionamento tramite un forward proxy aziendale standard.

Il fatto che la tua integrazione usi effettivamente il tuo proxy dipende dalla libreria client HTTP su cui è basata, non dalla RealityConnect API:

La maggior parte dei client HTTP (curl, requests di Python, undici/fetch di Node, HttpClient di .NET, ecc.) rispetta le variabili d’ambiente standard HTTPS_PROXY / HTTP_PROXY, oppure un’impostazione proxy equivalente nella configurazione del client. Consulta la documentazione della tua libreria client per confermarlo.
I proxy autenticati (che richiedono nome utente e password) sono gestiti anch’essi a livello del client HTTP, tramite lo stesso meccanismo di credenziali proxy che il client già supporta per qualsiasi altra destinazione HTTPS. La RealityConnect API non ha requisiti particolari in merito. Se il tuo client riesce già a raggiungere altri servizi HTTPS tramite il tuo proxy autenticato, può raggiungere la RealityConnect API allo stesso modo.

Proxy di ispezione TLS

Alcune reti aziendali utilizzano un proxy di ispezione TLS (decrittazione SSL): si posiziona nel mezzo della connessione, presenta alla tua integrazione un proprio certificato al posto di quello di Prevu3D e ricifra il traffico verso la destinazione reale. Questa è una causa nota di errori di connessione nelle integrazioni API in generale, RealityConnect API inclusa.

Come si manifesta: invece di una risposta normale, la chiamata HTTPS della tua integrazione fallisce durante l’handshake TLS con un errore di convalida del certificato. Il messaggio esatto dipende dal tuo client HTTP e dal sistema operativo, ma spesso è simile a “unable to verify the first certificate”, “certificate verify failed”, “unknown certificate authority”, oppure un semplice reset della connessione senza alcun codice di stato HTTP (perché la richiesta non è mai arrivata abbastanza avanti da ricevere una risposta).

Cosa significa: l’ambiente di runtime della tua integrazione non riconosce il certificato presentato dal proxy di ispezione, perché non si fida dell’autorità di certificazione (CA) interna che quel proxy usa per rifirmare il traffico.

Correzione richiesta, una delle due opzioni:

Aggiungi la CA radice aziendale al trust store effettivamente usato dall’integrazione. Questa è la soluzione più comune, e il passaggio più spesso trascurato: molti ambienti di runtime (Java, Node, Python) includono o caricano un proprio bundle di CA invece di usare quello del sistema operativo. Installare la CA radice aziendale nell’archivio certificati di Windows non li copre automaticamente. Verifica se il tuo linguaggio/ambiente di runtime richiede una configurazione propria (ad esempio una variabile d’ambiente NODE_EXTRA_CA_CERTS, un flag JVM -Djavax.net.ssl.trustStore, oppure l’aggiunta del certificato al bundle usato dalla tua installazione Python requests/certifi).
Escludi gli hostname della RealityConnect API dall’ispezione TLS, se il tuo proxy supporta regole di bypass per destinazione. Questo è spesso più semplice che correggere il trust store di ogni singolo ambiente di runtime.

L’opzione corretta dipende dal fornitore del proxy e dall’ambiente di runtime dell’integrazione.

Diagnosi: è la rete o è l’autenticazione?

Esegui questi quattro controlli in ordine. Ognuno isola un livello diverso, così puoi scoprire dove si trova realmente il problema invece di eseguire il debug del codice di autenticazione per un problema di rete (o viceversa).

1. DNS

Verifica che l’hostname venga risolto:

nslookup api-ue1.prevu3d.com

(Sostituisci con cloud-api.prevu3d.com o con l’host regionale della tua organizzazione, secondo necessità.) Se questo fallisce o va in timeout, il problema è nella risoluzione DNS. Controlla la configurazione DNS della macchina prima di proseguire.

2. Handshake TLS

Verifica che sia possibile stabilire una connessione sicura con l’host, indipendentemente da qualsiasi richiesta specifica di Prevu3D:

curl -v https://cloud-api.prevu3d.com

Cerca SSL certificate problem, unable to get local issuer certificate, oppure una connessione che si reimposta prima di qualsiasi risposta HTTP. Tutto questo indica un problema di proxy o firewall sul percorso di rete (vedi Proxy di ispezione TLS sopra), non qualcosa nel codice della tua integrazione. Una risposta con un codice di stato HTTP, anche un errore come 401, significa che il TLS è riuscito e il problema si trova più in alto nello stack.

Il curl incluso in Windows usa l’archivio certificati di Windows, quindi questo controllo può riuscire anche quando un runtime con un proprio bundle di CA (Node, Python, Java) continua a fallire dietro un proxy con ispezione TLS. Se il controllo riesce ma la tua integrazione segnala un errore di certificato, consulta Proxy di ispezione TLS.

3. Richiesta del token

Verifica di poter ottenere un token di accesso OAuth. Questo controlla che le tue credenziali e la tua richiesta OAuth siano formate correttamente, indipendentemente da qualsiasi chiamata alla RealityConnect API:

curl -v -X POST https://cloud-api.prevu3d.com/oauth/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

Un 403 (secret errato) o 404 (client ID sconosciuto) a questo punto è un problema di credenziali, non un problema di rete, perché DNS e TLS sono già riusciti per arrivare fin qui.

4. Prima chiamata autenticata

Verifica che il token funzioni effettivamente con l’API:

curl -H "Authorization: Bearer <access_token>" https://cloud-api.prevu3d.com/oauth/api-info

Una risposta JSON di successo qui conferma che l’intero percorso (DNS, TLS e autenticazione) funziona end-to-end. Un 401/403 a questo punto, dopo che il passaggio 3 è riuscito, indica un problema di scope o permessi piuttosto che un problema di rete o di credenziali. (/oauth/api-info richiede lo scope read:basic.)

Cosa c’è dopo?

Per iniziare: prerequisiti, il modello di sicurezza e la scelta di un flusso OAuth.