> ## 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.
# API Inventory de PlayFab
> Vue d'ensemble des API Inventory de PlayFab Economy v2 pour gérer les inventaires des joueurs, octroyer des objets, suivre les soldes de devises et lire les piles.
# 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](https://community.playfab.com).
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
1. Dans [Game Manager](/fr/services/playfab/live-service-management/gamemanager), accédez à `Players`
2. 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` :
```json theme={null}
{
"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](/fr/services/playfab/economy-monetization/economy-v2/inventory/collections).
##### 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` :
```json theme={null}
{
"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` :
```json theme={null}
{
"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` :
```json theme={null}
{
"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` :
```json theme={null}
{
"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](/fr/services/playfab/economy-monetization/economy-v2/catalog/stores)
Exemple de requête `PurchaseInventoryItems` :
```json theme={null}
{
"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é](/fr/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview).
#### 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](/fr/services/playfab/economy-monetization/economy-v2/catalog/bundles).
### Transférer des objets d'inventaire
L'API `TransferInventoryItems` peut être utilisée de trois manières différentes.
1. Pour transférer des objets entre joueurs (par exemple, le joueur A donne trois pommes au joueur B)
2. 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)
3. 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 :
```json theme={null}
{
"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 :
```json theme={null}
{
"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](/fr/services/playfab/economy-monetization/economy-v2/inventory/collections).
#### 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 :
```json theme={null}
{
"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](/fr/services/playfab/economy-monetization/economy-v2/inventory/stacks).
### 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` :
```json theme={null}
{
"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.
```json theme={null}
{
"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](/fr/services/playfab/economy-monetization/economy-v2/inventory/etags).
### 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` :
```json theme={null}
{
"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](/fr/services/playfab/economy-monetization/economy-v2/inventory/stacks).
#### 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` :
```json theme={null}
{
"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"
}
}
}
```
## Related topics
- [PFInventoryInventoryOperation](/es/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryoperation.md)
- [PFInventoryInventoryItem](/es/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitem.md)
- [PFInventoryInventoryItemReference](/es/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitemreference.md)
- [PFInventoryDeleteInventoryCollectionAsync](/es/services/playfab/api-references/c/pfinventory/functions/pfinventorydeleteinventorycollectionasync.md)
- [PFInventoryTransferInventoryItemsRequest](/es/services/playfab/api-references/c/pfinventorytypes/structs/pfinventorytransferinventoryitemsrequest.md)