Xbox 서비스 호출 모범 사례

아티클
05/09/2023

Xbox 서비스는 두 가지 방식으로, 즉 Xbox 서비스 API(XSAPI)를 사용하거나 REST 엔드포인트를 직접 호출하여 호출할 수 있습니다. 코드에서 Xbox 서비스를 호출하는 방법에 관계없이 적절한 호출 패턴과 다시 시도 논리를 갖는 것이 중요합니다.

적절한 재시도 로직을 작성하는 방법을 이해하려면 두 가지 유형의 REST 끝점, 즉 멱등(idempotent) 및 비멱등(non-idempotent) 끝점에 대해 반드시 알아야 합니다. 이들은 아래에 설명되어 있습니다.

비멱등 끝점

반복 호출 시 부작용이 있는 HTTP 메서드는 비멱등으로 간주합니다. 즉, 클라이언트가 끝점을 호출하려 했거나 네트워크 시간 제한이 발생하는 경우에는 메서드를 재시도하는 것이 안전하지 않습니다. 왜냐하면 리소스가 업데이트 되었을 수 있지만, 네트워크가 발신자에게 호출이 성공했음을 알릴 수 없었기 때문입니다.

오류 시, 클라이언트는 재시도를 하는 대신에 먼저 호출의 성공 여부를 확인하기 위해 쿼리를 수행해야 합니다. 호출이 성공하지 않은 경우에만 재시도를 해야 합니다.

Xbox 서비스 API에서 일부 API는 비멱등 끝점을 호출하는 것으로 내부적으로 표시됩니다. 따라서 이러한 끝점을 호출할 때 오류가 발생하면, API는 끝점을 자동으로 재시도하지 않습니다.

비멱등 API의 전체 목록은 다음과 같습니다.

멱등 메서드

반면 멱등 HTTP 메서드는 부작용을 남기지 않습니다. 따라서 안전하게 재시도가 가능합니다. Xbox 서비스 API에서 모든 멱등 메서드는 특정한 조건에서 자동으로 재시도됩니다.

위에서 비멱등으로 나열되지 않은 모든 API는 멱등 API에 속합니다.

재시도 로직 모범 사례

멱등 호출에서는 이러한 조건이 자동으로 재시도됩니다.

모든 네트워크 오류
401: Unauthorized
408: RequestTimeout
429: Too Many Requests
500: InternalError
502: BadGateway
503: ServiceUnavailable
504: GatewayTimeout

UWP에서 401: Unauthorized는 특별 처리됩니다. 이 값은 Xbox 서비스 인증 토큰이 만료되었음을 나타내므로 Xbox 서비스 API는 OS를 호출하여 토큰을 새로 고친 다음 단일 다시 시도로 수행합니다.

재시도가 수행되면 "Retry-After" 헤더 시간에 도달할 때까지 서비스를 호출하지 않는 것이 가장 좋습니다. 이제 XSAPI는 이러한 모범 사례를 실행합니다. 어떤 API에서든 오류 HTTP 상태 코드 및 "Retry-After" 헤더가 반환된 경우, Retry-After 시간이 되기 전에 같은 API를 추가로 호출하면 서비스에 타격을 입히지 않고 원래 오류가 즉시 반환됩니다.

호출을 재시도할 때 가장 좋은 방법은 임의 지터를 통해 지수 백오프를 수행하여 서비스에 로드를 분산시키는 것입니다. XSAPI는 XblContextSettingsSetHttpRetryDelay를 사용하여 제어되는 2초의 기본 지연으로 시작합니다. 즉, 기본적으로 각 다시 시도는 2, 4 또는 8초 이상의 지수 백오프를 수행합니다. 다시 시도를 시도하는 장치 세트 전체에 로드를 더 분산시키기 위해 응답 시간을 기준으로 현재 백오프 값과 다음 백오프 값 사이의 지연을 지터합니다.

