> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XBOX services 호출 모범 사례

> XSAPI 또는 REST로 XBOX Live 서비스를 호출하는 방법에 대한 지침. 멱등성 엔드포인트와 비멱등성 엔드포인트, 네트워크 실패에 대한 적절한 재시도 로직을 다룹니다.

XBOX services는 두 가지 주요 방법으로 호출할 수 있습니다: XBOX Services API(XSAPI)를 사용하거나 REST 엔드포인트를 직접 호출합니다.
코드가 XBOX services를 호출하는 방식과 관계없이 적절한 호출 패턴과 재시도 로직을 갖추는 것이 중요합니다.

적절한 재시도 로직을 작성하는 방법을 이해하려면 두 가지 유형의 REST 엔드포인트인 **멱등성**과 **비멱등성**에 대해 알아야 합니다.
아래에서 이에 대해 설명합니다.

## 비멱등성 엔드포인트

반복 호출 시 부작용이 있는 HTTP 메서드는 **비멱등성**으로 간주됩니다.
즉, 클라이언트가 엔드포인트를 호출하고 네트워크 타임아웃이 발생하면, 리소스가 업데이트되었을 수 있지만 네트워크가 호출자에게 성공했음을 알릴 수 없기 때문에 메서드를 다시 시도하는 것이 안전하지 않습니다.

오류 발생 시 재시도 대신 클라이언트는 먼저 호출이 성공했는지 확인하는 쿼리를 수행해야 합니다.
호출이 성공하지 못한 경우에만 재시도해야 합니다.

XBOX Services API에서 일부 API는 내부적으로 비멱등성 엔드포인트를 호출하는 것으로 표시되어 있습니다.
즉, 이러한 엔드포인트를 호출할 때 실패가 발생하면 API가 자동으로 엔드포인트를 다시 시도하지 않습니다.

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

* [XblMatchmakingCreateMatchTicketAsync](/reference/live/xsapi-c/matchmaking_c/functions/xblmatchmakingcreatematchticketasync)

* [XblMultiplayerWriteSessionAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionasync)

* [XblMultiplayerWriteSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync)

* [XblMultiplayerSendInvitesAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersendinvitesasync)

* [XblSocialSubmitReputationFeedbackAsync](/reference/live/xsapi-c/social_c/functions/xblsocialsubmitreputationfeedbackasync)

* [XblSocialSubmitBatchReputationFeedbackAsync](/reference/live/xsapi-c/social_c/functions/xblsocialsubmitbatchreputationfeedbackasync)

## 멱등성 메서드

반면에 **멱등성** HTTP 메서드는 부작용을 남기지 않습니다.
따라서 다시 시도하는 것이 안전합니다.
XBOX Services API에서 모든 멱등성 메서드는 특정 조건에서 자동으로 재시도됩니다.

멱등성 API의 전체 목록은 위에서 비멱등성으로 나열되지 않은 모든 API입니다.

## 재시도 로직 모범 사례

멱등성 호출의 경우, 이러한 조건은 자동으로 재시도되어야 합니다.

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

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

재시도를 수행할 때는 "Retry-After" 헤더 시간에 도달할 때까지 서비스를 호출하지 않는 것이 모범 사례입니다.
XSAPI는 이제 이 모범 사례를 구현합니다.
API에 대해 실패 HTTP 상태 코드와 "Retry-After" 헤더가 반환된 경우, Retry-After 시간 이전에 동일한 API에 대한 추가 호출은 서비스에 접근하지 않고 원래 오류로 즉시 반환됩니다.

호출을 재시도할 때 서비스에 대한 부하를 분산하기 위해 임의 지터가 있는 지수 백오프를 수행하는 것이 모범 사례입니다.
XSAPI는 기본 지연을 2초로 시작하며, 이는 [XblContextSettingsSetHttpRetryDelay](/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingssethttpretrydelay)로 제어됩니다.
즉, 기본적으로 각 재시도는 2, 4, 8초 이상의 지수 백오프를 수행합니다. 응답 시간에 따라 현재 및 다음 백오프 값 사이의 지연에 지터를 적용하여 재시도를 시도하는 장치 세트 전체에 부하를 더 분산시킵니다.

타이틀은 호출 재시도에 얼마나 시간을 소비할지 제어해야 합니다.
XSAPI를 사용하면 개발자는 [XblContextSettingsSetHttpTimeoutWindow](/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingssethttptimeoutwindow) 함수를 사용하여 이를 직접 제어할 수 있습니다.
기본적으로 이 값은 20초로 설정되어 있습니다.
이를 0초로 설정하면 재시도 로직이 사실상 꺼집니다.

### 내부 HTTP 타임아웃의 동적 조정

