Player Data Storage Interface

클라우드 기반 데이터 관리를 처리하는 인터페이스

14 분 소요

플레이어 데이터 저장 인터페이스(Player Data Storage Interface) 는 개발자가 에픽 온라인 서비스(EOS) 를 사용하여 암호화된 사용자별, 게임별 데이터를 클라우드 서버에 저장할 수 있도록 지원합니다. 이 인터페이스를 통해 저장한 데이터는 사용자가 로그인 가능한 모든 디바이스에서 액세스할 수 있습니다. 플레이어 데이터 저장 인터페이스는 모든 파일 형식을 지원합니다. 일반적인 사용 사례로는 저장된 게임이나 리플레이 데이터 등이 있습니다.

플레이어 데이터 저장 인터페이스에 액세스하려면 플랫폼 인터페이스 함수 EOS_Platform_GetPlayerDataStorageInterface 를 통해 EOS_HPlayerDataStorage 핸들을 얻어야 합니다. 모든 플레이어 데이터 저장 인터페이스 함수는 첫 파라미터로 이 핸들을 요청합니다. EOS_HPlatform 핸들이 콜백에 티킹하여 요청이 완료됐을 때 트리거하는지 확인해야 합니다.

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

  • const char* EncryptionKey : 이 64자 16진법 스트링은 EOS가 사용자 데이터를 암호화하기 위해 사용하는 256비트 키를 빌드합니다. 에픽의 백엔드 서버는 이 키를 저장하지 않습니다. 키가 없는 경우, 플레이어 데이터 저장 인터페이스의 파일 관리 함수 호출이 실패하고 EOS_PlayerDataStorage_EncryptionKeyNotSet 오류 코드를 반환합니다.

  • const char* CacheDirectory : 이 파라미터는 인터페이스가 데이터 파일 전송 도중 임시 스토리지로 사용할 로컬 디렉터리의 전체 경로입니다. 어떤 위치든 될 수 있으며 보통 시스템의 임시 디렉터리 또는 게임 데이터 디렉터리가 선택됩니다. 지정한 디렉터리가 존재하지 않는 경우 EOS가 생성을 시도합니다. 여러 사용자와 제품에 대해 동일한 디렉터리를 사용할 수 있으며 EOS가 충돌이 발생하지 않도록 합니다. 디렉터리에 문제가 있는 경우, 파일 관리 함수 호출이 실패하고 EOS_CacheDirectoryMissing 또는 EOS_CacheDirectoryInvalid 오류 코드를 반환합니다. 플랫폼별 폴더 사용 제한은 플랫폼에서의 EOS 활용에서 확인할 수 있습니다.

파일 관리

파일 이름 포맷

파일 이름은 EOS_PLAYERDATASTORAGE_FILENAME_MAX_LENGTH_BYTES 에 따라 64자를 초과할 수 없습니다.

파일 쿼리

EOS에 쿼리하여 클라우드에 저장된 하나 또는 모든 파일에 대한 정보를 얻을 수 있습니다. 모든 쿼리 타입은 발견한 파일의 이름, 데이터 크기(바이트, 암호화되지 않음), MD5 해시 등의 메타데이터를 반환합니다. 그런 다음 파일에 액세스하거나 파일을 수정하기에 앞서 이 정보의 사본을 캐시할 수 있습니다. 파일은 백엔드에 암호화된 형식으로 저장되며, 파일 크기, 해시와 같은 일부 메타데이터가 암호화된 파일에 제공됩니다. 메타데이터는 API에 전달하는 파일에 해당하는 값과 정확하게 일치하지 않습니다.

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

모든 파일 쿼리

모든 파일의 정보를 얻으려면 EOS_PlayerDataStorage_QueryFileListOptions 데이터 구조체를 다음과 같이 초기화하여 EOS_PlayerDataStorage_QueryFileList 를 호출합니다.

프로퍼티
ApiVersionEOS_PLAYERDATASTORAGE_QUERYFILELISTOPTIONS_API_LATEST
LocalUserId파일 데이터를 요청하고 있는 로컬 사용자의 EOS_ProductUserId

