Title Storage Interface

에픽 온라인 서비스(Epic Online Services, EOS) 를 사용하는 개발자는 타이틀 스토리지 인터페이스(Title Storage Interface) 를 통해 클라우드 서버에서 암호화된 데이터를 얻을 수 있습니다. 이 인터페이스를 통해 데이터를 저장하면 누구나 자신의 디바이스로 로그인하여 데이터에 액세스할 수 있습니다. 이 인터페이스는 플레이어 데이터 스토리지 인터페이스와 비슷하지만, 사용자별 데이터보다는 게임별 데이터를 처리하는 데 특화된 인터페이스이며, 사용자의 플랫폼, 지역 등의 조건에 따라 다른 파일 버전을 제공할 수 있습니다. 타이틀 스토리지 인터페이스와 플레이어 데이터 스토리지 인터페이스의 차이에 대한 자세한 정보는 이 문서 끝에 있는 플레이어 데이터 스토리지와의 차이 섹션을 참조하세요.

타이틀 스토리지 인터페이스에 액세스하려면 플랫폼 인터페이스 함수인 EOS_Platform_GetTitleStorageInterface 를 통해 EOS_HTitleStorage 핸들을 얻으세요. 모든 타이틀 스토리지 인터페이스 함수는 첫 번째 파라미터로 이 핸들이 필요합니다. 요청이 완료되었을 때 적절한 콜백을 트리거하려면 EOS_HPlatform 핸들의 틱이 실행 중인지 확인해야 합니다.

EOS의 파일명은 다음과 같은 형태입니다. 디렉터리0/디렉터리1/디렉터리N/파일명.확장자 '디렉터리' 및 '확장자' 부분은 선택 사항입니다. '/' 문자는 각 디렉터리명 다음에 나와야 하지만, 첫 번째 문자나 마지막 문자 등 다른 자리에 있으면 안 됩니다. 파일명에는 다음과 같은 문자를 사용할 수 있습니다.

• ASCII 영문자와 숫자
• !
• -
• _
• +
• .
• '
• (
• )

파일명은 EOS_TITLESTORAGE_FILENAME_MAX_LENGTH_BYTES (64)자 이하여야 합니다.

EOS SDK를 사용하면 몇 개의 쿼리 API 호출로 클라우드에 저장된 파일의 정보를 얻을 수 있습니다. 쿼리는 각 파일의 이름, 크기(바이트), MD5 해시 등 하나 이상의 파일에 대한 메타데이터를 반환합니다. 그러면 사용자는 자신만의 메타데이터 사본을 요청하고 관리할 수 있으며, 이 사본으로 파일들에 액세스하거나 파일들을 수정할 수 있습니다. 파일은 백엔드에 암호화된 형식으로 저장되므로, 파일 크기나 MD5 해시 같은 메타데이터는 개발자 포털을 통해 업로드한 원본 파일이 아니라 암호화된 파일을 반영합니다.

하나의 파일에 대한 정보만 필요하고 그 파일명을 안다면, 다음과 같이 초기화된 EOS_TitleStorage_QueryFileOptions 구조를 전달하여 EOS_TitleStorage_QueryFile 함수를 호출할 수 있습니다.

작업이 완료되면 EOS는 EOS_TitleStorage_QueryFileCallbackInfo 구조로 콜백( EOS_TitleStorage_OnQueryFileCompleteCallback 타입)을 실행합니다. 호출에 성공하면 EOS의 캐시에 파일 데이터가 생기게 됩니다.

한번에 여러 파일을 쿼리하거나 정확한 파일명을 모르는 상태로 파일을 쿼리하려면, 먼저 개발자 포털을 통해 파일에 태그부터 적용해야 합니다. 그러면 EOS SDK가 그 태그를 기반으로 쿼리할 수 있습니다. 파일 태그는 EOS 파일명과 같은 서식 규칙을 사용하는 스트링입니다. 이 방식으로 파일을 쿼리할 때는 하나 이상의 태그를 제공해야 합니다. 그러면 EOS SDK가 해당 태그를 하나 이상 포함하는 모든 파일 목록을 얻게 됩니다. 이렇게 하려면 다음과 같이 초기화된 EOS_TitleStorage_QueryFileListOptions 데이터 구조로 EOS_TitleStorage_QueryFileList 를 호출합니다.

완료되면 EOS는 EOS_TitleStorage_QueryFileListCallbackInfo 데이터 구조로 콜백 함수( EOS_TitleStorage_OnQueryFileListCompleteCallback 타입)를 실행합니다. 호출에 성공하면, 데이터 구조에 찾은 파일 수가 포함되며, 해당 파일의 정보는 EOS 캐시에서 확인할 수 있습니다.

