> ## 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 があります。エンティティ タイプの中には、PlayFab がその意味を知っていたり自動的に作成したりする「標準」または「組み込み」のものもあり、たとえば `namespace`、`title`、`group`、`master_player_account`、`title_player_account` などです。他のものは、PlayFab に固有の意味を持たなくても、ゲーム内で意味を持つ場合があります。

すべてのエンティティにはプロファイルがあり、そのエンティティが所有するさまざまなリソース (オブジェクト、ファイル、言語設定、ポリシー、その他今後追加されるもの) が含まれます。エンティティのプロファイルは `GetProfile` API で直接取得され、多くの他の API は `SetObjects` などプロファイル内の特定のリソースに対して操作を行います。

最後に、エンティティ間には親子関係があり、あるエンティティのリソースが他のエンティティによってどのようにアクセスされるかを制御する権限に影響します。特定のエンティティの「祖先」は、そのプロファイルの `Lineage` プロパティで確認できます。

## クラシック API との比較

これで、「クラシック」API と「エンティティ」API の違いを見ていきましょう。クラシック API を使用している場合は、エンティティ API で使用できるのと同じエンティティを既に扱っていますが、常に明示的というわけではありません。たとえば、Client API では、`UpdateUserData` は `title_player_account` エンティティで動作し、`GetUserPublisherData` は `master_player_account` で、`GetCharacterStatistics` は `character` (`title_player_account` の子) で、`GetTitleData` はタイトルで、`GetPublisherData` は `namespace` で動作します。

一般的に、各クラシック API は特定のエンティティ タイプに対して動作しますが、エンティティ タイプはしばしば暗黙的で、API 名から必然的に導かれるものではありません。さらに、2 つのエンティティ タイプの同等の API は、パラメーター、制限、動作の点で微妙に異なることがあります (例: `UpdatePlayerStatistics` と `UpdateCharacterStatistics`)。これに混乱を感じても、あなただけではありません。私たちは、既存の API との互換性を壊すことなく PlayFab API を簡素化したかったのです。

「エンティティ API」は、以下の設計目標に従う (一部例外あり) 新しい PlayFab API の呼び方です。

* 任意のタイプのエンティティで動作すること。
* エンティティ Type と Id の明示的なパラメーターを持つこと。
* エンティティ プロファイル内の特定のリソースに対して特定の操作を実行すること。
* ゲーム クライアント、ゲーム サーバー、Cloud Script、バックエンド サーバーなど、複数のセキュリティ コンテキストから、ポリシーによって定義され、API を呼び出しているエンティティに応じて選択される権限で呼び出せること。

これらの原則に従うことで、より少ない API でより多くのことを行えるようになり、維持と運用の効率が高まり、開発者が学習しやすくなると考えています。基本的に、これは、開発者が PlayFab をどのように使用しているかについて過去 5 年間に学んだすべてを踏まえて、最初から設計をやり直すとしたら、私たちがすべての PlayFab API を設計する方法です。もちろん、PlayFab で最も重要な原則の 1 つは、可能な限りライブ タイトルを壊さないことであり、そのため公開済みのすべての 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** ページでタイトルを見つけます。

Title ID はタイトル名のすぐ下に表示されます。

#### master\_player\_account

`master_player_account` は、スタジオ内のすべてのタイトル間で共有されるプレイヤー エンティティです。

ID フィールドを、任意の `LoginResult.PlayFabId` から返されるクラシック API の `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 のキャラクター](xref:titleid.playfabapi.com.client.characters.getalluserscharacters) を直接反映したものです。

`ID` フィールドを、`result.Characters[i].CharacterId` からの任意の `characterId` に設定します。

#### group

`group` は、他のエンティティを含むエンティティです。現在はプレイヤーとキャラクターに限定されています。

グループを作成する場合は `ID` フィールドを `result.Group.Id` に、[メンバーシップを一覧表示](xref:titleid.playfabapi.com.groups.groups.listmembership) する場合は `result.Groups[i].Group.Id` に設定します。

#### game\_server

`game_server` エンティティは、主にマッチメイキングとロビー機能で使用される、ゲーム サーバー専用の一意のエンティティです。将来、他の PlayFab 機能をサポートするシナリオが追加される可能性があります。

このエンティティは、マッチメイキングやロビーのリアルタイム更新をサブスクライブしたり、ロビーのオーナー移行などの特定の機能をサポートしたりするために、ゲーム サーバーを一意に識別できる独自の ID を提供します。

`game_server` エンティティとして認証するには、タイトル エンティティとして [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

- [エンティティ プログラミング モデル](/ja-jp/services/playfab/live-service-management/game-configuration/entities/index.md)
- [PlayFab ライブ サービス管理ドキュメント](/ja-jp/services/playfab/live-service-management/index.md)
- [Game Server Configuration の概要](/ja-jp/services/playfab/live-service-management/game-configuration/index.md)
- [エンティティ グループ](/ja-jp/services/playfab/community/associations/groups/quickstart.md)
- [Postman 向け PlayFab REST API コレクション クイックスタート](/ja-jp/services/playfab/sdks/postman/postman-quickstart.md)