타이틀은 호출 재시도에 소요되는 시간을 제어할 수 있어야 합니다. 개발자는 XSAPI를 통해 XblContextSettingsSetHttpTimeoutWindow 함수를 사용 하여 이를 직접 제어할 수 있습니다. 기본적으로 이 값은 20초로 설정되어 있습니다. 이를 1초로 설정하면 재시도 로직이 효과적으로 비활성화 됩니다.

내부 HTTP 시간 제한을 동적으로 조정

XSAPI에서 XblContextSettingsGetHttpTimeoutWindow에 남아 있는 시간을 기준으로 내부 HTTP 시간 제한을 동적으로 조정합니다.

내부 HTTP 시간 제한은 OS가 중단하기 전까지 HTTP 네트워크 작업을 수행하는 데 소요하는 시간을 제어합니다.

XblContextSettingsGetHttpTimeoutWindow에 5초 이상 남아 있는 경우에만 호출을 다시 시도하지 않습니다. 이 경우에는 호출이 완료될 때까지 충분한 시간을 줄 수 있습니다. 이 규칙은 첫 번째 호출에는 적용되지 않으므로 XblContextSettingsSetHttpTimeoutWindow를 0으로 설정하는 것이 좋습니다. 이 경우 한 번만 호출하면 됩니다.

이 논리는 API 호출이 반환되는 시기에 대해 XblContextSettingsGetHttpTimeoutWindow가 더 명확해지는 효과가 있습니다.

"Retry-After" 헤더가 반환된 경우에는 "Retry-After" 시간에 도달한 이후에 재시도가 수행되지 않습니다. "Retry-After" 시간이 XblContextSettingsGetHttpTimeoutWindow 이후인 경우 호출이 XblContextSettingsGetHttpTimeoutWindow의 끝에 반환됩니다.

오류 처리

타이틀 개발자는 모든 서비스 호출에 대해 항상 적절한 오류 처리를 사용해야 하고, 실패한 응답을 적절하게 처리하도록 보장해야 합니다.

다음과 같은 실패 코드를 반환하도록 Xbox 서비스에 요청할 수 있는 많은 실제 조건이 있습니다.

네트워크를 사용할 수 없는 경우입니다. 예를 들어, 디바이스에서 4G 또는 Wi-Fi 연결이 끊어졌거나 네트워크 운영이 중단된 경우입니다.
서비스에 대한 로드가 너무 많은 경우입니다(503).
해당 서비스에서 오류가 발생한 경우입니다(500).
서비스에 전송된 요청의 수가 너무 많은 경우입니다(429).
쓰기 작업 시 충돌이 발생한 경우입니다(412). 예를 들어, 멀티 플레이어 세션의 다른 플레이어가 먼저 변경 사항을 제출한 경우입니다.
사용자가 차단되었거나 권한을 가지고 있지 않습니다.
사용자가 로그아웃했습니다.

적절한 오류 처리기는 이러한 상황에서 게임이 올바르게 작동하도록 보장하는 데 중요한 역할을 합니다.

오류 처리를 위한 모범 사례에 대한 자세한 내용은 오류 처리를 참조하세요.

이 같은 내용의 비디오는 XSAPI: C++, 예외 없음!이라는 Xfest 2015 비디오의 대화를 참조하십시오

최상의 호출 패턴

요청 일괄 처리 사용

일부 끝점은 일련의 요청을 단일 호출로 일괄 처리 또는 집계할 수 있도록 지원합니다. 예를 들어 Xbox 서비스의 프로필 서비스를 사용하여 단일 사용자 프로필 또는 사용자 프로필 집합을 요청할 수 있습니다.

따라서 사용자 집합에 대한 사용자 프로필이 필요한 경우에는 각 사용자 프로필에서 끝점 또는 API를 한번에 하나씩 호출하는 것으로는 역부족입니다.

