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

エンティティは、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 と共有データ スコープを表します。 既定では、スタジオ内のすべてのタイトルにまたがっています。 名前空間は、管理グループである Studio とは異なります。 詳細については、「PlayFab の概念」を参照してください。

一部の API では、このスコープに古い用語 パブリッシャー を使用します。 パブリッシャー ID は名前空間を識別します。

注意

このエンティティへの変更は、リアルタイムで反映されません。

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

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

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

title

title エンティティは、1 つのタイトルにスコープが設定されたグローバル情報を表します。 タイトルは、ゲームまたはゲーム環境用の分離された PlayFab リソースです。

注意

このエンティティへの変更は、リアルタイムで反映されません。

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 を使用する場合は、このエンティティ キーを使用します。

  • 最終更新: