Matterport API 사용 방법

Matterport 개발자 커뮤니티는 Matterport를 일상 워크플로에 통합하려는 업계 전문가들이 모인 조직입니다. Matterport는 이 커뮤니티 지원을 위한 우선적인 노력의 일환으로 건축가, 엔지니어를 비롯하여 Matterport 플랫폼을 적극 활용하려는 기타 전문가들에게 API를 공개하고 있습니다. 

Matterport는 Matterport 백엔드 데이터 저장소에 직접 연결될 수 있는 개발자 도구 세트를 제공하며 고객들은 모델을 프로그래밍 방식으로 활용할 수 있습니다. 데이터 직접 액세스에서 콘텐츠 수정, 모델 상태 관리, 부가 가치 서비스 구매까지 개발자가 완벽한 제어 기능을 확보할 수 있도록 지원합니다.

문서화

참조 가이드에서 최신 GraphQL API 기능을 확인할 수 있으며 제한적으로 GraphQL API를 실험에 활용할 수 있는 대화형 콘솔을 이용할 수 있습니다.

대화형 콘솔을 이용하려면 관리자 자격 증명으로 Matterport 클라우드(my.matterport.com)에 로그인해야 합니다.

방법

API 키 생성

  1. Matterport 클라우드(my.matterport.com)로 이동합니다
  2. 오른쪽 "계정(Account)" 드롭다운을 클릭합니다
  3. "개발자 도구(Developer Tools)"를 선택합니다 
  4. "API 토큰 관리(API Token Management)" 섹션으로 스크롤합니다 
    • 여기서 API 키를 요청하고 취소할 수 있습니다.

API 엔드포인트에 연결할 수 있는 API 키를 생성해야 합니다. 구축하려는 여러 애플리케이션에서 사용할 키를 최대 5개까지 생성할 수 있습니다. 새 키를 생성할 때 제공되는 항목은 다음과 같습니다.

  1. 토큰 암호
    • 한 번만 제공되므로 복사하여 안전하게 저장해야 합니다.
  2. 토큰 ID
    • 설정 페이지에 표시됩니다

API 키는 "관리자" 또는 "모든 액세스 권한" 키입니다. 이는 사용자에게 고객 계정에 대한 관리 자격 증명을 부여함을 의미합니다. 개발자는 생성된 API 키로 API를 사용함으로써 모델 보관, 평면도 및 MatterPak 구매 등 API를 사용하는 모든 관리 기능을 수행할 수 있습니다. API 키를 공유하는 경우 타사 또는 외부 개발자와 API 키를 공유해서는 안 됩니다.

계정에서는 기본적으로 샌드박스 모드만 활성화됩니다. 샌드박스 모드에 대한 자세한 내용은 개발자 도구 가용성 및 가격을 참조하십시오.

