> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 엔티티 프로그래밍 모델

> PlayFab 엔티티 프로그래밍 모델, EntityKey 식별자, 프로필, 그리고 엔티티 API와 클래식 PlayFab API의 비교 소개.

엔티티는 PlayFab API가 동작하는 가장 기본적인 주소 지정 가능한 “대상”입니다. 각 엔티티에는 유형(Type)과 ID(Id)가 있으며, 이 둘이 함께 엔티티를 고유하게 식별합니다. 어떤 엔티티 유형은 “표준” 또는 “기본 제공” 유형으로, PlayFab이 그 의미를 알고 있거나 자동으로 만드는 것입니다. 예를 들면 `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가 더 많은 일을 하며, 유지 및 운영이 더 효율적이고, 개발자가 배우기 쉬워질 것이라고 믿습니다. 기본적으로, 지난 5년간 개발자가 PlayFab을 어떻게 사용하는지 배운 모든 것을 바탕으로 처음부터 다시 설계한다면 우리가 모든 PlayFab API를 이렇게 설계할 것입니다. 물론 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를 사용하기 시작할 수 있습니다. 어떤 상황에서는 클래식 “player data”에 저장된 기존 설정과 함께 파일에 더 많은 데이터를 저장하는 새로운 기능을 게임에 추가하는 것과 같이, 적은 비용으로 확실한 이점을 얻을 수 있는 경우가 있습니다.

## 기능 개요

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

* [Authentication](xref:titleid.playfabapi.com.authentication.authentication)
* [Profiles](xref:titleid.playfabapi.com.profiles.accountmanagement)
* [Groups](xref:titleid.playfabapi.com.groups.groups)
* [Data - File](xref:titleid.playfabapi.com.data.file)
* [Data - Object](xref:titleid.playfabapi.com.data.object)
* [Events](/services/playfab/api-references/events)
* [CloudScript](xref:titleid.playfabapi.com.cloudscript.server-sidecloudscript)
* [Multiplayer](xref:titleid.playfabapi.com.multiplayer.multiplayerserver)

### 지원되는 엔티티 유형

다음 목록은 `EntityKey`를 구성하는 데 사용할 수 있는 엔티티 유형을 설명합니다. Entity Key는 대부분의 최신 API 메서드에서 엔티티를 식별하는 데 사용됩니다.

이 값은 `EntityKey.Type` 필드에 사용해야 합니다.

<Note>
  이 값들은 *대/소문자를 구분*합니다. 다른/사용자 지정 값은 현재 *작동하지 않습니다*.
</Note>

#### namespace

`namespace`는 스튜디오 내 모든 타이틀에 대한 *전역* 정보를 참조하는 단일 엔티티입니다. 이 정보는 정적이어야 합니다. 이 엔티티에 대한 변경 사항은 실시간으로 반영되지 *않습니다*.

`ID` 필드를 `GamePublisherId`로 설정하세요. `GamePublisherId`를 가져오려면 다음과 같이 진행합니다.

* [Game Manager](https://developer.playfab.com)에 로그인합니다.
* **My Studios and Titles** 페이지에서 해당 타이틀을 선택합니다.
* 타이틀 페이지 왼쪽 상단의 톱니바퀴 아이콘을 선택하고 **Title Settings**를 선택합니다.
* **API Features** 탭을 선택합니다.

**API Features** 페이지의 **Publisher ID**가 `GamePublisherId`입니다.

#### title

`title`은 해당 타이틀에 대한 모든 전역 정보를 참조하는 단일 엔티티입니다. 이 정보는 정적이어야 합니다. 이 엔티티에 대한 변경 사항은 실시간으로 반영되지 *않습니다*.

`ID` 필드를 게임의 `TitleId`로 설정하세요. `TitleId`를 가져오려면 다음과 같이 진행합니다.

* [Game Manager](https://developer.playfab.com)에 로그인합니다.
* **My Studios and Titles** 페이지에서 타이틀을 찾습니다.

타이틀 ID는 타이틀 이름 바로 아래에 표시됩니다.

#### 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](xref:titleid.playfabapi.com.client.characters.getalluserscharacters)와 직접 대응합니다.

`ID` 필드를 `result.Characters[i].CharacterId`의 어떤 `characterId`로 설정하세요.

#### group

`group`은 다른 엔티티를 포함하는 엔티티입니다. 현재는 Players와 Characters로 제한되어 있습니다.

그룹을 만드는 경우에는 `ID` 필드를 `result.Group.Id`로 설정하고, [멤버십 나열](xref:titleid.playfabapi.com.groups.groups.listmembership) 시에는 `result.Groups[i].Group.Id`로 설정하세요.

#### game\_server

`game_server` 엔티티는 주로 Matchmaking과 Lobby 기능에서 사용되는 게임 서버의 고유 엔티티입니다. 앞으로 다른 PlayFab 기능을 지원하기 위한 시나리오가 추가될 수 있습니다.

이 엔티티는 게임 서버에 자체 신원을 제공하여 Matchmaking과 Lobby에 대한 실시간 업데이트를 구독하는 데 고유하게 식별하고, Lobby owner migration과 같은 특정 기능을 지원하는 데 유용합니다.

`game_server` 엔티티로 인증하려면 title 엔티티로서 [AuthenticateGameServerWithCustomId](xref:titleid.playfabapi.com.authentication.authentication.authenticategameserverwithcustomid) API를 호출하여 `game_server` 엔티티 키와 토큰 쌍을 가져오세요. PlayFab Multiplayer SDK를 사용할 때 [PFMultiplayerSetEntityToken](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayersetentitytoken)와 함께 이 엔티티 키를 사용합니다.


## Related topics

- [엔티티 프로그래밍 모델](/ko/services/playfab/live-service-management/game-configuration/entities/index.md)
- [PlayFab 라이브 서비스 관리 문서](/ko/services/playfab/live-service-management/index.md)
- [Entity Groups](/ko/services/playfab/community/associations/groups/quickstart.md)
- [Group Leaderboards](/ko/services/playfab/community/leaderboards/group-leaderboards.md)
- [토너먼트 및 리더보드](/ko/services/playfab/community/leaderboards/tournaments-leaderboards/index.md)