Démarrage rapide des entités - XBOX Game Development Documentation

Ce démarrage rapide sur les entités montre comment utiliser les objets d’entité et les fichiers d’entité. Pour plus d’informations sur la migration des anciens systèmes de compte et de données vers les entités PlayFab, consultez Informations de migration vers les entités.

Configuration requise

Un compte de développeur PlayFab.
Une copie installée de l’éditeur Unity. Pour plus d’informations sur l’installation de l’éditeur Unity, consultez Installing Unity dans la documentation Unity. Vous pouvez également installer une version d’Unity à l’aide du programme d’installation des fonctionnalités de Visual Studio.

Le SDK PlayFab Unity3D prend en charge l’éditeur Unity version 5.3 et ultérieure.

Un projet Unity. Pour plus d’informations sur la création d’un projet Unity, consultez le guide de démarrage rapide.

Si vous ne connaissez pas Unity, les packages d’installation récents vous proposent d’installer des procédures pas à pas de création de jeux. Vous pouvez utiliser l’une de ces procédures pour créer un exemple de jeu à utiliser dans le démarrage rapide suivant.

Le SDK PlayFab Unity3D.

Les exemples C# de cet article sont écrits pour le SDK Unity. Le SDK Unity utilise un modèle piloté par les événements pour gérer les tâches non synchrones. Pour exécuter l’exemple de code avec le SDK C#, vous devez modifier le code pour utiliser un modèle de tâches asynchrones. Les méthodes à modifier ont le suffixe Async ajouté à leur nom dans la signature. Par exemple, SetObject dans le SDK Unity devient SetObjectAsync dans le SDK C#. Pour plus d’informations, consultez Programmation asynchrone avec async et await.

Terminologie

Les entités désignent tout concept PlayFab pouvant contenir des données. Les types d’entités intégrés sont les suivants :

title : un titre contient des informations globales accessibles à tous les joueurs. Ceci est similaire à TitleData. Il est identifié par l’ID de titre (TitleId) du jeu ou de l’application.
master_player_account : ce type d’entité vous permet de partager des informations sur un joueur entre plusieurs jeux d’un espace de noms. Il est identifié par l’ID de joueur (PlayFabId) du joueur, renvoyé lors de toute connexion ou de tout appel visant à récupérer les informations du compte de joueur (par exemple, l’API Client PlayFab GetAccountInfo).
title_player_account : identifie un compte de joueur qui contient des informations pour le titre actuel. Il est identifié par l’ID d’entité (EntityKey.Id) renvoyé dans l’objet EntityKey lors de toute connexion.
character : identifie un personnage appartenant au joueur, qui contient des informations que vous pouvez récupérer. Il est identifié par l’ID de personnage (CharacterId) du personnage.

Pour plus d’informations sur les types d’entités intégrés, consultez Types d’entités intégrés disponibles.

Initialisation des entités

Pour appeler l’une des API d’entité, vous devez obtenir l’ID et le Type de l’entité. Vous utilisez l’ID et le Type pour appeler d’autres méthodes de l’API d’entité. Ce sont des membres d’un objet EntityKey. Pour ce faire, appelez l’une des méthodes de connexion, telle que LoginWithCustomID.

    void Login()
    {
        var request = new PlayFab.ClientModels.LoginWithCustomIDRequest
        {
            CustomId = SystemInfo.deviceUniqueIdentifier,
            CreateAccount = true,
        };
        PlayFabClientAPI.LoginWithCustomID(request, OnLogin, OnSharedFailure);
    }

    void OnLogin(PlayFab.ClientModels.LoginResult result)
    {
        entityId = result.EntityToken.Entity.Id;
        // The expected entity type is title_player_account.
        entityType = result.EntityToken.Entity.Type;
    }

Vous pouvez également obtenir l’ID et le Type de l’entité en appelant la méthode GetEntityToken.

PlayFabAuthenticationAPI.GetEntityToken(new GetEntityTokenRequest(),
(entityResult) =>
{
    var entityId = entityResult.Entity.Id;
    var entityType = entityResult.Entity.Type;
}, OnPlayFabError); // Define your own OnPlayFabError function to report errors

Lorsque cette méthode est appelée depuis le client, elle représente généralement le joueur connecté. Lorsqu’elle est appelée depuis des serveurs de jeu, elle représente votre titre.

Objets d’entité

Les objets d’entité vous permettent de lire et d’écrire de petits objets sérialisables en JSON attachés à une entité. Tous les types d’entités prennent en charge les méthodes GetObjects et SetObjects. Les extraits de code suivants montrent comment définir et lire un Object sur une entité title_player_account. Utilisez la méthode SetObjects pour définir des objets d’entité sur un joueur ou un titre.