엔드포인트에 연결

  1. API 엔드포인트(https://api.matterport.com/api/models/graph)에 액세스합니다. 
  2. 토큰 ID를 사용자 이름으로 사용합니다
  3. 토큰 암호를 암호로 사용합니다
    • 예: Authorization: Basic <base64_encode(<Token ID>:<Token Secret) 

모든 표준 http 라이브러리가 이 프로세스를 지원해야 하지만 선제적 권한 부여는 "true"로 설정해야 합니다.   

오류 코드

모든 애플리케이션 수준 오류는 오류 확장자에 "codes"가 포함됩니다. 아래 가이드를 참조하여 일반적인 오류 코드를 확인하고 문제를 해결합니다.

   1. request.unauthenticated 

인증 토큰이 없거나 인증 토큰이 만료되었습니다.

   2. request.unauthorized 

사용자가 허용되지 않는 작업 또는 필드에 액세스하려고 했습니다.

   3. request.invalid 

그래프 쿼리를 처리할 수 없습니다.

   4. error.internal 

서버가 요청을 처리할 수 없습니다.

   5. not.found 

요청한 개체가 존재하지 않습니다. 이 오류는 연결된 작업에서 특정 ID 필드를 사용할 때 나타납니다.

   6. not.unique 

보조 인덱스에서 단일 레코드를 검색하려고 시도했지만 제출된 쿼리와 일치하는 레코드가 여러 개 있습니다. 일반적으로 여러 모델의 내부 ID가 같은 경우입니다.

   7. quota.exceeded 

리소스 제한 변형 - 예를 들어 구독 제한으로 인해 허용되는 모델보다 더 많은 모델을 활성화하려고 시도했습니다.

코드 조각 예제

시작하려면 이 코드 조각 예제를 참조하십시오. 

FAQ

1. API란 무엇입니까? 

API는 "Application Programming Interface(애플리케이션 프로그래밍 인터페이스)"의 약자로 컴퓨터 프로그램의 다양한 요소를 연결하는 통신 프로토콜입니다. API의 주된 목적은 소프트웨어 구현과 유지 관리를 단순화하는 것입니다.

개발자(또는 고객)는 Matterport API를 사용함으로써 데이터 액세스, 수정을 위해 시스템 또는 애플리케이션을 Matterport 시스템에 직접 프로그래밍 방식으로 연결할 수 있습니다.

2. Matterport는 "SDK"도 제공합니다. API와의 차이점은 무엇입니까?

Matterport API 베타 이전까지 Matterport 개발자는 주로 Showcase SDK(소프트웨어 개발 키트)를 사용했습니다. API 베타는 추가 기능으로 그 차이점은 다음과 같습니다..

Showcase SDK 

Showcase SDK는 Showcase가 다른 사이트 또는 플랫폼에 직접 삽입되더라도 개발자가 Showcase 기능을 확장하기 위해 사용할 수 있는 프로그래밍 명령의 집합입니다. Showcase iFrame 위에 위치하는 눈에 보이지 않는 얇은 계층으로 이해할 수 있으며 개발자 페이지에만 나타납니다. 따라서 SDK는 사용당 한 개발자 페이지의 경험에만 영향을 미칩니다. 즉 여러 사이트에서 공유한 모델이라도 SDK가 적용된 개발자 페이지에서만 영향을 받습니다.

API

SDK와 반대로 API는 Matterport 백엔드에 직접 연결됩니다. 따라서 개발자는 검색, 데이터 읽기, 데이터 변경, 주문 이행과 같은 다양한 명령을 수행할 수 있습니다. 개발자는 Matterport API를 사용하여 고객이 Matterport 사이트에서 취하는 조치를 프로그래밍 방식으로 수행할 수 있습니다.

3. 모델 API란 무엇이며 고려 중인 다른 API들로는 어떤 것들이 있습니까?

API의 세계는 무궁무진합니다. 현재 Matterport는 개발자가 사용할 수 있는 다양한 명령을 다음과 같은 하위 범주로 분류하고 있습니다.

모델 API 명령

이 명령은 모델 데이터를 검색, 읽기 및/또는 변경합니다. 모델 데이터에는 어떤 것들이 있습니까? 모델 세부 정보(예: 공간의 이름과 주소), 공유 URL, 이미지, 동영상, 위치 데이터, OBJ 메시 파일, 포인트 클라우드 파일, 파노라마 이미지, 위치 지점, Mattertag. 

수집 API 명령

이 명령은 3D 재구성을 위해 파노라마 이미지 컬렉션을 Matterport 비전 파이프라인으로 직접 보냅니다. 개발자는 파노라마 이미지와 함께 파노라마 시퀀스, 층 파노라마 및 기타 위치 데이터와 같은 추가 메타데이터를 보낼 수 있습니다. 기본적으로 더 많은 메타데이터를 제공할수록 3D 재구성이 성공할 가능성이 높습니다. 

이 솔루션이 성숙되면서 이전에 Matterport 플랫폼과 호환되지 않은 다른 360° 카메라를 사용하여 파노라마 이미지 컬렉션을 촬영해 온 고객까지 지원할 수 있게 되기를 바랍니다.

계정 API 명령

이 명령은 권한 프로비저닝 및 설정을 포함해 사용자와 폴더를 관리합니다.

서비스 API 명령

개발자는 이 명령을 사용하여 프로그래밍 방식으로 검색, 주문 이행을 처리할 수 있으며 Matterport 모델 이외에 제공되는 부가 가치 서비스(예: MatterPak, 평면도)에도 프로그래밍 방식으로 액세스할 수 있습니다.

게시 API 명령

개발자는 이 명령을 사용하여 오늘날 Matterport가 지원하는 모든 게시 플랫폼을 프로그래밍 방식으로 검색, 사용할 수 있습니다. 대표적인 플랫폼은 Google Street View, Vrbo, realtor.com, homes.com을 예로 들 수 있습니다.

4. API를 사용하여 어떤 계정에 액세스할 수 있습니까? 

고객의 계정과 모델에 액세스할 때는 API만 사용하는 것이 좋습니다. API 토큰은 기본적으로 관리 자격 증명의 집합이며 계정에 대한 전체 액세스 권한을 제공합니다(API를 통한 구매도 가능). 

5. 어떻게 시작합니까? 

API 토큰을 요청해야 합니다. 아래의 간단한 지침을 따르십시오.

  1. Matterport 클라우드(my.matterport.com)로 이동합니다
  2. 오른쪽 "계정(Account)" 드롭다운을 클릭합니다
  3. "개발자 도구(Developer Tools)"를 선택합니다 
  4. "API 토큰 관리(API Token Management)" 섹션으로 스크롤합니다 
    • 여기서 API 키를 요청하고 취소할 수 있습니다.

6. 궁금한 점이 더 있으십니까?

보다 자세한 모델 API FAQ를 참조하십시오. 

또 다른 질문이 있으십니까? 문의 등록