Cloud Function 호출

Tencent CloudBase 콘솔에 등록한 Cloud Function을 호출하는 방법을 안내합니다.

본 문서에서는 TCB 모듈을 초기화한 뒤 ProcessGatewayRequestAsync()를 호출하고, 반환된 결과를 판별 유니온으로 처리하는 과정을 설명합니다.

Cloud Function 실행

public Task ProcessGatewayRequestAsync(ScfExecuteRequest request, ApiCallContext? context = null);

Tencent CloudBase에 등록한 Cloud Function을 실행하려면 Hive Axyl SDK가 제공하는 ProcessGatewayRequestAsync()를 호출하세요. 지정한 리전, 네임스페이스, 함수 이름과 JSON 문자열 파라미터를 Tencent CloudBase에 전달하고 실행 결과를 반환합니다.

호출 전에 로그인과 세션 설정, 그리고 TCB 모듈 설치 및 초기화를 완료하고 HiveCore.Resolve<ITcbService>()로 Tencent CloudBase 기능을 호출합니다.
Region, Namespace, FunctionName, FunctionParam은 실행할 Cloud Function에 맞게 지정해야 합니다.
FunctionParam은 Cloud Function에 전달할 JSON 문자열입니다. JSON 객체를 문자열로 직렬화한 뒤 전달하세요.
요청을 처리하려면 요청 프로젝트에 사용할 수 있는 API 자격 증명이 등록되어 있어야 합니다.

호출 파라미터

필드명	타입	필수 여부	설명
`request`	ScfExecuteRequest	Required	실행할 Cloud Function의 위치 정보와 전달할 파라미터를 담는 요청 객체입니다.
`context`	ApiCallContext?	Optional	API 호출 컨텍스트입니다. 생략하면 기본값이 사용됩니다.

ScfExecuteRequest

필드명	타입	필수 여부	설명
`Region` (`region`)	string	Required	Cloud Function이 배포된 Tencent CloudBase 리전 코드입니다.
`Namespace` (`namespace`)	string	Required	Cloud Function이 속한 Tencent CloudBase 네임스페이스(Environment ID) 이름입니다.
`FunctionName` (`function_name`)	string	Required	실행할 Cloud Function 이름입니다.
`FunctionParam` (`function_param`)	string	Required	Cloud Function에 전달할 파라미터입니다. JSON 문자열 형식으로 전달합니다.

호출 예시

ProcessGatewayRequestAsync()의 반환 객체 TcbProcessGatewayRequestResult는 성공, 기능별 결과, 알 수 없는 결과 및 실패 상태로 나뉩니다. 메서드 호출 시 예외(Exception)를 발생시키지 않으며, 모든 처리 결과가 반환 객체로 전달됩니다. 따라서 별도의 try/catch 구문을 사용하지 않고 switch 구문으로 응답 상태를 분기해 처리합니다.

Unity

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

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

var request = new ScfExecuteRequest
{
    Region = "ap-shanghai",
    Namespace = "your-environment-id",
    FunctionName = "your-function-name",
    FunctionParam = "{\"key\":\"value\"}",
};

TcbProcessGatewayRequestResult result =
    await tcb.ProcessGatewayRequestAsync(request);

