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

# Groupes d'entités

> Découvrez comment les groupes d'entités PlayFab modélisent les guildes, les clans, les groupes et les canaux de clavardage, avec des rôles de membres, des invitations et des données d'objets et de fichiers partagées.

Supposons que vous ayez besoin de guildes, de clans, de corporations, d'entreprises, de tribus, ou peu importe comment votre jeu les appelle : PlayFab peut répondre à votre besoin de regroupement durable de joueurs grâce au [modèle de programmation d'entités](/fr-CA/services/playfab/live-service-management/game-configuration/entities).

L'entité de groupe peut servir à stocker des collections d'autres entités, y compris des joueurs ou des personnages, qui peuvent répondre à de nombreux besoins dans votre jeu.

## Exemples

* **Clans/Guildes** - Les groupes d'entités peuvent servir à décrire un ensemble de joueurs qui jouent ensemble régulièrement, quel que soit le lien social qui les unit à long terme.

* **Groupes** - Les groupes d'entités peuvent servir à des groupes à court terme créés pour permettre à des joueurs individuels d'atteindre un objectif immédiat, puis facilement dissous par la suite.

* **Canaux de clavardage** - Des canaux de clavardage à court ou à long terme peuvent être définis comme groupe d'entités.

* **Abonnement à de l'information dans le jeu** - Avez-vous un objet légendaire à instance unique dans votre jeu? Les joueurs veulent-ils des mises à jour constantes sur ce qui arrive à cet objet? Créez un groupe d'entités axé sur cet objet, dont les membres sont toutes les entités de joueurs qui s'intéressent à l'objet.

En bref, les groupes d'entités peuvent être *n'importe quelle* collection d'entités (contrôlées par un PNJ ou par un joueur, réelles ou abstraites) qui nécessitent un état persistant lié à ce groupe.

De plus, puisque les groupes d'entités sont eux-mêmes des entités, ils contiennent toutes les fonctionnalités initiales des entités :

* **Données d'objet**
* **Données de fichier**
* **Profils**

<Note>
  Les groupes ont une limite par défaut de 1 000 membres par groupe et ne prennent en charge que les joueurs et les personnages comme membres
</Note>

## Utilisation des groupes d'entités

Lors de la création d'un groupe, la première entité ajoutée au groupe se voit attribuer un rôle d'administrateur (Admin) (par souci de simplicité, ce guide désigne cette entité comme le propriétaire). Le propriétaire pourra ensuite inviter de nouveaux membres, créer de nouveaux rôles avec une grande variété d'autorisations personnalisables, modifier les rôles des membres, expulser des membres, etc.

De plus, les mêmes fonctions d'entité qui existent pour les entités *fonctionnent également pour les groupes*, ce qui vous permet d'enregistrer des objets JSON et des fichiers directement dans le groupe pour conserver des données arbitraires propres au jeu.

L'exemple de code fourni ci-dessous devrait vous donner une longueur d'avance sur les interactions de base avec les guildes.

Il vous permet de créer des groupes, d'ajouter et de retirer des membres, et de supprimer le groupe. Il s'agit d'un point de départ, et il ne présente aucun des rôles ni des autorisations.

