Netzwerkanforderungen

Für die Nutzung der RealityConnect API ist ausgehender HTTPS-Zugriff auf die unten aufgeführten Hosts erforderlich. Diese Seite behandelt den gesamten Netzwerkpfad: was erreichbar sein muss, wie sich Proxys und TLS-Inspektion auf Verbindungen auswirken, und wie sich ein Netzwerkproblem von einem Authentifizierungsproblem unterscheiden lässt.

Zusammenfassung der Anforderungen

Nur ausgehend, über HTTPS (Port 443). Es sind keine eingehenden Ports, Firewall-Regeln oder NAT erforderlich. Siehe Eingehender Zugriff.
Erlauben Sie ausgehendes HTTPS zu den unten genannten Hostnamen.
Ein Standard-Unternehmens-Forward-Proxy funktioniert transparent, auch ein authentifizierungspflichtiger. Siehe Forward-Proxys.
Ein TLS-inspizierender Proxy unterbricht Verbindungen, sofern sein Root-Zertifikat nicht von der Laufzeitumgebung der Integration als vertrauenswürdig eingestuft wird. Siehe TLS-inspizierende Proxys.

Eingehender Zugriff

Für die Nutzung der RealityConnect API muss nichts eingehend geöffnet werden. Ihre Integration baut die Verbindung immer ausgehend zu Prevu3D auf; Prevu3D baut niemals eine Verbindung zurück in Ihr Netzwerk auf. Es gibt keinen Webhook, keine Callback-URL und keinen Listener zu registrieren, und keine eingehende Firewall-Regel zu erstellen.

Ausgehender Zugriff

Ihre Integration muss drei Arten von Hosts über ausgehendes HTTPS erreichen:

OAuth und API-Erkennung: https://cloud-api.prevu3d.com
Ihr regionaler RealityConnect-API-Host, genau einer von:
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
Dateiübertragungen: https://cdn.prevu3d.com (Downloads) und Amazon S3, *.amazonaws.com (vorsignierte Upload-URLs)

Welche Region ist meine?

Ihre Organisation ist in genau einer Region bereitgestellt, sodass Sie nicht alle vier Hostnamen erlauben müssen. Statt zu raten oder den Support zu fragen, lassen Sie Ihre Integration den Discovery-Endpunkt aufrufen (GET /oauth/api-info, beschrieben in jedem OAuth-Flow-Leitfaden), sobald Sie ein Token haben: Das Feld apiUrl in der Antwort zeigt Ihnen, welchen regionalen Host Ihre Organisation tatsächlich verwendet. Erlauben Sie diesen einen Hostnamen; die anderen drei können Sie auslassen.

Forward-Proxys

Die RealityConnect API ist eine Standard-HTTPS/JSON-API. Sie erfordert nichts Ungewöhnliches vom Netzwerkpfad und tut nichts (wie z. B. Certificate Pinning), was die Funktion über einen Standard-Unternehmens-Forward-Proxy verhindern würde.

Ob Ihre Integration Ihren Proxy tatsächlich verwendet, hängt von der HTTP-Client-Bibliothek ab, auf der sie aufbaut, nicht von der RealityConnect API:

Die meisten HTTP-Clients (curl, Python requests, Node undici/fetch, .NET HttpClient usw.) respektieren die Standard-Umgebungsvariablen HTTPS_PROXY / HTTP_PROXY oder eine entsprechende Proxy-Einstellung in der Client-Konfiguration. Prüfen Sie die Dokumentation Ihrer Client-Bibliothek, um dies zu bestätigen.
Authentifizierte Proxys (die Benutzername und Passwort erfordern) werden ebenfalls auf Ebene des HTTP-Clients behandelt, über denselben Proxy-Anmeldedaten-Mechanismus, den der Client bereits für jedes andere HTTPS-Ziel unterstützt. Die RealityConnect API stellt hier keine besonderen Anforderungen. Wenn Ihr Client bereits andere HTTPS-Dienste über Ihren authentifizierten Proxy erreichen kann, erreicht er die RealityConnect API auf die gleiche Weise.

TLS-inspizierende Proxys

Manche Unternehmensnetzwerke betreiben einen TLS-inspizierenden (SSL-entschlüsselnden) Proxy: Er sitzt in der Mitte der Verbindung, präsentiert Ihrer Integration sein eigenes Zertifikat anstelle des von Prevu3D und verschlüsselt den Datenverkehr zum tatsächlichen Ziel erneut. Dies ist eine bekannte Ursache für Verbindungsprobleme bei API-Integrationen im Allgemeinen, einschließlich der RealityConnect API.

Wie sich das zeigt: Statt einer sauberen Antwort schlägt der HTTPS-Aufruf Ihrer Integration während des TLS-Handshakes mit einem Zertifikatsvalidierungsfehler fehl. Der genaue Wortlaut hängt von Ihrem HTTP-Client und Betriebssystem ab, lautet aber häufig etwa „unable to verify the first certificate”, „certificate verify failed”, „unknown certificate authority” oder ein allgemeiner Verbindungsabbruch ganz ohne HTTP-Statuscode (weil die Anfrage nie weit genug kam, um eine Antwort zu erhalten).