var data = new Dictionary<string, object>()
{
    {"Health", 100},
    {"Mana", 10000}
};
var dataList = new List<SetObject>()
{
    new SetObject()
    {
        ObjectName = "PlayerData",
        DataObject = data
    },
    // A free-tier customer may store up to 3 objects on each entity
};

PlayFabDataAPI.SetObjects(new SetObjectsRequest()
{
    Entity = new EntityKey {Id = entityId, Type = entityType}, // Saved from GetEntityToken, or a specified key created from a titlePlayerId, CharacterId, etc
    Objects = dataList,
}, (setResult) => {
    Debug.Log(setResult.ProfileVersion);
}, OnPlayFabError);

Utilisez la méthode GetObjects pour récupérer les objets d’entité d’un joueur ou d’un titre.

var getRequest = new GetObjectsRequest {Entity = new EntityKey {Id = entityId, Type = entityType}};
PlayFabDataAPI.GetObjects(getRequest,
    result => { var objs = result.Objects; },
    OnPlayFabError
);

Fichiers d’entité

Les fichiers d’entité vous permettent de lire et d’écrire des fichiers de tout format attachés à une entité. Utilisez la méthode GetFiles pour récupérer les fichiers d’entité.

    void LoadAllFiles()
    {
        if (GlobalFileLock != 0)
            throw new Exception("This example overly restricts file operations for safety. Careful consideration must be made when doing multiple file operations in parallel to avoid conflict.");

        GlobalFileLock += 1; // Start GetFiles
        var request = new PlayFab.DataModels.GetFilesRequest { Entity = new PlayFab.DataModels.EntityKey { Id = entityId, Type = entityType } };
        PlayFabDataAPI.GetFiles(request, OnGetFileMeta, OnSharedFailure);
    }

Utilisez la méthode initiatefileuploads pour lancer le chargement d’un fichier dans le profil d’une entité.

    void UploadFile(string fileName)
    {
        if (GlobalFileLock != 0)
            throw new Exception("This example overly restricts file operations for safety. Careful consideration must be made when doing multiple file operations in parallel to avoid conflict.");

        ActiveUploadFileName = fileName;

        GlobalFileLock += 1; // Start InitiateFileUploads
        var request = new PlayFab.DataModels.InitiateFileUploadsRequest
        {
            Entity = new PlayFab.DataModels.EntityKey { Id = entityId, Type = entityType },
            FileNames = new List<string> { ActiveUploadFileName },
        };
        PlayFabDataAPI.InitiateFileUploads(request, OnInitFileUpload, OnInitFailed);
    }

Utilisez la méthode AbortFileUploads pour annuler un chargement de fichier en attente dans le profil d’une entité.

    void OnInitFailed(PlayFabError error)
    {
        if (error.Error == PlayFabErrorCode.EntityFileOperationPending)
        {
            // This is an error you should handle when calling InitiateFileUploads, but your resolution path may vary
            GlobalFileLock += 1; // Start AbortFileUploads
            var request = new PlayFab.DataModels.AbortFileUploadsRequest
            {
                Entity = new PlayFab.DataModels.EntityKey { Id = entityId, Type = entityType },
                FileNames = new List<string> { ActiveUploadFileName },
            };
            PlayFabDataAPI.AbortFileUploads(request, (result) => { GlobalFileLock -= 1; UploadFile(ActiveUploadFileName); }, OnSharedFailure); GlobalFileLock -= 1; // Finish AbortFileUploads
            GlobalFileLock -= 1; // Failed InitiateFileUploads
        }
        else
            OnSharedFailure(error);
    }

Utilisez la méthode FinalizeFileUploads pour finaliser les chargements de fichiers dans le profil d’une entité. Le système d’entités ne considère pas le chargement du fichier comme terminé et ne reflète aucune modification pour les autres appelants tant que l’opération de chargement atomique n’a pas été finalisée avec succès.

    void FinalizeUpload(byte[] data)
    {
        GlobalFileLock += 1; // Start FinalizeFileUploads
        var request = new PlayFab.DataModels.FinalizeFileUploadsRequest
        {
            Entity = new PlayFab.DataModels.EntityKey { Id = entityId, Type = entityType },
            FileNames = new List<string> { ActiveUploadFileName },
        };
        PlayFabDataAPI.FinalizeFileUploads(request, OnUploadSuccess, OnSharedFailure);
        GlobalFileLock -= 1; // Finish SimplePutCall
    }

L’exemple ci-dessous illustre une boucle complète de fichiers d’entité, de la connexion au chargement d’un fichier, puis à l’envoi d’un nouveau fichier. Les étapes sont les suivantes :

