You can use asynchronous invocation configuration to send the results of successful or failed function executions to specified services. You can also set the number of retries for failed functions and the validity period of requests. This topic describes asynchronous invocation and how to configure and monitor it.

What is asynchronous invocation?

Functions can be invoked asynchronously or synchronously. When you use the InvokeFunction API operation to invoke a function, you can specify whether to use asynchronous or synchronous invocation. In addition, the following triggers always use asynchronous invocation:

When an event triggers a function with an asynchronous invocation, Function Compute places the event in the internal queue and returns the request ID. The status of the invocation and that of the function execution are not returned. To obtain the results of an asynchronous invocation, you can configure destinations for asynchronous invocation.

The following figure shows the asynchronous invocation process.invoke_process

Configuration items

Asynchronous invocation configuration includes the following two parts:

  • Destination for asynchronous invocation: the cloud service to which the result of the asynchronous invocation is sent. In the data structure, this is the value of the destinationConfig parameter.
  • Asynchronous invocation policy: the validity period of requests and the number of retries for failed functions. In the data structure, these are the maxAsyncEventAgeInSeconds and maxAsyncRetryAttempts parameters, respectively.

Destinations for asynchronous invocation

If a destination for asynchronous invocation is configured and the results of the invocation meet the conditions you set, Function Compute can send the context and data of the invocation to the specified destination service. This process enables cloud services to interact with each other. You can configure different destinations for different functions, aliases, and versions. The following destination services for asynchronous invocation are supported:
  • Message Service (MNS) queue
  • MNS topic
  • Function Compute

You must note the following points when you configure destinations for asynchronous invocation:

  • Event content:
    {
        "timestamp": "2020-08-20T12:00:00.000Z",
        "requestContext": {
            "requestId": "xxx",
            "functionArn": "acs:fc:::services/{serviceName}/functions/{functionName}",
            "condition": "FunctionResourceExhausted", 
            "approximateInvokeCount": 3
        },
        "requestPayload": "",
        "responseContext": {
            "statusCode": 200,
            "functionError": ""
        },
        "responsePayload": ""
    }
    Parameter Description
    timestamp The timestamp of the invocation.
    requestContext The request context.
    requestContext.requestId The request ID.
    requestContext.functionArn The Alibaba Cloud Resource Name (ARN) of the function.
    requestContext.condition The error code of the invocation.
    requestContext.approximateInvokeCount The number of invocations. A value greater than 1 indicates that Function Compute has retried the function.
    requestPayload The original payload of the request.
    responseContext The response context.
    responseContext.statusCode The status code returned for the invoked function. A status code other than 200 indicates that a system error occurred.
    responseContext.functionError The error message of the invocation.
    responsePayload The original payload of the response.
  • Payload limits

    The payload of a destination cloud service for asynchronous invocation cannot exceed the following limits:

    • MNS queue or topic: 64 KB
    • Function Compute: 128 KB
    Note The default data of an asynchronous invocation, excluding requestPayload and responsePayload, must be less than 1 KB in size. Ensure that the total size of your invocation, including input parameters, function response, and default data, does not exceed the limit for the destination service.
  • Loop avoidance

    When you configure a destination for asynchronous invocation, ensure that you do not create a loop. For example, assume that you configure a successful invocation of function A to send its response to function B, and you configure a successful invocation of function B to send its response to function A. When function A is invoked, it begins an infinite loop where functions A and B continuously invoke each other.

Asynchronous invocation policy

High load may result in a backlog of requests. You can modify the asynchronous invocation configuration to ignore requests that have been in the queue for a long time:

  • Validity period of requests

    The maxAsyncEventAgeInSeconds parameter defines how long a request is valid, in seconds. The value range for this parameter is 1 to 2592000. The validity period of a request starts when an asynchronous invocation is triggered and ends when the request is removed from the queue. If this period of time is longer than the value of the maxAsyncEventAgeInSeconds parameter, the request is discarded. Discarded requests are tracked by the Asynchronous Invocation Requests Discarded Due to Timeout metric in Cloud Monitor. For more information, see View asynchronous invocation metrics in Cloud Monitor.

  • Number of retries

    The maxAsyncRetryAttempts parameter defines the number of times that Function Compute will retry a function that failed. The value range for this parameter is 0 to 8. By default, Function Compute retries a maximum of 3 times for a function that failed. You can adjust the value as needed.

Data structure

The following code shows the data structure of the asynchronous invocation configuration:

{
  "destinationConfig": {
        "onSuccess": {
          "destination": "acs:fc:{region}:{account}:services/{service_name}.{ Qualifier}/functions/{function_name}}",
        },
        "onFailure": {
          "destination": "acs:mns:{region}:{account}:/queues/{queue_name}/messages"
        }
  }
  "maxAsyncEventAgeInSeconds": 100,
  "maxAsyncRetryAttempts": 1
}
Table 1. Parameters
Parameter Description
destinationConfig The destination for asynchronous invocation.
onSuccess The destination for a successful function execution.
onFailure The destination for a function execution that fails due to an error in the function or a system error.
destination The destination for asynchronous invocation. Valid values:
  • mns/queues: An MNS queue. The ARN format is acs:mns:{region}:{account}:/queues/{queue_name}/messages.
  • mns/topics: An MNS topic. The ARN format is acs:mns:{region}:{account}:/topics/{topic_name}/messages.
  • fc: Function Compute. The ARN format is acs:fc:{region}:{account}:services/{service_name}.{ Qualifier}/functions/{function_name} .
