Modèle de programmation des entités

Les entités sont les « éléments » adressables les plus élémentaires sur lesquels opèrent les API PlayFab. Chaque entité possède un Type et un Id qui, ensemble, l’identifient de manière unique. Certains types d’entités sont « standard » ou « intégrés », c’est-à-dire que PlayFab connaît leur signification et/ou les crée automatiquement, par exemple namespace, title, group, master_player_account et title_player_account. D’autres peuvent n’avoir aucune signification intrinsèque pour PlayFab, mais en avoir une dans votre jeu. Chaque entité possède un profil qui contient diverses ressources appartenant à cette entité. Par exemple, des objets, des fichiers, des paramètres de langue, des stratégies, et d’autres à venir. Un profil d’entité est récupéré directement avec l’API GetProfile, et de nombreuses autres API opèrent sur des ressources spécifiques du profil, comme SetObjects. Enfin, il existe des relations parent/enfant entre les entités, qui interviennent dans les autorisations régissant la façon dont les ressources d’une entité peuvent être consultées par d’autres entités. Les « ancêtres » d’une entité donnée se trouvent dans la propriété Lineage de son profil.

​

Comparaison avec l’API classique

Ceci étant posé, examinons les différences entre les API « classiques » et les API « d’entité ». Si vous utilisez les API classiques, vous travaillez déjà avec les mêmes entités que celles utilisables avec les API d’entité, mais elles ne sont pas toujours explicites. Par exemple, dans l’API Client, UpdateUserData opère sur une entité title_player_account, GetUserPublisherData opère sur un master_player_account, GetCharacterStatistics opère sur un character (enfant du title_player_account), GetTitleData opère sur un titre et GetPublisherData opère sur un namespace. En général, chaque API classique opère sur un type d’entité spécifique, mais le type d’entité est souvent implicite et ne découle pas nécessairement du nom de l’API. De plus, les API équivalentes pour deux types d’entités peuvent différer subtilement en ce qui concerne leurs paramètres, leurs limites et leur comportement (par exemple, UpdatePlayerStatistics par rapport à UpdateCharacterStatistics). Si cela vous semble déroutant, vous n’êtes pas seul. Nous voulions simplifier les API PlayFab sans jamais rompre la compatibilité avec l’ensemble existant, ce qui nous amène à… « API d’entité » est le nom que nous donnons aux API PlayFab plus récentes, qui respectent les objectifs de conception suivants (à quelques exceptions près).

• Fonctionner avec des types d’entités arbitraires.
• Disposer de paramètres explicites pour le Type et l’Id de l’entité.
• Effectuer une opération spécifique sur une ressource spécifique du profil d’entité.
• Pouvoir être appelées dans plusieurs contextes de sécurité, par exemple depuis des clients de jeu, des serveurs de jeu, Cloud Script et des serveurs principaux, avec des autorisations définies par des stratégies et sélectionnées en fonction de l’entité qui appelle l’API.

Nous pensons que le respect de ces principes aboutira à moins d’API qui en font davantage, qui sont plus efficaces à maintenir et à exploiter, et plus faciles à apprendre pour les développeurs. En somme, c’est ainsi que nous concevrions toutes les API PlayFab si nous devions recommencer, en tirant parti de tout ce que nous avons appris au cours des cinq dernières années sur la façon dont les développeurs utilisent PlayFab. Bien entendu, l’un de nos principes les plus importants chez PlayFab est de ne jamais casser les titres en production, dans la mesure du possible, ce qui signifie que nous devons maintenir la rétrocompatibilité avec toutes les API publiées.

​

Considérations pour les utilisateurs de l’API classique

Pour atteindre nos objectifs de conception tout en préservant la compatibilité, nous avons généralement introduit ces API d’entité sous forme d’ensemble distinct, coexistant avec les API classiques. Bien que les API d’entité puissent fonctionner avec les mêmes entités que les API classiques, dans la plupart des cas, elles opèrent sur un ensemble distinct de ressources/données appartenant à ces entités. Par exemple, l’API d’entité SetObjects et l’API classique UpdateUserData peuvent toutes deux stocker des données sous une entité title_player_account, mais les données que les deux API « voient » sont distinctes. Voici quelques-unes des implications pratiques :

​

Les inconvénients

• Si votre titre utilise déjà les API classiques pour les données de joueur, les inventaires et d’autres ressources (également appelés title_player_account), ces données existantes n’apparaîtront pas automatiquement dans les API d’entité équivalentes.
• Il faut un certain temps pour que les API d’entité atteignent la parité fonctionnelle avec les API classiques. Les données sont stockées séparément dans la plupart des cas, et de nombreuses modifications côté serveur sont nécessaires pour les prendre en charge. Certaines fonctionnalités classiques pourraient ne jamais être intégrées à l’API d’entité.

