Administración de sesiones multijugador de servicio a servicio

En este tema se describe cómo usar patrones de llamada de servicio a servicio (S2S) con Multiplayer Session Directory (MPSD). Al igual que otros servicios, MPSD admite patrones de llamada S2S. Estos amplían los patrones de llamada de cliente y permiten a los servicios de título administrar de forma eficiente varios usuarios mediante llamadas de servicio individuales. La administración de sesiones multijugador a través de un servicio de título, en lugar de los clientes, puede simplificar la lógica de manejo de errores y evitar condiciones de carrera en las operaciones de escritura de la sesión. Esto se aplica específicamente a los tipos de sesión grandes con una gran cantidad de miembros. Por lo tanto, para los juegos multijugador masivos en línea (MMO) y los títulos con muchos jugadores en una sesión, el procedimiento recomendado es administrar las sesiones de MPSD a través del servidor del título. Para obtener información general sobre los patrones de llamada RESTful de MPSD, consulte Referencia RESTful de los servicios de XBOX.

Autenticación S2S de MPSD

La autenticación de las llamadas S2S al servicio multijugador de los servicios de XBOX difiere de la de otros servicios de XBOX. Las llamadas con un token Delegation no se admiten, y solo las llamadas con autenticación de servicio son funcionales. Este tipo de autenticación habilita la funcionalidad S2S adicional de MPSD. Como en otras llamadas S2S, se requiere un certificado de socio comercial (Business Partner Certificate). Debe existir una directiva Multiplayer.Manage de acceso completo. Esto es necesario para que el servicio web bajo el que se creó el certificado de socio comercial pueda proporcionar el nivel de acceso correcto para las llamadas S2S. Para la autenticación de servicio se usa el siguiente flujo de autenticación.

Llame al servicio de autorización de XBOX para servicios (XBOX Authorization Service for Services) con el certificado de socio comercial para recuperar un token S.
Llame al servicio de tokens seguros de XBOX (XSTS) con este token S y un SandboxId para recibir un token X. En este paso no debe usarse un token Delegation ni un token User. El SandboxId especificado en este flujo también debe estar en el conjunto de sandboxes que especificó durante la creación del certificado de socio comercial. Los certificados de socio comercial sin un sandbox específico no se admiten y provocan errores de autenticación que indican que falta un sandbox.
Llame al servicio de MPSD con el token X y los encabezados (tal como se especifica en la sección siguiente).

Encabezados S2S de MPSD

Encabezado de título

Para actuar como el título correcto, se requiere el encabezado X-Xbl-OnBehalfOf-Title con el siguiente formato.

X-Xbl-OnBehalfOf-Title:[titleid in decimal]

Ejemplo

Request.Headers["X-Xbl-OnBehalfOf-Title"] = "484921321";

Este encabezado debe especificarse para realizar llamadas en nombre de un título determinado.

Encabezado de usuario

Para actuar como un usuario específico o un conjunto de usuarios, se requiere el encabezado X-Xbl-OnBehalfOf-Users con el siguiente formato.

X-Xbl-OnBehalfOf-Users:[xuid][;privilege][,xuid[;privilege]]...

Ejemplo

Request.Headers["X-Xbl-OnBehalfOf-Users"] = "741837829132;priv=multiplayer","8922333146718;priv=multiplayer"

El único privilegio que se admite actualmente es priv=multiplayer. Indica que el usuario tiene el privilegio multijugador. Al usar el encabezado X-Xbl-OnBehalfOf-Users, es como si el usuario identificado en el encabezado estuviera realizando la llamada directamente desde su consola. Como resultado, el servicio que realiza la llamada debe mantener la seguridad del usuario.

Solo se pueden usar XUID reales.
Los privilegios declarados para el usuario deben ser correctos.
El usuario debe haber dado su consentimiento a cualquier acción que se haya realizado en su nombre.

El último requisito significa que el servicio solo puede realizar acciones que el propio título de la consola podría haber realizado. Por ejemplo, un servicio puede establecer a un usuario como activo en un título solo si el usuario está, de hecho, ejecutando ese título e interactuando con él en la consola. El servicio debe entonces establecer al usuario como inactivo cuando ya no esté interactuando con el título en la consola. De forma similar, un servicio puede enviar una invitación en nombre de un usuario solo si este ha realizado una acción explícita para enviar la invitación.

Encabezado Deny-Scope

