자산 사용 가이드

오픈 클라우드의 자산 API를 통해 스튜디오에 수동으로 가져오는 대신 단일 HTTP 요청으로 자산을 업로드하고 업데이트할 수 있습니다.이 API는 지원합니다:

새로운 자산 업로드 중.
버전 제어로 기존 자산 업데이트.
설명, 디스플레이 이름, 아이콘 및 미리 보기를 포함하여 자산 메타데이터 업데이트.
지정된 이전 버전으로 롤백하는 것과 같은 자산 버전 관리.
메타데이터, 버전 및 진행 중인 업데이트 작업을 포함하여 자산의 기존 정보를 확인합니다.

이 API에는 향후 릴리스에서 변경될 수 있는 베타 엔드포인트가 포함되어 있습니다.

지원되는 자산 유형 및 제한

새로운 자산을 생성하거나 기존 자산의 콘텐츠를 업데이트하지 않는 끝점의 경우 제한 또는 제한이 없습니다.그러나, 자산 생성 및 자산 업데이트 끝점으로 구동되는 자산 콘텐츠 업로드 기능은 제한된 유형의 자산만 지원합니다.각 호출에 대해 파일 크기가 20MB까지인 하나의 자산만 생성하거나 업데이트할 수 있으며 다음 제한이 적용됩니다:

자산 업데이트 끝점을 사용하여 자산 메타데이터를 업데이트하는 것은 다음 제한에 따라 영향을 받지 않습니다.

자산 입력	형식	콘텐츠 입력	제한
오디오	.mp3 .ogg	audio/mpeg audio/ogg	최대 7분 지속 시간.: ID가 확인된 경우 월별 최대 100개의 업로드.: ID가 확인되지 않은 경우 월별 최대 10개의 업로드.: 업데이트할 수 없습니다.
데칼	.png .jpeg .bmp .tga	image/png image/jpeg image/bmp image/tga	업데이트할 수 없습니다. 8000x8000픽셀보다 작아야 합니다.
모델	.fbx	model/fbx	사용 사례에 따라 3D 가져오기(3D 가져오기)를 사용하여 특정 모델을 수동으로 업로드하는 것을 고려하십시오.: 3D 가져오기는 3D 미리보기, 다양한 오류 검사 및 많은 사용자 지정 가능한 가져오기 설정을 제공합니다.
비디오	.mp4 .mov	video/mp4 video/mov	최대 60초 지속 시간.: 최대 4096x2160 해상도.: 최대 750MB.: 현재 영어, 스페인어, 포르투갈어, 인도네시아어, 중국어(간단하고 전통적), 일본어, 그리고/또는 한국어 오디오 및 텍스트만 허용됩니다.: 13+이고 ID가 확인된 경우 월별 최대 10개의 업로드입니다.

보안 권한

API는 API 키 권한과 OAuth 2 응용 프로그램에서 제3자 사용을 모두 지원합니다.각 방향마다 다른 보안 권한 설정이 필요합니다.

API 키

자체 스크립트나 도구에서 API를 사용하려면 인증과 보안을 위해 API 키를 만들어야 합니다.개별적으로 소유하는 자산을 관리하려면 계정에서 API 키를 생성하십시오.그룹 소유 자산을 관리하려면 대상 그룹 아래에 API 키를 만듭니다.그룹 소유 API 키에 대한 자세한 정보는 그룹 소유 API 키 권한을 참조하십시오.

API 키를 만들면 개인 또는 그룹 간에 소유권을 전환할 수 없으므로 자체 계정에서 API 키를 만들면 그룹 자산을 관리하는 데 사용할 수 없습니다.

그룹에 대한 API 키를 생성하거나 그룹 자산을 생성하려면 해당 권한이 있어야 합니다.그룹 권한 부여에 대한 자세한 정보는 그룹 역할 및 권한을 참조하십시오.

자신이나 그룹을 위한 API 키를 생성하는지 여부에 관계없이 다음 권한을 추가하십시오:

자산 을 액세스 권한 에 추가합니다.
요청할 끝점의 필요한 범위에 따라 선택한 경험에 읽기 및 쓰기 작업 권한을 추가하십시오.

API 키가 있으면 x-api-key 요청 헤더에 복사하십시오. 모든 끝점에는 x-api-key 요청 헤더가 필요합니다.

Example API Request Header
--header 'x-api-key: ${ApiKey}' \

OAuth 2.0 애플리케이션

타사 OAuth 2.0 응용 프로그램에 대해 API를 사용하려면, asset:read``asset:write를 추가하여 앱을 등록하세요.사용할 끝점의 요구 사항에 따라 이러한 범위를 선택합니다.

새로운 자산 생성

HTTP 요청으로 새 자산을 업로드하려면:

API 키를 x-api-key에 자산 생성 API 끝점의 요청 헤더에 복사하십시오.

요청에서:

대상 자산 유형을 지정합니다.
자산 이름과 설명을 추가합니다.
제작자 정보 추가.
- 자체 대신 자산을 생성하려면 사용자 ID를 추가하십시오 .Roblox 프로필의 URL에서 사용자 ID를 찾을 수 있습니다.예를 들어, https://www.roblox.com/users/1234567/profile 에 대해 사용자 ID는 1234567입니다.
- 자산 을 그룹 자산으로 만들려면 그룹의 그룹 ID를 추가하십시오. 그룹의 페이지 URL에서 그룹 ID를 찾을 수 있습니다.예를 들어, https://www.roblox.com/groups/7654321/example-group#!/ 에 대해 그룹 ID는 7654321 입니다.
자산의 파일 경로와 콘텐츠 유형을 추가합니다.

