xbox) está diseñada para que la ejecuten agentes de IA y scripts, además de personas. Sus
comandos aceptan argumentos explícitos, sus comandos de datos escriben JSON y sus errores van a stderr
con un código de salida distinto de cero. Esta página está dirigida a los agentes y a las personas que los configuran: cómo
iniciar sesión, elegir sobre qué actúa un comando, leer su salida y encontrar la API adecuada, y qué
preguntar antes de cambiar algo.
Antes de cambiar algo
El usuario que ha iniciado sesión suele tener derechos de administrador en los títulos y vendedores de producción, y nada en el lado del servidor detiene una llamada errónea. Seguridad y operaciones destructivas enumera sobre qué pregunta la CLI y sobre qué no. El resto depende de ti:- Trata una operación de PlayFab como de solo lectura únicamente si su nombre empieza por
Get,ListoSearch. Trata cualquier otra operación, y cualquier comandoxboxque cree, cambie o elimine algo, como un cambio en producción. - Antes de un cambio en producción, muestra al usuario el comando y explica en una frase qué
cambia y en qué título o vendedor, incluido si ese destino procede del contexto
guardado. Ejecútalo solo después de que diga que sí, aunque tu entorno de ejecución ejecutase
xboxsin preguntar. Un sí solo abarca las llamadas que mostraste. - Pasa el título o el vendedor como marca en cada cambio en producción. El contexto guardado lo comparten todas las sesiones del usuario del sistema operativo, por lo que puede cambiar entre el sí del usuario y tu llamada.
- Pregunta antes de
xbox pc sandbox set, que cambia el sandbox para todos los usuarios del PC, y antes dexbox pc sandbox launch-apps, que cierra Microsoft Store y la aplicación XBOX. - No agregues
--confirm(ni--yes) en lugar de preguntar. La CLI no puede saber quién lo agregó. - Antes de pedir permiso para publicar en RETAIL con
xbox xbl config publish, ejecútalo con--validate-onlyy muestra al usuario los logros que enumera. Después, publica con--configsetestablecido en elSourceVersionde su salida JSON. Los logros de RETAIL no se pueden quitar; consulta Logros que agrega una publicación en RETAIL. - Si un cambio en producción falla y su resultado es desconocido, es posible que se haya aplicado. Lee el estado afectado antes de reintentarlo; consulta Una escritura interrumpida indica que su resultado es desconocido.
- No modifiques el contexto guardado a menos que el usuario te lo pida.
xbox context set,xbox context unsetyxbox context profile deletecambian los valores predeterminados de todas las sesiones.
Inicio de sesión
auth status sale con el código 0 e indica {"signedIn":false} cuando nadie ha iniciado sesión, así que
ramifica según signedIn. Un código de salida distinto de cero significa que no pudo comprobarlo, y el error está en stderr.
Las llamadas a PlayFab fallan a menos que el usuario que ha iniciado sesión tenga el permiso Admin en el título. Consulta
Autenticación.
Elegir el título o el vendedor
Pasa el título o el vendedor como marca, por ejemplo--playfab-title-id ABC123. Sin ella, un
comando usa una variable de entorno XBOX_ o un valor guardado con xbox context set; consulta
Contexto para saber cuál prevalece. Ejecuta xbox context get --output json-compact para
ver lo que hay guardado y confirma el título con el usuario una vez antes de llamar a algo
importante.
Leer la salida
Combina--data-only y --output json-compact para obtener solo la carga útil, en una sola línea:
--data-only, stdout está
vacío cuando hay un error, así que comprueba el código de salida antes de analizar stdout.
playfab file upload, download y delete no escriben nada en stdout, y sus mensajes de stderr
pueden cambiar, así que comprueba su código de salida. Consulta Archivos.
La Ayuda marca los comandos Experimental, cuya interfaz puede cambiar. Consulta
Comandos experimentales.
Límites de velocidad
Cuando un servicio XBOX responde con HTTP 429, espera antes de volver a intentarlo; la CLI no reintenta por ti. Cuando el servicio especifica una espera, el error indica cuántos segundos, y los errores estructurados también la incluyen comoretryAfterSeconds. Un 429 con el código de error rate_limited significa que enviaste demasiadas
solicitudes en poco tiempo, así que reduce el ritmo.
Encontrar la API de PlayFab adecuada
xbox playfab api <api-path> llama a cualquier operación de la API de PlayFab. La ruta es
/<Prefix>/<Operation>, como /MultiplayerServer/ListBuildSummariesV2, y el cuerpo de la
solicitud es el objeto de solicitud JSON de la operación. PlayFab documenta ambos:
- Las especificaciones Swagger de PlayFab
son legibles por máquina. Cada archivo enumera sus operaciones por ruta, con sus esquemas de solicitud y
respuesta y los campos obligatorios. Los archivos llevan el nombre de los grupos de API de PlayFab, no
del primer segmento de la ruta, así que busca la operación en las
pathsde los archivos:/Cataloge/Inventoryestán enEconomy.swagger.json, y/Match,/Lobbyy/MultiplayerServerestán enMultiplayer.swagger.json. El camposecurityde cada operación indica la credencial que acepta:SecretKey,EntityToken,SessionTicketoNonepara las operaciones que no necesitan credenciales, como las llamadas de inicio de sesión de jugadores. Algunas operaciones también enumeran en su descripción los tipos de token de entidad permitidos. - La referencia de la API REST de PlayFab abarca las mismas operaciones para personas.
SessionTicket de jugador, o que solo aceptan tokens de entidad de jugador o
de servidor de juegos, no están autorizadas. Cuando una llamada falla, su respuesta de error suele indicar el problema, como
InvalidParameter o MissingParameter. Consulta Integración de la API de PlayFab para
obtener más información.
En Git Bash en Windows, establece MSYS_NO_PATHCONV=1 para el comando, porque, de lo contrario, Git Bash
convierte la ruta de la API en una ruta de Windows antes de que la CLI la reciba. Consulta
Ejecución desde Git Bash en Windows.
Mantener los secretos fuera de los registros
- Cuando el cuerpo de una solicitud pueda contener secretos, pásalo con
--body-fileen lugar de--body, para que no aparezca en el historial del shell ni en las listas de procesos.playfab mps certificate uploadyplayfab mps secret uploadrechazan--body, porque su cuerpo siempre contiene uno. - Mantén los secretos fuera de los archivos de configuración y de las variables de entorno.
ClientId,TenantIdy los ámbitos de OAuth son identificadores, no secretos. - Las respuestas de PlayFab pueden contener datos de jugadores, inventario o economía. La redacción, la retención y el control de acceso de todo lo que registre un agente son responsabilidad del propietario del agente.
Consulta también
- Comandos: la referencia completa de comandos
- Seguridad y operaciones destructivas: qué pregunta primero y qué hace más de lo que indica su nombre
