플레이어 데이터 스토리지 인터페이스

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

플레이어 데이터 스토리지 인터페이스**는 개발자가 에픽 온라인 서비스**(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의 파일 이름은 다음 형식을 따릅니다. Directory0/Directory1/DirectoryN/Filename.Extension

'Directory' 및 'Extension' 부분은 선택 사항입니다. 각 디렉터리 이름 뒤에는 '/' 문자를 반드시 입력해야 하며, 처음 또는 마지막 자리를 포함한 다른 위치에는 입력할 수 없습니다. 파일 이름에는 다음 문자를 사용할 수 있습니다.

*ASCII 문자의 모든 영숫자

  • !

  • -

  • _

  • +

  • .

  • *

  • '

  • (

  • )

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

파일 쿼리

EOS에 쿼리하여 클라우드에 저장된 하나 또는 모든 파일에 대한 정보를 얻을 수 있습니다. 모든 쿼리 타입은 발견한 파일의 이름, 데이터 크기(바이트, 암호화되지 않음), MD5 해시 등의 메타데이터를 반환합니다. 그런 다음 파일에 액세스하거나 파일을 수정하기에 앞서 이 정보의 사본을 캐시할 수 있습니다.

모든 파일 쿼리

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

프로퍼티

ApiVersion

EOS_PLAYERDATASTORAGE_QUERYFILELISTOPTIONS_API_LATEST

LocalUserId

파일 데이터를 요청하고 있는 로컬 사용자의 EOS_ProductUserId

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

단일 파일 쿼리

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

프로퍼티

ApiVersion

EOS_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_QueryFileCallbackInfo`의 ResultCode`가 EOS_Success`인지 점검하고 `EOS_PlayerDataStorage_CopyFileMetadataByFilename`을 호출하여 이 정보에 액세스하는 것이 가장 좋습니다.

파일 액세스 및 수정

EOS는 비동기 클라우드에서 파일 읽기, 쓰기, 삭제를 지원합니다. 읽기 및 쓰기는 스트리밍 작업이며, EOS는 게임이 각 진행 상황을 검토, 조절, 개입할 때 사용 가능한 핸들을 제공합니다.

파일 읽기

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

프로퍼티

ApiVersion

EOS_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`를 갖습니다.

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

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

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

PDSChart.png

여러 파일을 연속해서 다운로드할 때 파일 목록을 먼저 쿼리하고 메타데이터를 캐시한 다음 다운로드를 실행하면 퍼포먼스를 높일 수 있습니다. 이렇게 하면 복수의 쿼리를 수행하거나 파일 다운로드 사이마다 결과를 기다릴 필요가 없게 됩니다.

파일 쓰기

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

프로퍼티

ApiVersion

EOS_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`를 갖습니다.

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

파일 복사

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

프로퍼티

ApiVersion

EOS_PLAYERDATASTORAGE_DUPLICATEFILEOPTIONS_API_LATEST

LocalUserId

작업에 권한을 부여하는 로컬 사용자의 계정 ID(반드시 원본 파일 소유자여야 함)

SourceFilename

복사할 기존 파일 이름

DestinationFilename

복제된 파일에 사용할 이름

완료되면 EOS가 EOS_PlayerDataStorage_DuplicateFileCallbackInfo 파라미터로 EOS_PlayerDataStorage_OnDuplicateFileCompleteCallback 함수를 실행합니다. 사용자가 원본 파일을 가지고 있지 않거나 스토리지 공간이 부족한 경우 파일을 복제할 수 없습니다. `DestinationFilename`이 이미 존재하는 파일을 식별할 경우 해당 파일은 사본으로 대체됩니다.

파일 삭제

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

프로퍼티

ApiVersion

EOS_PLAYERDATASTORAGE_DELETEFILEOPTIONS_API_LATEST

LocalUserId

파일 삭제 권한을 부여하는 로컬 사용자의 계정 ID(반드시 원본 파일 소유자여야 함)

Filename

삭제할 파일 이름

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

데이터 캐싱 및 암호화

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

플레이어 데이터 스토리지 파일은 EOS 플랫폼 초기화 때 제공한 키로 항상 암호화되어 저장됩니다. 암호화 키 자체는 클라우드에 저장되지 않으므로 에픽게임즈 및 악성 외부자가 키를 사용하여 클라이언트 데이터에 액세스할 수 없습니다. 암호화 키는 각 사용자에 대해 자동으로 수정되므로 사용자들이 서로의 데이터 암호를 해독할 수 없습니다.

사용 제한

저장 공간은 파일별, 사용자별로 제한되어 있지만 정확한 값은 현재 고정되어 있지 않습니다. 또한 사용자는 업로드, 다운로드 등 데이터를 전송하는 속도에도 제한이 있습니다. 사용자가 스토리지 용량 한도를 초과하여 업로드하려고 시도할 경우 EOS는 오류와 함께 업로드 작업 실패를 유발합니다. 한꺼번에 너무 많은 데이터를 전송하는 것은 오류 원인이 아니지만 EOS가 해당 사용자 쪽으로의 전송을 임시 중지합니다. 이 상태에서도 사용자는 메타데이터를 얻거나 파일을 삭제할 수 있습니다.

사용 제한

성능 및 속도를 유지하기 위해 준수해야 하는 사용 제한에 대한 자세한 내용은 서비스 사용 제한 페이지 를 참고해 주세요.