La directiva de acceso Multiplayer.Manage invalida los permisos de acceso del usuario en las llamadas S2S al servicio de MPSD. Por lo tanto, el acceso a las sesiones no se restringe en función de los permisos del usuario. Para volver a habilitar las comprobaciones de permisos de usuario, puede usar el encabezado X-Xbl-Deny-Scope, como se muestra a continuación.

    X-Xbl-Deny-Scope: Multiplayer.Manage

Ejemplo

    Request.Headers["X-Xbl-Deny-Scope"] = "Multiplayer.Manage";

Este encabezado garantiza que la directiva de acceso Multiplayer.Manage no se use como invalidación al comprobar el acceso de un usuario (del encabezado de usuario) a una sesión. Puede usarse para asegurarse de que un usuario tiene el acceso correcto a una sesión y de que el acceso del servidor no está invalidando otros bloqueos debidos a restricciones de visibilidad o de unión.

Cuando establezca este encabezado, también debe conceder acceso Multiplayer.Runtime al servicio web como reserva. Esto permite el acceso incluso cuando se deniegan los permisos de usuario. De lo contrario, en un escenario de error no se concede ningún acceso al servicio y se devuelve un estado 403. El acceso Multiplayer.Runtime requiere un usuario que actúe. El encabezado X-Xbl-Deny-Scope solo funciona junto con X-Xbl-OnBehalfOf-Users o una notificación de usuario obtenida de una notificación DelegationToken.

Administración de miembros de sesión

Puede optimizar la administración de miembros de sesión en las llamadas S2S dirigiéndose a varios usuarios en una sola llamada. Cuando especifica el encabezado de usuario, no se puede usar el miembro estándar “me” en el cuerpo del documento de sesión. En su lugar, están disponibles las siguientes opciones.

{
    "members": {

        // (For example, me_59135345328) Requires a user principal with an xuid claim.
        "me_{xuid}": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },
        },

        // Applies the requested change to each acting user's member.
        "me_all": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },
        },

        // Applies the requested change to each acting user's member if they're 
        // already in the session.
        "me_allInSession": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },

        // Requires a single user principal with an xuid claim.
        "me": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },
        },

        }
    }
}

Los servicios de título deben usar estos patrones para realizar operaciones en varios usuarios (por ejemplo, agregar o quitar jugadores) mediante una sola llamada a MPSD.

Adición de miembros de sesión

Puede agregar o modificar miembros de sesión usando uno de los patrones mencionados anteriormente. En general, la operación mínima para agregar un jugador es establecer una propiedad o constante, normalmente la propiedad de estado activo del miembro.

Los miembros que no están establecidos como activos son eliminados automáticamente por el servicio en función del valor de InactiveTimeout de la sesión de MPSD.

Debe establecer otras propiedades y constantes necesarias para el usuario mediante la misma llamada (según sea necesario).

{
    "members": {

        "me_{xuid}": {
            "constants": { /* Property Bag */ },
            "properties": { "system": { "active": true } 
                            /* Additional Properties */ },
        }
    }
}

Ejemplo

{
     // Adding two session members with one call.
    "members": {

        "me_1234567890123456": {
            "properties": { "system": { "active": true }},
        },

        "me_2345678901234567": {
            "properties": { "system": { "active": true }},        
        } 
    }
}

Eliminación de miembros de sesión

Puede quitar miembros de sesión estableciendo la sección del miembro en null.

{
    "members": {

        "me_{xuid}": {
            null,
        }
    }
}

Ejemplo

{
     // Removing two session members with one call.
    "members": {

        "me_1234567890123456": {
            null,
        },

        "me_2345678901234567": {
            null,
        } 
    }
}

Reservas de miembros

En general, las reservas para miembros de sesión no son necesarias si toda la administración de la sesión la realiza el servicio del título. En este escenario, puede agregar y quitar miembros de sesión directamente sin necesidad de reservas. Las reservas de miembros de sesión solo deben usarse si las sesiones creadas también son administradas después por el cliente. Puede agregar reservas a la sesión para varios usuarios en el orden de usuarios especificado en el encabezado on-behalf-of-user. El siguiente patrón solo es válido al crear una sesión nueva.

{
    "members": {

        // Reservation requests must start with zero.
        "reserve_0": {
            "constants": { "system": {"xuid": "{xuid}" }
                           /* additional constants */ }
        },

        "reserve_1": {
            "constants": { "system": {"xuid": "{xuid}" }
                           /* additional constants */ }
        },

        //...//

    }
}

Ejemplo