Example Request for Create Asset
curl --location 'https://apis.roblox.com/assets/v1/assets' \
--header 'x-api-key: ${ApiKey}' \
--form 'request="{
  \"assetType\": \"Model\",
  \"displayName\": \"Name\",
  \"description\": \"This is a description\",
  \"creationContext\": {
    \"creator\": {
      \"userId\": \"${userId}\" # 그룹 자산 생성에 그룹ID 사용
    }
  }
}"' \
--form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

기존 자산 업데이트

자산 업데이트는 향후 릴리스에서 변경될 수 있는 베타 엔드포인트에 의해 구동됩니다.

HTTP 요청으로 기존 자산을 업데이트하려면:

API 키를 x-api-key 끝점의 요청 헤더에 복사하십시오.
요청에 자산 유형과 자산 ID를 추가하십시오. 자산 ID를 복사하려면:
1. 크리에이터 대시보드의 생성 페이지로 이동합니다.
2. 선택 개발 아이템 카테고리.
3. 자산 카테고리를 선택하고 대상 자산을 찾습니다.
4. 대상 자산의 썸네일 위로 마우스를 이동하고 ⋯ 버튼을 클릭하여 옵션 목록을 표시한 다음 목록에서 자산 ID 복사 를 선택합니다.

현재 자산 콘텐츠는 .fbx 파일에만 업데이트할 수 있습니다. 업데이트는 새 버전을 생성합니다.

Example Request for Updating Asset Content
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}' \
--form 'request={
    \"assetType\": \"{assetType}\",
    \"assetId\": \"{assetId}\",
    \"creationContext\": {
        \"creator\": {
            \"userId\": {userId}
        },
        \"expectedPrice\":{expectedPrice}
    },
}' \
--form 'fileContent=@"{file-path}"'

자산 작업 상태 검색

새 자산을 만들거나 기존 자산을 업데이트하는 요청이 성공하면 작업 ID 를 { "path": "operations/${operationId}" } 반환합니다.다음 단계로 업로드 상태 및 결과를 확인할 수 있습니다:

API 키를 x-api-key 요청 헤더에 복사하여 작업 가져오기 메서드의 요청을 보내고 다음 코드 샘플처럼 요청을 보냅니다.

Example Request for Get Operation
curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
--header 'x-api-key: {$ApiKey}'

요청이 성공하면 Operation 개체를 반환하며, 업로드된 자산 정보를 나타내는 response 또는 자산 업로드가 실패하는 이유를 설명하는 status 코드 샘플을 포함합니다.

Example Response for Get Operation
{
  "path": "operations/{operationId}",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/roblox.open_cloud.assets.v1.Asset",
    "path": "assets/2205400862",
    "revisionId": "1",
    "revisionCreateTime": "2023-03-02T22:27:04.062164400Z",
    "assetId": "2205400862",
    "displayName": "Name",
    "description": "This is a description",
    "assetType": "ASSET_TYPE_DECAL",
    "creationContext": {
      "creator": {
        "userId": "11112938575"
      }
    },
    "moderationResult": {
      "moderationState": "MODERATION_STATE_APPROVED"
    }
  }
}

(선택사항) Roblox 계정에서 생성된 자산을 확인합니다.
1. Navigate to the 인벤토리 페이지 of your Roblox 계정.
2. 확인하려는 자산의 카테고리 를 선택합니다.
3. 대상 자산을 찾아 자산 미리 보기를 클릭하여 자산을 봅니다.

OAuth 2.0 앱에 자산 API 추가

자산 API를 지원하는 OAuth 2.0 응용 프로그램을 생성하여 사용자가 Roblox에 자산을 업로드하고 업데이트할 수 있도록 할 수 있습니다.

OAuth 2.0을 통한 타사 앱 지원은 향후 릴리스에서 변경될 수 있는 베타 기능입니다.

응용 프로그램에 자산 API를 사용하고 사용자에게 권한을 요청하려면 다음 설정을 수행하십시오:

응용 프로그램을 등록할 때 권한 아래에서 자산:읽기 및 자산:쓰기 범위를 선택합니다.

권한 흐름을 구현할 때 , 사용자를 응용 프로그램으로 다시 리디렉션하는 권한 URL의 범위 매개변수로 및 을 포함하십시오, 다음 예제와 같이:


https://authorize.roblox.com?client_id=819547628404595165403873012&redirect_uri=https://my-app.com/redirect&scope=asset:read+asset:write&response_type=Code&prompts=login+consent&nonce=12345&state=6789

요청을 보낼 때 액세스 토큰을 권한 헤더와 자산 콘텐츠의 양식 데이터에 포함하여 요청 URI에서 만들거나 업데이트하려면 합니다.다음 예제에서는 새로운 자산을 업로드하는 샘플 요청을 보여줍니다:

예제 요청
curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \

--header 'Authorization: Bearer <access_token>' \

--header 'Content-Type: application/json' \

--form 'request="{

  \"assetType\": \"Decal\",

  \"displayName\": \"DecalDemo123\",

  \"description\": \"This is a description\",

  \"creationContext\": {

    \"creator\": {

    \"userId\": \"<user_id>\"

    }
  }

}"' \

--form 'fileContent=@"/filepath/p1.png"'

이 페이지