Entitätsprogrammiermodell

Entitäten sind die grundlegendsten adressierbaren "Dinge", auf denen PlayFab-APIs basieren. Jede Entität verfügt über einen Typ und eine ID, die sie zusammen eindeutig identifizieren. Einige Arten von Entitäten sind "standardmäßig" oder "eingebaut", da PlayFab etwas über ihre Bedeutung weiß und/oder sie automatisch erstellt, z. Bnamespace. , title, groupmaster_player_account, und title_player_account. Andere haben möglicherweise keine inhärente Bedeutung für PlayFab, haben aber eine Bedeutung für Ihr Spiel.

Jede Entität verfügt über ein Profil, das verschiedene Ressourcen enthält, die dieser Entität gehören. Zum Beispiel Objekte, Dateien, Spracheinstellungen, Richtlinien und andere, die noch kommen werden. Ein Entitätsprofil wird direkt mit der GetProfile API abgerufen, und viele andere APIs arbeiten mit bestimmten Ressourcen innerhalb des Profils, z. B SetObjects. .

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

Vergleich mit der klassischen API

Nachdem dies erledigt ist, sehen wir uns die Unterschiede zwischen den "klassischen" und "Entität"-APIs an. Wenn Sie die klassischen APIs verwenden, arbeiten Sie bereits mit denselben Entitäten, die Sie auch mit den Entitäts-APIs verwenden können, aber sie sind nicht immer explizit. In der Client-API wird beispielsweise auf einer title_player_account Entität ausgeführt, GetUserPublisherData auf einem master_player_accountGetCharacterStatistics , auf einem (d. h. auf einem character untergeordneten Element von ) title_player_accountGetTitleData ausgeführt, UpdateUserData auf einen Titel angewendet und GetPublisherData auf einem namespace.

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

"Entitäts-APIs" sind die neueren PlayFab-APIs, die (mit einigen Ausnahmen) den folgenden Designzielen entsprechen.

  • Arbeiten mit beliebigen Objekttypen.
  • Explizite Parameter für den Objekttyp und die 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, Spieleservern, Cloudskript- und Back-End-Servern, wobei die Berechtigungen durch Richtlinien definiert und entsprechend der Entität ausgewählt werden, die die API aufruft.

Wir sind der Meinung, dass die Befolgung dieser Prinzipien zu weniger APIs führt, die mehr leisten, effizienter zu warten und zu betreiben sind und für Entwickler einfacher zu erlernen sind. Grundsätzlich würden wir alle PlayFab-APIs auf diese Weise entwerfen, wenn wir von vorne anfangen würden, da wir alles wissen, was wir in den letzten fünf Jahren darüber gelernt haben, wie Entwickler PlayFab verwenden. Eines unserer wichtigsten Prinzipien bei PlayFab ist natürlich, Livetitel nach Möglichkeit niemals zu unterbrechen, was bedeutet, dass wir die Abwärtskompatibilität mit allen veröffentlichten APIs aufrechterhalten müssen.

Überlegungen für Benutzer klassischer APIs

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

Das Schlechte

  • Wenn Ihr Titel bereits klassische APIs für Spielerdaten, Inventare und andere Ressourcen (auch als title_player_accounts bezeichnet) verwendet, werden diese vorhandenen Daten nicht automatisch in den entsprechenden Entitäts-APIs angezeigt.
  • Es dauert einige Zeit, bis die Objekt-APIs die Funktionsparität mit den klassischen APIs aufweisen. 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 Objekt-API schaffen.

Das Gute

  • Sie müssen nichts tun. Wenn Ihr Spiel bereits gut mit 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 hat dies klare Vorteile, dies zu geringen Kosten zu tun. Sie können beispielsweise ein Feature hinzufügen, das größere Datenmengen in einer Datei zusätzlich zu vorhandenen Einstellungen speichert, 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.

Unterstützte Entitätstypen

Die folgende Liste beschreibt die verfügbaren Entitätstypen, die zum Erstellen einer .EntityKey Entitätsschlüssel werden zur Identifizierung von Entitäten in den meisten neueren API-Methoden verwendet.

Diese Werte sind für die Verwendung in diesem EntityKey.Type Feld vorgesehen.

Notiz

Bei diesen Groß - und Kleinschreibung wird zwischen Groß- und Kleinschreibung unterschieden. Andere/benutzerdefinierte Werte funktionieren derzeit nicht .

Namespace

Die namespace Entität stellt die titelübergreifende Spieleridentität und den Bereich der freigegebenen Daten dar. Standardmäßig umfasst sie jeden Titel in einem Studio. Der Namespace unterscheidet sich vom Studio, bei dem es sich um eine administrative Gruppierung handelt. Weitere Informationen finden Sie unter PlayFab-Konzepte.

Einige APIs verwenden den älteren Begriff Publisher für diesen Bereich. Die Herausgeber-ID identifiziert den Namespace.

Notiz

Änderungen an dieser Entität werden nicht in Echtzeit widergespiegelt.

Legen Sie das ID Feld auf Ihre GamePublisherId. So stellen Sie Folgendes GamePublisherIdzurück:

  • Melden Sie sich bei 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 Ihre GamePublisherId und-Namespace-ID.

Titel

Die title Entität stellt die globale Information dar, die auf einen Titel beschränkt ist. Ein Titel ist eine isolierte PlayFab-Ressource für ein Spiel oder eine Spielumgebung.

Notiz

Änderungen an dieser Entität werden nicht in Echtzeit widergespiegelt.

Legen Sie das ID Feld auf den TitleIdWert Ihres Spiels fest. So stellen Sie Folgendes TitleIdzurück:

  • Melden Sie sich bei 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

Das master_player_account ist eine Spielerentität, die von allen Titeln in einem Namespace gemeinsam genutzt wird.

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

title_player_account

title_player_accountdarstellt, stellt für die meisten Entwickler den Spieler auf die traditionellste Weise dar.

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

Zeichen

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

Legen Sie das Feld auf einen beliebigen characterId Wert von result.Characters[i].CharacterIdfestID.

Gruppe

Das group ist eine Entität, die andere Entitäten enthält. Derzeit ist es auf Spieler und Charaktere beschränkt.

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

game_server

Das game_server Objekt ist ein eindeutiges Objekt, das von Spielservern hauptsächlich zur Verwendung in den Features Spielersuche 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 Spielersuche und Lobby zu abonnieren, sowie um bestimmte Features wie die Migration von Lobbybesitzern zu unterstützen.

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

  • Zuletzt aktualisiert um