エンティティプログラミングモデル

[アーティクル]
11/17/2023

エンティティは、PlayFab API が動作する最も基本的なアドレス指定可能な "モノ" です。各エンティティにはタイプと ID があり、それによって一意に識別されます。一部の種類のエンティティは "標準" または "組み込み" です。PlayFab は、その意味について何かを認識し、namespace、title、group、master_player_account、title_player_accountなど、それらを自動的に作成します。他のエンティティは PlayFab に対しては固有の意味を持たないが、ゲーム内で意味を持つ場合があります。

すべてのエンティティには、そのエンティティが所有するさまざまなリソースを含むプロファイルがあります。たとえば、オブジェクト、ファイル、言語設定、ポリシーなどです。エンティティプロファイルは GetProfile API を使用して直接取得され、他の多くの API はプロファイル内の特定のリソース ( SetObjectsなど) で動作します。

最後に、エンティティ間には親/子リレーションシップがあり、エンティティのリソースに他のエンティティがアクセスする方法を制御するアクセス許可の要素として考慮されます。特定のエンティティの "先祖" は、そのプロファイルの Lineage プロパティにあります。

Classic API との比較

これをひとまず脇に置いておいて、"classic" API と "entity" API の違いを見てみましょう。クラシック API を使用している場合は、エンティティ API で使用できるのと同じエンティティを既に使用していますが、必ずしも明示的であるとは限りません。たとえば、クライアント API では、UpdateUserData はtitle_player_account エンティティで動作します。GetUserPublisherData は master_player_accountで動作し、GetCharacterStatistics は character (title_player_accountの子) で動作します。GetTitleData はタイトルで動作し、GetPublisherData は namespaceで動作します。

一般に、各クラシック API は 1 つの特定の種類のエンティティで動作しますが、多くの場合、エンティティ型は暗黙的であり、API 名からフォローする必要はありません。さらに、2 種類のエンティティの同等の API は、パラメーター、制限、動作 (UpdatePlayerStatistics 対 UpdateCharacterStatistics など) に関して微妙に異なる場合があります。これに混乱を感じているのは、ユーザー 1 人ではありません。既存のセットとの互換性を損なうことなく、PlayFab API を簡素化したいと考えました。これにより、...

"エンティティ API" は、新しい PlayFab API と呼ばれるもので、次の設計目標に準拠しています (一部の例外があります)。

任意の種類のエンティティで機能します。
エンティティの型と ID に明示的なパラメーターを持っています。
エンティティプロファイル内の特定のリソースに対して特定の操作を実行します。
ポリシーによって定義され、API を呼び出しているエンティティに応じて選択されたアクセス許可を使用して、ゲームクライアント、ゲームサーバー、Cloud Script、バックエンドサーバーなど、複数のセキュリティコンテキストで呼び出すことができます。

これらの原則に従うと、より少ない数の API で、より多くのことを行い、保守と運用の効率が向上し、開発者がより簡単に学習できるようになると考えています。基本的に、これは、開発者が PlayFab を使用する方法について過去 5 年間に Microsoft が学習したすべてのことを知ったうえで、もし最初からやり直すとしても、この方法ですべての PlayFab API を設計するに違いない方法です。もちろん、PlayFab の最も重要な原則の 1 つは、ライブタイトルを中断させないということです。可能であれば、リリースされたすべての API との下位互換性を維持する必要があります。

Classic API ユーザーに関する考慮事項

互換性を維持しながら設計目標を達成するために、これらのエンティティ API は、従来の API と並行して、通常は個別のセットとして導入されています。エンティティ API は従来の API として、同じエンティティで動作できますが、ほとんどの場合、これらのエンティティが所有する個別のリソース/データのセットで動作します。たとえば、SetObjects エンティティ API と UpdateUserData クラシック API の両方でデータを title_player_account エンティティの下に格納できますが、2 つの API が "参照" するデータは分離されています。実際の影響の一部を次に示します。

悪い点

タイトルがプレイヤー (title_player_account とも呼ばれます) のデータ、インベントリなどに従来の API を既に使用している場合、その既存のデータは同等のエンティティ API に自動的に表示されません。
エンティティ API が従来の API と同等の機能を持つには、しばらく時間がかかります。ほとんどの場合、データは個別に格納され、それらをサポートするために必要なバックエンドの変更が多数あります。エンティティ API に対して決して行わない従来の機能が存在する場合があります。

良い点

何もする必要がありません。ゲームが PlayFab クラシック API で既に正常に動作している場合は、引き続き動作します。
エンティティ API の使用を開始しながら、同じエンティティセットで従来の API を引き続き使用できます。状況によっては、従来の "プレイヤーデータ" に保存されている既存の設定に加えて、ファイルにより大量のデータを保存する新しい機能をゲームに追加する場合など、少しのコストで行えるなど、明確な利点があります。

機能の概要

エンティティプログラミングモデルは、PlayFab の次世代のデータとゲームサービスの基盤です。

サポートされているエンティティの種類

次の一覧では、使用可能なエンティティの種類について説明します。これは、EntityKey を構築するために使用できます。エンティティキーを使用して、最新の API の方法でエンティティを識別します。

これらの値は、EntityKey.Type フィールドで使用されます。

注意

これらは、大文字と小文字を区別します。その他の値またはカスタム値は、現在使用 できません。

名前空間

namespace は、スタジオ内の全タイトルの全てのグローバル情報を参照する唯一のエンティティです。この情報は、静的である必要があります。このエンティティへの変更は、リアルタイムで反映されません。

ID フィールドを GamePublisherIdに設定します。 GamePublisherId を取得するには:

ゲームマネージャーにサインインします。
[マイスタジオとタイトル] ページで、適切なタイトルを選択します。
左上隅の歯車アイコンを選択し、[タイトルの設定] を選択します。
[API 機能] タブを選択します。

[API 機能] ページのパブリッシャー IDは、お使いのGamePublisherIdです。

タイトル

title は、そのタイトルの全世界の情報を参照する唯一のエンティティです。この情報は、静的である必要があります。このエンティティへの変更は、リアルタイムで反映されません。

ID フィールドをゲームの TitleIdに設定します。 TitleId を取得するには:

ゲームマネージャーにサインインします。
マイスタジオとタイトル画面で、タイトルを見つけます。

タイトル ID は、タイトルの名前のすぐ下にあります。

master_player_account

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

ID フィールドは、従来の API で PlayFabId に設定しますが、LoginResult.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 は、他のエンティティを含むエンティティです。現在、プレイヤーとキャラクターに制限されています。

グループを作成する場合は ID フィールドを result.Group.Id に、メンバーシップを一覧表示するときは、result.Groups[i].Group.Id に設定します。

game_server

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

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

game_server のエンティティとして認証するには、API AuthenticateGameServerWithCustomId をタイトルエンティティとして呼び出し、game_server エンティティキーとトークンのペアを取得します。 PFMultiplayerSetEntityToken で PlayFab マルチプレイヤー SDK を使用する場合は、このエンティティキーを使用します。

エンティティ プログラミング モデル