ITcbService

Tencent CloudBase(TCB)에 등록한 Cloud Function을 실행하는 서비스입니다. 앱이 함수의 위치와 파라미터를 보내면 Hive Axyl 서버가 TCB를 호출하고, 함수의 실행 결과를 반환합니다.

항목	값
인터페이스	`ITcbService`
네임스페이스	`Hive.Axyl.Tcb`
패키지	`com.com2usplatform.hiveaxyl.tcb`

등록과 획득

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Tcb;

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddTcb();
});

ITcbService tcb = HiveCore.Resolve<ITcbService>();

메서드 요약

'인증' 열의 의미는 인증 요구 표기를 참조하세요.

메서드	인증	설명
ProcessGatewayRequestAsync	세션 필요	TCB에 등록한 Cloud Function을 실행합니다.

공통 파라미터

모든 메서드의 마지막 파라미터는 ApiCallContext? context = null입니다. 생략하면 기본값이 적용됩니다. 자세한 내용은 호출 컨텍스트를 참조하세요.

모든 메서드는 요청 본문을 request 파라미터로 받으며, request는 Required입니다. 아래 메서드 설명에서는 요청 타입만 표기하고 파라미터 표는 생략합니다. 각 요청 타입의 필드는 데이터 타입에서 확인하세요.

발생 예외

예외	발생 조건
`ArgumentNullException`	`request`가 `null`인 경우

실패 분기

이 모듈은 다른 모듈과 달리 공통 Failure 코드를 선언하지 않습니다. 요청 파라미터 오류처럼 다른 모듈에서 Failure로 분기하는 상황도 이 모듈에서는 결과 케이스로 분기합니다.

전송 실패, 호출 취소, SDK가 해석하지 못한 응답은 Failure로 분기합니다. 서버 내부 오류도 오류 코드 없이 응답하므로 Failure로 분기합니다. 결과 케이스 표에 없는 코드로 서버가 응답하면 UnknownOutcome으로 분기하며, 코드는 UnknownOutcome.Code에 담깁니다. 두 케이스 모두 실패로 처리하세요. 결과 갈래와 분기 방법은 Core 결과 모델을 참조하세요.

메서드

ProcessGatewayRequestAsync

요청에 지정한 리전과 네임스페이스에 등록된 Cloud Function을 실행하고 결과를 반환합니다. 함수는 동기식으로 호출하므로, 함수 실행이 끝난 뒤 결과가 반환됩니다. 실행 결과 메시지는 Data.ResultMsg에 담깁니다.

TCB 인증 정보는 Hive 콘솔에 등록한 값을 Hive Axyl 서버가 사용하므로 요청에 넣지 않습니다. 등록된 인증 정보가 없으면 CredentialNotFound로 분기합니다.

Unity

Task<TcbProcessGatewayRequestResult> ProcessGatewayRequestAsync(ScfExecuteRequest request, ApiCallContext? context = null);

항목	값
요청	ScfExecuteRequest
응답	AxylResponseScfExecuteResponseDataResponseData
인증	세션 필요

결과 케이스 — TcbProcessGatewayRequestResult

결과 케이스	와이어 코드	설명
`Success`	—	함수를 실행했습니다. 실행 결과는 `Data`에 담깁니다.
`InvalidParameter`	`invalid_parameter`	요청 파라미터가 검증을 통과하지 못했습니다.
`InvalidFunctionParam`	`invalid_function_param`	`FunctionParam`이 JSON 객체 문자열이 아닙니다.
`CredentialNotFound`	`credential_not_found`	요청한 프로젝트에 사용할 수 있는 TCB 인증 정보가 없습니다.
`FunctionNotFound`	`function_not_found`	요청한 함수나 네임스페이스, 버전이 TCB에 없습니다.
`ScfInvalidParameter`	`scf_invalid_parameter`	TCB가 요청 파라미터를 거부했습니다.
`ScfInvocationFailed`	`scf_invocation_failed`	TCB 호출 자체가 실패했습니다. TCB 인증 오류, 할당량 소진, 네트워크 오류가 원인입니다.
`FunctionExecutionFailed`	`function_execution_failed`	함수를 호출했지만 함수가 실행 중 오류로 종료됐습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

InvalidParameter, FunctionNotFound, ScfInvalidParameter, FunctionExecutionFailed에는 서버가 오류 상세 정보를 함께 보냅니다. 상세 정보는 결과 객체의 RawResponse에 담긴 응답 본문에서 확인하세요.

호출 예시

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Tcb;

var result = await tcb.ProcessGatewayRequestAsync(new ScfExecuteRequest
{
    Region        = "{region}",
    Namespace     = "{environmentId}",
    FunctionName  = "grantReward",
    FunctionParam = "{\"playerId\":12345,\"rewardId\":\"daily\"}",
});

switch (result)
{
    case TcbProcessGatewayRequestResult.Success success:
        string? resultMsg = success.Data.ResultMsg;   // 함수가 반환한 결과 메시지
        break;

    case TcbProcessGatewayRequestResult.FunctionExecutionFailed:
        // 함수가 실행 중 오류로 끝났습니다. 상세 내용은 RawResponse에서 확인합니다.
        break;

    case TcbProcessGatewayRequestResult.Failure failure:
        HiveError error = failure.Problem;
        break;

    default:
        // 그 밖의 결과 케이스와 UnknownOutcome
        break;
}

데이터 타입

AxylResponseScfExecuteResponseDataResponseData

Cloud Function 실행 결과입니다.

필드	타입	필수 여부	설명
`RequestId`	`string?`	Optional	실행한 Cloud Function 요청의 식별자입니다.
`ResultMsg`	`string?`	Optional	Cloud Function이 반환한 결과 메시지입니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다. 가공되지 않은 원본 JSON 문자열로 담깁니다.

ScfExecuteRequest

Cloud Function 실행 요청입니다. 실행할 함수의 위치와 함수에 전달할 파라미터를 담습니다.

필드	타입	필수 여부	설명
`Region`	`string`	Required	Cloud Function을 배포한 TCB 리전 코드입니다.
`Namespace`	`string`	Required	Cloud Function이 속한 TCB 네임스페이스 이름입니다. TCB 환경 ID를 넣습니다.
`FunctionName`	`string`	Required	실행할 Cloud Function의 이름입니다.
`FunctionParam`	`string`	Required	Cloud Function에 전달할 파라미터입니다. JSON 객체를 나타내는 문자열로 넣으며, JSON 객체가 아니면 `InvalidFunctionParam`으로 분기합니다.