완료되면 EOS가 EOS_PlayerDataStorage_QueryFileListCallbackInfo 데이터 구조체로 콜백 함수(EOS_PlayerDataStorage_OnQueryFileListCompleteCallback 타입)를 실행합니다. 호출이 성공하면 발견된 파일 수가 데이터 구조체에 포함되며 해당 파일에 대한 정보를 EOS 캐시에서 사용할 수 있습니다.

단일 파일 쿼리

파일 하나에 대한 정보만 필요하고 해당 파일의 이름을 아는 경우에는 다음과 같이 초기화된 EOS_PlayerDataStorage_QueryFileOptions 구조체에서 EOS_PlayerDataStorage_QueryFile 함수를 호출할 수 있습니다.

프로퍼티
ApiVersionEOS_PLAYERDATASTORAGE_QUERYFILEOPTIONS_API_LATEST
LocalUserId파일 데이터를 요청하고 있는 로컬 사용자의 EOS_ProductUserId
Filename쿼리하는 파일의 이름

작업이 완료되면 EOS가 EOS_PlayerDataStorage_QueryFileCallbackInfo 데이터 구조체로 콜백 함수(EOS_PlayerDataStorage_OnQueryFileCompleteCallback 타입)를 실행합니다. 호출에 성공하면 EOS는 파일에 대한 데이터를 캐시로 가져옵니다.

캐시된 파일 정보 검토

EOS가 하나 이상의 파일에 대한 정보를 얻고 캐시한 뒤에는 파일 이름으로 EOS_PlayerDataStorage_CopyFileMetadataByFilename 을 호출하거나 캐시 내 파일의 제로 기반 인덱스로 EOS_PlayerDataStorage_CopyFileMetadataAtIndex 를 호출하여 특정 파일에 대한 정보를 얻을 수 있습니다. 캐시에 파일이 몇 개인지 알고 싶은 경우에는 EOS_PlayerDataStorage_GetFileMetadataCount 를 호출합니다. 이 정보의 사본이 더 이상 필요하지 않은 경우에는 EOS_PlayerDataStorage_FileMetadata_Release 를 호출하여 사본이 사용하던 메모리를 해제합니다.

단일 파일에 대한 정보를 EOS에서 쿼리한 이후 EOS_PlayerDataStorage_GetFileMetadataCount 를 통해 캐시에 여러 파일이 있다는 사실이 확인될 수도 있습니다. 이러한 상황은 이전 쿼리의 결과가 캐시에 남아 있는 경우에 발생합니다. 이와 같은 경우에는 EOS_PlayerDataStorage_QueryFileCallbackInfoResultCodeEOS_Success 인지 점검하고 EOS_PlayerDataStorage_CopyFileMetadataByFilename 을 호출하여 이 정보에 액세스하는 것이 가장 좋습니다.

파일 메타데이터 구조는 다음과 같습니다.

프로퍼티
ApiVersionEOS_PLAYERDATASTORAGE_FILEMETADATA_API_LATEST
FileSizeBytes파일의 바이트 단위 총 크기(암호화된 형식, 예상보다 약간 클 수 있음)
MD5Hash전체 파일의 니블 단위 MD5 해시(암호화된 파일의 해시)
Filename파일의 이름
LastModifiedTime파일이 마지막으로 저장된 날짜와 시간. 타임 스탬프는 POSIX/Unix 형식(에포크 시간)입니다.
UnencryptedDataSizeBytes총 데이터 크기(페이로드, 바이트 단위, 암호화되지 않은 원래 형식)

파일 액세스 및 수정

EOS는 비동기 클라우드에서 파일 읽기, 쓰기, 삭제를 지원합니다. 읽기와 쓰기는 스트리밍 작업이며, EOS는 게임이 스트리밍 진행 상황을 확인하거나 스로틀링하거나 중단하는 데 사용할 수 있는 핸들을 제공합니다.

파일 읽기

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