타이틀 스토리지 인터페이스에서 모든 파일을 쿼리하는 특정 API 호출은 제공하지 않습니다. 하지만 업로드하는 파일 전부에 특정 태그를 적용하는 방법이 있습니다. 해당 태그와 함께 EOS_TitleStorage_QueryFileListOptions 를 사용하면 모든 파일의 데이터를 얻을 수 있습니다.

(#ExaminingCachedFileInformation)

EOS가 하나 이상의 파일에 대한 정보를 얻고 캐시하고 나면, 특정 파일의 정보를 얻기 위해 그 파일명으로 EOS_TitleStorage_CopyFileMetadataByFilename 을 호출하거나, 캐시 내에서 파일의 0부터 시작하는 인덱스로 EOS_TitleStorage_CopyFileMetadataAtIndex 를 호출하면 됩니다. 캐시에 있는 파일 수를 알아야 하는 경우, EOS_TitleStorage_GetFileMetadataCount 를 호출하면 됩니다. 이 정보의 사본이 더는 필요 없다면, EOS_TitleStorage_FileMetadata_Release 를 호출하여 사용하던 메모리를 해제합니다.

타이틀 스토리지 인터페이스는 클라우드에서 비동기식으로 파일을 읽는 기능을 지원합니다. 읽기는 스트리밍 작업이며, EOS는 스트리밍 진행상황을 확인하거나 스로틀하거나 중단하는 데 사용할 수 있는 핸들을 제공합니다.

파일 읽기

클라우드(또는 로컬 캐시)에서 이름이 알려진 파일을 읽으려면 EOS_TitleStorage_ReadFile 을 호출합니다. 다음과 같이 초기화된 EOS_TitleStorage_ReadFileOptions 를 전달해야 합니다.

이 함수는 전송 진행상황을 확인하거나 파일명을 얻거나 전송을 취소하는 데 사용할 수 있는 EOS_HTitleStorageFileTransferRequest 핸들을 반환합니다. 전송 중에 언제든지 EOS_TitleStorageFileTransferRequest_GetFileRequestState 를 호출하여 현재상태를 폴링하거나, EOS_TitleStorageFileTransferRequest_GetFilename 을 호출하여 전송 중인 파일명을 확인하거나, EOS_TitleStorageFileTransferRequest_CancelRequest 를 호출하여 (오류 생성 없이) 전송을 취소할 수 있습니다. 직접 전송을 폴링하는 것보다 EOS에서 업데이트를 받는 것을 선호하는 경우, FileTransferProgressCallback 파라미터로 전송 시작 시 유효한 EOS_TitleStorage_OnFileTransferProgressCallback 함수를 제공하면 EOS가 주기적으로 EOS_TitleStorage_FileTransferProgressCallbackInfo 파라미터로 이 함수를 호출하여 파일 전송 진행상황을 알려줍니다. 이 방식을 선택하면, 콜백 함수에 대한 호출을 최소 한 번은 꼭 받게 됩니다. 콜백 함수를 사용한다고 핸들 사용을 배제할 필요는 없습니다. 다만, 둘 다 매우 비슷한 용도로 사용되며, 둘 다 필요한 사례는 거의 없습니다.

파일 청크가 들어오면 ReadFileDataCallback ( EOS_TitleStorage_OnReadFileDataCallback 타입)이 EOS_TitleStorage_ReadFileDataCallbackInfo 타입의 파라미터로 실행됩니다. 이 구조에는 파일의 실제 데이터 청크가 포함되며, 이것이 마지막 청크인지 나타내는 변수도 포함됩니다. 또한 열거형 반환 타입인 EOS_TitleStorage_EReadResult 도 포함되는데, 이를 사용하여 EOS에 전송을 계속 진행하거나 오류 때문에 종료하거나 오류 보고 없이 취소하도록 지시할 수 있습니다.

파일 전송이 완료되면, EOS는 EOS_TitleStorage_ReadFileCallbackInfo 파라미터로 EOS_TitleStorage_OnReadFileCompleteCallback 콜백 함수를 실행합니다. 이 파라미터는 성공이나 실패를 나타내며, 파일명을 포함합니다.

EOS가 향후 읽기 작업을 더 빨리 수행하기 위해 로컬에 파일을 캐싱할 수도 있습니다. 이러한 파일은 EOS 플랫폼 초기화 때 제공한 키로 암호화됩니다. ReadFileDataCallback 함수에 전송된 데이터 청크는 암호화되지 않습니다.

다음 타임라인 다이어그램은 가상의 읽기 작업을 실행한 모습을 보여줍니다.

연속으로 여러 개의 파일을 다운로드하는 경우, 파일 목록을 먼저 쿼리하고 메타데이터를 캐시한 다음 다운로드하면 퍼포먼스를 개선할 수 있습니다. 이렇게 하면 여러 번 쿼리하지 않아도 되며, 파일 다운로드 간에 결과를 기다리지 않아도 됩니다.

(#DataCachingAndEncryption)

타이틀 스토리지 인터페이스는 파일 데이터와 메타데이터를 클라이언트 시스템의 CacheDirectory 폴더에 캐시합니다. EOS는 가능할 때마다 MD5 체크섬 테스트를 사용하여 클라우드에서 스트리밍하지 않고 대신 이 데이터를 사용하여 데이터 손상을 방지하고 로컬에 캐시된 파일이 클라우드에 있는 버전과 같은지 확인하는데, 그런 경우에는 읽기 작업을 한 번의 콜백 주기로 완료할 수 있습니다. 읽기 작업이 성공할 때마다 캐시가 업데이트됩니다. EOS는 종료 시 캐시를 삭제하지 않으므로 향후 세션에서 캐시된 파일을 재사용할 수 있습니다.

타이틀 스토리지 파일은 항상 EOS 플랫폼 초기화 때 제공한 키로 암호화되어 저장됩니다. 암호화 키 자체를 클라우드에 저장하지는 않습니다. 그 이유는 에픽게임즈와 악의적인 서드 파티가 해당 키로 데이터에 액세스하지 못하도록 하기 위해서입니다. 제품의 모든 사용자가 같은 암호화 키를 사용합니다.

기한이 지나거나 사용하지 않은 캐시 파일은 EOS가 주기적으로 자동 삭제하지만, 직접 EOS_TitleStorage_DeleteCache 함수를 호출하여 수동으로 캐시를 삭제할 수도 있습니다(예: 로컬 스토리지 공간이 매우 작은 경우). 다음과 같이 초기화된 EOS_TitleStorage_DeleteCacheOptions 를 전달해야 합니다.

게임 코드에 디폴트 파일을 관리할 수 있지만 이러한 파일의 대체 버전을 제공할 수도 있습니다. 예를 들어 각 게임 서버에는 사용할 자체 환경설정 파일이 있을 수 있습니다. 이러한 대체 파일은 개발자 포털을 통해 관리해야 합니다. 그러면 대체 파일 수신자를 지정하는 것을 포함하여 파일에 대한 설정을 구성할 수 있습니다. 타이틀 스토리지 인터페이스를 통해 파일을 쿼리하면 해당되는 경우 타이틀 스토리지 인터페이스에서 대체 파일을 반환합니다.

자세한 내용은 타이틀 스토리지 관리 문서를 참고하세요.

파일 복호화 툴을 사용하여 쉽고 편하게 새로운 파일을 생성하거나 타이틀 스토리지(Title Storage) 또는 플레이어 데이터 스토리지에 로드된 파일을 복호화할 수 있습니다.

타이틀 스토리지를 통해 개발자는 에픽 온라인 서비스(EOS)를 사용하여 클라우드 서버에서 게임별로 암호화된 데이터를 배포할 수 있습니다. 태그를 통해 데이터를 그룹화화여 플랫폼 전체의 모든 사용자에게 제공할 수 있습니다. 스로틀 조절, 사용 할당량, 모범 사례에 대한 일반적인 정보는 서비스 사용 제한을 참고하세요.

현재는 타이틀 스토리지에 대한 개별 파일 크기 제한이 없지만 다른 제한은 아래를 참조하세요.

타이틀 스토리지 인터페이스와 플레이어 데이터 스토리지 인터페이스 모두 클라우드 기반 데이터 파일을 처리하지만, 처리 방법과 목적이 다릅니다. 두 인터페이스의 주요 차이점은 다음과 같습니다.

1. 타이틀 스토리지 인터페이스는 개발자 포털을 통해 클라우드에 저장한 파일을 쿼리하고 다운로드만 가능하지만, 플레이어 데이터 스토리지 인터페이스는 이러한 파일을 생성하고 수정하고 삭제할 수도 있습니다.

2. 타이틀 스토리지 인터페이스는 제품별로 파일을 처리하며, 이러한 파일은 제품의 모든 사용자가 공통으로 사용합니다. 플레이어 데이터 스토리지 인터페이스는 사용자별로 작동하며, 파일은 다른 사용자에게 비공개됩니다.

3. 두 인터페이스는 서로 다른 방식으로 파일을 암호화합니다. 자세한 내용은 데이터 캐시 및 암호화 섹션을 참조하세요.

4. 타이틀 스토리지 인터페이스는 조건부 파일 오버라이드를 지원하므로 개발자는 조건에 따라 각기 다른 파일 버전을 제공할 수 있습니다. 자세한 내용은 파일 오버라이드 섹션을 참조하세요.

5. 타이틀 스토리지 인터페이스를 통해 파일을 쿼리하면 태그 시스템을 활용하여 관련 파일을 그룹으로 묶을 수 있습니다.

6. 타이틀 스토리지 인터페이스는 파일을 업로드하지 않으므로 사용자 스로틀이 발생할 염려는 없습니다.