XSAPI는 [XblContextSettingsGetHttpTimeoutWindow](/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow)에 남은 시간에 따라 내부 HTTP 타임아웃을 동적으로 조정합니다.

내부 HTTP 타임아웃은 OS가 HTTP 네트워크 작업을 중단하기 전에 이를 얼마나 오래 수행하는지 제어합니다.

호출이 완료될 만한 충분한 합리적인 시간을 제공하기 위해, [XblContextSettingsGetHttpTimeoutWindow](/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow)에 최소 5초가 남아 있지 않으면 호출은 재시도되지 않습니다.
이 규칙은 첫 번째 호출에는 적용되지 않으므로 [XblContextSettingsSetHttpTimeoutWindow](/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingssethttptimeoutwindow)를 0으로 설정하는 것은 허용되며, 단일 호출이 발생합니다.

이 로직은 [XblContextSettingsGetHttpTimeoutWindow](/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow)가 API 호출이 반환될 시점에 대해 더 결정론적이 되는 효과가 있습니다.

"Retry-After" 헤더가 반환된 경우, "Retry-After" 시간에 도달할 때까지 재시도가 이루어지지 않습니다.
"Retry-After" 시간이 [XblContextSettingsGetHttpTimeoutWindow](/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow) 이후인 경우, 호출은 [XblContextSettingsGetHttpTimeoutWindow](/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow)의 끝에서 반환됩니다.

## 오류 처리

타이틀 개발자는 **모든** 서비스 호출에 대해 **항상** 적절한 오류 처리를 사용해야 하며, 실패한 응답을 올바르게 처리하는지 확인해야 합니다.

XBOX services에 대한 요청이 실패 코드를 반환하는 다양한 실제 조건이 있습니다. 예를 들면 다음과 같습니다.

* 네트워크를 사용할 수 없습니다. 예를 들어, 장치가 4G를 잃거나 Wi-Fi를 잃거나 네트워크가 다운되었습니다.
* 서비스에 과부하가 걸렸습니다(503).
* 서비스에서 실패가 발생했습니다(500).
* 너무 많은 요청이 서비스로 전송되었습니다(429).
* 쓰기 작업 충돌(412). 예를 들어, 멀티플레이어 세션의 다른 플레이어가 먼저 변경 사항을 제출했습니다.
* 사용자가 차단되었거나 권한이 없습니다.
* 사용자가 로그아웃했습니다.

이러한 조건에서 게임이 올바르게 작동하도록 하려면 적절한 오류 처리기가 필수적입니다.

