> ## 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 d'inventaire PlayFab
> Vue d'ensemble des API d'inventaire de PlayFab Economy v2 pour gérer les inventaires des joueurs, octroyer des articles, suivre les soldes de devises et lire les piles.
# Inventaire
Economy v2 est maintenant en disponibilité générale. Pour obtenir du soutien et donner vos commentaires, rendez-vous sur le [forum PlayFab](https://community.playfab.com).
Les API d'inventaire PlayFab vous permettent de gérer et de stocker les inventaires de vos joueurs ainsi que leurs données d'inventaire. Des fonctionnalités comme les piles (Stacks) et les collections (Collections) offrent de la souplesse 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 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
1. Dans [Game Manager](/fr-CA/services/playfab/live-service-management/gamemanager), accédez à `Players`
2. Sélectionnez le joueur que vous souhaitez consulter ou créez un `New Player`, puis allez dans `Inventory (V2)`
#### API
Vous pouvez utiliser `GetInventoryItems` 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` :
```json theme={null}
{
"Entity": {
"Type": "title_player_account",
"Id": "ABCD12345678"
},
"CollectionId": "main_character",
"Count": 15,
"ContinuationToken": "abc="
}
```
***
Vous trouverez plus d'information sur l'utilisation de `CollectionId` et sur la possibilité d'avoir plusieurs inventaires par joueur [ici](/fr-CA/services/playfab/economy-monetization/economy-v2/inventory/collections).
##### Jetons de continuation
Le champ `ContinuationToken` 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'API `AddInventoryItems` 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` :
```json theme={null}
{
"Entity": {
"Type": "title_player_account",
"Id": "ABCD12345678"
},
"Item": {
"Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
},
"Amount": 10,
}
```
### Soustraire des articles d'inventaire
L'API `SubtractInventoryItems` 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` :
```json theme={null}
{
"Entity": {
"Type": "title_player_account",
"Id": "ABCD12345678"
},
"Item": {
"Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
},
"Amount": 10,
}
```
### Mettre à jour des articles d'inventaire
L'API `UpdateInventoryItems` 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` :
```json theme={null}
{
"Entity": {
"Type": "title_player_account",
"Id": "ABCD12345678"
},
"Item": {
"Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
"Amount": 10
}
}
```
### Supprimer des articles d'inventaire
L'API `DeleteInventoryItems` sert à supprimer une pile entière d'articles 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 articles d'inventaire
L'API `PurchaseInventoryItems` 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` :
* `PriceAmounts` est 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.
* `StoreId` est un paramètre facultatif indiquant la boutique dans laquelle l'article doit être acheté. Vous trouverez plus d'information sur les boutiques [ici](/fr-CA/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` 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é](/fr-CA/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview).
#### Ensembles
Lorsqu'un ensemble est acheté (au moyen de `PurchaseInventoryItems` 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](/fr-CA/services/playfab/economy-monetization/economy-v2/catalog/bundles).
### Transférer des articles d'inventaire
L'API `TransferInventoryItems` peut être utilisée de trois façons différentes.
1. Pour transférer des articles entre joueurs (par exemple, le joueur A donne trois pommes au joueur B)
2. 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)
3. 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)
Les paramètres `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 :
```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 la collection d'inventaire source et celui de la collection de destination.
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 exemplaires de l'article de la collection `default` du joueur vers sa collection `main_character`.
Vous trouverez plus d'information sur les collections [ici](/fr-CA/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 exemplaires de l'article de la pile `default` du joueur vers sa pile `MyNewStack`.
Vous trouverez plus d'information sur les piles [ici](/fr-CA/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 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.
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 d'inventaire, vous pouvez transmettre un `IdempotencyId` 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.
```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 optimiste de la concurrence au moyen d'ETags et d'en-têtes HTTP. Pour tous les détails, consultez [ETags d'inventaire](/fr-CA/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'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érations `AddInventoryItems`, `PurchaseInventoryItems`, `TransferInventoryItems` et `UpdateInventoryItems`.
#### Ajout de propriétés à de nouvelles piles ou de nouveaux articles
Pour les API `AddInventoryItems`, `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` :
```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'information sur les piles [ici](/fr-CA/services/playfab/economy-monetization/economy-v2/inventory/stacks).
#### 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'API `UpdateInventoryItems` peut être utilisée pour 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
- [PlayFab Events API](/services/playfab/api-references/rest/events/overview.md)
- [PlayFab Profiles API](/services/playfab/api-references/rest/profiles/overview.md)
- [PlayFab Experimentation API](/services/playfab/api-references/rest/experimentation/overview.md)
- [PlayFab Insights API](/services/playfab/api-references/rest/insights/overview.md)
- [PlayFab Progression API](/services/playfab/api-references/rest/progression/overview.md)