소개

RealityConnect API는 외부 시스템이 Prevu3D 생태계와 상호작용할 수 있게 하는 단일 공개 표면입니다. 이를 사용하여 RealityPlatform에서 콘텐츠를 읽고 쓰고, RealityTwin 워크스페이스를 구동하고, 조직을 관리하고, 파일과 데이터셋을 업로드하는 등 훨씬 더 많은 작업을 수행하세요.

---

API 구성 방식

구축을 시작하기 전에 알아둘 만한 몇 가지 설계 선택이 있습니다:

• 지역별 기본 URL. API는 여러 지역(US East, EU Central, Asia North, Canada Central)에서 실행됩니다. 조직은 그중 정확히 하나에 프로비저닝됩니다. 하드코딩하는 대신 항상 검색 엔드포인트에서 기본 URL을 가져오세요. 시작하기 가이드에서 방법을 보여줍니다.
• 모든 것이 조직으로 범위가 지정됩니다. 토큰은 서비스 사용자가 ì ‘ê·¼ 권한을 부여받은 노드만 ë³¼ 수 있습니다. 조직 ê°„ 호출은 불가능합니다.
• 리소스는 콘텐츠 계층 구조에 있습니다. 대부분의 작업은 UUIDë¡œ 식별되는 노드를 대상으로 합니다. 노드는 /nodes/{id}/browse 엔드포인트로 탐색할 수 있는 트리(organization → division → site → folder → asset)를 형성합니다.
• 3계층 ì ‘ê·¼ 제어. OAuth 스코프, 콘텐츠 ì ‘ê·¼, 노드별 역할이 모두 통과해야 요청이 성공합니다. 각각을 구성하는 방법은 보안 모델을 참조하세요.
• HTTPS를 통한 JSON. 모든 엔드포인트는 JSON을 수락하고 반환하며, bearer 토큰 인증을 사용하고, 표준 HTTP 상태 코드를 따릅니다.

OAuth 인증

API 인증은 OAuth2 프로토콜을 기반으로 합니다. 지원되는 플로:

OAuth 플로	설명	사용 사례 예시
Client Credentials	로그인한 사용자 없이 서버 대 서버 접근. 조직에 서비스 사용자를 생성합니다; 권한은 별도로 구성합니다.	스크립트, 자동화, 백엔드 연동, API 테스트
Native app	사용자가 브라우저를 통해 로그인하고 스코프에 동의합니다. PKCE와 http://localhost 리디렉션을 사용하는 Authorization Code + Native Application을 사용합니다. 클라이언트 시크릿 없음.	데스크톱 앱, CLI 도구, CAD 플러그인
Authorization Code + custom HTTPS redirect	자체 도메인에 콜백 URL이 있는 웹 애플리케이션. PKCE와 정확히 일치하는 HTTPS 리디렉션 URI를 사용하는 Authorization Code를 사용합니다.	웹 앱, SaaS 연동

다음 단계

• 시작하기: ì „ì œ ì¡°ê±´, 네트워크 ì ‘ê·¼, 보안 모델, OAuth 플로 선택.
• Client Credentials 플로: OAuth 앱 생성부터 첫 API 호출까지 서버 대 서버 설정.
• Native Application 플로: PKCE와 localhost 리디렉션을 사용한 사용자 로그인.
• Authorization Code + Custom Redirect 플로: PKCE와 도메인의 사용자 지정 HTTPS 콜백을 사용한 웹 앱 로그인.
• 대화형 API 참조: 요청/응답 스키마와 내장 요청 빌더가 있는 ì „ì²´ 엔드포인트 카탈로그.
• Data Bundle 워크플로: data bundle 생성, 데이터 업로드, 처리 시작, 진행 상황 모니터링, ìž…ë ¥ 파일 다운로드.