Puntos de conexión no idempotentes
Los métodos HTTP que tienen efectos secundarios al repetir llamadas se consideran no idempotentes. Esto significa que si un cliente llamara al punto de conexión y se produjera un tiempo de espera de red, no sería seguro reintentar el método, porque el recurso podría haberse actualizado sin que la red pudiera notificar al autor de la llamada que la operación se realizó correctamente. Ante un error, en lugar de reintentar, el cliente debe consultar primero para ver si la llamada se realizó correctamente. Solo si la llamada no se realizó correctamente debería reintentarla. En la API de servicios XBOX, algunas API están marcadas internamente como llamadas a puntos de conexión no idempotentes. Esto significa que si se producen errores al llamar a estos puntos de conexión, las API no reintentarán automáticamente el punto de conexión. La lista completa de API no idempotentes es:- XblMatchmakingCreateMatchTicketAsync
- XblMultiplayerWriteSessionAsync
- XblMultiplayerWriteSessionByHandleAsync
- XblMultiplayerSendInvitesAsync
- XblSocialSubmitReputationFeedbackAsync
- XblSocialSubmitBatchReputationFeedbackAsync
Métodos idempotentes
Los métodos HTTP idempotentes, por otro lado, no dejan efectos secundarios. Esto a su vez significa que es seguro reintentarlos. En la API de servicios XBOX, todos los métodos idempotentes se reintentan automáticamente bajo determinadas condiciones. La lista completa de API idempotentes son todas las API que no se han enumerado anteriormente como no idempotentes.Procedimientos recomendados de lógica de reintento
Para las llamadas idempotentes, estas condiciones deben reintentarse automáticamente:- Todos los errores de red
- 401: Unauthorized
- 408: RequestTimeout
- 429: Too Many Requests
- 500: InternalError
- 502: BadGateway
- 503: ServiceUnavailable
- 504: GatewayTimeout
Ajuste dinámico del tiempo de espera HTTP interno
XSAPI ajusta dinámicamente el tiempo de espera HTTP interno, en función del tiempo que quede en XblContextSettingsGetHttpTimeoutWindow. El tiempo de espera HTTP interno controla cuánto tiempo dedica el sistema operativo a la operación de red HTTP antes de anularla. La llamada no se reintentará a menos que queden al menos 5 segundos en XblContextSettingsGetHttpTimeoutWindow, para dar un tiempo razonable suficiente para que se complete la llamada. Esta regla no se aplica a la primera llamada, por lo que establecer XblContextSettingsSetHttpTimeoutWindow en 0 es aceptable y dará como resultado una única llamada. Esta lógica tiene el efecto de que XblContextSettingsGetHttpTimeoutWindow es más determinista sobre cuándo se producirá el retorno de la llamada API. Si se devolvió un encabezado “Retry-After”, no se realizarán reintentos hasta que se haya alcanzado el tiempo de “Retry-After”. Si el tiempo de “Retry-After” es posterior a XblContextSettingsGetHttpTimeoutWindow, la llamada retornará al final de XblContextSettingsGetHttpTimeoutWindow.Control de errores
Los desarrolladores de títulos deben usar siempre un control de errores adecuado para cada llamada de servicio, y deben asegurarse de que controlan correctamente las respuestas con error. Hay muchas condiciones del mundo real que pueden hacer que una solicitud a los servicios XBOX devuelva códigos de error, como:- La red no está disponible. Por ejemplo, el dispositivo perdió el 4G, perdió la conexión Wi-Fi o la red se cayó.
- Demasiada carga en los servicios por sobrecarga (503).
- Se produjo un error en el servicio (500).
- Se enviaron demasiadas solicitudes al servicio (429).
- Conflicto de operación de escritura (412). Por ejemplo, otro jugador de una sesión multijugador envió primero un cambio.
- El usuario ha sido expulsado o no tiene permiso.
- El usuario ha cerrado sesión.
Mejores patrones de llamada
Uso de solicitudes por lotes
Algunos puntos de conexión admiten el procesamiento por lotes o la agregación de un conjunto de solicitudes en una única llamada. Por ejemplo, con el servicio de perfiles de los servicios XBOX puede solicitar el perfil de un único usuario o los perfiles de un conjunto de usuarios. Por lo tanto, si necesita los perfiles de usuario de un conjunto de usuarios, sería muy ineficaz llamar al punto de conexión o a la API de uno en uno para cada perfil de usuario. Cada llamada agrega mucha sobrecarga de autenticación. Por lo tanto, en su lugar, pase a la API de una sola vez todos los usuarios sobre los que quiere información, para que el punto de conexión pueda procesar todos los perfiles de usuario al mismo tiempo y devolver una única respuesta.Uso del servicio de actividad en tiempo real (RTA) en lugar del sondeo
Un procedimiento recomendado es usar el servicio de actividad en tiempo real (RTA) en lugar del sondeo periódico. El servicio de actividad en tiempo real expone un socket web que envía una notificación a los clientes cuando los recursos de destino cambian en el servicio. El servicio RTA ofrece notificaciones sobre cambios de presencia, cambios de estadísticas, cambios en el documento de sesión multijugador y cambios en las relaciones sociales. Para saber en qué información está interesado el cliente, este debe suscribirse primero al elemento a través del socket web. Esto evita sondear el servicio para detectar cambios, ya que se le indicará exactamente cuándo cambia el elemento. XSAPI expone el servicio RTA como un conjunto de API de suscripción que los clientes pueden usar. Cada una de estas API tiene sus correspondientes API*ChangedHandler, que reciben una función de devolución de llamada que se llamará cuando un elemento cambie.
- XblPresenceSubscribeToDevicePresenceChange
- XblPresenceSubscribeToTitlePresenceChange
- XblUserStatisticsSubscribeToStatisticChange
- XblSocialSubscribeToSocialRelationshipChange
Uso de los administradores del lado cliente de XSAPI
XSAPI tiene un conjunto de administradores que actúan como caché y máquinas de estado que hacen todo el trabajo pesado en determinados escenarios.Administrador social
El administrador social hace todo el trabajo pesado relacionado con las listas de amigos y los perfiles. El administrador social mantiene actualizados su lista de amigos, sus perfiles y sus datos de presencia mediante el servicio RTA. El administrador social expone una API sincrónica muy adecuada para los motores de juego. Los juegos pueden llamar a las API del administrador social con frecuencia, porque el administrador social mantiene una caché en memoria con la información más reciente del servicio. Consulte Administrador social.Administrador multijugador
Para la administración de sesiones multijugador, el administrador multijugador es una solución lista para usar para los juegos multijugador tradicionales. La API del administrador multijugador incluye la administración de la lista de jugadores y de sesiones, controla las invitaciones a partidas, la unión en curso y el emparejamiento, y se conecta a su solución de red existente. Hace todo el trabajo pesado relacionado con la implementación de los flujos multijugador tradicionales. Consulte Administrador multijugador.Limitación de velocidad (limitación de velocidad específica)
Los servicios XBOX tienen una limitación de velocidad para evitar que un único dispositivo ejerza una carga extrema sobre el servicio. Es importante saber cuándo se ha limitado la velocidad de su título. Para determinar si se ha limitado la velocidad de su título, use cualquiera de estos enfoques:- Supervisar el código de estado HTTP 429
- Usar aserciones de depuración
- Usar la herramienta XBOX services Trace Analyzer