namespace, title, group, master_player_account, title_player_account가 있습니다. 다른 유형은 PlayFab에서는 특별한 의미가 없지만 게임에서는 의미를 가질 수 있습니다.
모든 엔티티에는 해당 엔티티가 소유한 다양한 리소스가 담긴 프로필이 있습니다. 예를 들어 객체, 파일, 언어 설정, 정책 등이 있으며 앞으로 더 추가될 예정입니다. 엔티티 프로필은 GetProfile API로 직접 가져오며, 다른 여러 API는 프로필 내부의 특정 리소스에 대해 동작합니다(예: SetObjects).
마지막으로, 엔티티 간에는 부모/자식 관계가 있으며, 이는 다른 엔티티가 어떤 엔티티의 리소스에 접근할 수 있는 방식을 규정하는 권한에도 영향을 줍니다. 특정 엔티티의 “조상”은 프로필의 Lineage 속성에서 찾을 수 있습니다.
클래식 API와의 비교
이제 “클래식”과 “엔티티” API의 차이점을 살펴보겠습니다. 클래식 API를 사용하고 있다면 이미 엔티티 API에서 사용할 수 있는 동일한 엔티티들과 작업하고 있지만, 항상 명시적이지는 않습니다. 예를 들어 Client API에서UpdateUserData는 title_player_account 엔티티에서 동작하고, GetUserPublisherData는 master_player_account에서 동작하며, GetCharacterStatistics는 (title_player_account의 자식인) character에서 동작합니다. GetTitleData는 title에서 동작하고 GetPublisherData는 namespace에서 동작합니다.
일반적으로 각 클래식 API는 하나의 특정 엔티티 유형에서만 동작하지만, 엔티티 유형은 종종 암묵적이며 API 이름에서 반드시 유추되지 않습니다. 또한 두 유형의 엔티티에 대한 동등한 API는 매개변수, 제한, 동작 면에서 미묘하게 다를 수 있습니다(예: UpdatePlayerStatistics vs. UpdateCharacterStatistics). 혼란스럽더라도 걱정하지 마세요. 기존 API 세트와의 호환성을 유지하면서 PlayFab API를 단순화하려는 시도가 있었고, 그로 인해…
“엔티티 API”는 다음과 같은 설계 목표를 따르는 최신 PlayFab API를 지칭하는 이름입니다(일부 예외 존재).
- 임의의 엔티티 유형과 함께 동작합니다.
- 엔티티 Type과 Id에 대해 명시적인 매개변수를 가집니다.
- 엔티티 프로필의 특정 리소스에 대해 특정 작업을 수행합니다.
- 정책에 의해 정의된 권한과 API를 호출하는 엔티티에 따라 게임 클라이언트, 게임 서버, Cloud Script, 백엔드 서버 등 여러 보안 컨텍스트에서 호출할 수 있습니다.
클래식 API 사용자를 위한 고려 사항
호환성을 유지하면서 설계 목표를 달성하기 위해, 이러한 엔티티 API는 일반적으로 클래식 API와 함께 별도의 세트로 도입되어 왔습니다. 엔티티 API는 클래식 API와 동일한 엔티티에서 동작할 수 있지만, 대부분의 경우 이러한 엔티티가 소유한 별도의 리소스/데이터 세트에서 동작합니다. 예를 들어SetObjects 엔티티 API와 UpdateUserData 클래식 API는 모두 title_player_account 엔티티 아래에 데이터를 저장할 수 있지만, 두 API가 “보는” 데이터는 서로 별개입니다. 몇 가지 실질적인 영향은 다음과 같습니다.
단점
- 타이틀이 이미 플레이어(즉
title_player_account)와 관련하여 데이터, 인벤토리 등에 클래식 API를 사용하고 있다면, 기존 데이터가 동등한 엔티티 API에 자동으로 나타나지 않습니다. - 엔티티 API가 클래식 API와 기능적으로 동등해지기까지는 시간이 걸립니다. 대부분의 경우 데이터가 별도로 저장되며, 이를 지원하기 위한 많은 백엔드 변경이 필요합니다. 일부 클래식 기능은 엔티티 API로 이전되지 않을 수도 있습니다.
장점
- 아무것도 할 필요가 없습니다. 게임이 이미 PlayFab 클래식 API에서 잘 동작하고 있다면 계속 작동합니다.
- 동일한 엔티티 세트에서 클래식 API를 계속 사용하면서 엔티티 API를 사용하기 시작할 수 있습니다. 어떤 상황에서는 클래식 “player data”에 저장된 기존 설정과 함께 파일에 더 많은 데이터를 저장하는 새로운 기능을 게임에 추가하는 것과 같이, 적은 비용으로 확실한 이점을 얻을 수 있는 경우가 있습니다.
기능 개요
엔티티 프로그래밍 모델은 PlayFab의 차세대 데이터 및 게임 서비스의 기반입니다.지원되는 엔티티 유형
다음 목록은EntityKey를 구성하는 데 사용할 수 있는 엔티티 유형을 설명합니다. Entity Key는 대부분의 최신 API 메서드에서 엔티티를 식별하는 데 사용됩니다.
이 값은 EntityKey.Type 필드에 사용해야 합니다.
이 값들은 대/소문자를 구분합니다. 다른/사용자 지정 값은 현재 작동하지 않습니다.
namespace
namespace는 스튜디오 내 모든 타이틀에 대한 전역 정보를 참조하는 단일 엔티티입니다. 이 정보는 정적이어야 합니다. 이 엔티티에 대한 변경 사항은 실시간으로 반영되지 않습니다.
ID 필드를 GamePublisherId로 설정하세요. GamePublisherId를 가져오려면 다음과 같이 진행합니다.
- Game Manager에 로그인합니다.
- My Studios and Titles 페이지에서 해당 타이틀을 선택합니다.
- 타이틀 페이지 왼쪽 상단의 톱니바퀴 아이콘을 선택하고 Title Settings를 선택합니다.
- API Features 탭을 선택합니다.
GamePublisherId입니다.
title
title은 해당 타이틀에 대한 모든 전역 정보를 참조하는 단일 엔티티입니다. 이 정보는 정적이어야 합니다. 이 엔티티에 대한 변경 사항은 실시간으로 반영되지 않습니다.
ID 필드를 게임의 TitleId로 설정하세요. TitleId를 가져오려면 다음과 같이 진행합니다.
- Game Manager에 로그인합니다.
- My Studios and Titles 페이지에서 타이틀을 찾습니다.
master_player_account
master_player_account는 스튜디오 내 모든 타이틀에서 공유되는 Player 엔티티입니다.
ID 필드를 클래식 API에서 반환되는 PlayFabId(어떤 LoginResult.PlayFabId)로 설정하세요.
title_player_account
대부분의 개발자에게title_player_account는 가장 전통적인 방식으로 플레이어를 나타냅니다.
ID 필드를 Client API의 LoginResult.EntityToken.Id 또는 Authentication API의 GetEntityTokenResponse.Entity.Id로 설정하세요.
character
character는 title_player_account의 하위 엔티티이며 Classic API의 Characters와 직접 대응합니다.
ID 필드를 result.Characters[i].CharacterId의 어떤 characterId로 설정하세요.
group
group은 다른 엔티티를 포함하는 엔티티입니다. 현재는 Players와 Characters로 제한되어 있습니다.
그룹을 만드는 경우에는 ID 필드를 result.Group.Id로 설정하고, 멤버십 나열 시에는 result.Groups[i].Group.Id로 설정하세요.
game_server
game_server 엔티티는 주로 Matchmaking과 Lobby 기능에서 사용되는 게임 서버의 고유 엔티티입니다. 앞으로 다른 PlayFab 기능을 지원하기 위한 시나리오가 추가될 수 있습니다.
이 엔티티는 게임 서버에 자체 신원을 제공하여 Matchmaking과 Lobby에 대한 실시간 업데이트를 구독하는 데 고유하게 식별하고, Lobby owner migration과 같은 특정 기능을 지원하는 데 유용합니다.
game_server 엔티티로 인증하려면 title 엔티티로서 AuthenticateGameServerWithCustomId API를 호출하여 game_server 엔티티 키와 토큰 쌍을 가져오세요. PlayFab Multiplayer SDK를 사용할 때 PFMultiplayerSetEntityToken와 함께 이 엔티티 키를 사용합니다.