> ## 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.

# Utilisation de l'inventaire des joueurs

> Utilisez l'inventaire des joueurs PlayFab à l'aide d'API client et serveur faisant autorité côté serveur pour acheter des objets, accorder des monnaies et gérer le contenu issu du catalogue.

# Inventaire des joueurs

## Exigences

Pour utiliser l'inventaire des joueurs, un catalogue doit être défini pour votre titre. Pour plus d'informations, consultez notre tutoriel sur les [catalogues](/fr-CA/services/playfab/economy-monetization/economy/items/catalogs).

<Note>
  Vous pouvez également définir des boutiques pour votre catalogue.
</Note>

Alors qu'un catalogue est la liste de tous les objets disponibles dans le jeu, une boutique est un sous-ensemble d'objets du catalogue qui peut offrir une tarification spécifique.

Plusieurs boutiques peuvent être définies par catalogue, ce qui vous permet de présenter au joueur des ensembles d'objets distincts en fonction de la segmentation des utilisateurs ou d'autres facteurs.

Une fois que vous avez défini un catalogue au moyen de [**Game Manager**](https://developer.playfab.com/) ou au moyen de nos appels d'API d'administration **[SetCatalogItems](xref:titleid.playfabapi.com.admin.title-widedatamanagement.setcatalogitems)** ou **[UpdateCatalogItems](xref:titleid.playfabapi.com.admin.title-widedatamanagement.updatecatalogitems)**, vous pouvez utiliser un large éventail d'appels d'API d'inventaire côté client et côté serveur.

## Vue d'ensemble de l'API

Tous les appels d'API d'inventaire sont conçus pour faire *autorité côté serveur* et être sécurisés. Lorsqu'ils sont utilisés correctement, les clients ne peuvent pas tricher ni acquérir des objets qu'ils n'ont pas mérités.

**Clients** :

* Acheter des objets avec une monnaie virtuelle : **[PurchaseItem](xref:titleid.playfabapi.com.client.playeritemmanagement.purchaseitem)**
* Effectuer des achats en argent réel : **[StartPurchase](xref:titleid.playfabapi.com.client.playeritemmanagement.startpurchase), [PayForPurchase](xref:titleid.playfabapi.com.client.playeritemmanagement.payforpurchase), [ConfirmPurchase](xref:titleid.playfabapi.com.client.playeritemmanagement.confirmpurchase)**
* Afficher les objets d'un joueur : **[GetUserInventory](xref:titleid.playfabapi.com.client.playeritemmanagement.getuserinventory)**
* Supprimer des objets : **[ConsumeItem](xref:titleid.playfabapi.com.client.playeritemmanagement.consumeitem), [UnlockContainerInstance](xref:titleid.playfabapi.com.client.playeritemmanagement.unlockcontainerinstance)**
* Échanger des objets : **[OpenTrade](xref:titleid.playfabapi.com.client.trading.opentrade), [GetPlayerTrades](xref:titleid.playfabapi.com.client.trading.getplayertrades), [AcceptTrade](xref:titleid.playfabapi.com.client.trading.accepttrade), [CancelTrade](xref:titleid.playfabapi.com.client.trading.canceltrade)**

**Serveur** :

* Offrir/accorder des objets : **[GrantItemsToUser](xref:titleid.playfabapi.com.server.playeritemmanagement.grantitemstouser)**
* Afficher les objets : **[GetUserInventory](xref:titleid.playfabapi.com.server.playeritemmanagement.getuserinventory)**
* Modifier des objets : **[ModifyItemUses](xref:titleid.playfabapi.com.server.playeritemmanagement.modifyitemuses), [UpdateUserInventoryItemCustomData](xref:titleid.playfabapi.com.server.playeritemmanagement.updateuserinventoryitemcustomdata)**
* Supprimer des objets : **[RevokeInventoryItem](xref:titleid.playfabapi.com.server.playeritemmanagement.revokeinventoryitem), [ConsumeItem](xref:titleid.playfabapi.com.server.playeritemmanagement.consumeitem), [UnlockContainerInstance](xref:titleid.playfabapi.com.server.playeritemmanagement.unlockcontainerinstance)**

L'exemple ci-dessous présente les blocs de code qui appellent ces méthodes d'API et met en place des cas d'usage de base de l'inventaire des joueurs.

<Note>
  Pour référence, ces exemples sont tirés de **Unicorn Battle**, un jeu que nous avons créé à titre d'exemple pour illustrer les fonctionnalités de PlayFab.
</Note>

La monnaie virtuelle **AU** utilisée ci-dessous est l'**or** (Gold), une monnaie gratuite gagnée en combattant des monstres (consultez notre tutoriel sur les [monnaies](/fr-CA/services/playfab/economy-monetization/economy-v2/tutorials/currencies)).

Avant de commencer, nous allons définir quelques fonctions utilitaires qui seront utilisées et réutilisées dans la plupart des exemples de ce guide.

```csharp theme={null}
// **** Shared example utility functions ****

// This is typically NOT how you handle success
// You will want to receive a specific result-type for your API, and utilize the result parameters
void LogSuccess(PlayFabResultCommon result) {
    var requestName = result.Request.GetType().Name;
    Debug.Log(requestName + " successful");
}

// Error handling can be very advanced, such as retry mechanisms, logging, or other options
// The simplest possible choice is just to log it
void LogFailure(PlayFabError error) {
    Debug.LogError(error.GenerateErrorReport());
}
```

## Exemple côté client uniquement : acheter et consommer une potion de soin

Ordre des appels d'API client : [PurchaseItem](xref:titleid.playfabapi.com.client.playeritemmanagement.purchaseitem), [GetUserInventory](xref:titleid.playfabapi.com.client.playeritemmanagement.getuserinventory), [ConsumeItem](xref:titleid.playfabapi.com.server.playeritemmanagement.consumeitem)

Nous devons d'abord définir l'objet dans notre catalogue.

<img src="https://mintcdn.com/microsoft-4404708b/N3T1ucKV7zIMBudj/images/playfab/player-progression/player-data/tutorials/playfab-edit-catalog-item.png?fit=max&auto=format&n=N3T1ucKV7zIMBudj&q=85&s=773db3352052dc2e8653fa2bca38fb0b" alt="PlayFab - Economy - Modifier un objet du catalogue" width="1280" height="1400" data-path="images/playfab/player-progression/player-data/tutorials/playfab-edit-catalog-item.png" />

Voici les exigences du `CatalogItem` pour la **potion de soin** (Health Potion).

* `PurchaseItem` nécessite un prix d'objet positif (`5 AU`).
* `ConsumeItem` nécessite que l'objet soit `Consumable`, avec un nombre d'utilisations positif (`3`).
* Le joueur qui effectue l'achat doit disposer de cinq AU dans son solde de monnaie virtuelle.

Le code de chaque appel est fourni ci-dessous.

```csharp theme={null}
void MakePurchase() {
    PlayFabClientAPI.PurchaseItem(new PurchaseItemRequest {
        // In your game, this should just be a constant matching your primary catalog
        CatalogVersion = "CharacterClasses",
        ItemId = "MediumHealthPotion",
        Price = 5,
        VirtualCurrency = "AU"
    }, LogSuccess, LogFailure);
}

void GetInventory() {
    PlayFabClientAPI.GetUserInventory(new GetUserInventoryRequest(), LogSuccess, LogFailure);
}

void ConsumePotion() {
    PlayFabClientAPI.ConsumeItem(new ConsumeItemRequest {
        ConsumeCount = 1,
        // This is a hex-string value from the GetUserInventory result
        ItemInstanceId = "potionInstanceId"
    }, LogSuccess, LogFailure);
}
```

## Exemple : un joueur reçoit un conteneur et l'ouvre

Ordre des appels d'API :

* API serveur PlayFab [GrantItemsToUser](xref:titleid.playfabapi.com.server.playeritemmanagement.grantitemstouser)
* API client PlayFab [UnlockContainerInstance](xref:titleid.playfabapi.com.client.playeritemmanagement.unlockcontainerinstance)

Nous devons d'abord disposer d'un conteneur défini dans notre catalogue. Pour le conteneur de cet exemple, nous avons sélectionné un **CrystalContainer**.

Cet exemple montre également comment ouvrir le conteneur avec une clé : un objet *facultatif* qui doit également figurer dans l'inventaire du joueur pour que l'appel `UnlockContainerInstance` réussisse.

<img src="https://mintcdn.com/microsoft-4404708b/N3T1ucKV7zIMBudj/images/playfab/player-progression/player-data/tutorials/playfab-edit-catalog-container.png?fit=max&auto=format&n=N3T1ucKV7zIMBudj&q=85&s=9de90fda3309e3046ca2835412f738cd" alt="PlayFab - Economy - Modifier un conteneur du catalogue" width="1280" height="1400" data-path="images/playfab/player-progression/player-data/tutorials/playfab-edit-catalog-container.png" />

Les exigences du `CatalogItem` pour notre **CrystalContainer** dans cet exemple sont les suivantes :

* **CrystalContainer** doit être défini comme **Container**.

* Les **conteneurs** peuvent éventuellement définir un **objet clé** (Key Item), qui est alors nécessaire pour déverrouiller le **conteneur**; dans ce cas, une **CrystalKey**.

* Il est fortement conseillé que votre **conteneur** et toute **clé** soient *tous deux* **consommables**, avec un nombre d'utilisations positif, afin qu'ils soient retirés de l'inventaire du joueur après utilisation.

### Code serveur

```csharp theme={null}
void GrantItem() {
    PlayFabServerAPI.GrantItemsToUser(new GrantItemsToUserRequest {
        // In your game, this should just be a constant
        CatalogVersion = "CharacterClasses",
        // Servers must define which character they're modifying in every API call
        PlayFabId = "playFabId",
        ItemIds = new List<string> { "CrystalContainer" }
    }, LogSuccess, LogFailure);
}
```

### Code client

```csharp theme={null}
void OpenContainer() {
    PlayFabClientAPI.UnlockContainerInstance(new UnlockContainerInstanceRequest {
        // In your game, this should just be a constant matching your primary catalog
        CatalogVersion = "CharacterClasses",
        ContainerItemInstanceId = "containerInstanceId",
        KeyItemInstanceId = "keyInstanceId"
    }, LogSuccess, LogFailure);
}
```

### Consommation des clés et des conteneurs

Dans l'exemple précédent, il est conseillé que la clé et/ou le conteneur soient *consommables*, mais il ne s'agit que d'une recommandation.

Toutefois, si un conteneur et sa clé (le cas échéant) ne sont *pas consommables*, le conteneur peut être rouvert *indéfiniment*, en accordant son contenu au joueur à chaque fois.

Comme la capacité de l'inventaire du joueur n'est *pas* infinie, ce modèle est fortement déconseillé. Lorsqu'un conteneur consommable est déverrouillé, le nombre d'utilisations du conteneur et de la clé consommable utilisée est automatiquement *diminué*, ce qui les retire de l'inventaire du joueur lorsque ce nombre atteint zéro.

### Options viables

**Conteneur consommable**, sans **clé** : le modèle le plus basique, dans lequel le conteneur est consommé à l'ouverture et il n'y a pas de clé.

**Conteneur consommable, clé consommable** : le cas simple du conteneur verrouillé, qui permet au joueur d'ouvrir le conteneur avec la clé. *Les deux* sont consommés, et le joueur ne peut ouvrir un conteneur disposant d'utilisations restantes qu'avec une clé disposant elle aussi d'utilisations restantes.

**Conteneur durable, clé consommable** : permet au joueur d'ouvrir le conteneur chaque fois qu'il trouve une clé. La clé est consommée, et le conteneur ne peut être ouvert que tant que la clé dispose d'utilisations restantes.

**Conteneur consommable, clé durable** : permet au joueur de conserver une clé capable d'ouvrir *tous* les conteneurs dont elle est l'objet clé. Le conteneur est consommé, mais le joueur conserve la possibilité d'ouvrir ultérieurement des conteneurs avec la clé.

## Exemple : racheter des objets d'inventaire au joueur

Il n'existe pas d'API intégrée permettant de racheter des objets d'inventaire au joueur, car ce processus est propre à chaque jeu. Vous pouvez toutefois utiliser les méthodes d'API *existantes* pour créer votre propre expérience **SellItem** :

* L'API serveur PlayFab [RevokeInventoryItem](xref:titleid.playfabapi.com.server.playeritemmanagement.revokeinventoryitem)\*\* vous permet de retirer un objet de l'inventaire.

* L'API serveur PlayFab [AddUserVirtualCurrency](xref:titleid.playfabapi.com.server.playeritemmanagement.adduservirtualcurrency)\*\* peut restituer un montant approprié de monnaie virtuelle. Il n'est actuellement pas possible de restituer de l'argent réel au moyen des méthodes d'API PlayFab.

<Note>
  Les objets et les monnaies virtuelles sont étroitement liés. Pour plus d'informations, consultez notre tutoriel sur les [monnaies](/fr-CA/services/playfab/economy-monetization/economy-v2/tutorials/currencies).
</Note>

La fonction CloudScript suivante combine les deux appels serveur décrits en un seul appel accessible depuis le client.

```javascript theme={null}
var SELL_PRICE_RATIO = 0.75;
function SellItem_internal(soldItemInstanceId, requestedVcType) {
    var inventory = server.GetUserInventory({ PlayFabId: currentPlayerId });
    var itemInstance = null;
    for (var i = 0; i < inventory.Inventory.length; i++) {
        if (inventory.Inventory[i].ItemInstanceId === soldItemInstanceId)
            itemInstance = inventory.Inventory[i];
    }
    if (!itemInstance)
        throw "Item instance not found"; // Protection against client providing incorrect data
    var catalog = server.GetCatalogItems({ CatalogVersion: itemInstance.CatalogVersion });
    var catalogItem = null;
    for (var c = 0; c < catalog.Catalog.length; c++) {
        if (itemInstance.ItemId === catalog.Catalog[c].ItemId)
            catalogItem = catalog.Catalog[c];
    }
    if (!catalogItem)
        throw "Catalog Item not found"; // Title catalog consistency check (You should never remove a catalog/catalogItem if any player owns that item
    var buyPrice = 0;
    if (catalogItem.VirtualCurrencyPrices.hasOwnProperty(requestedVcType))
        buyPrice = catalogItem.VirtualCurrencyPrices[requestedVcType];
    if (buyPrice <= 0)
        throw "Cannot redeem this item for: " + requestedVcType; // The client requested a virtual currency which doesn't apply to this item
    // Once we get here all safety checks are passed - Perform the sell
    var sellPrice = Math.floor(buyPrice * SELL_PRICE_RATIO);
    server.AddUserVirtualCurrency({ PlayFabId: currentPlayerId, Amount: sellPrice, VirtualCurrency: requestedVcType });
    server.RevokeInventoryItem({ PlayFabId: currentPlayerId, ItemInstanceId: soldItemInstanceId });
}

handlers.SellItem = function (args) {
    if (!args || !args.soldItemInstanceId || !args.requestedVcType)
        throw "Invalid input parameters, expected soldItemInstanceId and requestedVcType";
    SellItem_internal(args.soldItemInstanceId, args.requestedVcType);
};
```

### Pratiques exemplaires

* Assurez-vous de vérifier que toutes les informations saisies par le client sont *valides* avant d'effectuer toute modification.

* CloudScript n'est pas atomique; l'ordre des appels est donc important : **AddUserVirtualCurrency** peut réussir et **RevokeInventoryItem** échouer.

<Tip>
  Dans ce processus, il est généralement préférable de donner au joueur quelque chose qu'il *n'a pas* mérité plutôt que de lui retirer quelque chose *sans* compensation.
</Tip>

Cette fonction CloudScript est ensuite accessible depuis le client.

```csharp theme={null}
void SellItem()
{
    PlayFabClientAPI.ExecuteCloudScript(new ExecuteCloudScriptRequest
    {
        // This must match "SellItem" from the "handlers.SellItem = ..." line in the CloudScript file
        FunctionName = "SellItem",
        FunctionParameter = new Dictionary<string, string>{
            // This is a hex-string value from the GetUserInventory result
            { "soldItemInstanceId", "sellItemInstanceId" },
            // Which redeemable virtual currency should be used in your game
            { "requestedVcType", "AU" },
        }
    }, LogSuccess, LogFailure);
}
```


## Related topics

- [Vue d'ensemble des articles et de l'inventaire](/fr-CA/services/playfab/economy-monetization/economy-v2/inventory/items-and-inventory-overview.md)
- [Démarrage rapide de l'inventaire des joueurs](/fr-CA/services/playfab/economy-monetization/economy-v2/inventory/quickstart.md)
- [Démarrage rapide](/fr-CA/services/playfab/economy-monetization/economy-v2/quickstart.md)
- [Historique des transactions](/fr-CA/services/playfab/economy-monetization/economy-v2/inventory/transaction-history.md)
- [API d'inventaire PlayFab](/fr-CA/services/playfab/economy-monetization/economy-v2/inventory/index.md)