```csharp theme={null}
using PlayFab;
using PlayFab.GroupsModels;
using System;
using System.Collections.Generic;
using UnityEngine;

namespace TestGuildController
{
    /// <summary>
    /// Assumptions for this controller:
    /// + Entities can be in multiple groups
    ///   - This is game specific, many games would only allow 1 group, meaning you'd have to perform some additional checks to validate this.
    /// </summary>
    [Serializable]
    public class GuildTestController
    {
        // A local cache of some bits of PlayFab data
        // This cache pretty much only serves this example , and assumes that entities are uniquely identifiable by EntityId alone, which isn't technically true. Your data cache will have to be better.
        public readonly HashSet<KeyValuePair<string, string>> EntityGroupPairs = new HashSet<KeyValuePair<string, string>>();
        public readonly Dictionary<string, string> GroupNameById = new Dictionary<string, string>();

        public static EntityKey EntityKeyMaker(string entityId)
        {
            return new EntityKey { Id = entityId };
        }

        private void OnSharedError(PlayFab.PlayFabError error)
        {
            Debug.LogError(error.GenerateErrorReport());
        }

        public void ListGroups(EntityKey entityKey)
        {
            var request = new ListMembershipRequest { Entity = entityKey };
            PlayFabGroupsAPI.ListMembership(request, OnListGroups, OnSharedError);
        }
        private void OnListGroups(ListMembershipResponse response)
        {
            var prevRequest = (ListMembershipRequest)response.Request;
            foreach (var pair in response.Groups)
            {
                GroupNameById[pair.Group.Id] = pair.GroupName;
                EntityGroupPairs.Add(new KeyValuePair<string, string>(prevRequest.Entity.Id, pair.Group.Id));
            }
        }

        public void CreateGroup(string groupName, EntityKey entityKey)
        {
            // A player-controlled entity creates a new group
            var request = new CreateGroupRequest { GroupName = groupName, Entity = entityKey };
            PlayFabGroupsAPI.CreateGroup(request, OnCreateGroup, OnSharedError);
        }
        private void OnCreateGroup(CreateGroupResponse response)
        {
            Debug.Log("Group Created: " + response.GroupName + " - " + response.Group.Id);

            var prevRequest = (CreateGroupRequest)response.Request;
            EntityGroupPairs.Add(new KeyValuePair<string, string>(prevRequest.Entity.Id, response.Group.Id));
            GroupNameById[response.Group.Id] = response.GroupName;
        }
        public void DeleteGroup(string groupId)
        {
            // A title, or player-controlled entity with authority to do so, decides to destroy an existing group
            var request = new DeleteGroupRequest { Group = EntityKeyMaker(groupId) };
            PlayFabGroupsAPI.DeleteGroup(request, OnDeleteGroup, OnSharedError);
        }
        private void OnDeleteGroup(EmptyResponse response)
        {
            var prevRequest = (DeleteGroupRequest)response.Request;
            Debug.Log("Group Deleted: " + prevRequest.Group.Id);

            var temp = new HashSet<KeyValuePair<string, string>>();
            foreach (var each in EntityGroupPairs)
                if (each.Value != prevRequest.Group.Id)
                    temp.Add(each);
            EntityGroupPairs.IntersectWith(temp);
            GroupNameById.Remove(prevRequest.Group.Id);
        }

        public void InviteToGroup(string groupId, EntityKey entityKey)
        {
            // A player-controlled entity invites another player-controlled entity to an existing group
            var request = new InviteToGroupRequest { Group = EntityKeyMaker(groupId), Entity = entityKey };
            PlayFabGroupsAPI.InviteToGroup(request, OnInvite, OnSharedError);
        }
        public void OnInvite(InviteToGroupResponse response)
        {
            var prevRequest = (InviteToGroupRequest)response.Request;

            // Presumably, this would be part of a separate process where the recipient reviews and accepts the request
            var request = new AcceptGroupInvitationRequest { Group = EntityKeyMaker(prevRequest.Group.Id), Entity = prevRequest.Entity };
            PlayFabGroupsAPI.AcceptGroupInvitation(request, OnAcceptInvite, OnSharedError);
        }
        public void OnAcceptInvite(EmptyResponse response)
        {
            var prevRequest = (AcceptGroupInvitationRequest)response.Request;
            Debug.Log("Entity Added to Group: " + prevRequest.Entity.Id + " to " + prevRequest.Group.Id);
            EntityGroupPairs.Add(new KeyValuePair<string, string>(prevRequest.Entity.Id, prevRequest.Group.Id));
        }

        public void ApplyToGroup(string groupId, EntityKey entityKey)
        {
            // A player-controlled entity applies to join an existing group (of which they are not already a member)
            var request = new ApplyToGroupRequest { Group = EntityKeyMaker(groupId), Entity = entityKey };
            PlayFabGroupsAPI.ApplyToGroup(request, OnApply, OnSharedError);
        }
        public void OnApply(ApplyToGroupResponse response)
        {
            var prevRequest = (ApplyToGroupRequest)response.Request;

            // Presumably, this would be part of a separate process where the recipient reviews and accepts the request
            var request = new AcceptGroupApplicationRequest { Group = prevRequest.Group, Entity = prevRequest.Entity };
            PlayFabGroupsAPI.AcceptGroupApplication(request, OnAcceptApplication, OnSharedError);
        }
        public void OnAcceptApplication(EmptyResponse response)
        {
            var prevRequest = (AcceptGroupApplicationRequest)response.Request;
            Debug.Log("Entity Added to Group: " + prevRequest.Entity.Id + " to " + prevRequest.Group.Id);
        }
        public void KickMember(string groupId, EntityKey entityKey)
        {
            var request = new RemoveMembersRequest { Group = EntityKeyMaker(groupId), Members = new List<EntityKey> { entityKey } };
            PlayFabGroupsAPI.RemoveMembers(request, OnKickMembers, OnSharedError);
        }
        private void OnKickMembers(EmptyResponse response)
        {
            var prevRequest= (RemoveMembersRequest)response.Request;
            
            Debug.Log("Entity kicked from Group: " + prevRequest.Members[0].Id + " to " + prevRequest.Group.Id);
            EntityGroupPairs.Remove(new KeyValuePair<string, string>(prevRequest.Members[0].Id, prevRequest.Group.Id));
        }
    }
}
```

