Inventaire

Economy v2 est désormais en disponibilité générale. Pour obtenir de l’aide et donner votre avis, rendez-vous sur le forum PlayFab.

Les API Inventory de PlayFab vous permettent de gérer et de stocker les inventaires de vos joueurs ainsi que leurs données d’inventaire. Des fonctionnalités telles que les piles (Stacks) et les collections offrent de la flexibilité dans la structuration des inventaires des joueurs et permettent à ce système de fonctionner avec n’importe quel jeu

Gestion des inventaires des joueurs

Les API suivantes permettent d’ajouter, de retirer, de mettre à jour et de supprimer des objets dans l’inventaire d’un joueur. La limite actuelle est de 10 000 objets et vous recevrez 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 afficher ou créez un New Player, puis accédez à Inventory (V2)

API

Vous pouvez utiliser GetInventoryItems pour obtenir l’inventaire d’un joueur. Les joueurs ne peuvent accéder qu’à leur propre inventaire et ne peuvent manipuler que celui-ci. 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 :

{
  "Entity": {
    "Type": "title_player_account",
    "Id": "ABCD12345678"
  },
  "CollectionId": "main_character",
  "Count": 15,
  "ContinuationToken": "abc="
}

Vous trouverez plus d’informations sur l’utilisation de CollectionId et sur la possession de plusieurs inventaires par joueur ici.

Jetons de continuation

Le champ ContinuationToken renvoyé par une réponse de recherche peut être transmis dans une requête d’inventaire pour parcourir plusieurs pages de résultats.

Ajouter des objets d’inventaire

L’API AddInventoryItems permet d’ajouter directement des objets à l’inventaire d’un joueur spécifique. Elle prend les paramètres EntityId, ItemId et Amount, et ajoute l’objet donné à l’inventaire d’un joueur Exemple de requête AddInventoryItems :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}

Soustraire des objets d’inventaire

L’API SubtractInventoryItems permet de réduire directement d’une quantité spécifique un objet dans l’inventaire d’un joueur. Elle prend les paramètres EntityId, ItemId et Amount, et retire la quantité donnée de l’objet. Cette API génère une erreur si vous tentez de retirer une quantité supérieure à celle actuellement disponible. Exemple de requête SubtractInventoryItems :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}

Mettre à jour des objets d’inventaire

L’API UpdateInventoryItems permet de définir directement un objet de l’inventaire d’un joueur sur une quantité spécifique. Elle prend les paramètres EntityId, ItemId et Amount, et définit la quantité donnée de l’objet. Cette API peut être utilisée à la fois pour augmenter ou réduire la quantité d’un objet et pour ajouter des objets à l’inventaire d’un joueur si l’objet n’existe pas. Exemple de requête UpdateInventoryItems :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "Amount": 10
    }
}

Supprimer des objets d’inventaire

L’API DeleteInventoryItems permet de supprimer une pile entière d’objets de l’inventaire d’un joueur. Exemple de requête DeleteInventoryItems :

{
   "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
}

Acheter des objets d’inventaire

L’API PurchaseInventoryItems utilise le prix de l’objet défini dans le catalogue, déduit le coût de l’inventaire du joueur et l’échange contre la quantité souhaitée de l’objet. Vous devez spécifier l’Item que vous souhaitez acheter et la quantité (Amount) de l’objet que vous souhaitez acheter. Quelques paramètres clés sont propres à l’API PurchaseInventoryItems :

PriceAmounts est une liste d’objets et de quantités qui constituent les prix par objet de l’objet. Ces prix doivent correspondre à une valeur configurée dans le catalogue ou dans la boutique spécifiée.
StoreId est un paramètre facultatif indiquant la boutique dans laquelle l’objet doit être acheté. Vous trouverez plus d’informations sur les boutiques ici

Exemple de requête PurchaseInventoryItems :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5
        }
    ],
}

