Erste Schritte
Bevor Sie die RealityConnect API aufrufen, stellen Sie sicher, dass Ihre Umgebung sie erreichen kann, verstehen Sie, wie der Zugriff durchgesetzt wird, und wählen Sie den OAuth-Flow, der zu Ihrer Integration passt. Jeder Flow hat einen eigenen Schritt-für-Schritt-Leitfaden.
Voraussetzungen
Abschnitt betitelt „Voraussetzungen“Sie benötigen Organisationsadministrator-Zugriff, um Ihre erste OAuth-Anwendung zu erstellen. Wenn Sie diesen noch nicht haben, kann Ihr Organisationsadministrator Ihnen Zugriff gewähren oder die Anwendung für Sie erstellen.
API-URLs und Netzwerkzugriff
Abschnitt betitelt „API-URLs und Netzwerkzugriff“Bevor Sie OAuth-Zugangsdaten erstellen, bestätigen Sie, dass der Computer oder Server, auf dem Ihre Integration läuft, die Prevu3D-API über HTTPS erreichen kann. Unternehmens-Firewalls, Proxys und Allowlists blockieren häufig ausgehenden Datenverkehr und verursachen Verbindungszeitüberschreitungen oder DNS-Fehler.
Ihre Integration muss folgende Endpunkte erreichen können:
- OAuth und API-Erkennung: https://cloud-api.prevu3d.com
- Regionale RealityConnect API (Ihre Organisation verwendet eine Region; Ihr Flow-Leitfaden erklärt, wie Sie die genaue URL ermitteln):
Bitten Sie Ihr IT-Team, ausgehenden HTTPS-Zugriff auf diese Hosts zu erlauben, wenn Sie keine Verbindung herstellen können.
Sicherheitsmodell
Abschnitt betitelt „Sicherheitsmodell“Der API-Zugriff wird durch drei Ebenen durchgesetzt. Eine Anfrage muss alle drei bestehen; wenn eine Ebene den Zugriff verweigert, schlägt die Anfrage fehl.
Ebene 1 — OAuth-Scopes. Konfiguriert auf der OAuth-Anwendung. Scopes definieren, welche Arten von Operationen die Anwendung ausführen darf (z. B. read:basic, read:hierarchy).
Ebene 2 — Inhaltszugriff. Konfiguriert auf dem Konto, das die API aufruft. Bei Client Credentials ist das der mit Ihrer OAuth-Anwendung erstellte Service-Benutzer. Bei Authorization-Code-Flows ist es der angemeldete Benutzer. Diese Ebene bestimmt, welche Knoten (Organisationen, Divisionen, Sites usw.) der Aufrufer sehen und bearbeiten kann.
Ebene 3 — Rollen- und Berechtigungszugriff. Konfiguriert auf demselben Konto, pro Knoten. Bestimmt, was der Aufrufer mit diesem Inhalt tun kann (lesen, bearbeiten, verwalten usw.).
Jeder Flow-Leitfaden erläutert, wo und wie Sie diese Ebenen für Ihren Anwendungsfall konfigurieren.
OAuth-Flow auswählen
Abschnitt betitelt „OAuth-Flow auswählen“Wählen Sie den OAuth-Flow, der zu Ihrer Integration passt, und folgen Sie dem zugehörigen Leitfaden:
| Flow | Am besten geeignet für | Leitfaden |
|---|---|---|
| Client Credentials | Server-zu-Server-Integrationen, Skripte und Backend-Dienste, die im Namen Ihrer Organisation handeln | Client-Credentials-Flow |
| Native app | Integrationen, bei denen sich ein Benutzer im Browser anmeldet (Desktop-Apps, CLI, Plugins). Authorization Code + Native Application mit PKCE, localhost-Redirect, ohne Client Secret. | Native-Anwendungsflow |
| Authorization Code + benutzerdefinierte HTTPS-Redirect-URI | Webanwendungen mit Callback-URL auf Ihrer eigenen Domain | Demnächst verfügbar |
Nicht sicher, wo Sie anfangen sollen? Client Credentials ist der einfachste Weg, um die API zu testen oder serverseitige Automatisierung aufzubauen. Verwenden Sie Native app, wenn API-Aufrufe als bestimmter angemeldeter Benutzer laufen müssen.
Experimentelle Endpunkte
Abschnitt betitelt „Experimentelle Endpunkte“Einige Operationen in der API-Referenz sind als experimentell gekennzeichnet. Im OpenAPI-Dokument deklarieren sie x-scalar-stability: experimental.
Behandeln Sie experimentelle Endpunkte anders als stabile:
- Änderungen erwarten. Pfade, Parameter, Payloads, Antworten, Fehler oder Verfügbarkeit können sich ändern, ohne die gleichen Stabilitätsgarantien wie der Rest der API.
- Nutzung isolieren. Bevorzugen Sie für Produktionsworkloads stabile Operationen. Wenn Sie etwas Experimentelles nutzen, kapseln Sie es in einem kleinen Adapter, damit Sie sich bei Änderungen am Vertrag schnell anpassen können.
- Aktuell bleiben. Verfolgen Sie die Release Notes und prüfen Sie die API-Referenz nach Upgrades erneut, damit Sie nicht von Verhaltensänderungen überrascht werden.
Wie geht es weiter?
Abschnitt betitelt „Wie geht es weiter?“Wählen Sie einen Flow aus den folgenden Optionen und folgen Sie dem Leitfaden von Anfang bis Ende.
Erkunden Sie die API-Referenz, um alle verfügbaren Operationen zu sehen.