타이틀 스토리지 인터페이스

클라우드의 모든 플레이어가 공유하는 암호화된 데이터를 다운로드하는 인터페이스

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

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

이 인터페이스를 사용하려면 다음의 추가 파라미터를 사용하여 EOS 플랫폼을 초기화해야 합니다.

  • const char* EncryptionKey: 이 64자의 16진수 스트링은 EOS에서 사용자 데이터를 암호화하는 데 사용할 256비트 키를 빌드합니다. 에픽의 백엔드 서버는 이 키를 저장하지 않습니다. 키가 없으면 타이틀 스토리지 인터페이스의 파일 관리 함수 호출이 실패하고 'EOS_TitleStorage_EncryptionKeyNotSet' 오류 코드가 반환됩니다.

  • const char* CacheDirectory: 데이터 파일 전송 시 인터페이스에서 임시 스토리지로 사용할 로컬 디렉터리의 전체 경로입니다. 이 위치는 어디든 가능한데 일반적으로는 시스템의 임시 디렉터리나 게임의 데이터 디렉터리가 주로 사용됩니다. 지정한 디렉터리가 없으면, EOS에서 디렉터리를 직접 만듭니다. 여러 사용자 및 제품에 같은 디렉터리를 사용할 수 있으며, EOS에서 서로 충돌하지 않도록 합니다. 디렉터리에 문제가 있으면, 파일 관리 함수 호출이 실패하며 'EOS_CacheDirectoryMissing' 또는 'EOS_CacheDirectoryInvalid' 오류 코드가 반환됩니다. 플랫폼별 폴더 사용 제한은 EOS 플랫폼 문서에서 확인할 수 있습니다.

파일 관리

파일명 형식