Se connecter et récupérer l’ID et le Type de l’entité.
Initialiser l’opération de chargement atomique.
Charger tous les fichiers.
Finaliser l’opération de chargement atomique.

Par souci de simplicité, cet exemple enregistre un fichier à la fois, mais les fichiers peuvent être chargés de manière atomique par lots. L’exemple suppose que vous savez utiliser le moteur Unity 3D.

#if !DISABLE_PLAYFABENTITY_API && !DISABLE_PLAYFABCLIENT_API

using PlayFab;
using PlayFab.Internal;
using System;
using System.Collections.Generic;
using System.Text;
using UnityEngine;

public class EntityFileExample : MonoBehaviour
{
    public string entityId; // Id representing the logged in player
    public string entityType; // entityType representing the logged in player
    private readonly Dictionary<string, string> _entityFileJson = new Dictionary<string, string>();
    private readonly Dictionary<string, string> _tempUpdates = new Dictionary<string, string>();
    public string ActiveUploadFileName;
    public string NewFileName;
    // GlobalFileLock provides is a simplistic way to avoid file collisions, specifically designed for this example.
    public int GlobalFileLock = 0;

    void OnSharedFailure(PlayFabError error)
    {
        Debug.LogError(error.GenerateErrorReport());
        GlobalFileLock -= 1;
    }

    // OnGUI provides a way to build a Unity GUI entirely within script.
    // Your GUI will be game-specific.
    void OnGUI()
    {
        if (!PlayFabClientAPI.IsClientLoggedIn() && GUI.Button(new Rect(0, 0, 100, 30), "Login"))
            Login();
        if (PlayFabClientAPI.IsClientLoggedIn() && GUI.Button(new Rect(0, 0, 100, 30), "LogOut"))
            PlayFabClientAPI.ForgetAllCredentials();

        if (PlayFabClientAPI.IsClientLoggedIn() && GUI.Button(new Rect(100, 0, 100, 30), "(re)Load Files"))
            LoadAllFiles();

        if (PlayFabClientAPI.IsClientLoggedIn())
        {
            // Display existing files
            _tempUpdates.Clear();
            var index = 0;
            foreach (var each in _entityFileJson)
            {
                GUI.Label(new Rect(100 * index, 60, 100, 30), each.Key);
                var tempInput = _entityFileJson[each.Key];
                var tempOutput = GUI.TextField(new Rect(100 * index, 90, 100, 30), tempInput);
                if (tempInput != tempOutput)
                    _tempUpdates[each.Key] = tempOutput;
                if (GUI.Button(new Rect(100 * index, 120, 100, 30), "Save " + each.Key))
                    UploadFile(each.Key);
                index++;
            }
            // Apply any changes
            foreach (var each in _tempUpdates)
                _entityFileJson[each.Key] = each.Value;

            // Add a new file
            NewFileName = GUI.TextField(new Rect(100 * index, 60, 100, 30), NewFileName);
            if (GUI.Button(new Rect(100 * index, 90, 100, 60), "Create " + NewFileName))
                UploadFile(NewFileName);
        }
    }

    void Login()
    {
        var request = new PlayFab.ClientModels.LoginWithCustomIDRequest
        {
            CustomId = SystemInfo.deviceUniqueIdentifier,
            CreateAccount = true,
        };
        PlayFabClientAPI.LoginWithCustomID(request, OnLogin, OnSharedFailure);
    }

    void OnLogin(PlayFab.ClientModels.LoginResult result)
    {
        entityId = result.EntityToken.Entity.Id;
        entityType = result.EntityToken.Entity.Type;
    }

    void LoadAllFiles()
    {
        if (GlobalFileLock != 0)
            throw new Exception("This example overly restricts file operations for safety. Careful consideration must be made when doing multiple file operations in parallel to avoid conflict.");

        GlobalFileLock += 1; // Start GetFiles
        var request = new PlayFab.DataModels.GetFilesRequest { Entity = new PlayFab.DataModels.EntityKey { Id = entityId, Type = entityType } };
        PlayFabDataAPI.GetFiles(request, OnGetFileMeta, OnSharedFailure);
    }

    void OnGetFileMeta(PlayFab.DataModels.GetFilesResponse result)
    {
        Debug.Log("Loading " + result.Metadata.Count + " files");

        _entityFileJson.Clear();
        foreach (var eachFilePair in result.Metadata)
        {
            _entityFileJson.Add(eachFilePair.Key, null);
            GetActualFile(eachFilePair.Value);
        }
        GlobalFileLock -= 1; // Finish GetFiles
    }

