시작하기

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 플로를 사용하세요.

실험적 엔드포인트

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

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

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

참고

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

다음은?

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

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

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