Inventaire
Economy v2 est maintenant en disponibilité générale. Pour obtenir du soutien et donner vos commentaires, rendez-vous sur le forum PlayFab.
Gestion des inventaires des joueurs
Les API suivantes servent à ajouter, retirer, mettre à jour et supprimer des articles dans l’inventaire d’un joueur. La limite actuelle est de 10 000 articles; vous obtiendrez une erreur si vous la dépassez.Obtenir l’inventaire d’un joueur
Game Manager
- Dans Game Manager, accédez à
Players - Sélectionnez le joueur que vous souhaitez consulter ou créez un
New Player, puis allez dansInventory (V2)
API
Vous pouvez utiliserGetInventoryItems pour obtenir l’inventaire d’un joueur. Les joueurs peuvent uniquement accéder à leur propre inventaire et le manipuler. Les entités de titre peuvent transmettre un paramètre Entity pour indiquer à quel inventaire de joueur elles souhaitent accéder.
Exemple de requête GetInventoryItems :
Vous trouverez plus d’information sur l’utilisation de
CollectionId et sur la possibilité d’avoir plusieurs inventaires par joueur ici.
Jetons de continuation
Le champContinuationToken retourné dans une réponse de recherche peut être transmis dans une requête d’inventaire pour paginer à travers plusieurs lots de résultats.
Ajouter des articles d’inventaire
L’APIAddInventoryItems sert à ajouter directement des articles à l’inventaire d’un joueur précis. Elle prend les paramètres EntityId, ItemId et Amount, et ajoute l’article donné à l’inventaire d’un joueur
Exemple de requête AddInventoryItems :
Soustraire des articles d’inventaire
L’APISubtractInventoryItems sert à réduire directement la quantité d’un article dans l’inventaire d’un joueur d’un montant précis. Elle prend les paramètres EntityId, ItemId et Amount, et retire la quantité donnée de l’article. Cette API génère une erreur si vous tentez de retirer une quantité supérieure à celle actuellement disponible.
Exemple de requête SubtractInventoryItems :
Mettre à jour des articles d’inventaire
L’APIUpdateInventoryItems sert à définir directement la quantité d’un article dans l’inventaire d’un joueur. Elle prend les paramètres EntityId, ItemId et Amount, et définit la quantité donnée de l’article. Cette API peut servir à augmenter ou à réduire la quantité d’un article, ainsi qu’à ajouter des articles à l’inventaire d’un joueur si l’article n’existe pas.
Exemple de requête UpdateInventoryItems :
Supprimer des articles d’inventaire
L’APIDeleteInventoryItems sert à supprimer une pile entière d’articles de l’inventaire d’un joueur.
Exemple de requête DeleteInventoryItems :
Acheter des articles d’inventaire
L’APIPurchaseInventoryItems utilise le prix de l’article défini dans le catalogue, déduit le coût de l’inventaire du joueur et l’échange contre la quantité voulue de l’article. Vous devez spécifier l’Item que vous souhaitez acheter et la quantité (Amount) de l’article à acheter.
Quelques paramètres clés sont propres à l’API PurchaseInventoryItems :
PriceAmountsest une liste d’articles et de quantités qui représentent les prix par article. Ces prix doivent correspondre à une valeur configurée dans le catalogue ou dans la boutique spécifiée.StoreIdest un paramètre facultatif indiquant la boutique dans laquelle l’article doit être acheté. Vous trouverez plus d’information sur les boutiques ici
PurchaseInventoryItems :
L’API
PurchaseInventoryItems sert aux achats effectués avec des devises virtuelles. Pour les achats en argent réel au moyen de places de marché externes (Apple App Store, Google Play, Steam, Microsoft Store), utilisez les API Redeem correspondantes (comme RedeemAppleAppStoreInventoryItems, RedeemGooglePlayInventoryItems, RedeemSteamInventoryItems ou RedeemMicrosoftStoreInventoryItems). Ces API valident le reçu d’achat auprès de la place de marché et octroient les articles à l’inventaire du joueur. Pour plus d’information, consultez Échange sur les places de marché.Ensembles
Lorsqu’un ensemble est acheté (au moyen dePurchaseInventoryItems ou d’une API Redeem de place de marché), il est automatiquement dépaqueté dans l’inventaire du joueur. Les articles individuels référencés dans les ItemReferences de l’ensemble sont octroyés directement; l’ensemble lui-même n’apparaît pas comme un article dans l’inventaire du joueur.
Par exemple, l’achat d’un ensemble contenant 2 épées laser et 2 pistolets laser octroie ces articles individuellement. Le coût en devise virtuelle défini dans les PriceOptions de l’ensemble est déduit de l’inventaire du joueur dans le cadre de la transaction.
Les ensembles liés à des produits de places de marché au moyen d’AlternateIds suivent le même comportement de dépaquetage lorsqu’ils sont échangés. Pour plus d’information sur la création d’ensembles, consultez Ensembles.
Transférer des articles d’inventaire
L’APITransferInventoryItems peut être utilisée de trois façons différentes.
- Pour transférer des articles entre joueurs (par exemple, le joueur A donne trois pommes au joueur B)
- Pour transférer des articles entre les collections d’inventaire d’un même joueur (par exemple, le joueur A déplace son épée longue de l’inventaire de son personnage Sorcier vers l’inventaire de son personnage Guerrier)
- Pour transférer des articles à l’intérieur de l’inventaire d’un même joueur afin de créer, de retirer et de manipuler des piles d’articles (par exemple, le joueur A divise sa pile de 10 pièces d’or en deux piles de trois et de sept pièces d’or)
GivingItem et Amount servent à représenter la quantité et l’article transférés. ReceivingItem représente la destination de l’article dans le compte du joueur qui reçoit. Les paramètres GivingItem et ReceivingItem sont tous deux des objets InventoryItemReference qui contiennent l’Id de l’article et le StackId. GivingItem et ReceivingItem peuvent tous deux être vides pour gérer les transferts où une entité ne transfère pas d’articles. Sauf indication contraire, le StackId de tous les articles est défini à default lorsqu’ils sont ajoutés ou transférés à l’inventaire d’un joueur.
1. Transfert entre joueurs
Pour un transfert entre joueurs,GivingEntity et ReceivingEntity doivent être spécifiés, représentant respectivement le joueur qui transfère les articles et le joueur qui les reçoit.
Exemple de requête TransferInventoryItems entre joueurs :
2. Transfert entre collections
Pour un transfert entre collections,GivingCollectionId et ReceivingCollectionId doivent être définis; ils représentent respectivement l’ID de la collection d’inventaire source et celui de la collection de destination.
Exemple de requête TransferInventoryItems entre collections :
default du joueur vers sa collection main_character.
Vous trouverez plus d’information sur les collections ici.
3. Transfert entre piles
Pour un transfert entre piles, leStackId du GivingItem et du ReceivingItem de la requête doit être spécifié.
Exemple de requête TransferInventoryItems entre piles :
default du joueur vers sa pile MyNewStack.
Vous trouverez plus d’information sur les piles ici.
API ExecuteInventoryOperations
Vous pouvez utiliser l’APIExecuteInventoryOperations pour regrouper plusieurs opérations d’inventaire dans une seule requête. Les opérations s’exécutent dans l’ordre spécifié dans la requête et, si une opération ne peut pas être effectuée, l’ensemble des opérations est annulé.
ExecuteInventoryOperations prend un paramètre Operation qui est une liste d’opérations. La liste Operation peut contenir au plus 50 opérations, mais les types d’opérations peuvent se répéter (par exemple, 10 opérations Add sont valides). Il existe également une limite de 300 articles pouvant être modifiés ou ajoutés dans une seule requête. Par exemple, l’ajout d’un ensemble de 50 articles compte comme 50 articles modifiés. Les types d’opérations valides sont :
- Add
- Subtract
- Update
- Purchase
- Transfer*
- Delete
*Seuls les transferts à l’intérieur d’une même collection sont pris en charge dans un lot.
ExecuteInventoryOperations :
Idempotence
Lorsque vous appelez les API d’inventaire, vous pouvez transmettre unIdempotencyId qui peut servir dans les situations où des appels répétitifs sont effectués à des fins de repli ou de redondance. Si plusieurs appels d’API ont le même IdempotencyId, le système garantit qu’une seule de ces requêtes sera traitée.
Par exemple, la requête d’API PurchaseItem suivante peut être appelée plusieurs fois, mais puisque toutes les requêtes ont le même IdempotencyId, un seul achat sera effectué pour l’inventaire de ce joueur.
IdempotencyId sont stockés et appliqués pendant 14 jours, après quoi l’ID peut être réutilisé.
L’utilisation du même
IdempotencyId pour différents types de requêtes provoque un conflit et génère une erreur.ETags et contrôle de la concurrence
Les API d’écriture d’inventaire prennent en charge le contrôle optimiste de la concurrence au moyen d’ETags et d’en-têtes HTTP. Pour tous les détails, consultez ETags d’inventaire.Propriétés d’affichage
Les propriétés d’affichage (Display Properties) sont des propriétés d’article personnalisées qui peuvent être ajoutées aux articles et aux piles d’articles dans les inventaires des joueurs. Ces propriétés peuvent être ajoutées par les opérationsAddInventoryItems, PurchaseInventoryItems, TransferInventoryItems et UpdateInventoryItems.
Ajout de propriétés à de nouvelles piles ou de nouveaux articles
Pour les APIAddInventoryItems, PurchaseInventoryItems et TransferInventoryItems, les propriétés d’affichage peuvent seulement être ajoutées lors de la création d’une nouvelle pile. Pour définir les propriétés d’affichage de nouveaux articles, le paramètre NewStackValues doit être défini dans la requête d’API.
Exemple de requête AddInventoryItems avec NewStackValues :
Mise à jour des propriétés de piles ou d’articles existants
Pour mettre à jour les propriétés d’affichage d’articles existants, l’APIUpdateInventoryItems peut être utilisée pour modifier directement les propriétés.
Exemple de requête UpdateInventoryItems avec DisplayProperties :