switch (result)
{
    case TcbProcessGatewayRequestResult.Success success:
        var requestId = success.Data.RequestId;
        var resultMessage = success.Data.ResultMsg;
        var meta = success.Data.Meta;
        // Cloud Function 실행 결과를 처리합니다.
        break;

    case TcbProcessGatewayRequestResult.ScfInvocationFailed:
        // SCF 호출 실패 상태를 확인합니다.
        break;

    case TcbProcessGatewayRequestResult.FunctionExecutionFailed:
        // Cloud Function 실행 로그를 확인합니다.
        break;

    case TcbProcessGatewayRequestResult.InvalidParameter:
        // 요청 파라미터를 확인합니다.
        break;

    case TcbProcessGatewayRequestResult.CredentialNotFound:
        // 프로젝트의 API 자격 증명 등록 상태를 확인합니다.
        break;

    case TcbProcessGatewayRequestResult.InvalidFunctionParam:
        // Cloud Function에 전달한 JSON 파라미터를 확인합니다.
        break;

    case TcbProcessGatewayRequestResult.FunctionNotFound:
        // 리전, 네임스페이스, 함수 이름을 확인합니다.
        break;

    case TcbProcessGatewayRequestResult.ScfInvalidParameter:
        // SCF 요청 파라미터와 Tencent CloudBase 설정을 확인합니다.
        break;

    case TcbProcessGatewayRequestResult.UnknownOutcome unknown:
        // 이 SDK에서 알 수 없는 신규 결과입니다. 실패로 처리합니다.
        Debug.LogWarning($"처리되지 않은 결과 코드: {unknown.Code}");
        break;

    case TcbProcessGatewayRequestResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

요청 성공 시 TcbProcessGatewayRequestResult.Success 객체의 Data 필드에 Cloud Function 실행 결과가 반환됩니다.

필드명	타입	필수 여부	설명
`Data.RequestId` (`requestId`)	string?	Optional	요청 식별자입니다.
`Data.ResultMsg` (`resultMsg`)	string?	Optional	Cloud Function 실행 결과 메시지입니다.
`Data.Meta` (`meta`)	string?	Optional	Cloud Function 실행 결과의 메타데이터 JSON 원문 문자열입니다.

응답 예시

Unity

case TcbProcessGatewayRequestResult.Success success:
    Debug.Log($"requestId: {success.Data.RequestId}");
    Debug.Log($"resultMsg: {success.Data.ResultMsg}");
    Debug.Log($"meta: {success.Data.Meta}");
    break;

응답 상태

반환 객체 TcbProcessGatewayRequestResult는 아래 케이스 중 하나로 분기됩니다. switch 구문으로 처리하세요.

응답 케이스	설명	앱 클라이언트 대응
`Success`	Cloud Function 실행에 성공했습니다. `Data`에 요청 식별자, 결과 메시지, 메타데이터가 담깁니다.	`Data`를 앱의 결과 처리에 사용
`InvalidParameter`	요청 파라미터 검증에 실패했습니다. 와이어 코드(code)는 `invalid_parameter`입니다.	리전, 네임스페이스, 함수 이름, 함수 파라미터 확인
`CredentialNotFound`	요청 프로젝트에 사용할 수 있는 API 자격 증명이 등록되어 있지 않습니다. 와이어 코드(code)는 `credential_not_found`입니다.	프로젝트의 API 자격 증명 등록 상태 확인
`ScfInvocationFailed`	SCF 호출에 실패했습니다. 와이어 코드(code)는 `scf_invocation_failed`입니다.	Tencent CloudBase/SCF 서비스 상태와 호출 권한 확인
`FunctionExecutionFailed`	Cloud Function 실행 중 오류가 발생했습니다. 와이어 코드(code)는 `function_execution_failed`입니다.	Cloud Function 로그와 실행 오류 확인
`InvalidFunctionParam`	Cloud Function에 전달한 파라미터가 올바르지 않습니다. 와이어 코드(code)는 `invalid_function_param`입니다.	`FunctionParam` JSON 형식과 함수 입력 스키마 확인
`FunctionNotFound`	요청한 Cloud Function을 찾을 수 없습니다. 와이어 코드(code)는 `function_not_found`입니다.	리전, 네임스페이스, 함수 이름 확인
`ScfInvalidParameter`	SCF 호출 파라미터가 올바르지 않습니다. 와이어 코드(code)는 `scf_invalid_parameter`입니다.	SCF 요청 파라미터와 Tencent CloudBase 설정 확인
`UnknownOutcome`	현재 SDK가 해석하지 못하는 새로운 결과 코드입니다.	`Code`를 기록하고 실패로 처리
`Failure`	전송 또는 프레임워크 오류입니다. `Problem`(`HiveError`)에 상세가 담깁니다.	오류 기록 또는 재시도 안내

연관 문서

TCB 모듈 설치 및 초기화