Core 호출 컨텍스트

Hive Axyl 서버를 호출하는 메서드 하나에만 적용할 값을 담는 타입입니다. 멱등 키, 추가 헤더, 제한 시간과 재시도 정책, 인증 정보, 취소 토큰을 지정합니다.

ApiCallContext는 항상 마지막 파라미터이며 생략할 수 있습니다. 생략하면 기본값이 적용되므로 대부분의 호출에서는 지정할 필요가 없습니다. 네이티브 기능을 감싸는 Add-on 메서드는 호출 컨텍스트 대신 CancellationToken을 마지막 파라미터로 받습니다.

인스턴스는 호출마다 새로 만들고 스레드 간에 공유하지 마세요.

ApiCallContext

class — 네임스페이스 Hive.Axyl.Core

Hive Axyl 서버를 호출하는 메서드에 전달합니다.

프로퍼티

프로퍼티	타입	설명
`IdempotencyKey`	`string?`	멱등 처리에 사용하는 키입니다. 생성 시 UUIDv4가 기본으로 채워지며, 전송 계층이 재시도해도 같은 값을 유지합니다. 멱등이 아닌 요청이라면 `null`로 지정하세요.
`Metadata`	`Dictionary<string, string>`	요청에 추가로 실어 보낼 사용자 정의 헤더입니다. `null`을 지정하면 `ArgumentNullException`이 발생합니다.
`Policy`	RequestOptions?	이 호출에만 적용할 정책입니다. `null`이면 `CoreConfig`의 전역 기본값을 사용합니다.
`Credential`	CallCredential	이 호출이 사용할 인증 정보입니다. 기본값은 현재 세션을 사용하는 `Ambient`입니다.
`Token`	`CancellationToken`	호출을 취소할 때 사용하는 토큰입니다.

멱등 키는 서버가 요구하는 메서드에서만 Idempotency-Key 헤더로 전송됩니다. 논리적 호출 하나당 한 번 정해지며, 전송 계층이 재시도해도 값이 바뀌지 않습니다.

Metadata에 담을 수 없는 헤더

아래에 해당하는 항목은 전송되지 않고 경고가 기록됩니다.

Authorization, X-App-Id, traceparent처럼 SDK가 직접 채우는 헤더 이름
RFC 7230 토큰 형식이 아닌 헤더 이름
값이 비어 있거나, 제어 문자 또는 비 ASCII 문자를 포함하는 경우

이름이 겹치는 경우에는 항상 SDK가 채우는 값이 우선합니다.

WithAccessToken

현재 세션 대신 지정한 액세스 토큰으로 호출을 인증하는 컨텍스트를 만듭니다. Credential에 CallCredential.Bearer()를 지정한 것과 같습니다.

저장해 둔 토큰이 아직 유효한지 확인한 뒤 세션으로 확정하는 자동 로그인 흐름에서 사용합니다.

Unity

static ApiCallContext WithAccessToken(string accessToken)

파라미터	타입	필수 여부	설명
`accessToken`	`string`	Required	이 호출에 사용할 액세스 토큰입니다.

반환: ApiCallContext

토큰이 null이거나 비어 있어도 예외가 발생하지 않습니다. 네트워크에 도달하기 전에 InvalidArgument로 실패하므로, 저장소에서 읽은 값을 검사 없이 그대로 전달해도 됩니다.

호출 예시

Unity

using Hive.Axyl.Core;

var result = await auth.LoginWithAccessTokenAsync(
    request,
    ApiCallContext.WithAccessToken(storedAccessToken));

사용 시점은 자동 로그인을 참조하세요.

RequestOptions

class — 네임스페이스 Hive.Axyl.Core

ApiCallContext.Policy에 지정해 이 호출에만 다른 정책을 적용합니다. null인 프로퍼티는 CoreConfig의 전역 기본값을 사용합니다.

값의 범위는 검사하지 않습니다. 음수 같은 잘못된 값을 넣지 않도록 호출하는 쪽에서 주의하세요.

프로퍼티	타입	설명
`TimeoutMillis`	`int?`	이 요청의 제한 시간(밀리초)입니다.
`MaxRetries`	`int?`	이 요청의 최대 재시도 횟수입니다.
`IsIdempotent`	`bool`	`true`이면 HTTP 메서드와 무관하게 멱등 요청으로 처리해 일시적 실패에 재시도합니다.
`SkipLogging`	`bool`	`true`이면 요청과 응답 로깅을 생략합니다.

인증 정보는 정책이 아닙니다. 어떤 자격으로 호출할지는 ApiCallContext.Credential에 지정하세요.

CallCredential

struct — 네임스페이스 Hive.Axyl.Core

호출 하나가 사용할 인증 정보입니다. 종류와 토큰이 한 값에 묶여 있어 "어떤 자격으로" 와 "어떤 토큰으로" 가 어긋날 수 없습니다.

인증 정보 종류

인증 정보는 아래 세 종류입니다.

Ambient: 현재 세션으로 인증하는 기본값
Anonymous: 아무 인증 정보도 보내지 않는 값
Bearer(): 지정한 액세스 토큰으로 인증하는 값

현재 값이 어느 종류인지는 IsAmbient, IsAnonymous, IsBearer로 확인합니다. ToString()은 토큰을 출력하지 않고 Bearer(***) 형태로만 표기합니다.

Ambient

SDK의 현재 세션으로 인증합니다. 세션의 Authorization 헤더가 실리고, 401 응답을 받으면 토큰 자동 갱신이 동작하며, 갱신이 진행 중이면 그 뒤에서 대기합니다.

Credential을 지정하지 않은 것과 같습니다. 인증이 필요 없다고 선언된 메서드에 Ambient를 명시해도 인증 호출로 바뀌지는 않습니다.

Unity

static CallCredential Ambient { get; }

Anonymous

아무 인증 정보도 보내지 않습니다. Authorization 헤더가 실리지 않고, 401 응답이 자동 갱신을 일으키지도 않으며, 진행 중인 갱신 때문에 대기하거나 실패하지도 않습니다.

인증이 필요 없다고 선언된 메서드에 SDK가 자동으로 적용하는 값입니다.

Unity

static CallCredential Anonymous { get; }

Bearer

현재 세션 대신 지정한 액세스 토큰으로 인증합니다. 저장해 둔 토큰이 유효한지 확인한 뒤 세션으로 확정할 때 사용합니다.

자동 갱신에 참여하지 않습니다. 401 응답은 세션이 아니라 전달한 토큰에 대한 판정입니다.

Unity

static CallCredential Bearer(string accessToken)

파라미터	타입	필수 여부	설명
`accessToken`	`string`	Required	이 호출에 사용할 액세스 토큰입니다.

반환: CallCredential

토큰이 null이거나 비어 있거나 공백이면 유효하지 않은 인증 정보가 되며, 네트워크에 도달하기 전에 InvalidArgument로 실패합니다. 여기서 예외를 던지지 않으므로 저장소에서 읽은 값을 검사 없이 그대로 전달해도 되고, 실패는 모든 플랫폼에서 같은 결과 채널로 전달됩니다.