오류 처리의 모범 사례에 대한 자세한 내용은 [오류 처리](https://learn.microsoft.com/gaming/gdk/docs/services/archive/services-archive/live-error-handling-nav)를 참조하세요.

이를 다루는 비디오는 [Xfest 2015 Videos](https://aka.ms/xgddl)의 *XSAPI: C++, No Exceptions!* 강연을 참조하세요.

## 최적의 호출 패턴

### 일괄 처리 요청 사용

일부 엔드포인트는 요청 집합을 단일 호출로 일괄 처리하거나 집계하는 것을 지원합니다.
예를 들어, 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](/services/xbox-services/community/social-manager/live-social-manager-nav)를 참조하세요.

### Multiplayer Manager

멀티플레이어 세션 관리의 경우, Multiplayer Manager는 전통적인 멀티플레이어 게임을 위한 드롭인 솔루션입니다.
Multiplayer Manager API에는 플레이어 명부 및 세션 관리가 포함되어 있으며, 게임 초대, 진행 중 참여, 매치메이킹을 처리하고 기존 네트워킹 솔루션에 연결됩니다.
전통적인 멀티플레이어 흐름을 구현하는 것과 관련된 모든 힘든 작업을 수행합니다.

[Multiplayer Manager](/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-nav)를 참조하세요.

## Throttling(세분화된 속도 제한)

XBOX services는 단일 장치가 서비스에 극심한 부하를 주는 것을 방지하기 위해 throttling이 설정되어 있습니다.
타이틀이 언제 throttling되었는지 아는 것이 중요합니다.

타이틀이 throttling되었는지 확인하려면 다음 방법 중 하나를 사용하세요.

* HTTP 상태 코드 429 모니터링
* 디버그 어설션 사용
* XBOX services Trace Analyzer 도구 사용

이러한 접근 방식은 아래에서 설명합니다.

### HTTP 상태 코드 429 모니터링

Fiddler를 사용하여 HTTP 상태 코드 429가 반환되는지 확인할 수 있습니다.
JSON 응답에는 엔드포인트가 어떻게 throttling되었는지에 대한 세부 정보가 포함됩니다.

예를 들어:

```json theme={null}
{
  "version":1,
  "currentRequests":13,
  "maxRequests":10,
  "periodInSeconds":120,
  "limitType":"Rate"
}
```

XSAPI를 사용하는 경우, API는 **HTTP\_E\_STATUS\_429\_TOO\_MANY\_REQUESTS** 오류를 반환하고 API가 어떻게 throttling되었는지에 대한 세부 정보를 표시하도록 오류 메시지를 설정합니다.

### 디버그 어설션 사용

XSAPI를 사용할 때 개발자 샌드박스에 있고 타이틀의 디버그 빌드를 사용하는 동안 호출이 throttling되면, throttling이 발생했음을 개발자에게 즉시 알리기 위해 어설션이 발생합니다.
이는 잘못 작성된 코드로 인해 의도치 않게 429 throttling 오류를 놓치는 것을 방지하기 위한 것입니다.
문제가 있는 코드를 수정하지 않고 계속 작업하기 위해 이러한 어설션을 비활성화하려면 [XblDisableAssertsForXboxLiveThrottlingInDevSandboxes](/reference/live/xsapi-c/xbox_live_global_c/functions/xbldisableassertsforxboxlivethrottlingindevsandboxes) API를 사용할 수 있습니다:

```cpp theme={null}
XblDisableAssertsForXboxLiveThrottlingInDevSandboxes(
    XblConfigSetting::ThisCodeNeedsToBeChanged
);
```

이 API는 타이틀이 throttling되는 것을 막지 않는다는 점에 유의하세요. 타이틀은 여전히 throttling됩니다. 이는 단순히 개발 샌드박스에서 디버그 빌드를 사용하는 동안 어설션을 비활성화할 뿐입니다.

### XBOX services Trace Analyzer 도구 사용

타이틀이 throttling되었는지 확인하는 또 다른 옵션은 XBOX 서비스 호출의 추적을 기록한 다음 [XBOX services Trace Analyzer 도구](/tools/tools-services/live-trace-analyzer)를 사용하여 해당 추적을 분석하는 것입니다.

추적을 기록하려면 Fiddler를 사용하여 .SAZ 파일을 기록하거나 XSAPI의 내장 추적 로깅을 사용할 수 있습니다.
XSAPI에서 추적을 켜는 방법에 대한 자세한 내용은 XBOX 문서 [XBOX services Trace Analyzer (XblTraceAnalyzer.exe)](/tools/tools-services/live-trace-analyzer)를 참조하세요.
추적이 있으면 XBOX services Trace Analyzer 도구가 throttling된 호출을 감지할 때 경고합니다.

## XBOX services가 작동 중입니까?

XBOX 서비스는 프로필, 친구 및 상태, 통계, 리더보드, 성취, 멀티플레이어, 매치메이킹과 같은 XBOX 기능을 노출하는 마이크로서비스의 컬렉션입니다.
XBOX services가 작동 중인지 여부를 정의하는 단일 서버나 엔드포인트는 없습니다.
단일 서버가 다운되더라도 나머지 XBOX 서비스의 마이크로서비스는 대체로 독립적이며 정상 작동해야 합니다.

단일 서비스에 일시적인 중단이 발생한 경우, 해당 서비스 호출이 게임에 임무 필수적인지 아는 것이 중요합니다.
간헐적인 네트워크 또는 서비스 문제가 있는 동안 합리적인 경험을 제공하도록 노력하세요.
예를 들어, 상태 서비스가 실패를 반환하는 경우 해당 호출은 게임에 임무 필수적이지 않을 수 있습니다.
따라서 XBOX 네트워크(XBOX Live라고도 함)가 다운되었다고 보고하는 대신, 마지막으로 알려진 상태를 사용자에게 보고하기만 하면 됩니다.

XBOX services는 "결과적 일관성"의 일관성 모델을 따릅니다.
즉, 새로운 업데이트가 없으면 결국 해당 리소스에 대한 모든 요청이 마지막으로 업데이트된 값을 보고합니다.
즉, 데이터가 전파되는 동안 정보가 오래된 짧은 기간이 있습니다.


## Related topics

- [멀티플레이어 테스트를 위한 XBOX Manager 모범 사례](/ko/tools/tools-console/xbom/manager-tool-multiplayer.md)
- [모범 사례](/ko/services/xbox-services/develop/best-practices/index.md)
- [Insights 모범 사례](/ko/services/playfab/data-analytics/legacy/insights/best-practices.md)
- [RTA 서비스 모범 사례](/ko/services/xbox-services/fundamentals/rta/concepts/live-rta-best-practices.md)
- [SDK 오류 처리 모범 사례](/ko/services/playfab/live-service-management/service-gateway/automation/cloudscript/sdk-error-handling-best-practices.md)