서버 점검

서버 점검 조회 메서드로 현재 시각에 활성화된 점검 항목을 확인합니다.

1. Hive 콘솔에서 서버 점검 설정

서버 점검을 사용하려면 먼저 콘솔에 점검 항목을 등록하세요. Hive 콘솔 > 서비스 접근 제어 > 서비스 접근 제어에서 프로젝트를 선택하고 검색을 누른 뒤 새 서비스 접근 제어에서 유형을 서버 점검으로 고릅니다. 등록 화면의 입력 항목은 서비스 접근 제어 항목을 참조하세요. 점검 대상으로 고를 서버는 콘솔에 미리 등록해야 합니다. 등록 방법은 앱 서버를 참조하세요.

2. 호출 파라미터값 준비

호출 전에 조회 범위를 결정할 ServerCode와 ClientVersion, 허용 목록 적용 여부를 확인할 PlayerId를 준비합니다.

ServerCode

ServerCode는 Hive 콘솔 > 앱 정보 > 앱 서버에 등록한 서버 ID입니다. 앱 서버를 등록하는 방법은 앱 서버를 참조하세요. 특정 서버에 적용되는 점검만 조회할 때 지정합니다. 이 값을 전달하면 해당 서버를 대상으로 등록한 점검 항목과 함께, 대상 서버를 지정하지 않은 점검 항목도 조회합니다. 생략하거나 빈 문자열을 지정하면 대상 서버와 관계없이 활성화된 점검 항목을 모두 조회합니다.

ClientVersion

ClientVersion은 현재 실행 중인 앱 클라이언트 버전입니다. 이 값을 전달하면 대상 버전을 지정하지 않은 점검 항목과 함께, 앱의 App ID와 이 버전을 대상으로 등록한 점검 항목도 조회합니다. 생략하거나 빈 문자열을 지정하면 대상 버전을 지정한 점검 항목은 결과에서 빠지고, 버전을 지정하지 않은 점검 항목만 조회합니다.

서버는 버전 범위나 표기 차이를 해석하지 않고 문자열이 정확히 같은지만 비교합니다. 예를 들어 1.2와 1.2.0은 서로 다른 버전으로 봅니다. 콘솔에 등록한 버전 표기 그대로 전달하세요.

PlayerId

PlayerId는 사용자가 허용 목록에 등록된 대상인지 확인할 때 사용하는 Player ID입니다. 서버가 요청을 처리할 때 허용 목록을 자동으로 적용하므로 앱에서 허용 목록을 따로 조회할 필요는 없습니다. 접속 IP나 PlayerId가 허용 목록에 있으면 점검 중이어도 Data.Items는 빈 목록입니다. 서버 점검에서는 허용 목록 항목에 앱 버전을 지정했다면 요청의 ClientVersion이 그 버전과 같을 때만 해당 항목이 적용됩니다. ClientVersion을 생략하면 앱 버전을 지정하지 않은 허용 목록 항목만 적용됩니다. 허용 목록에 일치하는 항목이 없으면 PlayerId는 결과에 영향을 주지 않습니다.

로그인 전에는 Player ID가 없으므로 생략하고, 로그인한 뒤 다시 확인할 때 지정합니다. 로그인한 사용자의 Player ID는 ISessionManager의 PlayerId로 확인합니다.

3. 서버 점검 조회 메서드 호출

GetActiveMaintenancesAsync

GetActiveMaintenancesAsync()를 호출해 현재 시각에 적용 중인 서버 점검 항목을 조회합니다. 앱은 반환된 점검 목록에 따라 접속 제한이나 점검 안내 화면 노출 여부를 직접 결정합니다. 로그인 전에도 호출할 수 있으며 보통 앱 시작 시점에 실행합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	GetActiveMaintenancesRequest	Required	서버 점검 조회 요청
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

App ID와 안내 문구 언어는 모듈 설치 및 초기화에서 설정한 값을 SDK가 자동으로 전달하므로 요청에 따로 담지 않습니다.

GetActiveMaintenancesRequest

필드명	타입	필수 여부	설명
`ServerCode`	string	Optional	Hive 콘솔 > 앱 정보 > 앱 서버에 등록한 서버 ID입니다. 지정하면 이 서버를 대상으로 등록한 점검과 대상 서버를 지정하지 않은 점검을 조회하며, 생략하거나 빈 문자열이면 전체 서버 대상으로 조회합니다.
`ClientVersion`	string	Optional	현재 앱 클라이언트 버전. 문자열이 정확히 같은 대상 버전만 일치하며, 생략하거나 빈 문자열이면 대상 버전을 지정한 점검 항목은 조회되지 않습니다.
`PlayerId`	long?	Optional	허용 목록 적용 여부를 확인할 Player ID. 로그인 전에는 생략합니다.

호출 예시

GetActiveMaintenancesAsync() 호출 예제에서는 Success, Failure, UnknownOutcome를 구분해 처리합니다. 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

Unity

using Hive.Axyl.ServiceAccess;
using Hive.Axyl.Core;

IServiceAccessService service = HiveCore.Resolve<IServiceAccessService>();

var request = new GetActiveMaintenancesRequest {
    // ServerCode    = "{serverCode}",       // 특정 앱 서버만 조회할 때 지정
    // ClientVersion = Application.version,  // 현재 버전 대상 점검까지 조회하고 버전을 지정한 허용 목록도 적용할 때 지정
    // PlayerId      = HiveCore.Resolve<ISessionManager>().PlayerId,  // 로그인한 뒤 확인할 때 지정
};

ServiceAccessGetActiveMaintenancesResult result = await service.GetActiveMaintenancesAsync(request);

