엔터티 프로그래밍 모델

아티클
11/16/2023

엔터티는 PlayFab API가 작동하는 가장 기본적인 주소 지정 가능한 “사물”입니다. 각 엔터티에는 엔터티를 고유하게 식별하는 형식 및 ID가 있습니다. 일부 엔터티 형식은 “표준” 또는 “기본 제공”으로, PlayFab에서 해당 의미를 알고 있거나 자동으로 만듭니다(예: namespace, title, group, master_player_account 및 title_player_account). 다른 엔터티는 PlayFab에 내재된 의미가 없지만 게임에서는 의미가 있을 수 있습니다.

모든 엔터티에는 해당 엔터티가 소유한 다양한 리소스가 포함된 프로필이 있습니다. 해당 리소스로는 개체, 파일, 언어 설정, 정책 등을 예로 들 수 있습니다. 엔터티 프로필은 GetProfile API를 사용하여 직접 검색되며, 다른 많은 API는 프로필 내의 특정 리소스(예: SetObjects)에서 작동합니다.

마지막으로 엔터티의 리소스에 다른 엔터티에서 액세스하는 방법을 제어하는 사용 권한을 고려하는 엔터티 간의 부모/자식 관계가 있습니다. 지정된 엔터티의 “상위 항목”은 해당 프로필의 Lineage 속성에서 확인할 수 있습니다.

클래식 API와 비교

그럼 다른 이야기로 “클래식” API와 “엔터티” API의 차이점을 살펴보겠습니다. 클래식 API를 사용하는 경우 이미 엔터티 API와 함께 사용할 수 있는 동일한 엔터티로 작업하고 있지만 항상 명시적인 것은 아닙니다. 예를 들어 클라이언트 API에서 UpdateUserData은(는) title_player_account 엔터티에서 작동하고, GetUserPublisherData은(는) master_player_account에서 작동하고, GetCharacterStatistics은(는) character(title_player_account의 자녀)에서 작동하고, GetTitleData은(는) 타이틀에서 작동하고, GetPublisherData은(는) namespace에서 작동합니다.

일반적으로 각 클래식 API는 하나의 특정 엔터티 형식에서 작동하지만 엔터티 형식은 암시적인 경우가 많으며 API 이름을 따르지 않을 수도 있습니다. 또한 두 가지 유형의 엔터티에 해당하는 API는 매개 변수, 제한 및 동작(예: UpdatePlayerStatistics 및 UpdateCharacterStatistics)에 따라 부분적으로 달라질 수 있습니다. 이 때문에 혼동을 느끼는 사람은 비단 여러분뿐이 아닙니다. 기존 집합과의 호환성을 손상하지 않고 PlayFab API를 간소화하고자 다음과 같이 했습니다...

"엔터티 API"는 다음과 같은 디자인 목표를 준수하는 최신 PlayFab API를 호출한 것입니다(몇 가지 예외가 있음).

임의의 엔터티 형식으로 작업
엔터티 형식 및 ID에 대해 명시적 매개 변수 사용
엔터티 프로필의 특정 리소스에 대해 특정 작업 수행
게임 클라이언트, 게임 서버, 클라우드 스크립트, 백 엔드 서버 등과 같은 여러 보안 컨텍스트에서 정책에 의해 정의되고 API를 호출하는 엔터티에 따라 선택된 사용 권한으로 호출할 수 있음

이러한 원칙을 따르면 더 적은 API로 더 많은 작업을 수행하고, 더 효율적으로 유지 관리 및 운영하고, 개발자가 더 쉽게 학습할 수 있게 됩니다. 기본적으로 이는 우리가 처음부터 모든 PlayFab API를 디자인하는 방식이며 지난 5년간 개발자가 PlayFab을 사용하는 방법에 대해 배운 모든 지식을 바탕으로 합니다. 물론 PlayFab의 가장 중요한 원칙 중 하나는 가능한 경우 라이브 타이틀을 중단시키지 않는 것, 즉 이전에 릴리스된 모든 API와의 호환성을 유지하는 것입니다.

클래식 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를 계속 사용하면서 엔터티 API 사용을 시작할 수 있습니다. 경우에 따라 약간의 비용으로 이렇게 하면 확실히 유익할 수 있습니다. 예를 들어 클래식 “플레이어 데이터”에 저장된 기존 설정 외에 파일에 더 많은 양의 데이터를 저장하는 새로운 기능을 게임에 추가합니다.