Was das bedeutet: Die Laufzeitumgebung Ihrer Integration erkennt das vom inspizierenden Proxy präsentierte Zertifikat nicht, weil sie der internen Zertifizierungsstelle (CA) nicht vertraut, mit der dieser Proxy den Datenverkehr neu signiert.

Erforderliche Maßnahme, eine der beiden Optionen:

Fügen Sie die Unternehmens-Root-CA in den Trust Store ein, den die Integration tatsächlich verwendet. Dies ist die häufigste Lösung und der am häufigsten übersehene Schritt: Viele Laufzeitumgebungen (Java, Node, Python) liefern oder laden ein eigenes CA-Bundle statt das des Betriebssystems zu verwenden. Das Installieren der Unternehmens-Root-CA im Windows-Zertifikatsspeicher deckt diese nicht automatisch mit ab. Prüfen Sie, ob Ihre Sprache/Laufzeitumgebung eine eigene Konfiguration benötigt (z. B. eine Umgebungsvariable NODE_EXTRA_CA_CERTS, ein JVM-Flag -Djavax.net.ssl.trustStore oder das Hinzufügen des Zertifikats zum Bundle, das Ihre Python-Installation von requests/certifi verwendet).
Nehmen Sie die Hostnamen der RealityConnect API von der TLS-Inspektion aus, falls Ihr Proxy zielbasierte Bypass-Regeln unterstützt. Das ist oft einfacher, als den Trust Store jeder einzelnen Laufzeitumgebung zu korrigieren.

Welche Option die richtige ist, hängt vom Proxy-Hersteller und der Laufzeitumgebung der Integration ab.

Diagnose: Liegt es am Netzwerk oder an der Authentifizierung?

Arbeiten Sie diese vier Prüfungen der Reihe nach ab. Jede isoliert eine andere Ebene, sodass Sie herausfinden, wo das Problem tatsächlich liegt, statt Authentifizierungscode für ein Netzwerkproblem zu debuggen (oder umgekehrt).

1. DNS

Bestätigen Sie, dass der Hostname überhaupt aufgelöst wird:

nslookup api-ue1.prevu3d.com

(Ersetzen Sie dies durch cloud-api.prevu3d.com oder den regionalen Host Ihrer Organisation.) Schlägt dies fehl oder läuft in ein Timeout, liegt das Problem bei der DNS-Auflösung. Prüfen Sie die DNS-Konfiguration des Rechners, bevor Sie weitermachen.

2. TLS-Handshake

Bestätigen Sie, dass eine sichere Verbindung zum Host aufgebaut werden kann, unabhängig von einer Prevu3D-spezifischen Anfrage:

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

Achten Sie auf SSL certificate problem, unable to get local issuer certificate oder eine Verbindung, die zurückgesetzt wird, bevor eine HTTP-Antwort erfolgt. All das deutet auf ein Proxy- oder Firewall-Problem im Netzwerkpfad hin (siehe TLS-inspizierende Proxys oben), nicht auf etwas in Ihrem Integrationscode. Eine Antwort mit einem HTTP-Statuscode, selbst ein Fehlercode wie 401, bedeutet, dass TLS erfolgreich war und das Problem weiter oben in der Kette liegt.

Das mit Windows ausgelieferte curl verwendet den Windows-Zertifikatspeicher. Diese Prüfung kann daher erfolgreich sein, während eine Laufzeitumgebung mit eigenem CA-Bundle (Node, Python, Java) hinter einem TLS-inspizierenden Proxy weiterhin fehlschlägt. Wenn die Prüfung erfolgreich ist, Ihre Integration aber einen Zertifikatfehler meldet, siehe TLS-inspizierende Proxys.

3. Token-Anfrage

Bestätigen Sie, dass Sie ein OAuth-Access-Token erhalten können. Damit prüfen Sie, ob Ihre Anmeldedaten und Ihre OAuth-Anfrage korrekt aufgebaut sind, unabhängig von einem RealityConnect-API-Aufruf:

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

Ein 403 (falsches Secret) oder 404 (unbekannte Client-ID) an dieser Stelle ist ein Problem mit den Anmeldedaten, kein Netzwerkproblem, da DNS und TLS bereits erfolgreich waren, um bis hierher zu gelangen.

4. Erster authentifizierter Aufruf

Bestätigen Sie, dass das Token tatsächlich gegen die API funktioniert:

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

Eine erfolgreiche JSON-Antwort bestätigt hier, dass der gesamte Pfad (DNS, TLS und Authentifizierung) durchgängig funktioniert. Ein 401/403 an dieser Stelle, nachdem Schritt 3 erfolgreich war, deutet auf ein Problem mit Scopes oder Berechtigungen hin, nicht auf ein Netzwerk- oder Anmeldedatenproblem. (/oauth/api-info erfordert den read:basic-Scope.)

Wie geht es weiter?

Erste Schritte: Voraussetzungen, das Sicherheitsmodell und die Wahl eines OAuth-Flows.