switch (result)
{
    case ServiceAccessGetActiveMaintenancesResult.Success success:
        if (success.Data.Items.Count > 0)
        {
            // 활성 점검 있음 -> 점검 안내 화면 노출 (실제 접속 제한은 앱이 구현)
            foreach (Maintenance m in success.Data.Items)
                Debug.Log($"점검 중: {m.Title} ({m.Content})");
        }
        else
        {
            // 활성 점검 없음 -> 정상 진행
        }
        break;

    // 공통 실패 처리 (네트워크·서버 오류, 요청 값 오류)
    case ServiceAccessGetActiveMaintenancesResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}/{err.ExternalCode}] {err.Message} (trace: {err.TraceId})");
        break;

    // 이 SDK 버전에서 정의하지 않은 결과와 서버 내부 오류(UnknownOutcome)는 실패로 처리합니다.
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공하면 ServiceAccessGetActiveMaintenancesResult.Success의 Data(GetActiveMaintenancesResponseData)에 결과가 담깁니다. Data.Items는 가장 최근에 등록한 점검 항목부터 정렬되며, 활성 점검이 없으면 빈 목록입니다.

필드명	타입	필수 여부	설명
`Data.Items`	`IReadOnlyList<Maintenance>`	Required	활성화된 서버 점검 목록. 활성 점검이 없으면 빈 목록입니다.

Maintenance

필드명	타입	필수 여부	설명
`Id`	long	Required	점검 식별자
`Title`	string	Required	점검 안내 제목
`Content`	string	Required	점검 안내 본문
`RedirectUrl`	string	Required	점검 안내 URL. 콘솔에 설정하지 않았으면 빈 문자열
`Servers`	`IReadOnlyList<string>`	Required	점검 대상 서버 ID 목록. 대상 서버를 지정하지 않아 서버와 관계없이 적용되는 점검이면 빈 목록
`Versions`	`IReadOnlyList<MaintenanceVersion>`	Required	요청한 App ID에 지정한 점검 대상 버전 목록. 대상 버전을 지정하지 않은 점검이면 빈 목록. 항목 구조는 아래 `MaintenanceVersion` 참고
`AlwaysOn`	bool	Required	상시 점검 여부
`StartAt`·`EndAt`	DateTimeOffset?	Optional	점검 시작·종료 시각. `StartAt`은 시작 시각 없이 등록한 상시 점검에서만 `null`이고, `EndAt`은 종료 시점이 없는 상시 점검이면 `null`
`Timezone`	`TimeZoneInfo`	Required	`StartAt`·`EndAt`을 해석하는 기준 시간대. 항목 구조는 아래 `TimeZoneInfo` 참고

MaintenanceVersion

필드명	타입	필수 여부	설명
`AppId`	string	Required	점검 대상 App ID
`ClientVersion`	string	Required	점검 대상 클라이언트 버전

TimeZoneInfo

Timezone은 StartAt과 EndAt을 해석하는 시간대 정보이며 점검 항목마다 항상 담깁니다. 서버는 접속 IP로 판별한 국가를 기준으로 시간대를 정하므로 앱에서 시간대 정보를 따로 전달할 필요는 없습니다. 국가를 판별할 수 없으면 UTC를 사용합니다.

StartAt과 EndAt의 시차는 각 시각에 이 시간대에서 적용되는 값입니다. 따라서 두 시각 사이에 서머타임 전환이 있으면 두 시각의 시차가 서로 다릅니다. UtcOffset, OffsetSeconds, Dst는 StartAt을 기준으로 계산하며, StartAt이 null이면 EndAt을, 둘 다 null이면 현재 시각을 기준으로 계산합니다.

Note

이 타입의 정식 이름은 Hive.Axyl.ServiceAccess.TimeZoneInfo입니다. 같은 파일에서 using System;을 함께 사용하면 System.TimeZoneInfo와 이름이 겹쳐 컴파일 오류가 나므로, 이때는 정식 이름을 모두 적거나 using 별칭을 지정하세요.

필드명	타입	필수 여부	설명
`Id`	string	Required	IANA 시간대 식별자. 예: `Asia/Seoul`
`UtcOffset`	string	Required	`±HH:MM` 형식의 UTC 기준 시차. 서머타임을 반영하며, 시차가 0이면 `+00:00`
`OffsetSeconds`	int	Required	초 단위의 UTC 기준 시차
`Dst`	bool	Required	서머타임 적용 여부
`IsInEuropeanUnion`	bool	Required	시간대를 정한 국가의 유럽 연합 소속 여부. UTC를 사용하면 `false`
`Name`	string	Optional	요청 언어로 표기한 국가 이름. 요청 언어 태그의 이름이 없으면 언어 부분만 남긴 태그, 영어, 제공되는 다른 언어 순으로 찾은 이름. 예를 들어 요청 언어가 `pt-BR`이면 `pt-BR`, `pt`, `en` 순. 국가 이름이 없거나 UTC를 사용하면 `null`
`Names`	`IReadOnlyDictionary<string, string>`	Required	언어 태그별 국가 이름. UTC를 사용하면 비어 있음

Warning

반환된 점검 목록은 안내 정보만 제공합니다. 실제 접속 차단, 점검 화면 노출, 리다이렉트 처리 방식은 앱 클라이언트가 직접 구현해야 합니다.

응답 헤더

성공하면 ServiceAccessGetActiveMaintenancesResult.Success의 Headers(GetActiveMaintenancesResponseHeaders)에 응답 헤더 값이 담깁니다.

필드명	타입	필수 여부	설명
`Headers.XTraceId`	string	Optional	서버가 응답마다 발급하는 요청 추적 식별자. 문제를 문의하거나 로그를 조회할 때 사용합니다.

응답 예시