프로퍼티
ApiVersionEOS_PLAYERDATASTORAGE_READFILEOPTIONS_API_LATEST
LocalUserId요청된 파일을 읽을 로컬 사용자의 계정 ID
Filename읽을 파일 이름
ReadChunkLengthBytes단일 EOS_PlayerDataStorage_OnReadFileDataCallback 호출에서 읽을 데이터의 최대 용량
ReadFileDataCallback데이터가 들어오는 대로 처리하고 전송을 조기에 중단할 수 있는 콜백 함수
FileTransferProgressCallback전송 진행 상황을 알려줄 선택적 콜백 함수(설정하면 최소 1회 호출됨)

이 함수는 전송 진행 상황을 점검하고 파일 이름을 얻거나 전송을 취소할 때 사용 가능한 EOS_HPlayerDataStorageFileTransferRequest 핸들을 반환합니다. 전송 도중 아무 때나 EOS_PlayerDataStorageFileTransferRequest_GetFileRequestState 를 호출하여 현재 상황을 조사하거나, EOS_PlayerDataStorageFileTransferRequest_GetFilename 을 호출하여 전송 중인 파일 이름을 확인하거나, EOS_PlayerDataStorageFileTransferRequest_CancelRequest 를 호출하여 오류 생성 없이 전송을 취소합니다. 전송을 직접 조사하기보다 EOS의 업데이트를 받는 것을 선호하는 경우, 전송을 시작할 때 유효한 EOS_PlayerDataStorage_OnFileTransferProgressCallback 함수와 FileTransferProgressCallback 파라미터를 입력합니다. 그러면 EOS가 이를 EOS_PlayerDataStorage_FileTransferProgressCallbackInfo 파라미터로 호출하여 주기적으로 파일 전송 진행 상황을 알립니다. 이 방법을 선택하면 콜백 함수에 대해 최소 한 번의 호출을 받을 수 있습니다. 콜백 함수를 사용해도 핸들 사용에는 아무런 지장이 없지만 이 둘은 매우 비슷한 목적을 수행하므로 대부분의 사용 사례에서는 함께 사용할 필요가 없습니다.

파일 청크가 나타나면 ReadFileDataCallback(EOS_PlayerDataStorage_OnReadFileDataCallback 타입)이 타입 EOS_PlayerDataStorage_ReadFileDataCallbackInfo 파라미터로 실행됩니다. 이 구조체는 파일의 실제 데이터 청크와 해당 청크가 최종인지 아닌지를 나타내는 변수를 포함합니다. 또한 EOS에 전송을 계속하거나, 오류로 종료하거나, 오류 보고 없이 취소하도록 명령할 때 사용할 수 있는 열거 반환 타입 EOS_PlayerDataStorage_EReadResult 를 갖습니다.

ReadFileDataCallback 은 메인 SDK 스레드(SDK 티킹에 사용하는 스레드)에서만, 틱당 1회만 호출됩니다. 따라서 ReadChunkLengthBytes 값을 정확하게 설정하는 것이 중요합니다. 청크 크기를 너무 작은 값으로 설정하면 사용자의 읽기 퍼포먼스가 떨어집니다. 4096을 여러 개 사용할 것을 권장합니다. 일반적으로 시스템의 메모리 페이지 크기에 해당하는 값이기 때문입니다. ReadChunkLengthBytes 에 SDK 틱 빈도를 곱하여 최대 읽기 속도를 추정할 수 있습니다. 예: 4096 * 30은 초당 120kb입니다. 반면에 청크 크기를 너무 큰 값으로 설정하면 SDK가 내부적으로 더 많은 메모리를 할당하게 됩니다. 적당한 공간을 남기기 위해서는 필요 조건에 가장 적합한 값을 선택해야 합니다.

파일 전송이 완료되면 EOS가 EOS_PlayerDataStorage_ReadFileCallbackInfo 파라미터로 EOS_PlayerDataStorage_OnReadFileCompleteCallback 콜백 함수를 실행합니다. 이 파라미터는 성공 또는 실패를 표시하며 파일 이름을 포함합니다.

