Skip to main content
이 엔터티 빠른 시작에서는 엔터티 개체와 엔터티 파일을 다루는 방법을 보여줍니다. 레거시 계정 및 데이터 시스템에서 PlayFab 엔터티로 마이그레이션하는 방법에 대한 자세한 내용은 엔터티 마이그레이션 정보를 참조하세요.

요구 사항

  • PlayFab 개발자 계정.
  • Unity Editor 설치본. Unity Editor 설치에 대한 자세한 내용은 Unity 설명서의 Unity 설치를 참조하세요. Visual Studio 기능 설치 관리자를 사용하여 Unity 버전을 설치할 수도 있습니다.
PlayFab Unity3D SDK는 Unity Editor 버전 5.3 이상을 지원합니다.
  • Unity 프로젝트. Unity 프로젝트 생성에 대한 자세한 내용은 빠른 시작 가이드를 참조하세요.
Unity에 익숙하지 않은 경우, 최신 설치 패키지에서는 게임 제작 안내를 설치할 수 있는 옵션을 제공합니다. 이러한 안내 중 하나를 사용하여 다음 빠른 시작에서 사용할 샘플 게임을 만들 수 있습니다.
  • PlayFab Unity3D SDK.
이 문서의 C# 샘플은 Unity SDK용으로 작성되었습니다. Unity SDK는 비동기 작업을 처리하기 위해 이벤트 기반 모델을 사용합니다. C# SDK를 사용하여 샘플 코드를 실행하려면 async Task 모델을 사용하도록 코드를 수정해야 합니다. 수정해야 하는 메서드에는 시그니처의 메서드 이름에 Async가 추가됩니다. 예를 들어 Unity SDK의 SetObject는 C# SDK에서 SetObjectAsync가 됩니다. 자세한 내용은 async 및 await를 사용한 비동기 프로그래밍을 참조하세요.

용어

엔터티는 데이터를 포함할 수 있는 모든 PlayFab 개념입니다. 기본 제공 엔터티 유형은 다음과 같습니다.
  • title - 타이틀은 모든 플레이어가 사용할 수 있는 전역 정보를 포함합니다. 이는 TitleData와 유사합니다. 게임/애플리케이션의 타이틀 ID(TitleId)로 식별됩니다.
  • master_player_account - 이 엔터티 유형을 사용하면 네임스페이스 내 여러 게임에 걸쳐 플레이어에 대한 정보를 공유할 수 있습니다. 이는 플레이어의 플레이어 ID(PlayFabId)로 식별되며, 로그인 또는 플레이어 계정에 대한 계정 정보를 검색하는 모든 호출(예: PlayFab Client API GetAccountInfo)의 일부로 반환됩니다.
  • title_player_account - 현재 타이틀에 대한 일부 정보를 포함하는 플레이어 계정을 식별합니다. 이는 모든 로그인 시 EntityKey 개체에서 반환되는 엔터티 ID(EntityKey.Id)로 식별됩니다.
  • character - 플레이어가 소유한 캐릭터를 식별하며, 검색할 수 있는 정보를 포함합니다. 이는 캐릭터의 캐릭터 ID(CharacterId)로 식별됩니다.
기본 제공 엔터티 유형에 대한 자세한 내용은 사용 가능한 기본 제공 엔터티 유형을 참조하세요.

엔터티 초기화

Entity API를 호출하려면 엔터티 ID와 엔터티 Type을 얻어야 합니다. IDType을 사용하여 다른 Entity API 메서드를 호출합니다. 이들은 EntityKey 개체의 멤버입니다. LoginWithCustomID와 같은 로그인 메서드 중 하나를 호출하여 이 작업을 수행합니다.
GetEntityToken 메서드를 호출하여 엔터티 ID와 엔터티 Type을 얻을 수도 있습니다.
클라이언트에서 호출할 경우 일반적으로 로그인한 플레이어를 나타냅니다. 게임 서버에서 호출할 경우 타이틀을 나타냅니다.

엔터티 개체

엔터티 개체를 사용하면 엔터티에 연결된 작은 JSON 직렬화 가능한 개체를 읽고 쓸 수 있습니다. 모든 엔터티 유형은 GetObjectsSetObjects 메서드를 지원합니다. 다음 코드 조각은 title_player_account 엔터티에서 Object를 설정하고 읽는 방법을 보여줍니다. 플레이어 또는 타이틀에 엔터티 개체를 설정하려면 SetObjects 메서드를 사용하세요.
플레이어 또는 타이틀의 엔터티 개체를 검색하려면 GetObjects 메서드를 사용하세요.

엔터티 파일

엔터티 파일을 사용하면 어떤 형식으로든 엔터티에 첨부된 파일을 읽고 쓸 수 있습니다. 엔터티 파일을 검색하려면 GetFiles 메서드를 사용하세요.
엔터티 프로필에 파일 업로드를 시작하려면 initiatefileuploads 메서드를 사용하세요.
엔터티 프로필로의 보류 중인 파일 업로드를 중단하려면 AbortFileUploads 메서드를 사용하세요.
엔터티 프로필로의 파일 업로드를 완료하려면 FinalizeFileUploads 메서드를 사용하세요. 원자성 업로드 작업이 성공적으로 완료될 때까지 엔터티 시스템은 파일 업로드를 완료된 것으로 간주하지 않으며, 다른 호출자에게 변경 사항을 반영하지도 않습니다.
아래에 표시된 예제는 로그인부터 파일 로드, 새 파일 업로드에 이르는 전체 엔터티-파일 루프를 보여줍니다. 이에 대한 단계는 다음과 같습니다.
  • 로그인하고 엔터티 ID와 엔터티 Type을 검색합니다.
  • 원자성 업로드 작업을 초기화합니다.
  • 모든 파일을 업로드합니다.
  • 원자성 업로드 작업을 완료합니다.
간결하게 하기 위해 이 예제는 한 번에 하나의 파일을 저장하지만, 파일은 세트로 원자적으로 업로드될 수 있습니다. 예제는 Unity 3D 엔진 사용에 익숙하다고 가정합니다.
각 파일 작업에는 많은 단계와 여러 API 호출이 필요하므로, 동일한 파일에 여러 가지 방식으로 동시에 접근하지 마세요. 매우 신중하게 처리한다면 잠금 메커니즘이 필요하지 않을 수도 있습니다. 복잡한 작업을 수행하려는 경우 잠금 메커니즘이 훨씬 더 복잡해질 수 있습니다.

Game Manager 및 엔터티

Game Manager를 사용하면 플레이어의 개체와 파일을 조작할 수 있습니다. 플레이어 개요에는 title player와 master player account 정보가 모두 표시됩니다. 또한 파일과 개체는 이제 Players 탭에 자체 섹션이 있습니다.

참고 항목

PlayFab 블로그의 엔터티, 개체 및 파일 소개.
마지막 수정일 2026년 8월 25일