L’API PurchaseInventoryItems est utilisée pour les achats avec des devises virtuelles. Pour les achats en argent réel via des places de marché externes (Apple App Store, Google Play, Steam, Microsoft Store), utilisez les API Redeem correspondantes (telles que RedeemAppleAppStoreInventoryItems, RedeemGooglePlayInventoryItems, RedeemSteamInventoryItems ou RedeemMicrosoftStoreInventoryItems). Ces API valident le reçu d’achat auprès de la place de marché et octroient les objets à l’inventaire du joueur. Pour plus d’informations, consultez Échange sur les places de marché.

Lots

Lorsqu’un lot (bundle) est acheté (via PurchaseInventoryItems ou une API Redeem de place de marché), il est automatiquement décompressé dans l’inventaire du joueur. Les objets individuels référencés dans les ItemReferences du lot sont octroyés directement ; le lot lui-même n’apparaît pas comme un objet dans l’inventaire du joueur. Par exemple, l’achat d’un lot contenant 2 épées laser et 2 pistolets laser octroie ces objets individuellement. Le coût en devise virtuelle défini dans les PriceOptions du lot est déduit de l’inventaire du joueur dans le cadre de la transaction. Les lots liés à des produits de places de marché via AlternateIds suivent le même comportement de décompression lorsqu’ils sont échangés. Pour plus d’informations sur la création de lots, consultez Lots.

Transférer des objets d’inventaire

L’API TransferInventoryItems peut être utilisée de trois manières différentes.

Pour transférer des objets entre joueurs (par exemple, le joueur A donne trois pommes au joueur B)
Pour transférer des objets 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 Magicien vers l’inventaire de son personnage Guerrier)
Pour transférer des objets au sein de l’inventaire d’un même joueur afin de créer, supprimer et manipuler des piles d’objets (par exemple, le joueur A divise sa pile de 10 pièces d’or en deux piles de trois et sept pièces d’or)

Les paramètres GivingItem et Amount représentent la quantité et l’objet transférés. ReceivingItem représente la destination de l’objet dans le compte du joueur destinataire. Les paramètres GivingItem et ReceivingItem sont tous deux des objets InventoryItemReference qui contiennent l’Id de l’objet et le StackId. GivingItem et ReceivingItem peuvent tous deux être vides pour gérer les transferts dans lesquels une entité ne transfère pas d’objets. Sauf indication contraire, tous les objets ont la valeur default pour le StackId lorsqu’ils sont ajoutés ou transférés dans l’inventaire d’un joueur.

1. Transfert entre joueurs

Pour un transfert entre joueurs, GivingEntity et ReceivingEntity doivent être spécifiés ; ils représentent respectivement le joueur qui transfère les objets et le joueur qui les reçoit. Exemple de requête TransferInventoryItems entre joueurs :

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "DEFG98765432"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 1
}

2. Transfert entre collections

Pour un transfert entre collections, GivingCollectionId et ReceivingCollectionId doivent être définis ; ils représentent respectivement l’ID de collection d’inventaire source et destination du transfert. Exemple de requête TransferInventoryItems entre collections :

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingCollectionId": "default",
    "ReceivingCollectionId": "main_character",
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10
}

La requête ci-dessus transfère 10 unités de l’objet de la collection default du joueur vers sa collection main_character. Vous trouverez plus d’informations sur les collections ici.

3. Transfert entre piles

Pour un transfert entre piles, le StackId du GivingItem et du ReceivingItem de la requête doit être spécifié. Exemple de requête TransferInventoryItems entre piles :

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "default",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "MyNewStack",
    },
    "Amount": 10
}

La requête ci-dessus transfère 10 unités de l’objet de la pile default du joueur vers sa pile MyNewStack. Vous trouverez plus d’informations sur les piles ici.

API ExecuteInventoryOperations

Vous pouvez utiliser l’API ExecuteInventoryOperations 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 maximum 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 objets pouvant être modifiés ou ajoutés dans une seule requête. Par exemple, l’ajout d’un lot de 50 objets compte comme 50 objets modifiés. Les types d’opérations valides sont :

Add
Subtract
Update
Purchase
Transfer*
Delete

*Seuls les transferts au sein d’une même collection sont pris en charge dans un lot.

Exemple de requête ExecuteInventoryOperations :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Operations": [
        {
            "Update": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                    "Amount": 10
                }
            }
        },
        {
            "Subtract": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                },
                "Amount": 5
            }
        }
    ]
}