EOS는 이후 읽기 작업의 속도를 높이기 위해 파일을 로컬로 캐시할 수 있습니다. 이러한 파일은 EOS 플랫폼 초기화 때 제공한 키로 암호화됩니다. ReadFileDataCallback 함수로 전송된 데이터 청크는 암호화되지 않습니다.

다음 타임라인 다이어그램은 작동 중인 읽기 작업의 예시입니다.

파일 쓰기

알고 있는 이름으로 파일을 쓰려면 EOS_PlayerDataStorage_WriteFile 을 호출합니다. 다음과 같이 초기화된 EOS_PlayerDataStorage_WriteFileOptions 를 전달해야 합니다.

프로퍼티
ApiVersionEOS_PLAYERDATASTORAGE_WRITEFILEOPTIONS_API_LATEST
LocalUserId파일을 클라우드에 쓸 로컬 사용자의 계정 ID
Filename쓸 파일 이름
ChunkLengthBytes단일 틱에서 쓸 데이터의 최대 용량
WriteFileDataCallback데이터 청크를 EOS에 제공하는 콜백 함수
FileTransferProgressCallback전송 진행 상황을 알려줄 선택적 콜백 함수(EOS_PlayerDataStorage_OnFileTransferProgressCallback 타입, 설정하면 최소 1회 호출됨)

이 함수는 전송 진행 상황을 점검하고 파일 이름을 얻거나 전송을 취소할 때 사용 가능한 EOS_HPlayerDataStorageFileTransferRequest 핸들을 반환합니다. 전송 도중 아무 때나 EOS_PlayerDataStorageFileTransferRequest_GetFileRequestState 를 호출하여 현재 상황을 조사하거나, EOS_PlayerDataStorageFileTransferRequest_GetFilename 을 호출하여 전송 중인 파일 이름을 확인하거나, EOS_PlayerDataStorageFileTransferRequest_CancelRequest 를 호출하여 오류 생성 없이 전송을 취소합니다. 전송을 직접 조사하기보다 EOS의 업데이트를 받는 것을 선호하는 경우, 전송을 시작할 때 유효한 EOS_PlayerDataStorage_OnFileTransferProgressCallback 함수와 FileTransferProgressCallback 파라미터를 입력합니다. 그러면 EOS가 이를 EOS_PlayerDataStorage_FileTransferProgressCallbackInfo 파라미터로 호출하여 주기적으로 파일 전송 진행 상황을 알립니다. 이 방법을 선택하면 콜백 함수에 대해 최소 한 번의 호출을 받을 수 있습니다. 콜백 함수를 사용해도 핸들 사용에는 아무런 지장이 없지만 이 둘은 매우 비슷한 목적을 수행하므로 대부분의 사용 사례에서는 함께 사용할 필요가 없습니다.

EOS가 클라우드로 다음 파일 청크를 보내려 할 때 WriteFileDataCallback (EOS_PlayerDataStorage_OnWriteFileDataCallback 타입)이 EOS_PlayerDataStorage_WriteFileDataCallbackInfo 타입 파라미터로 실행됩니다. 송신 데이터에 대한 버퍼 포인터 void 및 해당 데이터 크기를 나타내는 포인터 uint32_t 도 포함됩니다. EOS_PlayerDataStorage_WriteFileDataCallbackInfo 에는 버퍼에 넣을 수 있는 최대 바이트 수를 나타내는 DataBufferLengthBytes 변수가 있습니다. 이 콜백 함수는 또한 EOS에 전송을 계속하거나, 성공적인 완료 또는 오류로 종료하거나, 오류 보고 없이 취소하도록 명령할 때 사용할 수 있는 열거 반환 타입 EOS_PlayerDataStorage_EWriteResult 를 갖습니다.

