시작하기

RealityConnect API를 호출하기 전에, 네트워크가 API에 도달할 수 있는지 확인하고, 접근이 어떻게 적용되는지 이해하고, 연동에 맞는 OAuth 플로를 선택하세요. 각 플로에는 자체 단계별 가이드가 있습니다.

---

전제 조건

첫 OAuth 애플리케이션을 생성하려면 조직 관리자 접근 권한이 필요합니다. 아직 없는 경우, 조직 관리자가 접근 권한을 부여하거나 대신 애플리케이션을 생성해 줄 수 있습니다.

참고

API 접근은 계정에 따라 다를 수 있습니다. 여기에 설명된 항목을 사용할 수 없는 경우, 계정 관리자나 고객 성공 담당자에게 문의하세요.

API URL 및 네트워크 접근

OAuth 자격 증명을 생성하기 전에, 연동을 실행하는 머신이나 서버가 HTTPS를 통해 Prevu3D API에 도달할 수 있는지 확인하세요. 기업 방화벽, 프록시, 허용 목록은 종종 아웃바운드 트래픽을 차단하고 연결 시간 초과나 DNS 오류를 유발합니다.

연동은 다음에 도달할 수 있어야 합니다:

• OAuth 및 API 검색: https://cloud-api.prevu3d.com
• 지역별 RealityConnect API (조직은 하나의 지역을 사용합니다; 플로 가이드에서 정확한 URL을 검색하는 방법을 설명합니다):
  • https://api-ue1.prevu3d.com/realityconnect-api/
  • https://api-ec1.prevu3d.com/realityconnect-api/
  • https://api-an1.prevu3d.com/realityconnect-api/
  • https://api-cc1.prevu3d.com/realityconnect-api/

연결할 수 없는 경우 IT 팀에 이러한 호스트에 대한 아웃바운드 HTTPS 접근을 허용하도록 요청하세요.

보안 모델

API 접근은 3계층을 통해 적용됩니다. 요청이 성공하려면 모든 계층을 통과해야 합니다; 어느 계층이든 접근을 거부하면, 요청은 실패합니다.

계층 1 — OAuth 스코프. OAuth 애플리케이션에서 구성됩니다. 스코프는 애플리케이션이 수행할 수 있는 작업 계열(예: read:basic, read:hierarchy)을 정의합니다.

계층 2 — 콘텐츠 접근. API를 호출하는 계정에서 구성됩니다. Client Credentials의 경우, OAuth 애플리케이션으로 생성된 서비스 사용자입니다. Native app 플로의 경우, 로그인한 사용자입니다. 이 계층은 호출자가 볼 수 있고 작업할 수 있는 노드(조직, 디비전, 사이트 등)를 결정합니다.

계층 3 — 역할/권한 접근. 동일한 계정에서 노드별로 구성됩니다. 호출자가 해당 콘텐츠로 무엇을 할 수 있는지(읽기, 편집, 관리 등)를 결정합니다.

각 플로 가이드는 사용 사례에 대해 이러한 계층을 구성하는 위치와 방법을 안내합니다.

OAuth 플로 선택

연동이 실행되는 방식에 맞는 OAuth 플로를 선택한 다음, 전용 가이드를 따르세요:

플로	적합한 용도	가이드
Client Credentials	조직을 대신하여 작동하는 서버 대 서버 연동, 스크립트, 백엔드 서비스	Client Credentials 플로
Native app	사용자가 브라우저를 통해 로그인하는 연동(데스크톱 앱, CLI 도구, 플러그인). PKCE, localhost 리디렉션, 클라이언트 시크릿 없이 Authorization Code + Native Application을 사용합니다.	Native Application 플로
Authorization Code + custom HTTPS redirect	자체 도메인에 콜백 URL이 있는 웹 애플리케이션	Authorization Code + Custom Redirect 플로

어디서 시작할지 잘 모르겠나요? Client Credentials는 API를 테스트하거나 서버 측 자동화를 구축하는 가장 간단한 경로입니다. API 호출이 특정 로그인한 사용자로 실행되어야 할 때는 Native app 플로를 사용하세요.

라이선스

RealityTwin 관련 엔드포인트를 호출하면 조직의 플로팅 라이선스 풀에서 RealityTwin Data Manager 라이선스 1개가 사용됩니다. 라이선스 풀의 작동 방식과 사용량 계산 방법은 RealityTwin 라이선스를 참조하세요.

조직에 사용 가능한 라이선스가 없으면 라이선스가 해제되거나 추가 라이선스가 추가될 때까지 RealityTwin 관련 API 호출이 실패합니다.

실험적 엔드포인트

API 참조의 일부 작업은 experimental로 표시됩니다.

실험적 엔드포인트는 안정적인 것과 다르게 취급하세요:

• 변경을 예상하세요. 경로, 매개변수, 페이로드, 응답, 오류, 가용성은 API의 나머지 부분과 동일한 안정성 보장 없이 변경될 수 있습니다.
• 사용을 격리하세요. 연동에서, 안정적인 작업을 선호하세요. 실험적인 것에 의존하는 경우, 계약이 발전할 때 빠르게 조정할 수 있도록 작은 어댑터 뒤에 두세요.
• 최신 상태를 유지하세요. 릴리스 노트를 따르고 업그레이드 후 API 참조를 다시 확인하여 동작 변경에 놀라지 않도록 하세요.

참고

Experimental은 테스트나 조기 도입에 신뢰할 수 없다는 의미가 아닙니다. 하위 호환 동작을 확정하기 전에 형태와 의미가 여전히 정착 중이라는 의미입니다.

다음은?

다음 옵션에서 플로를 선택하고 그 가이드를 끝까지 따르세요.

• Client Credentials 플로
• Native Application 플로
• Authorization Code + Custom Redirect 플로

사용 가능한 모든 작업을 보려면 API 참조를 살펴보세요.