You can use Flow Definition Languages (FDLs) to integrate CloudFlow with other Alibaba Cloud services and invoke other Alibaba Cloud services in CloudFlow. This topic describes how CloudFlow is integrated with Function Compute and invokes functions.
Background information
CloudFlow describes a business flow based on states of flows and models of state machines, and uses API call parameters that you specify to complete each step of the flow.
If you want to add functions to CloudFlow and invoke functions of CloudFlow, you must follow orchestration specifications. The following sections provide a sample procedure on how to add a function to CloudFlow and then invoke the function.
Step 1: Select a state type
Add a Task state to the flow, and then orchestrate Function Compute based on the definition of Tasks.
Type: StateMachine
Name: MyWorkflow
SpecVersion: v1
StartAt: an example of function invocation
States:
- Name: an example of function invocation
Type: Task
TaskMode: RequestComplete
Action: FC:InvokeFunction
Parameters:
resourceArn: xxx
invocationType: xxx
body: xxx
End: true
Step 2: Configure invocation parameters
Invocations of functions of Function Compute involve the following major parameters: the Alibaba Cloud Resource Name (ARN) that identifies the function, the function invocation mode, and the event parameter. The following table describes the parameters.
According to the Spec specification, the parameters follow the camel case naming conventions and start with a lowercase letter.
Parameter | Required | Parameter data type | Description |
resourceArn | Yes | String. | The ARN of the function, which is used to identify the function. |
invocationType | Yes | Sync or Async. | The function invocation mode. |
body | No | JSON object or string, which is serialized into a byte array before being passed to the invoked function. | The event parameter, which is the input parameter of the function execution process. |
Sample code:
Type: StateMachine
Name: MyWorkflow
SpecVersion: v1
StartAt: an example of synchronous function invocation
States:
- Name: an example of synchronous function invocation
Type: Task
Action: FC:InvokeFunction
TaskMode: RequestComplete
Parameters:
resourceArn: acs:fc:::services/myService1.LATEST/functions/myFunction1
invocationType: Sync
body:
testKey: the content of the testKey parameter in the event of the function
Next: an example of asynchronous function invocation
- Name: an example of asynchronous function invocation
Type: Task
Action: FC:InvokeFunction
TaskMode: RequestComplete
Parameters:
resourceArn: acs:fc:::services/myService2.LATEST/functions/myFunction2
invocationType: Async
body:
key1: value1
key2: value2
End: true
Step 3: Set an integration mode
Task states support the TaskMode attribute, which defines how the current state handles the API call. The integration of CloudFlow and Function Compute supports the following integration modes:
In this mode, after the system responds to the request and returns the result, the flow advances to the next state. This mode is effective for synchronous function invocations, asynchronous function invocations, and asynchronous task invocations.
In this mode, after the system sends a request for function invocations, the function system sends a system callback notification. After the workflow receives the system callback notification, the workflow executes the next step. This mode is effective only for asynchronous function invocations and asynchronous task invocations.
After a function invocation request is completed, the workflow continues to wait. The workflow does not advance until the user program notifies the API to send a notification by using the callback that is provided by CloudFlow and CloudFlow receives the callback notification. This mode is effective only for asynchronous function invocations and asynchronous task invocations.
For more information about function invocations, see Synchronous invocations, Asynchronous invocations, and Asynchronous task management.
Type: StateMachine
Name: MyWorkflow
SpecVersion: v1
StartAt: an example of synchronous function invocation
States:
- Name: an example of synchronous function invocation
Type: Task
Action: FC:InvokeFunction
TaskMode: RequestComplete
Parameters:
resourceArn: acs:fc:::services/myService1.LATEST/functions/myFunction1
invocationType: Sync
body:
testKey: the content of the testKey parameter in the event of the function
Next: an example of asynchronous function invocation
- Name: an example of asynchronous function invocation
Type: Task
Action: FC:InvokeFunction
TaskMode: RequestComplete
Parameters:
resourceArn: acs:fc:::services/myService2.LATEST/functions/myFunction2
invocationType: Async
body:
key1: value1
key2: value2
End: true
You must add the callbackToken custom field to the body
parameter and reference the $Context.Current.TaskToken
expression in the callbackToken custom field. The expression specifies the token attribute that must be used when the workflow calls back the task execution result.
Step 4: Construct invocation parameters
In actual flow orchestration, you must construct the parameters that are required by the current function invocation based on the context of the workflow and the result of the previous state. The following code provides an example on how to construct invocation parameters.
You can use the
$Context
and$Input
constants reserved by the Spec specification to access data in the flow.
Type: StateMachine
Name: MyWorkflow
SpecVersion: v1
StartAt: an example of function invocation
States:
- Name: an example of function invocation
Type: Task
TaskMode: RequestComplete
Action: FC:InvokeFunction
Parameters:
resourceArn: acs:fc:::services/myService1.LATEST/functions/myFunction1
invocationType: Sync
body:
argument1.$: $Input.input.BucketName
argument2.$: $Input.input.TaskId
End: true
Step 5: Handle the invocation result
You invoke states to complete the entire flow. In a function invocation scenario, the workflow returns the execution result after the workflow completes the invocation. You can use the returned result as a conditional statement of the flow or as an input of the next state. According to the InvokeFunction API definition of Function Compute, if the value of the Type response parameter of the function is Byte, the actual data type is Byte. The return value of the function can be a string, JSON object, JSON array, or of a basic data type.
In RequestComplete integration mode, after the workflow receives the returned result, the workflow encapsulates the result into a JSON object. The following code shows the result encapsulation structure in the workflow.
{ "Body": "function invocation result" }
You can use the JSONPath of
$Output.Body
in the description of the workflow to access the returned result of the function. If the return value is a JSON object, you can invoke the built-in function in the workflow to deserialize the return value. Then, you can access the members in the return value based on the operation of JSON objects.Type: StateMachine Name: MyWorkflow SpecVersion: v1 Description: ' ' StartAt: Example 1 of function invocation States: - Name: Example 1 of function invocation Type: Task TaskMode: RequestComplete Action: FC:InvokeFunction Parameters: resourceArn: acs:fc:::services/myService1.LATEST/functions/myFunction1 invocationType: Sync body: argument1.$: $Input.Records argument2.$: $Input.BucketName Next: conditional statement - Type: Choice Name: conditional statement Branches: - Condition: $Input.ObjectSize >= $Input.Threshold Next: Example 2 of function invocation Default: No action is performed. - Type: Pass Name: No action is performed. End: true - Name: Example 2 of function invocation Type: Task TaskMode: RequestComplete Action: FC:InvokeFunction Parameters: resourceArn: acs:fc:::services/myService2.LATEST/functions/myFunction2 invocationType: Sync body: argument1.$: $Input.BucketName argument2.$: $Input.TaskId End: true
In WaitForSystemCallback and WaitForCustomCallback integration modes, the external system calls the ReportTaskSucceeded or ReportTaskFailed API operation to query the function invocation result and passes the result to the flow. The workflow does not encapsulate the returned result. For example, if the return value of the function is {"message": "hello"}, the structure of the return value in the workflow is shown as the following code.
{ "message": "hello" }
You can use the $Output expression in the description of your workflow to access the returned result of the function.
Common error definitions
FC.ResourceThrottled
: Your functions are throttled due to high concurrency. The total number of your function invocations cannot be greater than a specific concurrency value. CloudFlow synchronously invokes Function Compute when CloudFlow executes Task states. The concurrency value covers the function invocations in CloudFlow and the function invocations in other modes. You can request to modify the concurrency value if the concurrency value cannot meet your requirements.FC.ResourceExhausted
: Your functions are throttled due to insufficient resources. Contact us when this error occurs.FC.InternalServerError
: A system error occurs in Function Compute. Re-execute the flow.FC.AccessDenied
: Your access request is denied because your Alibaba Cloud account does not have the required permissions.FC.InvalidArgument
: The parameter is invalid.FC.EntityTooLarge
: The specified input parameter value exceeds the valid value range.
For information about other errors in Function Compute, see Error codes.