The ARNs include the following parameters:
  • {region}: the region ID. For more information, see Endpoints.
  • {account}: the account ID. For more information, see Obtain an Alibaba Cloud account ID.
  • {queue_name}: the name of the MNS queue.
  • {topic_name}: the name of the MNS topic.
  • {service_name}: the name of the service in Function Compute.
  • {Qualifier}: the alias of the service in Function Compute.
  • function_name: the name of the function.

A sample ARN for an MNS queue is acs:mns:cn-hangzhou:1111******:/queues/myqueue/messages.

maxAsyncEventAgeInSeconds The validity period of the request. Valid values: 1 to 2592000. Unit: seconds.
maxAsyncRetryAttempts The maximum number of retries after an asynchronous invocation fails. Default value: 3. Valid values: 0 to 8.

Configuration methods

Before you configure asynchronous invocation, ensure that the service role of the function has the required permissions on the destination service.

Destination service Minimum required permission
MNS queue mns:SendMessage
MNS topic mns:PublishMessage
Function Compute fc:InvokeFunction

For more information, see Permissions.

Configure asynchronous invocation by using the console

  1. Log on to the Function Compute console.
  2. In the top navigation bar, select your region.
  3. In the left-side navigation pane, click Service/Function.
  4. Find the target function in the target service and click the name of the function.
  5. Click the Asynchronous Invocation Configuration tab.
  6. On the Asynchronous Invocation Configuration tab, configure the following parameters.
    Configure parameters
    Parameter Example Description
    Asynchronous Invocation Policy Configuration
    Maximum Retries 1 The maximum number of retries after an asynchronous invocation fails. Default value: 3. Valid values: 0 to 8.
    Maximum Validity Period of Invocation Requests (Seconds) 1 The validity period of the request. Valid values: 1 to 2592000. Unit: seconds.
    Destination Configuration - Condition: On Success
    Resource Type fc The destination service for asynchronous invocation. The configuration is different for each destination service type. Valid values:
    • fc: Function Compute
    • mns/queues: MNS queue
    • mns/topics: MNS topic
    Service fnf-demo The service in Function Compute.
    Note This parameter is required only when Resource Type is set to fc.
    Version/Alias 2 The version or alias of the service in Function Compute.
    Note This parameter is required only when Resource Type is set to fc.
    Function Operation The name of the function.
    Note This parameter is required only when Resource Type is set to fc.
    Queue Name MyQueue The name of the MNS queue.
    Note This parameter is required only when Resource Type is set to mns/queues.
    Topic Name MyTopic The name of the MNS topic.
    Note This parameter is required only when Resource Type is set to mns/topics.
    Resource acs:fc:cn-hangzhou:188077086902****:services/fnf-demo.2/functions/Operation The Alibaba Cloud Resource Name (ARN) of the destination service.
    Destination Configuration - Condition: On Failure

    The parameters are the same as those previously described for the success condition.

  7. Click Save Configurations.
    The Success message appears.

What to do next

  • To update an asynchronous invocation configuration, click the Asynchronous Invocation Configuration tab, modify the parameters, and then click Save Configurations.
    Notice Configurations are incrementally updated. If you want to remove a specific setting, you must delete all asynchronous invocation configurations and then create the configuration again.
  • To delete asynchronous invocation configurations, click Delete Configurations on the Asynchronous Invocation Configuration tab.
  • For information about the monitoring metrics for asynchronous invocation, see View asynchronous invocation metrics in Cloud Monitor.

Configure asynchronous invocation by using the SDK

For more information, see Supported SDKs.

Configure asynchronous invocation by using the API operations

You can call the FunctionAsyncInvokeConfig API operations to configure asynchronous invocation for a function in a service. You can create configurations for a specific version or alias.

API Description
PutFunctionAsyncInvokeConfig Creates or updates a specified asynchronous invocation configuration of a function in a service.
GetFunctionAsyncInvokeConfig Queries a specified asynchronous invocation configuration of a function in a service.
ListFunctionAsyncInvokeConfigs Queries all asynchronous invocation configurations of a function in a service.
DeleteFunctionAsyncInvokeConfig Deletes a specified asynchronous invocation configuration of a function in a service.

View asynchronous invocation metrics in Cloud Monitor

The destination service for asynchronous invocation may fail to be used in the following situations: the service role of the function does not have the permissions to invoke the destination service, the response is too large, or the destination service is not operating normally. You can find more information about your asynchronous invocations by viewing metrics in Cloud Monitor.

  1. Log on to the Function Compute console.
  2. In the top navigation bar, select your region.
  3. In the left-side navigation pane, click Service/Function.
  4. Find the target function in the target service and click the name of the function.
  5. Click the Function Metrics tab.
  6. On the Function Metrics tab, set Time Range and view the metrics for your function.
    timespan
    Sample Cloud Monitor metrics are shown in the following figure. Asynchronous invocation metrics are shown in the box.metrics-result

    The following metrics are used to monitor asynchronous invocations:

    • Error Rate: the total attempts by Function Compute to send events to the destination service, and the error rate due to server, client, and function problems. Invalid permissions, invalid resource configurations, and exceeding thresholds may cause the error rate to increase.
    • Invocation Record Sending Metrics: the number of times that results of asynchronous invocations are sent and failed to be sent to the destination service.
    • Asynchronous Invocation Requests Discarded Due to Timeout: the number of requests that are discarded because their time in the queue exceeded the value of the maxAsyncEventAgeInSeconds parameter.