Remarque : les entités personnalisées sont une fonctionnalité du forfait Plus. Choisissez l'un des nombreux forfaits Plus (y compris le forfait Développement Plus à 5 $/mois) pour y accéder.
Avantages
Les entités personnalisées sont les versions optimisées des entités globales et usager. Elles intègrent toutes les fonctionnalités de nos systèmes d'entités standard (propriété, liste de contrôle d'accès, durée de vie et gestion des versions simultanées), ainsi que la prise en charge des index personnalisés (beaucoup plus rapide !) et de la migration de déploiement (plus pratique !). Nous les recommandons particulièrement pour les jeux de données volumineux avec de nombreux accès.
Les entités personnalisées sont similaires aux entités globales et aux entités usager, avec des avantages certains en termes de performances, grâce à la possibilité de créer des index personnalisés. Les index permettent une exécution efficace des requêtes. Sans eux, la base de données doit analyser chaque document d'une collection pour sélectionner ceux qui correspondent à la requête. Si un index approprié existe pour une requête, la base de données peut l'utiliser pour réduire le nombre de documents à inspecter.
Pour bénéficier de ces avantages, vous devez définir vos entités personnalisées à l'avance ; c'est là que nous attachons les métadonnées d'index, etc. En comparaison, les entités globales et les entités usager sont essentiellement "non typées".
Voici l'essentiel : il existe deux grandes classifications d'entités personnalisées : celles qui sont "détenues" (c'est-à-dire détenues par les utilisateurs) et celles qui ne le sont pas.
Les entités personnalisées non détenues ressemblent beaucoup aux entités globales (en particulier ce que nous appelons entités système - qui sont la propriété de l'application et non d'un utilisateur spécifique), elles incluent également la prise en charge de la migration des données d'application de déploiement - vous pouvez donc facilement transférer les données d'application mises à jour du développement vers la production.
Les entités personnalisées possédées, cependant, ressemblent beaucoup aux entités usager, vous obtenez tous les mêmes concepts que la confidentialité (elles sont privées pour les joueurs individuels - contrôlées par ACL), la gestion des versions de concurrence, etc.
Vous pouvez même afficher les entités appartenant à un joueur dans la surveillance des utilisateurs - ce qui est bien sûr très pratique (et ressemble beaucoup aux entités usager).
Cela dit, vous pouvez également consulter l'intégralité de la collection d'entités personnalisées détenues au niveau de la surveillance globale, ce qui peut être utile pour rechercher tous les joueurs ayant atteint le niveau 40 ou plus. Cette fonctionnalité est impossible avec les entités usager.
Globalement, les entités personnalisées non détenues sont bien meilleures que les entités globales. Et les entités personnalisées détenues sont nettement meilleures que les entités usager.
Portail de conception
Les pages de portail suivantes vous permettent de manipuler facilement les entités personnalisées :
Conception > Cloud Data > Entités personnalisées - vous permet de définir des entités personnalisées, leurs index personnalisés et même des modèles JSON pratiques pour créer de nouvelles entités.
Global > Data Global > Entités personnalisées - Afficher et modifier toutes les collections d'entités - avec fonctionnalités complètes de recherche et d'importation/exportation
Données > Entités personnalisées du menu Usager - Visualisez/modifiez facilement les entités appartenant à un usager spécifique
Créer une entité personnalisée
Étape 1 : Créez un type d'entité personnalisé si vous n'en avez pas ou si vous souhaitez en créer un nouveau : cliquez sur le bouton [+ Créer un type d'entité] sur la page de Collections: Conception > Cloud Data > Entités personnalisées, saisissez le nom du type d'entité (obligatoire) et l'identifiant (facultatif), cochez la case Possédé si vous souhaitez que l'instance de cette entité soit détenue par les utilisateurs (remarque : une fois définie, elle ne peut pas être modifiée ultérieurement) et cochez la case Migrer si vous souhaitez que cette collection puisse être migrée lors d'un déploiement/exportation.
Remarque : les opérations ci-dessus peuvent également être réalisées à partir de l'appel d'API brainCloud SysCreateCollection().
Étape 2 : Ajoutez une entité personnalisée au type de collection créé en cliquant sur le bouton [+Créer une entité] de la page Global > Data Global > Entités personnalisées. Saisissez les données dans la zone de texte Données. Définissez respectivement les valeurs ACL et TTL (facultatif ; si vous laissez ce champ vide, la valeur par défaut sera "Jamais expiré").
Remarque : les opérations ci-dessus peuvent également être réalisées à partir de l'appel d'API brainCloud SysCreateEntity().
Récupérer des entités personnalisées
Vous pouvez ensuite utiliser ces index personnalisés comme critères de recherche pour analyser rapidement votre collection de données. Vous pouvez également utiliser des index sous sortCriteria pour le tri en appelant l'API GetEntityPage().
Ajouter des index
Une fois un type d'entité créé, cliquez sur "Configurer" sous "Actions" (bouton curseur vers le bas) pour ouvrir la page Détails, puis cliquez sur [+ Ajouter un index] pour ajouter un index à cette collection. Ajoutez le nom du champ (clés indexées) et la direction de chaque clé (par exemple, 1 ou -1) dans la zone de texte "Clés", puis ajoutez des options (propriétés d'index, telles que "sparse", "TTL", "insensible à la casse") à l'index que vous ajoutez dans la zone de texte "Options". Les types d'index couramment utilisés dans brainCloud incluent les index à champ unique et les index composés (les index composés peuvent prendre en charge les requêtes correspondant à plusieurs champs).
Remarque : l'option d'arrière-plan est définie sur true par défaut, car c'est le seul moyen sûr de créer un index lorsque le système est en ligne.
Remarque : les opérations ci-dessus peuvent également être réalisées à partir de l'appel d'API brainCloud SysCreateIndex().
Remarque : après avoir créé des index, vous pouvez exécuter SysListIndexes() pour vérifier que tous les index existent dans la collection personnalisée spécifique.
Exemple de création d'index à champ unique avec un paramètre d'option TTL
Remarque : Une propriété d'index TTL spéciale prend en charge l'implémentation des collections TTL. Cette option d'index est utilisée avec un champ d'horodatage, tel que "createdAt" ou "expireAt", et spécifie la valeur expireAfterSeconds pour définir l'heure d'expiration à un certain laps de temps après l'heure spécifiée par l'horodatage.
Exemple de création d'index composés (interrogation de votre collection en référençant le nom après la création)
Remarque : L'ordre des champs listés dans un index composé est important. Dans l'exemple ci-dessus, l'index contiendra des références à des documents triés d'abord par les valeurs du champ "nom" et, pour chaque valeur de ce champ, par les valeurs du champ "position". En plus de prendre en charge les requêtes correspondant à tous les champs de l'index, les index composés peuvent prendre en charge les requêtes correspondant au préfixe des champs de l'index.
Transition des données des entités globales
Les données d'entité personnalisée sont structurées de manière très similaire aux entités globales, ce qui permet aux usagers existants de la fonctionnalité d'entité globale de passer facilement à la fonctionnalité de collections personnalisées.
Différence importante : les entités personnalisées n'ont pas d'objet entityIndexedId. Gardez cela à l'esprit si vous migrez vos entités globales vers des entités personnalisées.
Transition des données des entités globales vers les entités personnalisées
Étape 1 : Accédez à la page Global > Data Global > Entités globales, choisissez un type d'entité dans le sélecteur Filtrer par type, cliquez sur [Actions groupées] et sélectionnez un format sous "Exporter tout". Un fichier objet JSON sera téléchargé sur votre ordinateur local. Le nom du fichier sera le suivant : XGE_12832_ALL_2020-04-16-10-30_raw.json si vous choisissez le fichier objet JSON brut.
Étape 2 : Accédez ensuite à la page Global > Data Global > Entités personnalisées, sélectionnez un type d'entité (collection) dans lequel vous souhaitez importer des données à partir de la liste des types d'entités personnalisées et cliquez sur Afficher les entités sous le bouton d'insertion vers le bas Actions pour ouvrir la page d'affichage des entités, puis cliquez sur [Actions en masse] et sélectionnez le même format en conséquence sous Importer.
Étape 3 : téléchargez ensuite le fichier JSON que vous avez exporté depuis Global Entities ici.
Étape 4 : La transition des données est terminée ! Les entités globales sont transférées vers des entités personnalisées et conservent les mêmes attributs (ACL, durée de vie et gestion des versions simultanées, etc.), même avec le même identifiant d'entité.
Remarque : Le transfert de données des entités globales vers les entités personnalisées via les opérations ci-dessus est limité. Un seul type d'entité est autorisé par importation. Même si les entités globales contiennent plusieurs types, un seul type d'entité peut être traité, car l'opération d'importation ci-dessus relève d'un type d'entité personnalisée spécifique.