호출을 할 때마다 수많은 인증 오버헤드가 추가됩니다. 따라서 이런 방법 대신에 끝점이 모든 사용자 프로필을 동시에 처리하고 단일 응답을 반환할 수 있도록 정보를 얻고 싶은 모든 사용자를 한번에 API에 전달합니다.

폴링 대신 실시간 활동(RTA) 서비스 사용

주기적 폴링 대신에 실시간 활동(RTA) 서비스를 사용하는 것이 가장 좋은 방법입니다. 실시간 활동 서비스는 대상 리소스가 서비스에서 변경될 때 클라이언트에 알림을 보내는 웹 소켓을 노출합니다.

RTA 서비스는 프레즌스 변경, 통계 변경, 멀티 플레이어 세션 문서 변경 및 소셜 관계 변경에 대한 알림을 제공합니다.

클라이언트가 관심 있는 정보가 무엇인지 알기 위해 클라이언트는 먼저 웹 소켓을 통해 항목을 구독해야 합니다. 이렇게 하면 해당 항목이 변경되는 정확한 시점을 알 수 있기 때문에 변경 감지를 위해 서비스를 폴링할 필요가 없습니다.

XSAPI는 클라이언트가 사용할 수 있는 구독 API 세트로 RTA 서비스를 표시합니다. 이러한 API 각각에는 항목 변경 시 호출되는 콜백 기능을 받아들이는 대응하는 *ChangedHandler API가 있습니다.

XblPresenceSubscribeToDevicePresenceChange
XblPresenceSubscribeToTitlePresenceChange
XblUserStatisticsSubscribeToStatisticChange
XblSocialSubscribeToSocialRelationshipChange

XSAPI 클라이언트 측 관리자 사용

XSAPI에는 특정 시나리오에서 캐시 및 상태 컴퓨터 역할을 하면서 어려운 작업을 모두 수행하는 관리자가 있습니다.

소셜 관리자는 친구 목록 및 프로필과 관련된 모든 어려운 작업을 수행합니다. 소셜 관리자는 RTA 서비스를 사용하여 친구 목록, 프로필 및 프레즌스 데이터를 업데이트 상태로 유지합니다.

또한 게임 엔진에 친숙한 비동기 API를 표시합니다. 소셜 관리자는 서비스에서 얻은 최신 정보를 메모리 내 캐시에 보관하기 때문에, 게임은 소셜 관리자 API를 자주 호출할 수 있습니다.

자세한 내용은 소셜 관리자를 참조하세요.

멀티 플레이어 관리자

멀티 플레이어 세션 관리를 위해, 멀티 플레이어 관리자는 기존의 멀티 플레이어 게임을 위한 새로운 적응 솔루션을 제공합니다. 멀티 플레이어 관리자 API에는 플레이어 명단 및 세션 관리, 게임 초대 처리, 진행 중 합류, 매치 메이킹, 기존 네트워킹 솔루션 연결 등이 포함되어 있습니다. 이들은 기존의 멀티 플레이어 게임 흐름 구현과 관련해 모든 어려운 과제를 수행합니다.

멀티 플레이어 관리자를 참조하세요.

FGRL(Fine Grained Rate Limiting) 등의 제한

Xbox 서비스는 단일 서비스가 서비스에 과도한 부담이 되지 않도록 막기 위해 제한을 두고 있습니다. 타이틀이 제한된 경우를 아는 것이 중요합니다.

타이틀 제한 여부를 알려면 다음과 같은 접근 방식을 사용합니다.

HTTP 상태 코드 429 모니터링
디버그 어설션 사용
Xbox 서비스 추적 분석기 도구 사용

이러한 접근 방식은 아래에 설명되어 있습니다.

HTTP 상태 코드 429 모니터링

Fiddler를 사용하여 HTTP 상태 코드 429가 반환되는지 여부를 감시할 수 있습니다. JSON 응답에는 끝점 제한 방법에 대한 세부 정보가 포함됩니다.

예:

