XRCLOUD API (1.0)
Download OpenAPI specification:Download
해당 문서의 모든 API 호출은 ApiKey를 필요로 합니다.
ApiKey는 XRCLOUD 페이지에 로그인 한 후 페이지 우상단의 My page에서 발급 받을 수 있습니다.
XRCLOUD의 Project는 개발자의 프로젝트, 플랫폼, 또는 3rd-party 애플리케이션이 될 수 있습니다. 이는 Scene과 Room을 관리하는 단위로, 여러 Scene과 Room이 특정 Project에 속하게 됩니다.
webhookUrl은 XRCLOUD 페이지에서 Project를 생성하거나 정보를 수정할 때 설정할 수 있습니다.
get project
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- 200
- default
{- "id": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
- "name": "example project name",
- "createdAt": "2023-07-12T09:27:41.600Z",
- "updatedAt": "2023-07-12T09:27:41.600Z",
}
웹페이지 기반의 3D 가상공간을 제작하는 공간으로 Room을 생성할 때 필요한 공간입니다.
get-creation-url api를 호출하면 얻을 수 있는 필드 중 'sceneCreationUrl'에 접속하여 에디터(Spoke)에 접근한 후 우상단의 Publish Scene 버튼을 통해 Scene을 생성할 수 있습니다. 또, get-scene api를 호출하면 얻을 수 있는 필드 중 'sceneModificationUrl'에 접근하여 수정합니다.
optId값은 XRCLOUD에서 Scene의 생성 및 수정을 확인하기위한 callback value 입니다. 변형하여 사용하면 오류가 발생할 수 있습니다.
get scenes
query Parameters
| projectId required | uuid Project의 고유 ID. |
| name | string (search) 해당 이름을 가진 Object 조회. |
| creator | string (search) 특정 제작자의 Object 조회. |
| take | number (pagination) 가져올 데이터의 갯수. |
| skip | number (pagination) 건너뛸 데이터의 갯수. |
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- 200
- default
{- "items": [
- {
- "id": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
- "name": "example scene name",
- "createdAt": "2023-07-12T09:27:41.600Z",
- "updatedAt": "2023-07-12T09:27:41.600Z",
- "sceneModificationUrl": "https://room.xrcloud.app:4000/spoke/projects/ASJCJK1?optId=35e75895-9db7-4eee-bae3-87e20ee156dc"
}
], - "total": 0,
- "skip": 0,
- "take": 0
}
get creation url
query Parameters
| projectId required | uuid Project의 고유 ID. |
| creator | string Scene의 제작자를 지정할 수 있습니다. 사용자별 'My Assets'를 구분하는 데에 쓰이며 해당 파라미터를 포함하지 않고 호출하여 제작하는 경우 'Admin'이 제작한 것과 동일하게 취급됩니다. |
| callback | string Example: callback=https://api.xrcloud.app/rooms Scene 제작 직후에 특정 동작이 필요한 경우(해당 Scene으로 곧장 Room을 제작하는 경우 등) 포함하여 호출합니다. XRCloud 측에서의 호출은 아래와 같이 이루어집니다. { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sceneId }) } |
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- 200
- default
{
}get scene
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- 200
- default
{- "id": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
- "name": "example scene name",
- "createdAt": "2023-07-12T09:27:41.600Z",
- "updatedAt": "2023-07-12T09:27:41.600Z",
- "sceneModificationUrl": "https://room.xrcloud.app:4000/spoke/projects/ASJCJK1?optId=35e75895-9db7-4eee-bae3-87e20ee156dc"
}remove scene
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- default
{- "statusCode": 400,
- "method": "Method",
- "url": "/example/endpoint",
- "body": {
- "key": "value"
}, - "message": "Detailed error messages"
}Room은 에디터(Spoke)를 통해 생성된 Scene으로 구성된 공간입니다.
각 Room에는 정보 요청 시마다 주소가 변하는 private room URL과 고정된 주소를 가진 public room URL이 있습니다. 이 URL들은 또한 방의 호스트에게 권한을 부여하는 host URL과 게스트 권한을 부여하는 guest URL로 구분됩니다.
'returnUrl'은 방을 떠날 때 돌아갈 웹 주소를 의미하며, XRCloud의 Rooms 탭에서 설정할 수 있습니다.
create room
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Request Body schema: application/jsonrequired
| projectId required | uuid Project의 고유 ID. |
| sceneId required | uuid Scene의 고유 ID. |
| name required | string Room의 이름. |
| returnUrl required | string Room 퇴장 시 돌아갈 URL. |
| size | number Room에 입장할 수 있는 최대 인원 수. |
Responses
Request samples
- Payload
{- "projectId": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
- "sceneId": "1234e5ba-5678-4f7a-86ed-abcd95ea1efg",
- "name": "example room name",
- "size": 10
}Response samples
- 201
- default
{- "id": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
- "name": "example room name",
- "size": 10,
- "tags": [ ],
- "sceneId": "c322b49b-6e12-47d9-b293-b5ab3727459c",
- "createdAt": "2023-07-12T09:27:41.600Z",
- "updatedAt": "2023-07-12T09:27:41.600Z",
- "roomUrl": {
},
}get rooms
해당 API는 projectId 또는 sceneId 중 하나를 필수적으로 포함하여 호출해야 합니다.
query Parameters
| projectId | uuid Project의 고유 ID. |
| sceneId | uuid Scene의 고유 ID. |
| name | string (search) 해당 이름을 가진 Object 조회. |
| userId | string Project(app)의 사용자. Room에 입장하는 사용자를 구분하기 위해 사용됩니다. |
| avatarUrl | string Example: avatarUrl=https://storage.com/bucket/avatar-file.glb Room에서 사용할 아바타 파일의 경로. |
| linkPayload | string Example: linkPayload=belivvr:eyJhbGciOiJIUzI1,test:NiIsInR5cCI6IkpXVCJ9,xrcloud:testValue Scene의 element인 'inline viewer'에 전달할 값. 각각의 key는 'inline viewer'의 name과 맵핑되며 쉼표(,)로 구분되고 key와 value는 콜론(:)으로 구분됩니다. |
| take | number (pagination) 가져올 데이터의 갯수. |
| skip | number (pagination) 건너뛸 데이터의 갯수. |
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- 200
- default
{- "items": [
- {
- "id": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
- "name": "example room name",
- "size": 10,
- "tags": [ ],
- "sceneId": "c322b49b-6e12-47d9-b293-b5ab3727459c",
- "createdAt": "2023-07-12T09:27:41.600Z",
- "updatedAt": "2023-07-12T09:27:41.600Z",
- "roomUrl": {
},
}
], - "total": 0,
- "skip": 0,
- "take": 0
}get room
query Parameters
| userId | string Project(app)의 사용자. Room에 입장하는 사용자를 구분하기 위해 사용됩니다. |
| avatarUrl | string Example: avatarUrl=https://storage.com/bucket/avatar-file.glb Room에서 사용할 아바타 파일의 경로. |
| linkPayload | string Example: linkPayload=belivvr:eyJhbGciOiJIUzI1,test:NiIsInR5cCI6IkpXVCJ9,xrcloud:testValue Scene의 element인 'inline viewer'에 전달할 값. 각각의 key는 'inline viewer'의 name과 맵핑되며 쉼표(,)로 구분되고 key와 value는 콜론(:)으로 구분됩니다. |
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- 200
- default
{- "id": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
- "name": "example room name",
- "size": 10,
- "tags": [ ],
- "sceneId": "c322b49b-6e12-47d9-b293-b5ab3727459c",
- "createdAt": "2023-07-12T09:27:41.600Z",
- "updatedAt": "2023-07-12T09:27:41.600Z",
- "roomUrl": {
},
}update room
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Request Body schema: application/jsonrequired
| name | string Room의 이름. |
| size | number Room에 입장할 수 있는 최대 인원 수. |
| returnUrl | string Room 퇴장 시 돌아갈 URL. |
Responses
Request samples
- Payload
{- "name": "example room name",
- "size": 10,
}Response samples
- 200
- default
{- "id": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
- "name": "example room name",
- "size": 10,
- "tags": [ ],
- "sceneId": "c322b49b-6e12-47d9-b293-b5ab3727459c",
- "createdAt": "2023-07-12T09:27:41.600Z",
- "updatedAt": "2023-07-12T09:27:41.600Z",
- "roomUrl": {
},
}remove room
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- default
{- "statusCode": 400,
- "method": "Method",
- "url": "/example/endpoint",
- "body": {
- "key": "value"
}, - "message": "Detailed error messages"
}get room logs
header Parameters
| X-XRCLOUD-API-KEY required | string 헤더에 다음과 같은 형태로 인증 키를 포함시켜야합니다. |
Responses
Response samples
- 200
- default
{- "id": "77",
- "infraUserId": "user@domain.com",
- "roomId": "1234e5ba-5678-4f7a-86ed-abcd95ea1efg",
- "sessionId": "4f7edfb6-b8a1-4f58-96ee-1deb4da98740",
- "joinedAt": "2023-12-12T09:27:41.600Z",
- "exitedAt": "2023-12-12T09:30:41.600Z"
}