> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Démarrage rapide des entités

> Commencez à utiliser les entités PlayFab en C# Unity : authentifiez-vous pour obtenir une EntityKey, puis lisez et écrivez des objets et des fichiers d'entité avec des exemples du SDK.

Ce démarrage rapide sur les entités montre comment utiliser les objets d'entité et les fichiers d'entité.

Pour plus de renseignements 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](https://docs.xbox.com/fr-CA/services/playfab/live-service-management/game-configuration/entities/migration-information.md).

## Configuration requise

* Un [compte de développeur PlayFab](https://developer.playfab.com).
* Une copie installée de l'éditeur Unity. Pour plus de renseignements sur l'installation de l'éditeur Unity, consultez [Installing Unity](https://docs.unity3d.com/Manual/GettingStartedInstallingUnity.html) dans la documentation Unity. Vous pouvez également installer une version d'Unity à l'aide du programme d'installation des fonctionnalités de Visual Studio.

> [!NOTE]
>
> Le SDK PlayFab Unity3D prend en charge l'éditeur Unity version 5.3 et ultérieure.

* Un projet Unity. Pour plus de renseignements sur la création d'un projet Unity, consultez [le guide de démarrage rapide](https://docs.unity3d.com/Manual/Quickstart3D.html).

> [!NOTE]
>
> 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 de renseignements, consultez [Programmation asynchrone avec async et await](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/).

## 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](xref:titleid.playfabapi.com.client.title-widedatamanagement.gettitledata). 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, retourné lors de toute connexion ou de tout appel visant à récupérer les informations du compte de joueur (p. ex., l'API Client PlayFab [GetAccountInfo](xref:titleid.playfabapi.com.client.accountmanagement.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`) retourné dans l'objet [EntityKey](xref:titleid.playfabapi.com.authentication.authentication.getentitytoken#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 de renseignements sur les types d'entités intégrés, consultez [Types d'entités intégrés disponibles](https://docs.xbox.com/fr-CA/services/playfab/live-service-management/game-configuration/entities/available-built-in-entity-types.md).

## 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](xref:titleid.playfabapi.com.authentication.authentication.getentitytoken#entitykey).

Pour ce faire, appelez l'une des méthodes de connexion, telle que `LoginWithCustomID`.

```csharp theme={null}
    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](xref:titleid.playfabapi.com.authentication.authentication.getentitytoken).

```csharp theme={null}
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](xref:titleid.playfabapi.com.data.object.setobjects) pour définir des objets d'entité sur un joueur ou un titre.

```csharp theme={null}
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](xref:titleid.playfabapi.com.data.object.getobjects) pour récupérer les objets d'entité d'un joueur ou d'un titre.

```csharp theme={null}
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](xref:titleid.playfabapi.com.data.file.getfiles) pour récupérer les fichiers d'entité.

```csharp theme={null}
    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](xref:titleid.playfabapi.com.data.file.initiatefileuploads) pour lancer le téléversement d'un fichier dans le profil d'une entité.

```csharp theme={null}
    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](xref:titleid.playfabapi.com.data.file.abortfileuploads) pour annuler un téléversement de fichier en attente dans le profil d'une entité.

```csharp theme={null}
    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](xref:titleid.playfabapi.com.data.file.finalizefileuploads) pour finaliser les téléversements de fichiers dans le profil d'une entité. Le système d'entités ne considère pas le téléversement du fichier comme terminé et ne reflète aucune modification pour les autres appelants tant que l'opération de téléversement atomique n'a pas été finalisée avec succès.

```csharp theme={null}
    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 au téléversement 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 téléversement atomique.
* Téléverser tous les fichiers.
* Finaliser l'opération de téléversement atomique.

Par souci de simplicité, cet exemple enregistre un fichier à la fois, mais les fichiers peuvent être téléversés de façon atomique par lots.

L'exemple suppose que vous savez utiliser le moteur Unity 3D.

```csharp theme={null}
#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
```

> [!NOTE]
>
> 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](https://mintcdn.com/microsoft-4404708b/3hg2JQs0m7qmDqay/images/playfab/live-service-management/game-configuration/entities/tutorials/game-manager-entities-player-overview.png?fit=max\&auto=format\&n=3hg2JQs0m7qmDqay\&q=85\&s=ceac36d3b1e7fd248caeedbf4bea8055)

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](https://mintcdn.com/microsoft-4404708b/3hg2JQs0m7qmDqay/images/playfab/live-service-management/game-configuration/entities/tutorials/game-manager-entities-player-files.png?fit=max\&auto=format\&n=3hg2JQs0m7qmDqay\&q=85\&s=70b96669460d8bb673ec25fdbcd1bd41)

## Voir aussi

[Introducing Entities, Objects and Files](https://blog.playfab.com/blog/introducing-entities-objects-and-files) sur le blog PlayFab.


## Related topics

- [Démarrage rapide des classements](https://docs.xbox.com/fr-CA/services/playfab/community/leaderboards/quickstart-leaderboards.md)
- [Informations de migration vers les entités](https://docs.xbox.com/fr-CA/services/playfab/live-service-management/game-configuration/entities/migration-information.md)
- [Démarrage rapide des statistiques](https://docs.xbox.com/fr-CA/services/playfab/player-progression/statistics/quickstart-statistics.md)
- [Démarrage rapide des propriétés personnalisées de joueur](https://docs.xbox.com/fr-CA/services/playfab/live-service-management/game-configuration/segmentation/player-custom-properties-qs.md)
- [Démarrage rapide (Windows) - Appel des services PlayFab](https://docs.xbox.com/fr-CA/services/playfab/sdks/unified-sdk/quickstart-services.md)