Idempotence

Lorsque vous appelez les API Inventory, vous pouvez transmettre un IdempotencyId utilisable dans les situations où des appels répétés sont effectués à des fins de secours 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 comme toutes les requêtes ont le même IdempotencyId, un seul achat sera effectué pour l’inventaire de ce joueur.

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5
        }
    ],
    "IdempotencyId": "ABC123"
}

Les 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 de concurrence optimiste au moyen d’ETags et d’en-têtes HTTP. Pour plus de 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’objet personnalisées qui peuvent être ajoutées aux objets et aux piles d’objets dans les inventaires des joueurs. Ces propriétés peuvent être ajoutées par les opérations AddInventoryItems, PurchaseInventoryItems, TransferInventoryItems et UpdateInventoryItems.

Ajout de propriétés à de nouvelles piles ou de nouveaux objets

Pour les API AddInventoryItems, PurchaseInventoryItems et TransferInventoryItems, les propriétés d’affichage peuvent uniquement être ajoutées lors de la création d’une nouvelle pile. Pour définir des propriétés d’affichage pour de nouveaux objets, le paramètre NewStackValues doit être défini dans la requête d’API. Exemple de requête AddInventoryItems avec NewStackValues :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack"
    },
    "Amount": 15,
    "NewStackValues": {
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": true,
            "Rarity": "Legendary"
        }
    }
}

Vous trouverez plus d’informations sur les piles ici.

Mise à jour des propriétés de piles ou d’objets existants

Pour mettre à jour les propriétés d’affichage d’objets existants, vous pouvez utiliser l’API UpdateInventoryItems afin de modifier directement les propriétés. Exemple de requête UpdateInventoryItems avec DisplayProperties :

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack",
        "Amount": 15,
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": false,
            "Rarity": "Epic"
        }
    }
}

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

API Inventory de PlayFab

Inventaire

Gestion des inventaires des joueurs

Obtenir l’inventaire d’un joueur

Game Manager

API

Jetons de continuation

Ajouter des objets d’inventaire

Soustraire des objets d’inventaire

Mettre à jour des objets d’inventaire

Supprimer des objets d’inventaire

Acheter des objets d’inventaire

Lots

Transférer des objets d’inventaire

1. Transfert entre joueurs

2. Transfert entre collections

3. Transfert entre piles

API ExecuteInventoryOperations

Idempotence

ETags et contrôle de la concurrence

Propriétés d’affichage

Ajout de propriétés à de nouvelles piles ou de nouveaux objets

Mise à jour des propriétés de piles ou d’objets existants

​Inventaire

​Gestion des inventaires des joueurs

​Obtenir l’inventaire d’un joueur

​Game Manager

​API

Jetons de continuation

​Ajouter des objets d’inventaire

​Soustraire des objets d’inventaire

​Mettre à jour des objets d’inventaire

​Supprimer des objets d’inventaire

​Acheter des objets d’inventaire

​Lots

​Transférer des objets d’inventaire

​1. Transfert entre joueurs

​2. Transfert entre collections

​3. Transfert entre piles

​API ExecuteInventoryOperations

​Idempotence

​ETags et contrôle de la concurrence

​Propriétés d’affichage

​Ajout de propriétés à de nouvelles piles ou de nouveaux objets

​Mise à jour des propriétés de piles ou d’objets existants

Inventaire

Gestion des inventaires des joueurs

Obtenir l’inventaire d’un joueur

Game Manager

API

Ajouter des objets d’inventaire

Soustraire des objets d’inventaire

Mettre à jour des objets d’inventaire

Supprimer des objets d’inventaire

Acheter des objets d’inventaire

Lots

Transférer des objets d’inventaire

1. Transfert entre joueurs

2. Transfert entre collections

3. Transfert entre piles

API ExecuteInventoryOperations

Idempotence

ETags et contrôle de la concurrence

Propriétés d’affichage

Ajout de propriétés à de nouvelles piles ou de nouveaux objets

Mise à jour des propriétés de piles ou d’objets existants