ITcbService

A service that runs Cloud Functions registered in Tencent CloudBase (TCB). When the app sends the function's location and parameters, the Hive Axyl server calls TCB and returns the function's execution result.

Item	Value
Interface	`ITcbService`
Namespace	`Hive.Axyl.Tcb`
Package	`com.com2usplatform.hiveaxyl.tcb`

Registration and retrieval

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>();

Method summary

For the meaning of the 'Authentication' column, see Authentication requirement notation.

Method	Authentication	Description
ProcessGatewayRequestAsync	Session required	Runs a Cloud Function registered in TCB.

Common parameters

The last parameter of every method is ApiCallContext? context = null. If you omit it, the default values apply. For details, see Call context.

Every method takes the request body as the request parameter, and request is Required. The method descriptions below show only the request type and omit the parameter table. Check the fields of each request type in Data types.

Exceptions

Exception	When thrown
`ArgumentNullException`	When `request` is `null`

Failure branches

Unlike other modules, this module does not declare common Failure codes. Situations that branch to Failure in other modules, such as request parameter errors, branch to result cases in this module.

Transport failures, call cancellations, and responses the SDK could not interpret branch to Failure. Internal server errors are also returned without an error code, so they branch to Failure. If the server responds with a code that is not in the result case table, the result branches to UnknownOutcome, and the code is held in UnknownOutcome.Code. Handle both cases as failures. For the result branches and how to branch, see Core result model.

Methods

ProcessGatewayRequestAsync

Runs the Cloud Function registered in the region and namespace specified in the request and returns the result. The function is called synchronously, so the result is returned after the function finishes running. The execution result message is held in Data.ResultMsg.

The Hive Axyl server uses the TCB credentials registered in the Hive Console, so you do not put them in the request. If no credentials are registered, the result branches to CredentialNotFound.

Unity

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

Item	Value
Request	ScfExecuteRequest
Response	AxylResponseScfExecuteResponseDataResponseData
Authentication	Session required

Result cases — TcbProcessGatewayRequestResult

Result case	Wire code	Description
`Success`	—	The function ran. The execution result is held in `Data`.
`InvalidParameter`	`invalid_parameter`	The request parameters did not pass validation.
`InvalidFunctionParam`	`invalid_function_param`	`FunctionParam` is not a JSON object string.
`CredentialNotFound`	`credential_not_found`	There are no TCB credentials available for the requested project.
`FunctionNotFound`	`function_not_found`	The requested function, namespace, or version does not exist in TCB.
`ScfInvalidParameter`	`scf_invalid_parameter`	TCB rejected the request parameters.
`ScfInvocationFailed`	`scf_invocation_failed`	The TCB call itself failed. The cause is a TCB authentication error, quota exhaustion, or a network error.
`FunctionExecutionFailed`	`function_execution_failed`	The function was called, but it ended with an error while running.
`UnknownOutcome`	`UNKNOWN`	A new result this SDK version does not recognize.
`Failure`	`FAILURE`	The call could not be completed. Check the cause with the HiveError in `Problem`.

For InvalidParameter, FunctionNotFound, ScfInvalidParameter, and FunctionExecutionFailed, the server also sends error details. Check the details in the response body held in the result object's RawResponse.

Call example

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;   // Result message returned by the function
        break;

    case TcbProcessGatewayRequestResult.FunctionExecutionFailed:
        // The function ended with an error while running. Check the details in RawResponse.
        break;

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

    default:
        // Other result cases and UnknownOutcome
        break;
}

Data types

AxylResponseScfExecuteResponseDataResponseData

The Cloud Function execution result.

Field	Type	Required	Description
`RequestId`	`string?`	Optional	The identifier of the Cloud Function request that ran.
`ResultMsg`	`string?`	Optional	The result message returned by the Cloud Function.
`Meta`	`string?`	Optional	Additional information that the server sends along. It is held as the raw, unprocessed JSON string.

ScfExecuteRequest

A Cloud Function execution request. It holds the location of the function to run and the parameters to pass to the function.

Field	Type	Required	Description
`Region`	`string`	Required	The TCB region code where the Cloud Function is deployed.
`Namespace`	`string`	Required	The name of the TCB namespace that the Cloud Function belongs to. Enter the TCB environment ID.
`FunctionName`	`string`	Required	The name of the Cloud Function to run.
`FunctionParam`	`string`	Required	The parameters to pass to the Cloud Function. Enter them as a string that represents a JSON object; if it is not a JSON object, the result branches to `InvalidFunctionParam`.