{
  "version":1,
  "currentRequests":13,
  "maxRequests":10,
  "periodInSeconds":120,
  "limitType":"Rate"
}

XSAPI를 사용 하는 경우 API는 HTTP_E_STATUS_429_TOO_MANY_REQUESTS 오류를 반환하고, API를 제한하는 방법에 대한 세부 정보를 표시하는 오류 메시지를 설정합니다.

디버그 어설션 사용

XSAPI 사용 시 타이틀의 디버그 빌드를 사용하는 동안 개발자 샌드박스에 있을 때 호출이 제한된 경우에는 제한이 발생했다는 것을 개발자에게 즉시 알리도록 어설션을 수행합니다. 이렇게 하면 잘못 작성된 코드로 인해 429 제한 오류가 실수로 누락되는 일을 방지할 수 있습니다. 이러한 어설션을 비활성화하여 위반 코드를 수정하지 않고 계속 작업을 수행하고 싶은 경우에는 XblDisableAssertsForXboxLiveThrottlingInDevSandboxes API를 사용할 수 있습니다.

XblDisableAssertsForXboxLiveThrottlingInDevSandboxes(
    XblConfigSetting::ThisCodeNeedsToBeChanged
);

이 API는 타이틀이 제한되는 것을 막지 않습니다. 타이틀은 여전히 제한이 됩니다. 이렇게 하면 디버그 빌드를 사용하는 동안 개발자 샌드박스에 있을 때 어설션을 간단하게 비활성화할 수 있습니다.

Xbox 서비스 추적 분석기 도구 사용

타이틀이 제한되었는지 여부를 확인하는 또 다른 옵션은 Xbox 서비스 호출의 추적을 기록한 다음 Xbox 서비스 추적 분석기 도구를 사용하여 해당 추적을 분석하는 것입니다.

추적 내용을 기록하기 위해 Fiddler를 사용해 .SAZ 파일을 기록하거나, XSAPI에서 기본 제공되는 추적 로깅을 사용할 수 있습니다. XSAPI에서 추적을 켜는 방법에 대한 자세한 내용은 Xbox 문서 Xbox 서비스 추적 분석기(XblTraceAnalyzer.exe)를 참조하세요. 추적이 있으면 Xbox 서비스 추적 분석기 도구가 제한된 호출을 감지하면 경고를 표시합니다.

Xbox 서비스가 작동 중인가요?

Xbox 서비스는 프로필, 친구 및 프레즌스, 통계, 순위표, 도전 과제, 멀티 플레이어, 매치 메이킹 같은 Xbox 기능을 표시하는 마이크로 서비스 컬렉션입니다. Xbox 서비스의 가동 여부를 정의하는 단일 서버 또는 엔드포인트는 없습니다. 단일 서버가 다운되더라도 나머지 Xbox 서비스의 마이크로 서비스들이 완전히 독립적으로 작동해야 합니다.

단일 서비스에서 임시 중단이 발생하면 일단 이 서비스 호출이 게임에 미션 크리티컬한 것인지 알아야 합니다. 일시적인 네트워크 또는 서비스 문제가 있더라도 적절한 환경을 제공하려고 노력합니다. 예를 들어, 프레즌스 서비스가 오류를 반환하면 해당 호출은 게임에서 미션 크리티컬하지 않을 가능성이 있습니다. 따라서 Xbox 네트워크(Xbox Live라고도 함)가 다운되었다고 보고하는 대신 마지막으로 알려진 현재 상태를 사용자에게 보고하기만 하면 됩니다.

Xbox 서비스는 "궁극적 일관성"이라는 일관성 모델을 따릅니다. 즉, 새로운 업데이트가 수행되지 않은 경우에는 궁극적으로 해당 리소스에 대한 모든 요청이 마지막 업데이트된 값을 보고합니다. 이는 데이터가 전파되는 동안 정보가 업데이트 되지 않은 상태로 있는 기간이 짧다는 의미입니다.

다음을 통해 공유