    void GetActualFile(PlayFab.DataModels.GetFileMetadata fileData)
    {
        GlobalFileLock += 1; // Start Each SimpleGetCall
        PlayFabHttp.SimpleGetCall(fileData.DownloadUrl,
            result => { _entityFileJson[fileData.FileName] = Encoding.UTF8.GetString(result); GlobalFileLock -= 1; }, // Finish Each SimpleGetCall
            error => { Debug.Log(error); }
        );
    }

    void UploadFile(string fileName)
    {
        if (GlobalFileLock != 0)
            throw new Exception("This example overly restricts file operations for safety. Careful consideration must be made when doing multiple file operations in parallel to avoid conflict.");

        ActiveUploadFileName = fileName;

        GlobalFileLock += 1; // Start InitiateFileUploads
        var request = new PlayFab.DataModels.InitiateFileUploadsRequest
        {
            Entity = new PlayFab.DataModels.EntityKey { Id = entityId, Type = entityType },
            FileNames = new List<string> { ActiveUploadFileName },
        };
        PlayFabDataAPI.InitiateFileUploads(request, OnInitFileUpload, OnInitFailed);
    }

    void OnInitFailed(PlayFabError error)
    {
        if (error.Error == PlayFabErrorCode.EntityFileOperationPending)
        {
            // This is an error you should handle when calling InitiateFileUploads, but your resolution path may vary
            GlobalFileLock += 1; // Start AbortFileUploads
            var request = new PlayFab.DataModels.AbortFileUploadsRequest
            {
                Entity = new PlayFab.DataModels.EntityKey { Id = entityId, Type = entityType },
                FileNames = new List<string> { ActiveUploadFileName },
            };
            PlayFabDataAPI.AbortFileUploads(request, (result) => { GlobalFileLock -= 1; UploadFile(ActiveUploadFileName); }, OnSharedFailure); GlobalFileLock -= 1; // Finish AbortFileUploads
            GlobalFileLock -= 1; // Failed InitiateFileUploads
        }
        else
            OnSharedFailure(error);
    }

    void OnInitFileUpload(PlayFab.DataModels.InitiateFileUploadsResponse response)
    {
        string payloadStr;
        if (!_entityFileJson.TryGetValue(ActiveUploadFileName, out payloadStr))
            payloadStr = "{}";
        var payload = Encoding.UTF8.GetBytes(payloadStr);

        GlobalFileLock += 1; // Start SimplePutCall
        PlayFabHttp.SimplePutCall(response.UploadDetails[0].UploadUrl,
            payload,
            FinalizeUpload,
            error => { Debug.Log(error); }
        );
        GlobalFileLock -= 1; // Finish InitiateFileUploads
    }

    void FinalizeUpload(byte[] data)
    {
        GlobalFileLock += 1; // Start FinalizeFileUploads
        var request = new PlayFab.DataModels.FinalizeFileUploadsRequest
        {
            Entity = new PlayFab.DataModels.EntityKey { Id = entityId, Type = entityType },
            FileNames = new List<string> { ActiveUploadFileName },
        };
        PlayFabDataAPI.FinalizeFileUploads(request, OnUploadSuccess, OnSharedFailure);
        GlobalFileLock -= 1; // Finish SimplePutCall
    }
    void OnUploadSuccess(PlayFab.DataModels.FinalizeFileUploadsResponse result)
    {
        Debug.Log("File upload success: " + ActiveUploadFileName);
        GlobalFileLock -= 1; // Finish FinalizeFileUploads
    }
}
#endif

Chaque action sur un fichier nécessite de nombreuses étapes et plusieurs appels d’API ; n’essayez donc pas d’accéder au même fichier de plusieurs façons en même temps. Si vous êtes très prudent, vous n’aurez peut-être pas besoin de mécanisme de verrouillage. Si vous souhaitez faire quelque chose de compliqué, votre mécanisme de verrouillage pourrait être beaucoup plus complexe.

Game Manager et entités

Game Manager vous permet de manipuler les objets et les fichiers des joueurs. La vue d’ensemble du joueur affiche à la fois les informations du compte de joueur du titre et du compte de joueur principal.

Game Manager : entités, vue d'ensemble du joueur

En outre, les fichiers et les objets disposent désormais de leurs propres sections dans l’onglet Players.

Game Manager : entités, fichiers et objets du joueur

Voir aussi

Introducing Entities, Objects and Files sur le blog PlayFab.

​Configuration requise

​Terminologie

​Initialisation des entités

​Objets d’entité

​Fichiers d’entité

​Game Manager et entités

​Voir aussi

Configuration requise

Terminologie

Initialisation des entités

Objets d’entité

Fichiers d’entité

Game Manager et entités

Voir aussi