Title Storage Interface

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

21 분 소요

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

타이틀 스토리지 인터페이스에 액세스하려면 플랫폼 인터페이스 함수인 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 플랫폼 문서에서 확인할 수 있습니다.

파일 관리

파일명 형식

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

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

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

파일 쿼리하기

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

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

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

단일 파일 쿼리하기

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

프로퍼티
ApiVersionEOS_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 를 호출합니다.

프로퍼티
ApiVersionEOS_TITLESTORAGE_QUERYFILELISTOPTIONS_API_LATEST
LocalUserId(선택 사항) 파일 데이터를 요청하는 로컬 사용자의 EOS_ProductUserId
NumTags태그 목록의 태그 수(양수여야 함)
ListOfTags파일 쿼리에 사용하는 태그의 배열(ASCII 스트링)

완료되면 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_GetFileMetadataCount 가 캐시에 여러 개의 파일이 있다고 알릴 수도 있습니다. 이러한 일은 캐시에 이전 쿼리 결과가 남아있으면 발생할 수 있습니다. 이 경우에 가장 좋은 방법은 EOS_TitleStorage_QueryFileCallbackInfo 내의 ResultCodeEOS_Success 인지 확인하고 EOS_TitleStorage_CopyFileMetadataByFilename 을 호출하여 그 정보에 액세스하는 것입니다. 여러 파일 쿼리에 성공하면 전에 캐시된 메타데이터가 제거됩니다.

파일에 액세스하기

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

파일 읽기

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

프로퍼티
ApiVersionEOS_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 함수에 전송된 데이터 청크는 암호화되지 않습니다.

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

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

(#DataCachingAndEncryption)

데이터 캐시 및 암호화

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

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

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

프로퍼티
ApiVersionEOS_TITLESTORAGE_DELETECACHEOPTIONS_API_LATEST
LocalUserId로컬 사용자의 계정 ID

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

파일 오버라이드

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

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

파일 복호화 툴

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

사용 제한

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

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

기능서비스 제한
폴더 크기 제한10GB
최대 파일 수100

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

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

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

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

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

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

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

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