{
     // Adding reservations for two session members with one call.
    "members": {

        "reserve_0": {
            "constants": { "system": {"xuid": "1234567890123456" }}
        },

        "reserve_1": {
            "constants": { "system": {"xuid": "2345678901234567" }}
        },
    }
}

Las sesiones grandes no admiten reservas. No se admite mezclar reservas con la adición o eliminación de miembros de sesión.

Estado de los miembros de sesión

Un servicio de título puede realizar el seguimiento y establecer el estado de un miembro de sesión mediante propiedades del sistema. Esto permite un control total del estado y la información del miembro.

Estado activo del miembro

El estado activo de un miembro marca al jugador como activo en la sesión. Esto evita su eliminación por parte del sistema según lo definido en la configuración de sesión inactiveRemovalTimeout, como se muestra a continuación.

{
    "members": {

        // Member access through XUID.
        "me_{xuid}": {
            "properties": { "system": {"active": [true|false] }
                           /* additional constants */ }
        }
    }
}

En general, siempre debe establecer los miembros de sesión como active cuando se agregan a la sesión. Solo debe usar miembros inactivos en flujos en los que los miembros de sesión deban permanecer temporalmente en la sesión, incluso si están desconectados. En los flujos S2S, esto también puede administrarse directamente en el servidor del título.

Estado de reserva del miembro

Puede determinar el estado de reserva de un miembro de sesión mediante la propiedad reserved member. Si esta propiedad está establecida en true, el miembro de sesión está en estado de reserva y aún no está activo en la sesión. A continuación se muestra un documento de sesión de ejemplo.

{
    /.../

    "members": {

        // First session member as an example.
        "1": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },

            /.../

            "reserved": true,
            /.../
        }
    }
}

MPSD quita estos miembros de la sesión cuando expira reservedRemovalTimeout.

Limitaciones de las sesiones grandes

Las sesiones de MPSD con la capacidad large habilitada admiten más de 100 jugadores. Estas sesiones funcionan de forma diferente a las sesiones normales. Para obtener más información, consulte Habilitar sesiones grandes para multijugador. Las operaciones en sesiones grandes siempre se realizan como un solo usuario. Como resultado, las llamadas S2S a sesiones grandes solo deben incluir un único usuario en el encabezado X-Xbl-OnBehalfOf-Users. No se admiten operaciones con varios usuarios. Debe agregar o quitar usuarios mediante llamadas individuales para cada usuario. Realice estas llamadas S2S de forma secuencial para evitar la congestión de bloqueos en el documento de sesión subyacente. Las operaciones en paralelo sobre el mismo documento producen tiempos de llamada más largos y no aceleran el tiempo total de la operación. Los resultados de las llamadas S2S tampoco proporcionan acceso a la lista completa de miembros de una sesión grande. Solo se devuelven los datos del miembro correspondiente al usuario especificado en la llamada. Como resultado, los servicios de título deben realizar el seguimiento de la información de los miembros de las sesiones grandes con su propia lógica y usar la pertenencia de MPSD para cumplir correctamente los requisitos de XBOX (XR).

Encuentros y grupos

Las sesiones con la capacidad large no actualizan automáticamente la lista de jugadores recientes. En su lugar, los demás jugadores se agregan directamente a la lista de jugadores recientes mediante encuentros (Encounters) y grupos (Groups). Para obtener más detalles, consulte Habilitar sesiones grandes para multijugador. Use el siguiente patrón para marcar miembros de sesión como parte de un encuentro.

