Entitätsprogrammiermodell

Entitäten sind die grundlegendsten adressierbaren "Dinge", mit denen PlayFab-APIs arbeiten. Jede Entität verfügt über einen Typ und eine ID, die sie zusammen eindeutig identifizieren. Einige Arten von Entitäten sind "Standard" oder "integriert", da PlayFab etwas über ihre Bedeutung weiß und/oder sie automatisch erstellt, z. B namespace. , title, group, master_player_accountund title_player_account. Andere haben möglicherweise keine inhärente Bedeutung für PlayFab, aber eine Bedeutung in Ihrem Spiel.

Jede Entität verfügt über ein Profil, das verschiedene Ressourcen enthält, die dieser Entität gehören. Beispiele hierfür sind Objekte, Dateien, Spracheinstellungen, Richtlinien und weitere, die in der Zukunft verfügbar sind. Ein Entitätsprofil wird direkt mit der GetProfile API abgerufen, und viele andere APIs arbeiten mit bestimmten Ressourcen innerhalb des Profils, z SetObjects. B. .

Schließlich gibt es über- und untergeordnete Beziehungen zwischen Entitäten, die die Berechtigungen berücksichtigen, die bestimmen, wie andere Entitäten auf die Ressourcen einer Entität zugreifen können. Die "Vorgänger" einer bestimmten Entität finden Sie in der Lineage -Eigenschaft ihres Profils.

Vergleich mit der klassischen API

Damit lassen Sie uns die Unterschiede zwischen den APIs "klassisch" und "Entität" betrachten. Wenn Sie die klassischen APIs verwenden, arbeiten Sie bereits mit denselben Entitäten, die Sie mit den Entitäts-APIs verwenden können, aber diese sind nicht immer explizit. In der Client-API UpdateUserData wird z. B. auf eine title_player_account Entität, auf eine master_player_accountGetCharacterStatistics ausgeführt, GetUserPublisherData auf einer character ausgeführt (die ein untergeordnetes Element von title_player_accountist), GetTitleData auf einem -Titel und GetPublisherData auf einem namespace-Objekt ausgeführt.

Im Allgemeinen arbeitet jede klassische API mit einem bestimmten Entitätstyp, aber der Entitätstyp ist häufig implizit und folgt nicht aus dem API-Namen. Darüber hinaus können die entsprechenden APIs für zwei Arten von Entitäten subtil in Bezug auf ihre Parameter, Grenzwerte und ihr Verhalten (z. B. UpdatePlayerStatistics vs. ) variieren. UpdateCharacterStatistics Wenn Sie sich dadurch verwirrt fühlen, sind Sie nicht allein. Wir wollten die PlayFab-APIs vereinfachen, ohne jemals die Kompatibilität mit dem vorhandenen Satz zu unterbrechen, was uns zu...

"Entitäts-APIs" nennen wir die neueren PlayFab-APIs, die den folgenden Entwurfszielen entsprechen (mit einigen Ausnahmen).

• Arbeiten mit beliebigen Entitätstypen.
• Explizite Parameter für entitätstyp und id haben.
• Führen Sie einen bestimmten Vorgang für eine bestimmte Ressource im Entitätsprofil aus.
• Kann in mehreren Sicherheitskontexten aufgerufen werden, z. B. von Spielclients, Spielservern, Cloudskripts, Back-End-Servern usw., mit den Berechtigungen, die durch Richtlinien definiert und ausgewählt werden, je nachdem, welche Entität die API aufruft.

Wir glauben, dass die Einhaltung dieser Prinzipien zu weniger APIs führen wird, die mehr leisten, effizienter zu verwalten und zu betreiben sind und für Entwickler einfacher zu erlernen sind. Im Grunde ist dies die Art und Weise, wie wir alle PlayFab-APIs entwerfen würden, wenn wir von vorn beginnen würden, und wissen, was wir in den letzten fünf Jahren über die Verwendung von PlayFab gelernt haben. Eines unserer wichtigsten Prinzipien bei PlayFab besteht natürlich darin, Livetitel niemals zu brechen, wenn überhaupt möglich, was bedeutet, dass wir die Abwärtskompatibilität mit allen veröffentlichten APIs aufrechterhalten müssen.

Überlegungen für Klassische API-Benutzer

Um unsere Entwurfsziele zu erreichen und gleichzeitig die Kompatibilität aufrechtzuerhalten, haben wir diese Entitäts-APIs in der Regel als separate Gruppe eingeführt, die parallel zu den klassischen APIs vorhanden sind. Die Entitäts-APIs können zwar mit denselben Entitäten wie die klassischen APIs arbeiten, aber in den meisten Fällen arbeiten sie mit einem separaten Satz von Ressourcen/Daten, die diesen Entitäten gehören. Beispielsweise können sowohl die Entitäts-API SetObjects als auch die UpdateUserData klassische API Daten unter einer title_player_account Entität speichern, aber die Daten, die von den beiden APIs "see" angezeigt werden, sind getrennt. Hier sind einige der praktischen Auswirkungen:

Das Schlechte

