비멱등성 엔드포인트
반복 호출 시 부작용이 있는 HTTP 메서드는 비멱등성으로 간주됩니다. 즉, 클라이언트가 엔드포인트를 호출하고 네트워크 타임아웃이 발생하면, 리소스가 업데이트되었을 수 있지만 네트워크가 호출자에게 성공했음을 알릴 수 없기 때문에 메서드를 다시 시도하는 것이 안전하지 않습니다. 오류 발생 시 재시도 대신 클라이언트는 먼저 호출이 성공했는지 확인하는 쿼리를 수행해야 합니다. 호출이 성공하지 못한 경우에만 재시도해야 합니다. XBOX Services API에서 일부 API는 내부적으로 비멱등성 엔드포인트를 호출하는 것으로 표시되어 있습니다. 즉, 이러한 엔드포인트를 호출할 때 실패가 발생하면 API가 자동으로 엔드포인트를 다시 시도하지 않습니다. 비멱등성 API의 전체 목록은 다음과 같습니다.- XblMatchmakingCreateMatchTicketAsync
- XblMultiplayerWriteSessionAsync
- XblMultiplayerWriteSessionByHandleAsync
- XblMultiplayerSendInvitesAsync
- XblSocialSubmitReputationFeedbackAsync
- XblSocialSubmitBatchReputationFeedbackAsync
멱등성 메서드
반면에 멱등성 HTTP 메서드는 부작용을 남기지 않습니다. 따라서 다시 시도하는 것이 안전합니다. XBOX Services API에서 모든 멱등성 메서드는 특정 조건에서 자동으로 재시도됩니다. 멱등성 API의 전체 목록은 위에서 비멱등성으로 나열되지 않은 모든 API입니다.재시도 로직 모범 사례
멱등성 호출의 경우, 이러한 조건은 자동으로 재시도되어야 합니다.- 모든 네트워크 오류
- 401: Unauthorized
- 408: RequestTimeout
- 429: Too Many Requests
- 500: InternalError
- 502: BadGateway
- 503: ServiceUnavailable
- 504: GatewayTimeout
내부 HTTP 타임아웃의 동적 조정
XSAPI는 XblContextSettingsGetHttpTimeoutWindow에 남은 시간에 따라 내부 HTTP 타임아웃을 동적으로 조정합니다. 내부 HTTP 타임아웃은 OS가 HTTP 네트워크 작업을 중단하기 전에 이를 얼마나 오래 수행하는지 제어합니다. 호출이 완료될 만한 충분한 합리적인 시간을 제공하기 위해, XblContextSettingsGetHttpTimeoutWindow에 최소 5초가 남아 있지 않으면 호출은 재시도되지 않습니다. 이 규칙은 첫 번째 호출에는 적용되지 않으므로 XblContextSettingsSetHttpTimeoutWindow를 0으로 설정하는 것은 허용되며, 단일 호출이 발생합니다. 이 로직은 XblContextSettingsGetHttpTimeoutWindow가 API 호출이 반환될 시점에 대해 더 결정론적이 되는 효과가 있습니다. “Retry-After” 헤더가 반환된 경우, “Retry-After” 시간에 도달할 때까지 재시도가 이루어지지 않습니다. “Retry-After” 시간이 XblContextSettingsGetHttpTimeoutWindow 이후인 경우, 호출은 XblContextSettingsGetHttpTimeoutWindow의 끝에서 반환됩니다.오류 처리
타이틀 개발자는 모든 서비스 호출에 대해 항상 적절한 오류 처리를 사용해야 하며, 실패한 응답을 올바르게 처리하는지 확인해야 합니다. XBOX services에 대한 요청이 실패 코드를 반환하는 다양한 실제 조건이 있습니다. 예를 들면 다음과 같습니다.- 네트워크를 사용할 수 없습니다. 예를 들어, 장치가 4G를 잃거나 Wi-Fi를 잃거나 네트워크가 다운되었습니다.
- 서비스에 과부하가 걸렸습니다(503).
- 서비스에서 실패가 발생했습니다(500).
- 너무 많은 요청이 서비스로 전송되었습니다(429).
- 쓰기 작업 충돌(412). 예를 들어, 멀티플레이어 세션의 다른 플레이어가 먼저 변경 사항을 제출했습니다.
- 사용자가 차단되었거나 권한이 없습니다.
- 사용자가 로그아웃했습니다.
최적의 호출 패턴
일괄 처리 요청 사용
일부 엔드포인트는 요청 집합을 단일 호출로 일괄 처리하거나 집계하는 것을 지원합니다. 예를 들어, XBOX 서비스의 프로필 서비스에서는 단일 사용자의 프로필 또는 사용자 집합의 프로필을 요청할 수 있습니다. 따라서 사용자 집합에 대한 사용자 프로필이 필요한 경우 각 사용자 프로필에 대해 엔드포인트나 API를 한 번에 하나씩 호출하는 것은 매우 비효율적입니다. 각 호출은 많은 인증 오버헤드를 추가합니다. 대신, 정보를 원하는 모든 사용자를 한 번에 API로 전달하여 엔드포인트가 모든 사용자 프로필을 동시에 처리하고 단일 응답을 반환할 수 있도록 하세요.폴링 대신 Real Time Activity(RTA) 서비스 사용
주기적인 폴링 대신 Real-Time Activity(RTA) 서비스를 사용하는 것이 모범 사례입니다. Real-Time Activity 서비스는 대상 리소스가 서비스에서 변경되면 클라이언트에 알림을 보내는 웹 소켓을 노출합니다. RTA 서비스는 상태 변경, 통계 변경, 멀티플레이어 세션 문서 변경 및 소셜 관계 변경에 대한 알림을 제공합니다. 클라이언트가 관심 있는 정보를 파악하려면 클라이언트는 먼저 웹 소켓을 통해 항목을 구독해야 합니다. 이렇게 하면 항목이 변경된 정확한 시점을 알 수 있으므로 변경 사항을 감지하기 위해 서비스를 폴링하는 것을 피할 수 있습니다. XSAPI는 클라이언트가 사용할 수 있는 구독 API 세트로 RTA 서비스를 노출합니다. 이러한 각 API에는 항목이 변경될 때 호출되는 콜백 함수를 받는 해당*ChangedHandler API가 있습니다.
- XblPresenceSubscribeToDevicePresenceChange
- XblPresenceSubscribeToTitlePresenceChange
- XblUserStatisticsSubscribeToStatisticChange
- XblSocialSubscribeToSocialRelationshipChange
XSAPI 클라이언트 측 관리자 사용
XSAPI에는 특정 시나리오에 대한 모든 힘든 작업을 수행하는 캐시와 상태 머신 역할을 하는 관리자 세트가 있습니다.Social Manager
Social Manager는 친구 목록과 프로필과 관련된 모든 힘든 작업을 수행합니다. Social Manager는 RTA 서비스를 사용하여 친구 목록, 프로필, 상태 데이터를 최신 상태로 유지합니다. Social Manager는 게임 엔진 친화적인 동기 API를 노출합니다. Social Manager는 서비스의 최신 정보에 대한 메모리 내 캐시를 유지하므로 게임에서 Social Manager API를 자주 호출할 수 있습니다. Social Manager를 참조하세요.Multiplayer Manager
멀티플레이어 세션 관리의 경우, Multiplayer Manager는 전통적인 멀티플레이어 게임을 위한 드롭인 솔루션입니다. Multiplayer Manager API에는 플레이어 명부 및 세션 관리가 포함되어 있으며, 게임 초대, 진행 중 참여, 매치메이킹을 처리하고 기존 네트워킹 솔루션에 연결됩니다. 전통적인 멀티플레이어 흐름을 구현하는 것과 관련된 모든 힘든 작업을 수행합니다. Multiplayer Manager를 참조하세요.Throttling(세분화된 속도 제한)
XBOX services는 단일 장치가 서비스에 극심한 부하를 주는 것을 방지하기 위해 throttling이 설정되어 있습니다. 타이틀이 언제 throttling되었는지 아는 것이 중요합니다. 타이틀이 throttling되었는지 확인하려면 다음 방법 중 하나를 사용하세요.- HTTP 상태 코드 429 모니터링
- 디버그 어설션 사용
- XBOX services Trace Analyzer 도구 사용