​

Les avantages

• Vous n’avez rien à faire. Si votre jeu fonctionne déjà bien avec les API classiques de PlayFab, il continue de fonctionner.
• Vous pouvez commencer à utiliser les API d’entité tout en continuant à utiliser les API classiques sur le même ensemble d’entités. Dans certaines situations, cela présente des avantages évidents pour un coût minime. Par exemple, vous pouvez ajouter une fonctionnalité qui enregistre de plus grandes quantités de données dans un fichier, en plus des paramètres existants stockés dans les « données de joueur » classiques.

​

Vue d’ensemble des fonctionnalités

Le modèle de programmation des entités est le fondement de la prochaine génération de services de données et de jeu de PlayFab.

• Authentification
• Profils
• Groupes
• Données - Fichier
• Données - Objet
• Événements
• CloudScript
• Multijoueur

​

Types d’entités pris en charge

La liste suivante décrit les types d’entités disponibles, qui peuvent être utilisés pour construire une EntityKey. Les clés d’entité servent à identifier les entités dans la plupart des méthodes d’API récentes. Ces valeurs sont destinées à être utilisées dans le champ EntityKey.Type.

​

namespace

L’entité namespace représente l’identité de joueur inter-titres et la portée des données partagées. Par défaut, elle couvre tous les titres d’un studio. L’espace de noms est distinct du studio, qui est un regroupement administratif. Pour plus d’informations, consultez Concepts PlayFab. Certaines API utilisent l’ancien terme publisher pour désigner cette portée. Le Publisher ID identifie l’espace de noms. Définissez le champ ID sur votre GamePublisherId. Pour récupérer votre GamePublisherId :

• Connectez-vous à Game Manager.
• Sur la page My Studios and Titles, sélectionnez le titre approprié.
• Sélectionnez l’icône d’engrenage dans le coin gauche de la page du titre, puis sélectionnez Title Settings.
• Sélectionnez l’onglet API Features.

Le Publisher ID de la page API Features correspond à votre GamePublisherId et à l’ID de l’espace de noms.

​

title

L’entité title représente les informations globales limitées à un titre. Un titre est une ressource PlayFab isolée destinée à un jeu ou à un environnement de jeu. Définissez le champ ID sur le TitleId de votre jeu. Pour récupérer votre TitleId :

• Connectez-vous à Game Manager.
• Sur la page My Studios and Titles, repérez votre titre.

Le Title ID apparaît sous le nom de votre titre.

​

master_player_account

Le master_player_account est une entité de joueur partagée par tous les titres d’un espace de noms. Définissez le champ ID sur le PlayFabId de l’API classique, renvoyé par tout LoginResult.PlayFabId.

​

title_player_account

Pour la plupart des développeurs, title_player_account représente le joueur de la manière la plus traditionnelle. Définissez le champ ID sur LoginResult.EntityToken.Id dans l’API Client, ou sur GetEntityTokenResponse.Entity.Id dans l’API Authentication.

​

character

Le character est une sous-entité de title_player_account et reflète directement les personnages des API classiques. Définissez le champ ID sur n’importe quel characterId issu de result.Characters[i].CharacterId.

​

group

Le group est une entité qui contient d’autres entités. Il est actuellement limité aux joueurs et aux personnages. Définissez le champ ID sur result.Group.Id si vous créez un groupe, ou sur result.Groups[i].Group.Id lorsque vous listez vos appartenances.

​

game_server

L’entité game_server est une entité unique utilisée par les serveurs de jeu, principalement pour les fonctionnalités Matchmaking et Lobby. D’autres scénarios pourront être ajoutés à l’avenir pour prendre en charge d’autres fonctionnalités PlayFab. Cette entité donne aux serveurs de jeu leur propre identité, ce qui permet de les identifier de manière unique pour s’abonner aux mises à jour en temps réel de Matchmaking et Lobby, ainsi que de prendre en charge des fonctionnalités spécifiques comme la migration du propriétaire de lobby. Pour vous authentifier en tant qu’entité game_server, appelez l’API AuthenticateGameServerWithCustomId en tant qu’entité de titre et récupérez la paire clé d’entité et jeton game_server. Utilisez cette clé d’entité lorsque vous utilisez le SDK PlayFab Multiplayer avec PFMultiplayerSetEntityToken.