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

# Interroger les droits d'utilisation des utilisateurs à partir de vos services

> Interrogez les droits d'utilisation des utilisateurs à partir de vos services au moyen des API Collections Query du Microsoft Store, y compris les droits d'utilisation satisfaisants et l'état de propriété.

Les API Collections Query constituent le principal moyen pour les services de déterminer la propriété et l'état des droits d'utilisation des utilisateurs. Comparativement aux API XStore côté client, les requêtes de service à service prennent en charge des scénarios plus vastes au niveau de l'éditeur ainsi que des architectures de services centralisées.

Les résultats des API Collections comprennent uniquement les produits que l'utilisateur ciblé possède directement ou qu'il a directement le droit d'utiliser. Les droits d'utilisation partagés valides sur le client ne sont pas renvoyés dans les réponses de service à service. Pour plus d'information sur les scénarios de partage, consultez [Modèle de partage de produits pour les jeux](/fr-CA/publishing/xstore-commerce/xstore-product-sharing).

Cet article vous aide à comprendre les API Query et à les intégrer au moyen des sections suivantes :

* [Choisir l'API Collections Query adaptée à vos besoins](#selecting-the-right-collections-query-api-for-your-needs)
* [Comprendre les droits d'utilisation satisfaisants dans la réponse](#understanding-satisfying-entitlements-in-the-response)
* [Comprendre les éléments en double dans la réponse](#understanding-duplicate-items-in-the-response)

<Note>
  Consultez les [prérequis pour les API de service à service](/fr-CA/publishing/xstore-commerce/xstore-authenticating-service). Si les produits ne sont pas correctement configurés pour votre type d'authentification, les appels peuvent réussir, mais ne renvoyer aucun résultat.
</Note>

## Choisir l'API Collections Query adaptée à vos besoins

Il existe deux versions de Collections Query : `b2bLicensePreview` (v8) et `publisherQuery` (v9). Dans la plupart des cas, utilisez `publisherQuery`, car ses paramètres de requête sont simplifiés et elle prend en charge l'état XBOX Game Pass. Utilisez `b2bLicensePreview` lorsque vous avez besoin de comportements hérités, comme la prise en charge de LegacyProductId.

| Fonctionnalité de l'API Query | [b2bLicensePreview (v8)](/fr-CA/reference/microsoft-store-apis/xstore-v8-query-for-products) | [publisherQuery (v9)](/fr-CA/reference/microsoft-store-apis/xstore-v9-query-for-products) |
| - | - | - |
| Afficher l'état de l'abonnement XBOX Game Pass d'un utilisateur | Non | Oui |
| Authentification par jeton X | Oui | Oui |
| Authentification Microsoft Entra ID / User Store ID | Oui | Oui |
| StoreId de Partner Center | Oui | Oui |
| LegacyProductId (ID de produit provenant d'XBOX Inventory / XBOX Developer Portal) | Oui | Non |
| Possibilité de désactiver les résultats de droits d'utilisation satisfaisants | Oui | Non |

<Note>
  Bien qu'il n'existe pas d'URI v9 équivalent pour la fonctionnalité de consommation, vous pouvez utiliser publisherQuery et l'URI de consommation v8 ensemble sans problème.
</Note>

## Comprendre les droits d'utilisation satisfaisants dans la réponse

Un utilisateur peut avoir un droit d'utilisation sur un produit directement (achat/échange) ou indirectement (ensemble/abonnement). Si le droit d'utilisation est indirect, le tableau `satisfiedByProductIds` contient le ou les ProductId dont provient le droit d'utilisation.

Exemple : Un utilisateur a acheté l'ensemble Édition Deluxe d'un jeu. L'appel des API Query renvoie dans le résultat le produit du jeu et tous les produits inclus dans l'ensemble. Chacun de ces éléments contient le ProductID de l'ensemble Édition Deluxe dans sa liste `satisfiedByProductIds`.

## Comprendre les éléments en double dans la réponse

Vous pourriez voir plusieurs éléments ayant le même ProductId/SKU lorsque des utilisateurs ont plusieurs sources de droits d'utilisation. Les différences apparaissent habituellement dans des champs comme `acquisitionType`, les dates et `satisfiedByProductIds`. Définissez `excludeDuplicates` sur true pour regrouper plusieurs sources de droits d'utilisation en un seul élément correspondant au droit de propriété le plus direct, dans cet ordre :

* Achat direct / code d'échange
* Droit satisfait par un ensemble acheté directement
* Droit satisfait par un abonnement
* Droit satisfait par un achat promotionnel (p. ex. Games With Gold)

Si les doublons proviennent de la même source (par exemple, des périodes d'abonnement `Active` et `Expired`), un seul élément est renvoyé (même si `excludeDuplicates` est désactivé), selon la priorité d'état suivante :

* `Active`
* `Invalid` (s'il existe plusieurs droits d'utilisation non valides, l'élément invalidé le plus récemment est renvoyé)
* `Revoked`

Les scénarios de doublons courants et leurs résultats sont présentés dans le tableau suivant.

| Scénario | `excludeDuplicates: false` | `excludeDuplicates: true` |
| - | - | - |
| Achat direct + droit d'utilisation par un ensemble | Les deux éléments peuvent apparaître. | L'élément de l'achat direct est renvoyé. |
| Achat direct + droit d'utilisation Game Pass | Les deux éléments peuvent apparaître (`Single` et `Recurring`). | L'élément de l'achat direct est renvoyé. |
| Même source de droit d'utilisation avec plusieurs périodes (par exemple, périodes d'abonnement Active + Expired) | Un seul élément est renvoyé selon la priorité d'état. | Un seul élément est renvoyé selon la priorité d'état. |

### Exemple

Un utilisateur achète le jeu A et le module complémentaire B, puis achète plus tard un passe saisonnier qui inclut aussi le module complémentaire B. La réponse peut contenir deux entrées pour le module complémentaire B : l'achat direct et le droit d'utilisation satisfaisant provenant du passe saisonnier. Si `excludeDuplicates` est défini sur true, seule l'entrée de l'achat direct est renvoyée.

## Documentation de référence des API

* [XStore (contenu de l'API)](/fr-CA/reference/system/xstore/xstore_members)

## Voir aussi

[Vue d'ensemble du commerce](/fr-CA/publishing/xstore-commerce/xstore-commerce-overview)

[Gérer les produits à partir de vos services](/fr-CA/publishing/xstore-commerce/xstore-authenticating-service)

[Référence de l'API XStore](/fr-CA/reference/system/xstore/xstore_members)


## Related topics

- [Ensembles et passes de saison](/fr-CA/publishing/xstore-commerce/xstore-bundles-season-passes.md)
- [Accorder aux joueurs l'accès au contenu des modules complémentaires](/fr-CA/publishing/xstore-commerce/xstore-granting-access.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/fr-CA/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [collections.mp.microsoft.com/v8.0/collections/consume](/fr-CA/reference/microsoft-store-apis/xstore-v8-consume.md)
- [API de modification de récurrence d'abonnement de Microsoft Store v8](/fr-CA/reference/microsoft-store-apis/xstore-v8-recurrence-change.md)