자산 사용 가이드

Open Cloud의 자산 API를 사용하면 Studio에 자산을 수동으로 가져오는 대신 단일 HTTP 요청으로 자산을 업로드하고 업데이트할 수 있습니다. 이 API는 다음을 지원합니다:

• 새로운 자산 업로드.
• 버전 관리를 통해 기존 자산 업데이트.
• 설명, 표시 이름, 아이콘 및 미리보기를 포함한 자산 메타데이터 업데이트.
• 특정 이전 버전으로 롤백하는 등 자산 버전 관리.
• 메타데이터, 버전 및 진행 중인 업데이트 작업을 포함한 자산의 기존 정보 확인.

지원되는 자산 유형 및 제한 사항

새 자산을 생성하거나 기존 자산의 콘텐츠를 업데이트하지 않는 엔드포인트에는 제한 사항이 없습니다. 그러나 자산 생성 및 자산 업데이트 엔드포인트에서 제공하는 자산 콘텐츠 업로드 기능은 제한된 유형의 자산만 지원합니다. 각 호출마다 최대 20MB의 파일 크기로 하나의 자산만 생성하거나 업데이트할 수 있습니다. 다음 제한 사항이 적용됩니다:

보안 권한

API는 API 키 인증을 통한 1차 사용과 OAuth 2 애플리케이션을 통한 3차 사용을 모두 지원합니다. 각 방식에는 서로 다른 보안 권한 설정이 필요합니다.

API 키

자신의 스크립트나 도구에서 API를 사용하려면 인증 및 보안을 위해 API 키를 생성해야 합니다.

API 키를 생성할 때 다음 권한을 추가해야 합니다:

1. 액세스 권한에 자산 추가.
2. 호출하려는 엔드포인트의 필요 범위에 따라 선택한 게임에 읽기 및 쓰기 작업 권한 추가.

API 키를 수신하면 x-api-key 요청 헤더에 복사합니다. 모든 엔드포인트에 x-api-key 요청 헤더가 필요합니다.

예시 API 요청 헤더
--header 'x-api-key: ${ApiKey}' \

OAuth 2.0 앱

타사 OAuth 2.0 애플리케이션에 API를 사용하려면 앱 등록 시 asset:read 및 asset:write 권한 범위를 추가하세요. 사용하려는 엔드포인트의 요구 사항에 따라 이러한 범위를 선택하세요.

새로운 자산 생성

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

1. 자산 생성 엔드포인트의 x-api-key 요청 헤더에 API 키를 복사합니다.

2. 요청에서:

   1. 대상 자산 유형을 지정합니다.
   2. 자산 이름 및 설명을 추가합니다.
   3. 생성자 정보를 추가합니다.

      • 자신을 대신하여 자산을 생성하려면 사용자 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입니다.
   4. 자산의 파일 경로 및 콘텐츠 유형을 추가합니다.

   자산 생성 요청 예시
   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}\" # 그룹 자산 생성을 위해 groupId 사용
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

기존 자산 업데이트

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

1. 자산 업데이트 엔드포인트의 x-api-key 요청 헤더에 API 키를 복사합니다.
2. 요청에서 자산 유형 및 자산 ID를 추가합니다. 자산 ID를 복사하려면:

   1. 크리에이터 대시보드의 생성 페이지로 이동합니다.
   2. 개발 항목 범주를 선택합니다.
   3. 자산 범주를 선택하고 대상 자산을 찾습니다.
   4. 대상 자산의 썸네일 위에 마우스를 올리고 ⋯ 버튼을 클릭하여 옵션 목록을 표시한 다음, 목록에서 자산 ID 복사를 선택합니다.

자산 콘텐츠 업데이트 요청 예시
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}"'

자산 작업 상태 검색

새 자산 생성 또는 기존 자산 업데이트 요청이 성공하면 { "path": "operations/${operationId}" } 형식의 작업 ID가 반환됩니다. 이 ID를 사용하여 다음 단계와 같이 업로드 상태와 결과를 확인할 수 있습니다:

1. 작업 가져오기 메서드의 x-api-key 요청 헤더에 API 키를 복사하고 요청을 전송합니다. 다음 코드 샘플과 같이:

   작업 가져오기 요청 예시
   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. 요청이 성공하면 Operation 객체가 반환되며, 업로드된 자산 정보가 포함된 response 또는 자산 업로드 실패 이유를 설명하는 status가 포함될 수 있습니다. 다음 코드 샘플과 같습니다:

   작업 가져오기 응답 예시
   {
     "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"
       }
     }
   }

3. (선택 사항) Roblox 계정에서 생성된 자산을 확인합니다.

   1. 로블록스 계정의 인벤토리 페이지로 이동합니다.
   2. 확인하려는 자산의 범주를 선택합니다.
   3. 대상 자산을 찾아 썸네일을 클릭하여 자산을 봅니다.

자산 API를 OAuth 2.0 앱에 추가

사용자가 로블록스에 자산을 업로드하고 업데이트할 수 있도록 자산 API를 지원하는 OAuth 2.0 애플리케이션을 생성할 수 있습니다.

애플리케이션에서 자산 API를 사용하고 사용자로부터 권한을 요청하려면 다음 설정을 수행하십시오:

1. 애플리케이션 등록 시 권한에서 asset:read 및 asset:write 범위를 선택합니다.

2. 사용자 인증 흐름 구현 시, 사용자를 애플리케이션으로 되돌리는 인증 URL의 범위 매개변수로 asset:read 및 asset:write를 포함합니다. 다음 예시와 같습니다:

   https://apis.roblox.com/oauth/v1/authorize?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

3. 요청을 보낼 때, 요청 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"'