자산 사용 가이드

Open Cloud의 자산 API는 자산을 스튜디오에 수동으로 가져오는 대신 단일 HTTP 요청으로 업로드하고 업데이트할 수 있도록 합니다. 이 API는 다음을 지원합니다:

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

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

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

보안 권한

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

API 키

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

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

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

API 키를 얻은 후, 이를 x-api-key 요청 헤더에 복사합니다. 모든 엔드포인트는 x-api-key 요청 헤더가 필요합니다.

--header 'x-api-key: ${ApiKey}' \

OAuth 2.0 앱

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

새로운 자산 생성

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

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

2. 요청에서:

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

      • 자신의 이름으로 자산을 생성하려면 사용자 ID를 추가합니다. 사용자 ID는 Roblox 프로필의 URL에서 찾을 수 있습니다. 예를 들어, https://www.roblox.com/users/1234567/profile,의 경우 사용자 ID는 1234567`입니다.
      • 그룹 자산으로 자산을 생성하려면 그룹의 그룹 ID를 추가합니다. 그룹 ID는 그룹 페이지의 URL에서 찾을 수 있습니다. 예를 들어, 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가 반환됩니다. 이를 사용하여 다음 단계로 업로드 상태와 결과를 확인할 수 있습니다:

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

   작업 조회 요청 예제

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

2. 요청이 성공하면 Operation 객체가 반환되며, 업로드된 자산 정보 또는 자산 업로드 실패 이유를 설명하는 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. Roblox 계정의 인벤토리 페이지로 이동합니다.
   2. 확인하려는 자산의 카테고리를 선택합니다.
   3. 대상 자산을 찾아 썸네일을 클릭하여 자산을 확인합니다.

자산 API를 OAuth 2.0 앱에 추가

사용자가 Roblox에 자산을 업로드하고 업데이트할 수 있도록 지원하는 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"'