기능 개요

엔터티 프로그래밍 모델은 PlayFab의 차세대 데이터 및 게임 서비스를 위한 기반입니다.

지원되는 엔터티 형식

다음 목록에는 사용 가능한 엔터티 형식이 설명되어 있으며 이 목록은 EntityKey를 구성하는 데 사용할 수 있습니다. 엔터티 키는 최신 API 메서드에서 엔터티를 식별하는 데 사용됩니다.

이러한 값은 EntityKey.Type 필드에서 사용하기 위한 것입니다.

참고 항목

이러한 값은 ‘대/소문자를 구분’합니다. 다른/사용자 지정 값은 현재 작동하지 ‘않습니다’.

namespace

namespace(은)는 스튜디오 내에 있는 모든 타이틀에 대한 모든 전역 정보를 나타내는 단일 엔터티입니다. 이 정보는 정적이어야 합니다. 이 엔터티에 대한 변경 내용은 실시간으로 반영되지 않습니다.

ID 필드를 GamePublisherId로 설정합니다. GamePublisherId를 검색하려면 다음을 수행합니다.

게임 관리자에 로그인합니다.
My Studios and Titles(내 스튜디오 및 타이틀) 페이지에서 적절한 타이틀을 선택합니다.
타이틀 페이지의 왼쪽 모서리에 있는 기어 아이콘을 선택한 다음 제목 Title Settings(타이틀 설정)를 선택합니다.
API 기능 탭을 선택합니다.

API 기능 페이지의 게시자 ID가 GamePublisherId입니다.

title

title(은)는 해당 타이틀에 대한 모든 전역 정보를 나타내는 단일 엔터티입니다. 이 정보는 정적이어야 합니다. 이 엔터티에 대한 변경 내용은 실시간으로 반영되지 않습니다.

ID 필드를 게임의 TitleId로 설정합니다. TitleId를 검색하려면 다음을 수행합니다.

게임 관리자에 로그인합니다.
My Studios and Titles(내 스튜디오 및 타이틀) 페이지에서 타이틀을 찾습니다.

타이틀 ID는 타이틀 이름 바로 아래에 있습니다.

master_player_account

master_player_account는 스튜디오 내의 모든 타이틀에서 공유하는 플레이어 엔터티입니다.

ID 필드를 LoginResult.PlayFabId에서 반환된 클래식 API의 PlayFabId로 설정합니다.

title_player_account

title_player_account는 대부분의 개발자에게 가장 일반적으로 플레이어를 표시하는 방식입니다.

ID 필드를 클라이언트 API의 LoginResult.EntityToken.Id 또는 인증 API의 GetEntityTokenResponse.Entity.Id로 설정합니다.

character

character(은)는 title_player_account의 하위 엔터티이며 클래식 API에서 캐릭터의 직접적인 미러입니다.

ID 필드를 result.Characters[i].CharacterId에서 characterId(으)로 설정합니다.

group

group(은)는 다른 엔터티를 포함하는 엔터티입니다. 현재 플레이어 및 문자로 제한됩니다.

ID 필드는 그룹을 생성 중인 경우 result.Group.Id로 설정하고, 혹은 멤버십을 나열하는 경우 result.Groups[i].Group.Id로 설정합니다.

game_server

game_server 엔터티는 주로 매치 메이킹 및 로비 기능에 사용하기 위해 게임 서버에서 사용하는 고유한 엔터티입니다. 다른 PlayFab 기능을 지원하기 위해 향후 시나리오가 추가될 수 있습니다.

이 엔터티는 게임 서버에 매치 메이킹 및 로비에 대한 실시간 업데이트를 구독하고, 로비 소유자 마이그레이션과 같은 특정 기능을 지원하기 위해 게임 서버를 고유하게 식별하는 데 유용한 고유한 ID를 제공합니다.

game_server 엔터티로 인증하려면 타이틀 엔터티로 AuthenticateGameServerWithCustomId API를 호출하고 game_server 엔터티 키와 토큰 쌍을 검색합니다. PFMultiplayerSetEntityToken으로 PlayFab 멀티 플레이어 SDK를 사용할 경우 이 엔터티 키를 사용합니다.

다음을 통해 공유