{
    "members": {

        "me_{xuid}": {
            "properties": { 
                "system": { 
                    "encounters": [ "{uniqueEncounterID1}", 
                                    "{uniqueEncounterID2}",
                                    // ... //
                                  ] },
        }
    }
}

Ejemplo

{
     // Marking two members as part of the same encounter.
    "members": {

        "me_1234567890123456": {
            "properties": {
                "system": {
                    "encounters": [ "757093D8-E41F-49D0-BB13-17A49B20C6B9" ] }},
        },

        "me_2345678901234567": {
            "properties": {
                "system": {
                    "encounters": [ "757093D8-E41F-49D0-BB13-17A49B20C6B9" ] }},
        },
    }
}

Para capturar correctamente un encuentro, la propiedad encounters debe escribirse en todos los miembros de sesión participantes en menos de 30 segundos. El conjunto de encuentros es una propiedad de un momento dado. Se consume inmediatamente y no es visible en una respuesta.

Use el siguiente patrón para marcar miembros de sesión como parte de un grupo.

{
    "members": {

        "me_{xuid}": {
            "properties": { 
                "system": { 
                    "groups": [ "{uniqueGroupID1}", 
                                "{uniqueGroupID2}",
                                // ... //
                              ] },
        }
    }
}

Ejemplo

{
     // Marking two members as part of the same group.
    "members": {

        "me_1234567890123456": {
            "properties": { 
                "system": { 
                    "groups": [ "group-ADFB431" ] }},
        },

        "me_2345678901234567": {
            "properties": { 
                "system": { 
                    "groups": [ "group-ADFB431" ] }},
        },
    }
}

La lista de grupos se reemplaza con cada operación de escritura. Para quitar a un miembro de un grupo, quite el grupo de la lista de la propiedad groups. Una operación de escritura con una lista vacía elimina todas las pertenencias a grupos.

La propiedad groups es persistente y es visible en las respuestas de un miembro.

Administración de la sesión de actividad

El identificador (handle) de actividad de MPSD de un usuario determina qué sesión se usa para las invitaciones de la plataforma y la unión a una partida en curso. Este identificador no puede establecerse mediante llamadas S2S y solo está disponible a través de las API de cliente. Un servidor del título puede compartir el nombre de la sesión con un cliente para permitir la creación del identificador de actividad de una sesión S2S. Para obtener más información sobre los identificadores, consulte lo siguiente:

La sección Session handles del tema de información general sobre conceptos de multijugador
La sección MPSD handles to sessions del tema de información general de Multiplayer Session Directory

Para el control directo de la actividad del jugador, consulte Multiplayer Activity Service (MPA). Tenga en cuenta que MPA y MPSD no pueden usarse al mismo tiempo.

Procedimientos recomendados

Al realizar llamadas S2S a MPSD, los títulos deben seguir los siguientes procedimientos recomendados para evitar problemas y mejorar el rendimiento.

Combine las operaciones para varios usuarios Siempre que sea posible, las llamadas S2S a MPSD deben realizarse como operaciones por lotes para varios usuarios. Esto mejora el rendimiento y reduce el tráfico de red. Un enfoque eficiente para reducir las llamadas es poner en cola las operaciones de MPSD en el servidor del título y combinar todas las solicitudes en intervalos de cinco segundos. Esto proporciona un equilibrio entre eficiencia y latencia.
Combine varias operaciones de sesión y de miembros Los títulos deben asegurarse de combinar las operaciones de usuario tanto como sea posible. La adición de miembros de sesión siempre debe combinarse con el establecimiento de todas las propiedades relevantes del miembro al mismo tiempo.
Realice de forma secuencial las llamadas S2S al mismo documento Todas las llamadas al mismo documento de MPSD deben realizarse siempre de forma secuencial. Realizar operaciones en paralelo puede causar congestión de bloqueos en el documento de MPSD subyacente y provocar un rendimiento más lento y solicitudes con error.
Responda a las operaciones de identificadores de actividad en el cliente Los identificadores de actividad de MPSD solo se admiten a través de las API de cliente. Un servicio de título debe usar un cliente para crear estos identificadores compartiendo el nombre de la sesión y usando las API de cliente pertinentes.
Las suscripciones de sesión del cliente y la conectividad no son necesarias Para todas las sesiones de MPSD que se administran completamente mediante llamadas S2S, la capacidad de conectividad no es necesaria. En los flujos de llamada S2S, no se necesitan conexiones WebSocket con el cliente. En su lugar, el servicio del título debe encargarse por completo de agregar o quitar directamente los miembros de sesión.
Operaciones de sesiones grandes La lógica S2S para sesiones grandes debe manejarse de forma diferente a la de las sesiones pequeñas, porque las operaciones con varios miembros no están disponibles. Los servicios de título deben realizar de forma secuencial todas las operaciones sobre el mismo documento de sesión, incluida la adición o eliminación de miembros. Con un gran número de miembros, esto puede producir retrasos en la operación de miembros. Estos retrasos son aceptables y no infringen los requisitos de la plataforma. Para simplificar la lógica de miembros en las sesiones grandes, un título puede usar la sesión de MPSD solo para realizar el seguimiento de la pertenencia de los jugadores y manejar internamente todos los demás datos de los jugadores. Lo más sencillo es crear la sesión grande de MPSD para un servidor del título en el momento del inicio del servidor, incluso sin jugadores en ella. Esto requiere la configuración de sessionEmptyTimeout en las constantes de la sesión de MPSD, como se muestra en los ejemplos siguientes.
Unión a una partida en curso o invitaciones en sesiones grandes Las sesiones grandes admiten la unión a una partida en curso y las invitaciones a través de los servicios de XBOX. En la mayoría de los escenarios, es más sencillo usar una sesión normal para admitir esta funcionalidad. Esta sesión puede ser controlada por el servidor del título o por el cliente, y debe contener información para unirse a la sesión grande correspondiente.
Encuentros en sesiones grandes Para garantizar que los encuentros en sesiones grandes se capturen correctamente, todas las propiedades de miembro encounters deben escribirse en menos de 30 segundos. Un servicio de título siempre debe intentar agrupar en una sola llamada de servicio las actualizaciones de la propiedad encounters de todos los miembros participantes. Los encuentros deben usar un identificador único. Se recomienda usar un GUID.

Ejemplo de plantilla de sesión S2S

La siguiente plantilla de sesión es un punto de partida para una sesión controlada mediante llamadas S2S.

{
   "constants": {
        "system": {
            "version": 1,
            // Should be set to the maximum supported player number on the server.
            "maxMembersCount": 50,
            "visibility": "open",
            "inviteProtocol": "game",
            "capabilities": {
                "gameplay": true
            },
            // Optional: allows the session to linger for 60 minutes when it's empty.
            "sessionEmptyTimeout": 3600
        },
        "custom": {}
    }
}

Ejemplo de plantilla de sesión grande S2S

La siguiente plantilla de sesión es un punto de partida para una sesión grande con flujo de llamadas S2S.

{
   "constants": {
        "system": {
            "version": 1,
            // Should be set to the maximum supported player number on the server.
            "maxMembersCount": 5000,
            "visibility": "open",
            "capabilities": {
                "large": true,
                "gameplay": true
            },
            // Optional: allows the session to linger for 60 minutes when it's empty.
            "sessionEmptyTimeout": 3600
        },
        "custom": {}
    }
}

Consulte también

Referencia RESTful de los servicios de XBOX Llamadas del servicio del título a los servicios de XBOX

XBOX Services

PlayFab

Administración de sesiones multijugador de servicio a servicio

Autenticación S2S de MPSD

Encabezados S2S de MPSD

Encabezado de título

Ejemplo

Encabezado de usuario

Ejemplo

Encabezado Deny-Scope

Ejemplo

Administración de miembros de sesión

Adición de miembros de sesión

Ejemplo

Eliminación de miembros de sesión

Ejemplo

Reservas de miembros

Ejemplo

Estado de los miembros de sesión

Estado activo del miembro

Estado de reserva del miembro

Limitaciones de las sesiones grandes

Encuentros y grupos

Ejemplo

Ejemplo

Administración de la sesión de actividad

Procedimientos recomendados

Ejemplo de plantilla de sesión S2S

Ejemplo de plantilla de sesión grande S2S

Consulte también

​Autenticación S2S de MPSD

​Encabezados S2S de MPSD

​Encabezado de título

​Ejemplo

​Encabezado de usuario

​Ejemplo

​Encabezado Deny-Scope

​Ejemplo

​Administración de miembros de sesión

​Adición de miembros de sesión

​Ejemplo

​Eliminación de miembros de sesión

​Ejemplo

​Reservas de miembros

​Ejemplo

​Estado de los miembros de sesión

​Estado activo del miembro

​Estado de reserva del miembro

​Limitaciones de las sesiones grandes

​Encuentros y grupos

​Ejemplo

​Ejemplo

​Administración de la sesión de actividad

​Procedimientos recomendados

​Ejemplo de plantilla de sesión S2S

​Ejemplo de plantilla de sesión grande S2S

​Consulte también

Autenticación S2S de MPSD

Encabezados S2S de MPSD

Encabezado de título

Ejemplo

Encabezado de usuario

Ejemplo

Encabezado Deny-Scope

Ejemplo

Administración de miembros de sesión

Adición de miembros de sesión

Ejemplo

Eliminación de miembros de sesión

Ejemplo

Reservas de miembros

Ejemplo

Estado de los miembros de sesión

Estado activo del miembro

Estado de reserva del miembro

Limitaciones de las sesiones grandes

Encuentros y grupos

Ejemplo

Ejemplo

Administración de la sesión de actividad

Procedimientos recomendados

Ejemplo de plantilla de sesión S2S

Ejemplo de plantilla de sesión grande S2S

Consulte también