[INCLUDE:GameServices/PlayerDataStorage#FileNameFormat]

파일명은 'EOS_TITLESTORAGE_FILENAME_MAX_LENGTH_BYTES'(64)자를 초과할 수 없습니다.

파일 쿼리하기

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

쿼리의 콜백 함수 처리 기간 동안 캐시에서 필요할 수 있는 정보를 복사해야 합니다. 이 데이터의 수명은 콜백 함수 기간보다 더 오래 지속될 것이라고 보장되지 않습니다. 이는 여러 개의 쿼리를 실행할 때 특히 중요합니다. 각 쿼리가 성공할 때마다 캐시의 콘텐츠가 변경될 수 있기 때문입니다.

대부분의 함수에는 추적이 더 용이하도록 제품 사용자 ID 파라미터 옵션이 포함되어 있습니다. 제품 사용자 ID 없이 nullptr을 전달하는 방법으로 데이터를 쿼리할 수 있지만, 개발자 포털에서 설정한 사용자 ID 오버라이드를 사용할 수 없게 됩니다. 콜백에는 전달한 동일 사용자 제품 ID 값이 포함됩니다.

단일 파일 쿼리하기

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

프로퍼티

ApiVersion

EOS_TITLESTORAGE_QUERYFILEOPTIONS_API_LATEST

LocalUserId

(옵션) 파일 데이터를 요청하는 로컬 사용자의 EOS_ProductUserId

Filename

쿼리하는 파일의 이름

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

태그로 여러 파일 쿼리하기

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

프로퍼티

ApiVersion

EOS_TITLESTORAGE_QUERYFILELISTOPTIONS_API_LATEST

LocalUserId

(옵션) 파일 데이터를 요청하는 로컬 사용자의 EOS_ProductUserId

NumTags

태그 목록의 태그 수(양수여야 함)

ListOfTags

파일 쿼리에 사용하는 태그의 배열(ASCII 스트링)

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

모든 파일 쿼리하기

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

캐시된 파일 정보 조사하기

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

EOS에 단일 파일에 대한 정보를 쿼리한 후에, EOS_TitleStorage_GetFileMetadataCount`가 캐시에 여러 개의 파일이 있다고 알릴 수도 있습니다. 이는 캐시에 이전 쿼리 결과가 남아있으면 발생할 수 있습니다. 이 경우에 가장 좋은 방법은 EOS_TitleStorage_QueryFileCallbackInfo 내의 ResultCode`가 EOS_Success`인지 확인하고 EOS_TitleStorage_CopyFileMetadataByFilename`을 호출하여 그 정보에 액세스하는 것입니다. 여러 파일 쿼리에 성공하면 전에 캐시된 메타데이터가 제거됩니다.

파일에 액세스하기

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

파일 읽기

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

프로퍼티

ApiVersion

EOS_TITLESTORAGE_READFILEOPTIONS_API_LATEST

LocalUserId

(옵션) 요청된 파일을 읽을 로컬 사용자의 계정 ID

Filename

읽을 파일명

ReadChunkLengthBytes

하나의 EOS_TitleStorage_OnReadFileDataCallback 호출에서 읽을 최대 데이터 양

ReadFileDataCallback

들어오는 대로 데이터를 처리하고 전송을 조기에 중지할 수 있는 콜백 함수

FileTransferProgressCallback

선택적인 콜백 함수로, 전송 진행 상황을 알려주며, 설정하면 최소 한 번은 호출됨

이 함수는 전송 진행 상황을 확인하거나 파일명을 얻거나 전송을 취소하는 데 사용할 수 있는 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 함수에 전송된 데이터 청크는 암호화되지 않습니다.

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

ReadOperationDiagram.png

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

데이터 캐시 및 암호화

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

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

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

프로퍼티

ApiVersion

EOS_TITLESTORAGE_DELETECACHEOPTIONS_API_LATEST

LocalUserId

로컬 사용자의 계정 ID

이 함수는 대부분의 경우 필요 없습니다. 캐시를 삭제하면 시스템의 다운로드 횟수가 증가할 수 있으며, 게임과 백엔드 서비스 퍼포먼스가 둘 다 저하될 수 있습니다.

파일 오버라이드

일부 경우에는 조건에 따라 파일을 여러 가지 버전으로 제공하는 것이 좋습니다. 예를 들어, 게임 서버가 다르면 구성 설정도 달라질 수 있습니다. 타이틀 스토리지 레벨에서 특정 파일명에 대한 요청을 대체 파일로 리디렉션할 수 있습니다. 이렇게 하려면 개발자 포털을 이용하여 파일 구조를 설정해야 합니다. 백엔드 서비스는 들어오는 쿼리에 따라 반환할 파일을 정합니다. 이렇게 설정하면 최종 결과로 개발자가 애플리케이션 안에서부터 EOS SDK를 통해 단일 파일명을 요청할 수 있지만, 백엔드 시스템의 기준에 따라 다른 파일 데이터를 받게 될 수 있습니다. 오버라이드 설정에 대한 자세한 내용은 [타이틀 스토리지 개발자 포털 경험]을 참조하세요.

사용 제한

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

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

기능

서비스 제한

폴더 크기 제한

10GB

최대 파일 수

100

플레이어 데이터 스토리지와의 차이

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

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

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

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

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

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

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

암호화/암호화 해제 명령줄 툴

파일 암호화 해제 툴(File Decryption Tool)은 쉽고 편리하게 새 파일을 생성하거나 타이틀 스토리지에 로드된 파일의 암호화를 해제하게 해주는 개발자용 명령줄 툴입니다. 파일의 암호화를 해제하려면 암호화 키와 타이틀 스토리지에서 가져온 암호화된 파일 사본이 필요합니다. 파일을 암호화하려면 동일한 키와 아직 암호화되지 않은 암호화할 파일이 필요합니다.

타이틀 스토리지 인터페이스는 로컬 캐시를 유지하므로, 그 캐시에서 암호화된 파일을 복사하고 암호화 해제할 수 있습니다.

SDK 배포에서 `FileDecryptionTool`을 찾은 다음, 명령줄에서 실행합니다. 이 툴은 단일 파일 모드와 디렉터리 모드를 지원합니다. 단일 파일 모드는 단일 입력 파일을 암호화하거나 암호화 해제한 다음, 그 결과를 다른 파일에 출력합니다. 디렉터리 모드는 타깃 디렉터리와 그 하위 디렉터리의 모든 파일을 살펴보고 다른 위치의 복제 디렉터리 구조에 출력 파일을 배치합니다.

이 툴이 지원하는 기본 파일 타입은 플레이어 데이터 스토리지 파일이므로, 타이틀 스토리지 모드를 활성화하려면 '-mode title' 파라미터를 사용해야 합니다. 타이틀 스토리지 모드에서 툴이 플레이어 데이터 스토리지 파일을 발견하거나, 플레이어 데이터 스토리지 모드에서 타이틀 스토리지 파일을 발견하면, 해당 파일을 건너뛰고 오류를 보고합니다.

파라미터 목록

파라미터

효과

-input(위치)

읽을 암호화된 데이터가 포함된 파일이나 폴더의 경로 설정

-output(위치)

암호화 해제된 데이터가 기록될 파일이나 폴더 경로 설정

-key(암호화 키)

암호화 및 암호화 해제 작업에 사용할 암호화 키 설정, 키는 16진수 64자 이하여야 함

-mode(타이틀 스토리지 또는 플레이어 데이터 스토리지 모드의 사용자 또는 타이틀)

타이틀 스토리지 또는 플레이어 데이터 스토리지 모드 활성화(기본값은 플레이어 데이터 스토리지 모드)

-Encrypt

암호화 모드 활성화, 즉 출력 파일이 입력 파일의 암호화된 사본이 됨, 이 파라미터를 설정하지 않으면 출력 파일은 입력 파일의 암호화 해제된 사본이 됨

툴은 입력 파일의 데이터 형식을 알지 못하므로 잘못된 암호화 키를 제공하더라도 오류가 나타나지 않습니다. 다만 키가 맞지 않기 때문에 애플리케이션에서 출력 파일을 사용할 수 없습니다.

샘플 명령줄

FileDecryptionTool -input encrypted_ts_data -output unencrypted_ts_data -key 123abcdef -mode title

FileDecryptionTool -input raw_ts_data_file -output encrypted_ts_data_file -key 123abcdef -encrypt -mode title