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 ユーザーへの考慮事項
互換性を維持しながら設計目標を達成するために、これらのエンティティ 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 は、スタジオ内のすべてのタイトル間で共有されるプレイヤー エンティティです。
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 のキャラクター を直接反映したものです。
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 のエンティティ キーとトークンのペアを取得します。このエンティティ キーは、PlayFab Multiplayer SDK で PFMultiplayerSetEntityToken を使用するときに使用してください。