• Wenn Ihr Titel bereits klassische APIs für Daten, Inventare usw. mit Spielern (auch als title_player_account"s" bezeichnet) verwendet, werden diese vorhandenen Daten nicht automatisch in den entsprechenden Entitäts-APIs angezeigt.
• Es dauert einige Zeit, bis die Entitäts-APIs featureparität mit den klassischen APIs haben. Die Daten werden in den meisten Fällen separat gespeichert, und es sind viele Back-End-Änderungen erforderlich, um sie zu unterstützen. Möglicherweise gibt es einige klassische Funktionen, die es nie in die Entitäts-API schafft.

Das Gute

• Sie müssen nichts tun. Wenn Ihr Spiel bereits gut auf klassischen PlayFab-APIs funktioniert, funktioniert es weiterhin.
• Sie können mit der Verwendung von Entitäts-APIs beginnen, während Sie weiterhin klassische APIs für denselben Satz von Entitäten verwenden. In einigen Situationen gibt es klare Vorteile, dies zu geringen Kosten zu tun, z. B. das Hinzufügen eines neuen Features zu Ihrem Spiel, das größere Datenmengen in einer Datei speichert, zusätzlich zu vorhandenen Einstellungen, die in klassischen "Spielerdaten" gespeichert sind.

Übersicht über die Funktionalität

Das Entitätsprogrammiermodell ist die Grundlage für die nächste Generation von Daten- und Spieldiensten von PlayFab.

• Authentifizierung
• Profile
• Gruppen
• Daten – Datei
• Daten – Objekt
• Ereignisse
• CloudScript
• Multiplayer

Unterstützte Entitätstypen

In der folgenden Liste werden die verfügbaren Entitätstypen beschrieben, die zum Erstellen eines EntityKeyverwendet werden können. Entitätsschlüssel werden verwendet, um Entitäten in den meisten neueren API-Methoden zu identifizieren.

Diese Werte sollen im EntityKey.Type Feld verwendet werden.

Notiz

Dabei wird die Groß-/Kleinschreibung beachtet. Andere/benutzerdefinierte Werte funktionieren derzeit nicht .

Namespace

Ist namespace die einzelne Entität, die auf alle globalen Informationen für jeden Titel in einem Studio verweist. Diese Informationen sollten statisch sein. Änderungen an dieser Entität werden nicht in Echtzeit widerspiegelt.

Legen Sie das ID Feld auf ihre GamePublisherIdfest. So rufen Sie Ihre GamePublisherIdab:

• Melden Sie sich beim Game Manager an.
• Wählen Sie auf der Seite Meine Studios und Titel den entsprechenden Titel aus.
• Wählen Sie das Zahnradsymbol in der linken Ecke der Titelseite und dann Titeleinstellungen aus.
• Wählen Sie die Registerkarte API-Features aus.

Die Herausgeber-ID auf der Seite API-Features ist Ihr GamePublisherId.

Titel

ist title die einzelne Entität, die auf alle globalen Informationen für diesen Titel verweist. Diese Informationen sollten statisch sein. Änderungen an dieser Entität werden nicht in Echtzeit widerspiegelt.

Legen Sie das ID Feld auf die des TitleIdSpiels fest. So rufen Sie Ihre TitleIdab:

• Melden Sie sich beim Game Manager an.
• Suchen Sie auf der Seite Meine Studios und Titel Ihren Titel.

Die Titel-ID befindet sich direkt unter dem Namen Ihres Titels.

master_player_account

ist master_player_account eine Playerentität, die von allen Titeln in einem Studio gemeinsam verwendet wird.

Legen Sie das ID-Feld aus der klassischen API auf fest PlayFabId , das von einem beliebigen LoginResult.PlayFabIdzurückgegeben wird.

title_player_account

title_player_accountstellt für die meisten Entwickler den Player auf die traditionellste Weise dar.

Legen Sie das ID Feld in der Client-API oder GetEntityTokenResponse.Entity.Id in der Authentifizierungs-API auf LoginResult.EntityToken.Id fest.

Charakter

ist character eine Unterentität von title_player_account und ist eine direkte Spiegel von Zeichen in den klassischen APIs.

Legen Sie das ID Feld von auf ein beliebiges characterId fest result.Characters[i].CharacterId.

Gruppe

ist group eine Entität, die andere Entitäten enthält. Es ist derzeit auf Spieler und Charaktere beschränkt.

Legen Sie das ID Feld auf fest result.Group.Id , wenn Sie eine Gruppe erstellen, oder auf , result.Groups[i].Group.Id wenn Sie Ihre Mitgliedschaften auflisten.

game_server

Die game_server Entität ist eine eindeutige Entität, die von Spielservern hauptsächlich für die Verwendung in den Features Matchmaking und Lobby verwendet wird. Zukünftige Szenarien können hinzugefügt werden, um andere PlayFab-Features zu unterstützen.

Diese Entität gibt Spielservern eine eigene Identität, die nützlich ist, um sie eindeutig zu identifizieren, um Echtzeitupdates für Matchmaking und Lobby zu abonnieren, sowie spezifische Features wie die Migration von Lobbybesitzern zu unterstützen.

Um sich game_server als Entität zu authentifizieren, rufen Sie die API AuthenticateGameServerWithCustomId als Titelentität auf, und rufen Sie das game_server Entitätsschlüssel- und Tokenpaar ab. Verwenden Sie diesen Entitätsschlüssel, wenn Sie das PlayFab Multiplayer SDK mit PFMultiplayerSetEntityToken verwenden.