WriteFileDataCallback 은 메인 SDK 스레드(SDK 티킹에 사용하는 스레드)에서만, 틱당 1회만 호출됩니다. 따라서 ChunkLengthBytes 값을 정확하게 설정하는 것이 중요합니다. 청크 크기를 너무 작은 값으로 설정하면 사용자의 쓰기 퍼포먼스가 떨어집니다. 4096을 여러 개 사용할 것을 권장합니다. 일반적으로 시스템의 메모리 페이지 크기에 해당하는 값이기 때문입니다. ChunkLengthBytes 에 SDK 틱 빈도를 곱하여 최대 쓰기 속도를 추정할 수 있습니다. 예: 4096 * 30은 초당 120kb입니다. 반면에 청크 크기를 너무 큰 값으로 설정하면 SDK가 내부적으로 더 많은 메모리를 할당하게 됩니다. 적당한 공간을 남기기 위해서는 필요 조건에 가장 적합한 값을 선택해야 합니다.

파일 전송이 완료되면 EOS가 EOS_PlayerDataStorage_WriteFileCallbackInfo 파라미터로 EOS_PlayerDataStorage_OnWriteFileCompleteCallback 콜백 함수를 실행합니다. 이 파라미터는 성공 또는 실패를 표시하며 파일 이름을 포함합니다. 데이터 손실을 피하려면 사용자가 게임 또는 콘솔을 종료하기 전에 이 콜백이 실행되도록 합니다.

파일 복사

파일의 전체 데이터 콘텐츠를 수동으로 읽고 쓰지 않고도 파일을 복사할 수 있습니다. 다음 값이 들어 있는 EOS_PlayerDataStorage_DuplicateFileOptionsEOS_PlayerDataStorage_DuplicateFile 을 호출합니다.

프로퍼티
ApiVersionEOS_PLAYERDATASTORAGE_DUPLICATEFILEOPTIONS_API_LATEST
LocalUserId작업에 권한을 부여하는 로컬 사용자의 계정 ID(반드시 원본 파일 오너여야 함)
SourceFilename복사할 기존 파일 이름
DestinationFilename복제된 파일에 사용할 이름

완료되면 EOS가 EOS_PlayerDataStorage_DuplicateFileCallbackInfo 파라미터로 EOS_PlayerDataStorage_OnDuplicateFileCompleteCallback 함수를 실행합니다. 다음과 같은 경우 파일 복제가 실패합니다.

  • 원본 파일이 존재하지 않습니다.
  • 사용자가 원본 파일을 가지고 있지 않습니다.
  • 사용자의 스토리지 공간이 부족합니다.

DestinationFilename 이 이미 존재하는 파일을 식별할 경우 해당 파일은 사본으로 대체됩니다.

파일 삭제

다음과 같이 초기화된 EOS_PlayerDataStorage_DeleteFileOptionsEOS_PlayerDataStorage_DeleteFileOptions 를 호출하여 파일을 삭제할 수 있습니다.

프로퍼티
ApiVersionEOS_PLAYERDATASTORAGE_DELETEFILEOPTIONS_API_LATEST
LocalUserId파일 삭제 권한을 부여하는 로컬 사용자의 계정 ID(반드시 원본 파일 오너여야 함)
Filename삭제할 파일 이름

완료되면 EOS가 콜백 함수(EOS_PlayerDataStorage_OnDeleteFileCompleteCallback 타입)를 실행하고 EOS_PlayerDataStorage_DeleteFileCallbackInfo 타입의 파라미터를 전달합니다. 사용자가 파일을 소유하고 있지 않은 경우 파일 삭제 작업을 실행할 수 없습니다.

데이터 캐싱 및 암호화

플레이어 데이터 저장 인터페이스는 파일 데이터 및 메타데이터를 클라이언트 시스템의 'CacheDirectory' 폴더에 캐시합니다. EOS는 가능한 경우 읽기 및 쓰기 작업에 대해 클라우드에서 스트리밍하는 대신 이 데이터를 사용하며, MD5 체크섬 테스팅을 통해 데이터 오염을 방지하고 로컬에 캐시된 파일이 클라우드에 있는 버전과 동일한지 확인합니다. 읽기 및 쓰기 작업은 이를 단일 콜백 주기에서 완료할 수 있습니다. 읽기 또는 쓰기 작업이 성공하면 캐시가 업데이트되며, 삭제 작업이 성공하면 캐시 파일 및 메타데이터가 제거됩니다. EOS는 셧다운 시에 캐시를 지우지 않기 때문에 캐시된 파일을 다음 세션에서도 사용할 수 있습니다.

플레이어 데이터 저장 파일은 EOS 플랫폼 초기화 때 제공한 키로 항상 암호화되어 저장됩니다. 암호화 키 자체는 클라우드에 저장되지 않으므로 에픽게임즈는 사용자 데이터에 액세스하는 키를 사용할 수 없습니다.

파일 암호 해독 툴

파일 암호 해독 툴(Decryption Tool) 을 사용하여 쉽고 편하게 새 파일을 생성하거나 타이틀 스토리지(Title Storage) 또는 플레이어 데이터 저장(Player Data Storage) 에 로드된 파일의 암호 해독을 수행할 수 있습니다.

사용 제한

플레이어 데이터 저장 인터페이스를 통해 EOS를 사용하는 개발자는 암호화된 사용자별 및 게임별 데이터를 클라우드 서버에 저장할 수 있습니다. 이 인터페이스를 통해 저장한 데이터는 사용자가 로그인 가능한 모든 디바이스에서 액세스할 수 있습니다. 플레이어 데이터 저장 인터페이스는 모든 파일 형식을 지원합니다. 일반적인 사용 사례로는 저장된 게임이나 리플레이 데이터 등이 있습니다.

이 서비스는 스토리지 용량과 사용률에 제한을 적용합니다. 스로틀링은 사용률을 제한하며, 서비스는 스토리지 공간을 제한하기 위해 파일을 삭제할 수 있습니다. 스로틀링, 사용 할당량, 모범 사례에 대한 일반적인 정보는 서비스 사용 제한을 참고하세요.

사용 타입제한
읽기 또는 쓰기분당 요청 1,000건
최대 개별 파일 크기(아래 참고 사항 참조)200MB
자동 삭제 파일 크기400MB
사용자당 총 스토리지 공간400MB
사용자당 최대 파일1,000개

사용자가 각 스토리지 공간 한도를 초과하는 파일을 업로드하려는 경우 EOS_PlayerDataStorage_WriteFile 호출이 실패하며 EOS_Result_PlayerDataStorageFileSizeTooLarge가 반환됩니다. 사용자의 스토리지가 꽉 차면 EOS_PlayerDataStorage_WriteFile에 대한 추가 호출이 실패하고 EOS_Result_PlayerDataStorageUserThrottled가 반환되어 사용자 스토리지가 스로틀 상태임을 알립니다. 사용자 스토리지는 공간 활용이 한도를 넘지 않도록 파일이 충분히 제거될 때까지 스로틀 상태로 유지됩니다. 파일이 자동 삭제 파일 크기를 초과하면 업로드 후 삭제됩니다.

플레이어 데이터 저장과 EGS 클라우드 세이브

에픽이 제공하는 클라우드 저장 서비스는 두 가지, 런처 클라우드 저장(Launcher Cloud Save)과 EOS 플레이어 데이터 저장이 있습니다. 전자는 더 널리 사용되며 에픽게임즈 스토어에서 게임 환경설정의 일부로 구성될 수 있습니다. 그러나 서비스 간에 약간의 차이가 있어서 사용할 서비스에 영향을 미칩니다.

  1. 런처 클라우드 저장은 에픽게임즈 런처 내의 게임과 연결됩니다. 플레이어가 런처 외부에서 게임을 실행할 수 있는 경우 게임은 저장 데이터의 로컬 버전에만 액세스합니다.
  2. 일단 구성되면 런처의 클라우드 저장은 전적으로 에픽 측에서 처리합니다.
  3. EOS 플레이어 데이터 저장은 플레이어가 온라인 상태여야 사용할 수 있으며, EOS API를 사용하여 전적으로 게임 측에서 주도합니다. 따라서 런처 클라우드 저장과 달리 플랫폼 간 데이터 공유가 가능합니다.