Passer au contenu principal
La famille de commandes playfab service-principal est expérimentale. Son interface CLI pourrait changer ou être retirée en fonction des commentaires. 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 accepte le principal de service seulement après 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 de principal de service; connectez-vous donc plutôt avec xbox auth login. list accepte --output table; les autres commandes ne l’acceptent pas. list retourne une seule page : lorsqu’il y en a d’autres, le ContinuationToken de la réponse est défini, et exécuter list de nouveau avec --continuation-token défini à cette valeur permet d’obtenir la page suivante.

Identificateurs

  • --studio-id nomme 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 celui de son inscription d’application. xbox auth status l’indique sous la forme objectId lorsque vous êtes connecté en tant que principal de service.
  • Vous ne transmettez pas l’ID d’application (client). PlayFab l’enregistre à partir du premier jeton du principal de service, et list et get l’indiquent 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 retire 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 transmettez-la à set, avec sa Version comme valeur de --expected-version :
Un fichier d’octrois d’accès peut être la sortie complète de get, son champ data, l’objet ServicePrincipal qu’il contient, ou seulement 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 retirer l’octroi d’accès d’un titre, omettez le titre.
  • Les noms de propriétés ne sont pas sensibles à la casse. Une propriété non reconnue constitue une erreur; ainsi, un TitleGrants mal orthographié ne peut pas retirer tous les octrois d’accès aux titres.
  • Les valeurs TenantId, ObjectId et DisplayName du fichier, lorsqu’elles sont présentes, doivent correspondre à --principal-tenant-id, --principal-object-id et --display-name. Pour renommer le principal de service, modifiez aussi DisplayName dans le fichier, ou retirez-le.

Version attendue

Chaque modification des octrois d’accès d’un principal de service leur attribue une nouvelle Version, que retournent 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 que vous les avez lus. --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 contient une Version, --expected-version est obligatoire et doit lui être égale. Si elles diffèrent, exécutez get de nouveau et refaites vos modifications sur sa sortie. Pour remplacer les octrois d’accès dans tous les cas, retirez Version du fichier et omettez --expected-version.

Si set échoue

Si set échoue, le principal de service pourrait n’avoir aucun accès dans le studio jusqu’à ce qu’une commande 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 set de nouveau 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 transmettez-la à set avec sa Version comme valeur de --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é :
Retirer 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 aussi lorsque le principal de service n’a déjà aucun accès. Pour rétablir l’accès, exécutez set avec l’ensemble complet des octrois d’accès.
Dernière modification le 19 novembre 2026