Passer au contenu principal
La famille de commandes playfab service-principal est expérimentale. Son interface CLI peut changer ou être supprimée en fonction des retours. Un pipeline d’intégration continue (CI) ou une autre tâche sans surveillance se connecte en tant que principal de service Microsoft Entra ID ; consultez Authentification pour l’automatisation (principal de service). PlayFab n’accepte le principal de service qu’une fois qu’une personne lui a accordé l’accès dans un studio PlayFab. Ces commandes gèrent ces octrois d’accès. Seule une personne connectée disposant de l’autorisation Admin sur le studio peut exécuter ces commandes. Elles refusent de s’exécuter lorsque XBOX_AUTHENTICATION__MODE sélectionne un mode principal de service : connectez-vous donc plutôt avec xbox auth login. list accepte --output table ; les autres commandes non. list renvoie une page : lorsqu’il en existe davantage, le ContinuationToken de la réponse est défini, et exécuter de nouveau list avec --continuation-token défini sur cette valeur permet d’obtenir la page suivante.

Identificateurs

  • --studio-id désigne le studio propriétaire des octrois d’accès. Ces commandes n’acceptent pas de titre PlayFab : --playfab-title-id et le contexte enregistré ne s’appliquent donc pas.
  • --principal-tenant-id et --principal-object-id identifient le principal de service : son locataire Entra ID, et l’ID d’objet de son application d’entreprise, et non de son inscription d’application. xbox auth status le signale sous la forme objectId lorsque vous êtes connecté en tant que principal de service.
  • Vous ne passez pas l’ID d’application (client). PlayFab l’enregistre à partir du premier jeton du principal de service, et list et get le signalent sous la forme ClientId.
  • Les options globales --tenant-id et --client-id configurent votre propre connexion, et non le principal de service auquel vous accordez l’accès.

Fichier d’octrois d’accès

set remplace tous les octrois d’accès du principal de service par le contenu de --grants-file, et supprime toute autorisation de studio ou tout titre que le fichier omet.
Partez des octrois d’accès actuels plutôt que d’écrire un fichier à partir de zéro. Enregistrez la sortie de get, modifiez ses StudioPermissions et TitleGrants, puis passez-la à set, avec sa Version en tant que --expected-version :
Un fichier d’octrois d’accès peut être la sortie complète de get, son data, l’objet ServicePrincipal qu’il contient, ou uniquement les octrois d’accès :
  • Les deux propriétés sont obligatoires. Une liste vide n’accorde rien de ce type.
  • Chaque titre a besoin d’au moins une autorisation. Pour supprimer l’octroi d’accès d’un titre, omettez le titre.
  • Les noms de propriétés ne respectent pas la casse. Une propriété non reconnue est une erreur : ainsi, un TitleGrants mal orthographié ne peut pas supprimer tous les octrois d’accès aux titres.
  • Les champs TenantId, ObjectId et DisplayName du fichier, lorsqu’ils sont présents, doivent correspondre à --principal-tenant-id, --principal-object-id et --display-name. Pour renommer le principal de service, modifiez également DisplayName dans le fichier, ou supprimez-le.

Version attendue

Chaque modification des octrois d’accès d’un principal de service leur attribue une nouvelle Version, que renvoient get et set. Avec --expected-version, set ne modifie rien, sauf si les octrois d’accès sont toujours à cette version : elle ne peut donc pas annuler une modification effectuée par quelqu’un après votre lecture. --expected-version 0 exige que le principal de service n’ait encore aucun accès. Sans --expected-version, set remplace les octrois d’accès quels qu’ils soient actuellement. Lorsque le fichier d’octrois d’accès comporte une Version, --expected-version est obligatoire et doit lui être égale. Si elles diffèrent, exécutez de nouveau get et refaites vos modifications sur sa sortie. Pour remplacer les octrois d’accès dans tous les cas, supprimez Version du fichier et omettez --expected-version.

En cas d’échec de set

Si set échoue, le principal de service peut n’avoir aucun accès dans le studio jusqu’à ce qu’un set réussisse, ce qui peut interrompre un pipeline.
Un échec n’indique pas si les octrois d’accès ont changé : n’exécutez donc pas de nouveau set avec l’ancienne version. Exécutez get, vérifiez ses octrois d’accès et sa Version, et s’ils ne correspondent pas à ce que vous vouliez définir, modifiez cette sortie et passez-la à set avec sa Version en tant que --expected-version.

Exemples

Répertorier les principaux de service d’un studio, et afficher les octrois d’accès de l’un d’eux :
Remplacer les octrois d’accès du principal de service par ceux de grants.json, que vous avez enregistré à partir de get et modifié :
Supprimer le principal de service et ses octrois d’accès du studio :
Après revoke, la requête PlayFab suivante du principal de service dans le studio échoue. revoke réussit également lorsque le principal de service n’a déjà aucun accès. Pour restaurer l’accès, exécutez set avec l’ensemble complet des octrois d’accès.
Dernière modification le 19 novembre 2026