Saltar al contenido principal
La familia de comandos playfab service-principal es experimental. Su interfaz de la CLI puede cambiar o quitarse en función de los comentarios. Una canalización de integración continua (CI) u otro trabajo desatendido inicia sesión como una entidad de servicio de Microsoft Entra ID; consulta Autenticación para automatización (entidad de servicio). PlayFab acepta la entidad de servicio solo después de que una persona le conceda acceso en un estudio de PlayFab. Estos comandos administran esas concesiones. Solo una persona que haya iniciado sesión y tenga el permiso Admin en el estudio puede ejecutar estos comandos. Se niegan a ejecutarse cuando XBOX_AUTHENTICATION__MODE selecciona un modo de entidad de servicio, así que inicia sesión con xbox auth login en su lugar. list acepta --output table; los demás comandos no. list devuelve una página: cuando existen más, se establece el ContinuationToken de la respuesta, y volver a ejecutar list con --continuation-token establecido en ese valor obtiene la página siguiente.

Identificadores

  • --studio-id indica el estudio propietario de las concesiones. Estos comandos no aceptan un título de PlayFab, por lo que --playfab-title-id y el contexto guardado no se aplican.
  • --principal-tenant-id y --principal-object-id identifican la entidad de servicio: su inquilino de Entra ID y el identificador de objeto de su aplicación empresarial, no el de su registro de aplicación. xbox auth status lo indica como objectId cuando se ha iniciado sesión como la entidad de servicio.
  • No pasas el identificador de aplicación (cliente). PlayFab lo registra a partir del primer token de la entidad de servicio, y list y get lo indican como ClientId.
  • Las opciones globales --tenant-id y --client-id configuran tu propio inicio de sesión, no la entidad de servicio a la que concedes acceso.

Archivo de concesiones

set reemplaza todas las concesiones de la entidad de servicio por el contenido de --grants-file, y quita cualquier permiso de estudio o título que el archivo omita.
Parte de las concesiones actuales en lugar de escribir un archivo desde cero. Guarda la salida de get, edita sus StudioPermissions y TitleGrants, y pásala a set, con su Version como --expected-version:
Un archivo de concesiones puede ser la salida completa de get, su data, el objeto ServicePrincipal que contiene o solo las concesiones:
  • Ambas propiedades son obligatorias. Una lista vacía no concede nada de ese tipo.
  • Cada título necesita al menos un permiso. Para quitar la concesión de un título, omite el título.
  • Los nombres de propiedad no distinguen mayúsculas de minúsculas. Una propiedad no reconocida es un error, de modo que un TitleGrants mal escrito no puede quitar todas las concesiones de títulos.
  • Los valores TenantId, ObjectId y DisplayName del archivo, cuando están presentes, deben coincidir con --principal-tenant-id, --principal-object-id y --display-name. Para cambiar el nombre de la entidad de servicio, cambia también DisplayName en el archivo o quítalo.

Versión esperada

Cada cambio en las concesiones de una entidad de servicio les asigna una nueva Version, que devuelven get y set. Con --expected-version, set no cambia nada a menos que las concesiones sigan en esa versión, por lo que no puede deshacer un cambio que alguien hizo después de que las leyeras. --expected-version 0 requiere que la entidad de servicio aún no tenga acceso. Sin --expected-version, set reemplaza las concesiones sean cuales sean en ese momento. Cuando el archivo de concesiones tiene una Version, --expected-version es obligatoria y debe ser igual a ella. Si son distintas, vuelve a ejecutar get y rehaz tus modificaciones sobre su salida. Para reemplazar las concesiones de todos modos, quita Version del archivo y omite --expected-version.

Si set falla

Si set falla, es posible que la entidad de servicio no tenga acceso en el estudio hasta que un set se complete correctamente, lo que puede dejar sin acceso a una canalización.
Un error no indica si las concesiones cambiaron, así que no vuelvas a ejecutar set con la versión anterior. Ejecuta get, comprueba sus concesiones y su Version y, si no son las que querías establecer, edita esa salida y pásala a set con su Version como --expected-version.

Ejemplos

Enumerar las entidades de servicio de un estudio y mostrar las concesiones de una:
Reemplazar las concesiones de la entidad de servicio por las de grants.json, que guardaste a partir de get y editaste:
Quitar del estudio la entidad de servicio y sus concesiones:
Después de revoke, la siguiente solicitud de PlayFab de la entidad de servicio en el estudio falla. revoke también se completa correctamente cuando la entidad de servicio ya no tiene acceso. Para restaurar el acceso, ejecuta set con el conjunto completo de concesiones.
Última modificación el 19 de noviembre de 2026