## Analyse de l'exemple

Cet exemple est conçu comme un contrôleur, qui enregistre un minimum de données dans un cache local (PlayFab étant la couche de données faisant autorité), et offre un moyen d'effectuer des opérations CRUD sur les groupes.

Examinons certaines des fonctions de l'exemple fourni :

* `OnSharedError` - Il s'agit d'un modèle typique des exemples PlayFab. La façon la plus simple de gérer une erreur est de la signaler. Votre client de jeu aura probablement une logique de gestion des erreurs beaucoup plus sophistiquée.

* `ListMembership` - Cette fonction appelle `ListMembership` pour déterminer tous les groupes auxquels appartient l'entité donnée. Les joueurs veulent connaître les groupes dont ils font déjà partie.

* `CreateGroup`/`DeleteGroup` - Ces fonctions parlent d'elles-mêmes. Cet exemple montre la mise à jour du cache local d'information sur les groupes lorsque ces appels sont exécutés avec succès.

* `InviteToGroup`/`ApplyToGroup` - Se joindre à un groupe est un processus en deux étapes, qui peut être lancé dans les deux sens :
  * Un joueur peut demander à se joindre à un groupe.
  * Un groupe peut inviter un joueur.

* `AcceptGroupInvitation`/`AcceptGroupApplication` - La deuxième étape du processus d'adhésion. L'entité qui répond accepte l'invitation, ce qui complète le processus visant à faire du joueur un membre du groupe.

* `RemoveMembers` - Les membres qui en ont l'autorité (définie par les autorisations de leur rôle) pourront expulser des membres d'un groupe.

## Serveur ou client

Comme pour toutes les nouvelles méthodes d'API d'entités, il n'y a aucune distinction entre l'API serveur et l'API client.

L'action est effectuée par l'appelant, selon la façon dont le processus a été authentifié. Un client sera identifié comme tel et appellera ces méthodes en tant qu'entité de joueur du titre; ses rôles et autorisations au sein du groupe seront évalués à chaque appel, afin de s'assurer qu'il a l'autorisation d'effectuer cette action.

Un serveur est authentifié avec la même `developerSecretKey`, qui identifie ce processus comme une entité de titre. Un titre contourne les vérifications de rôle, et les appels d'API exécutés par un titre n'échoueront que si l'action est impossible à effectuer, par exemple si une entité ne peut pas être retirée parce qu'elle n'est pas membre.

## Voir aussi

Pour stocker des données pour vos groupes, guildes ou clans :

* [Objets](/fr-CA/services/playfab/live-service-management/game-configuration/entities/entity-objects)
* [Fichiers](/fr-CA/services/playfab/live-service-management/game-configuration/entities/entity-files)


## Related topics

- [Fichiers d'entité](/fr-CA/services/playfab/live-service-management/game-configuration/entities/entity-files.md)
- [Types d'entités intégrés disponibles](/fr-CA/services/playfab/live-service-management/game-configuration/entities/available-built-in-entity-types.md)
- [PlayStream avec les événements d'entité](/fr-CA/services/playfab/data-analytics/ingest-data/playstream-with-entity-events.md)
- [Tutoriel de mise à niveau suite à la restructuration de l'API d'entité](/fr-CA/services/playfab/live-service-management/game-configuration/entities/entity-api-restructure-upgrade-tutorial.md)
- [Utiliser des objets d'entité pour stocker des données de joueur](/fr-CA/services/playfab/live-service-management/game-configuration/entities/entity-objects.md)