Call Cloud Functions

This page describes how to call Cloud Functions registered in TCB (Tencent Cloud Base).

This document explains how to call ProcessGatewayRequestAsync() after initializing the TCB module and how to handle the returned result as a discriminated union.

Run a Cloud Function

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

To run a Cloud Function registered in TCB, call ProcessGatewayRequestAsync() provided by the Hive Axyl SDK. It passes the specified region, namespace, function name, and JSON string parameter to TCB and returns the execution result.

Before calling, complete login, session setup, and TCB module installation and initialization, and get the TCB service with HiveCore.Resolve<ITcbService>().
You must specify Region, Namespace, FunctionName, and FunctionParam to match the Cloud Function to run.
FunctionParam is the JSON string to pass to the Cloud Function. Serialize a JSON object to a string before you pass it.
To process the request, an API credential that the requesting project can use must be registered.

Call parameters

Field name	Type	Required	Description
`request`	ScfExecuteRequest	Required	The request object that holds the location of the Cloud Function to run and the parameters to pass.
`context`	ApiCallContext?	Optional	The API call context. If omitted, the default values are used.

ScfExecuteRequest

Field name	Type	Required	Description
`Region` (`region`)	string	Required	The TCB region code where the Cloud Function is deployed.
`Namespace` (`namespace`)	string	Required	The name of the TCB namespace (Environment ID) that the Cloud Function belongs to.
`FunctionName` (`function_name`)	string	Required	The name of the Cloud Function to run.
`FunctionParam` (`function_param`)	string	Required	The parameter to pass to the Cloud Function. Pass it as a JSON string.

Call example

The return object of ProcessGatewayRequestAsync(), TcbProcessGatewayRequestResult, is divided into success, feature-specific results, unknown results, and failure states. The method call does not throw exceptions (Exception), and all processing results are delivered through the return object. Therefore, instead of using a separate try/catch statement, branch on the response status with a switch statement.

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;
        // Handle the Cloud Function execution result.
        break;

    case TcbProcessGatewayRequestResult.ScfInvocationFailed:
        // Check the SCF invocation failure status.
        break;

    case TcbProcessGatewayRequestResult.FunctionExecutionFailed:
        // Check the Cloud Function execution logs.
        break;

    case TcbProcessGatewayRequestResult.InvalidParameter:
        // Check the request parameters.
        break;

    case TcbProcessGatewayRequestResult.CredentialNotFound:
        // Check the API credential registration status of the project.
        break;

    case TcbProcessGatewayRequestResult.InvalidFunctionParam:
        // Check the JSON parameter passed to the Cloud Function.
        break;

    case TcbProcessGatewayRequestResult.FunctionNotFound:
        // Check the region, namespace, and function name.
        break;

    case TcbProcessGatewayRequestResult.ScfInvalidParameter:
        // Check the SCF request parameters and TCB settings.
        break;

    case TcbProcessGatewayRequestResult.UnknownOutcome unknown:
        // A new result that this SDK does not recognize. Treat it as a failure.
        Debug.LogWarning($"Unhandled result code: {unknown.Code}");
        break;

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

    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Response data

When the request succeeds, the Cloud Function execution result is returned in the Data field of the TcbProcessGatewayRequestResult.Success object.

Field name	Type	Required	Description
`Data.RequestId` (`requestId`)	string?	Optional	The request identifier.
`Data.ResultMsg` (`resultMsg`)	string?	Optional	The Cloud Function execution result message.
`Data.Meta` (`meta`)	string?	Optional	The raw JSON string of the metadata of the Cloud Function execution result.

Response example