Asynchronous invocation is a way to call a function. By asynchronous invocation, you can send the execution status information of the function, such as execution in progress and execution failure, to other target services. You can also set the number of retries and the message survival period for asynchronous invocation. This topic describes the basic concepts, scenarios, limits, configuration structure, and how to configure asynchronous invocation in the Function service console.

What is an asynchronous invocation?

In an asynchronous call, the event returns the result after it is written to the Function service internal queue. The Function service system ensures that the message is reliably processed and returns the request ID, while the specific call situation and function execution status will not be returned. To obtain the result of the asynchronous invocation, you can configure destinations for the asynchronous invocation.

The following figure shows the asynchronous invocation process. Asynchronous invocation process
Asynchronous calls contain the following call states:
  • Stateless asynchronous invocation
    A stateless asynchronous call ensures that the function is executed at least once. When some special circumstances such as system hardware errors and system upgrades occur, the function may be executed multiple times to ensure that each message will be processed.
    Note By default, stateless asynchronous calls are enabled.
  • Stateful asynchronous invocation
    Stateful asynchronous calls can save the state transition information and execution results during the execution of the call. With stateful asynchronous calls, Function service can meet the following requirements:
    • View the execution status during function invocation. such as in the status of queuing, executing, or failed execution.
    • Has call-level control capabilities. For example, you can proactively terminate calls, etc.

Applicable scenarios

  • Common scenarios
    When you set the following trigger for a function, your function will be called asynchronously to implement the linkage between cloud services:
  • Applicable scenarios of stateless asynchronous invocation
    • The execution duration of a function is short.
    • There is no need to frequently view each execution result.
    • There is no need to stop the function being executed.
  • Applicable scenarios of stateful asynchronous invocation
    • The execution duration of a function is long.
    • The result of each execution needs to be viewed.
    • The execution of a function needs to be interrupted.
    Note If the stateful asynchronous invocation mode is enabled, an additional latency exists for invoking and executing a function because status information needs to be saved. This delay does not incur additional fees. For more information about billing, see Billing.

Limits

  • General limit

    Resource call limit: The default maximum number of pay-as-you-go instances for your Alibaba Cloud account (master account) in a single region is 300.

  • Limits on stateful asynchronous calls
    • Supported regions

      Stateful asynchronous calls support the China (Hangzhou), China (Shanghai), China (Beijing), China (Shenzhen), China (Zhangjiakou), Hong Kong, Singapore, UK (London), US (Silicon Valley), US (Virginia), Germany (Frankfurt), Australia (Sydney), and India (Mumbai) regions.

    • Aging limit

      You can query only the execution data within seven days.

Execution concurrency

Execution concurrency is the number of concurrent invocations of a function in a specified period of time. You can use the following formula to estimate the execution concurrency:

Execution concurrency = Request rate × Function execution duration
  • Request Rate: the rate at which the function is called, that is, the number of requests per second or the number of events per second.
  • Function Execution Time: the duration between when the function request arrives at the start of the instance and when the request is executed. Unit: seconds.
For example, you have a function that processes OSS events. The average execution duration for the function is 3 seconds, and 10 OSS events are generated per second. You can use the formula to calculate that the execution concurrency for your function is 30.
Note The number of concurrent function executions affects your billing. For more information about billing, see Billing.

Execution status of asynchronous calls

Status of a stateful asynchronous invocation:
status Description
Enqueued The asynchronous message is enqueued and is waiting to be processed.
Dequeued The asynchronous message is out of queue and is waiting to be triggered.
Running The call is being executed.
Succeeded The call is successful.
Failed The error message returned because the call failed.
Stopped The execution of the call is terminated.
Stopping The call execution is stopped.
Expired You have configured a validity period for an asynchronous message that has been discarded (not triggered) due to expiration.
Invalid Your execution is in an invalid state (not triggered) due to the deletion of a function or service.
Retrying The asynchronous call is being retried due to an execution error.

Configuration items for an asynchronous invocation

Asynchronous invocation contains asynchronous invocation targets and asynchronous invocation policy sections:

  • Destination for the asynchronous invocation: the cloud service or resource to which the result of the asynchronous invocation is sent. It corresponds to the destinationConfig parameter in the data structure.
  • Asynchronous invocation policy: specifies whether to enable an asynchronous invocation policy and configure the maximum number of messages for asynchronous invocation, which are mapped to statefulInvocation, maxAsyncEventAgeInSeconds, and maxAsyncRetryAttempts in the data structure.

Destinations for the asynchronous invocation

When you configure an asynchronous call target for a function and the result after the asynchronous call meets the conditions, the Function service pushes the asynchronous call context and data to the corresponding service to implement the linkage between cloud services. You can configure different destinations for different functions, aliases, and versions. The following types of destinations for the asynchronous invocation are supported:
  • MNS
  • Function service
  • EventBridge
    Note You can set EventBridge as the destination for an asynchronous invocation in the following regions: China (Hangzhou), China (Shanghai), US (Silicon Valley), US (Virginia), China (Beijing), and China (Hong Kong).
  • Message Queue for Apache RocketMQ
    Note You can set Message Queue for Apache RocketMQ as the destination for an asynchronous invocation in the China (Hangzhou) and China (Qingdao) regions.

Take note of the following points when you configure destinations for an asynchronous invocation:

  • Event content sent to the destinations for the asynchronous invocation
    {
        "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": ""
    }
    Table 1. Asynchronous call target parameter description
    Parameter Description
    timestamp The timestamp of the invocation.
    requestContext The context of the request.
    requestContext.requestId The request ID of the asynchronous invocation.
    requestContext.functionArn The Alibaba Cloud Resource Name (ARN) of the function that is asynchronously invoked.
    requestContext.condition The error code of the invocation.
    requestContext.approximateInvokeCount The number of times that the function is asynchronously invoked. If the value is greater than 1, you Function service retry your function.
    requestPayload The original payload of the function request.
    responseContext The context of the response.
    responseContext.statusCode The system status code that is 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 that is returned after the function is executed.
    Notice When a EventBridge is used as the target of an asynchronous call to a function, the event content will have more parameters. For more information about these parameters, see Overview. The following code shows an example of the event content:
    {
        "datacontenttype": "application/json",
        "aliyunaccountid": "143xxxx",
        "data": {
            "requestContext": {
                "condition": "",
                "approximateInvokeCount": 1,
                "requestId": "0fcb7f0c-xxxx",
                "functionArn": "acs:fc:::services/xxxx.LATEST/functions/xxxx"
            },
            "requestPayload": "",
            "responsePayload": "",
            "responseContext": {
                "functionError": "",
                "statusCode": 200
            },
            "timestamp": 12345
        },
        "subject": "acs:fc:::services/xxxx.LATEST/functions/xxxx",
        "source": "acs:fc",
        "type": "fc:AsyncInvoke:succeeded",
        "aliyunpublishtime": "2021-01-03T09:44:31.233Asia/Shanghai",
        "specversion": "1.0",
        "aliyuneventbusname": "xxxxxxx",
        "id": "ecc4865xxxxxx",
        "time": "2021-01-03T01:44:31Z",
        "aliyunregionid": "cn-shanghai-vpc",
        "aliyunpublishaddr": "199.99.xxx.xxx"
    }
  • Payload limits

    The payload that is supported by a destination for the asynchronous invocation cannot exceed the following limits:

    • MNS: 64 KB
    • Function service :128 KB
    • EventBridge: 64 KB
    • Message Queue for Apache RocketMQ: 4 MB
    Note The default data sent to a destination for the asynchronous invocation, except the values of the requestPayload and responsePayload parameters, must be less than 1 KB in size. Make sure that the total size of the input parameters, function response, and default data of your asynchronous invocation does not exceed the payload limit.
  • Loop avoidance

    When you configure a destination for the asynchronous invocation, make sure that you do not create a loop. For example, you configure Function B as the destination for a successful asynchronous invocation of Function A and Function A as the destination for a successful asynchronous invocation of Function B. When you trigger function A asynchronously and execute successfully, a loop call from A to B to A... may occur.

Asynchronous invocation policy

  • Specifies whether to enable stateful asynchronous invocation.
    The statefulInvocation in the asynchronous invocation configuration is used to set whether to enable stateful asynchronous invocation. The value of this parameter is as follows:
    • true: indicates that stateful asynchronous calls are enabled.
    • false: indicates that stateful asynchronous calls are disabled.
    By default, the stateful asynchronous invocation mode is disabled. If the stateful asynchronous invocation mode is enabled, all status transition information during the invocation is saved.
  • In some scenarios, a high invocation payload may result in a backlog of messages. You can modify the following asynchronous invocation configurations to ignore messages that exist for an extended period of time:
    • Maximum validity period of messages

      The maxAsyncEventAgeInSeconds parameter in the asynchronous invocation configurations specifies the maximum validity period of messages. Valid values: [1,2592000]. Unit: seconds.

      The period starts when an asynchronous invocation is triggered and ends when the message is removed from the queue for processing. If this period of time is greater than the maxAsyncEventAgeInSeconds configuration value, the message will be discarded. Messages that are not consumed are counted in the asynchronous invocation trigger event (times) Cloud Monitor metric. For more information about metrics, see the View the asynchronous invocation metrics provided by CloudMonitor in the following section.

    • Max Retries

      Function service allows you to configure the number of retries by using the maxAsyncRetryAttempts parameter in the asynchronous invocation configuration. Valid values: [0,8].

      Function service, by default, three retries are performed for messages that fail to be triggered asynchronously. You can reduce or increase retries for asynchronous calls based on your business requirements.

Data structure of asynchronous invocation configurations

This section describes the data structures of asynchronous invocation configurations.
{
  "statefulInvocation": true,
  "destinationConfig": {
        "onSuccess": {
          "destination": "acs:fc:{region}:{accountId}:services/{service_name}.{Qualifier}/functions/{function_name}}",
        },
        "onFailure": {
          "destination": "acs:mns:{region}:{account}:/queues/{queue_name}/messages"
        }
  },
  "maxAsyncEventAgeInSeconds": 100,
  "maxAsyncRetryAttempts": 1
}

Configuration methods

The following section describes how to configure asynchronous calls in the Function service console.

Prerequisites

For all configuration methods of asynchronous invocations, make sure that the service role of the function has the required permissions on the destination. For more information about how to set permissions for Function Compute to access other target cloud services, see Grant Function Compute permissions to access other Alibaba Cloud services.
Target cloud service Minimum permissions
MNS Queue mode: mns:SendMessage
Topic mode: mns:PublishMessage
Function service fc:InvokeFunction
EventBridge eventbridge:PutEvents
Message Queue for Apache RocketMQ AliyunMQPubOnlyAccess

Procedure

  1. Log on to the Function Compute console.
  2. In the left-side navigation pane, click Services and Functions.
  3. In the top navigation bar, select the region where your Kubernetes cluster is deployed.
  4. On the Services page, click the target service.
  5. On the Functions page, click the name of the function that you want to manage.
  6. On the details page of the target function, click the Asynchronous Call tab.
  7. On the Asynchronous Call tab, set the parameters as needed.
    • Configure an asynchronous invocation policy
      1. In the Asynchronous Invocation Policy section, click Edit.
      2. In the Edit Asynchronous Call Policy panel, set the following parameters:
        Parameter Description
        Asynchronous call type Select an asynchronous invocation type. When the asynchronous call type is selected as stateful, the Function service records detailed state transition information for each call process, such as call input, execution result, and error information.
        Note If you fail to enable stateful asynchronous calls, submit a ticket.
        Max Retries The maximum number of retries after an asynchronous invocation fails. Default value: 3. Valid values: [0,8].
        Maximum validity period of messages The maximum validity period of messages. Valid values: [1,2592000]. Unit: seconds.
      3. Click OK.
    • Configure success targets
      1. In the Destination section, click Edit.
      2. In the Edit Target panel, configure the target cloud service that sends the execution information after the function is successfully executed. The following table describes the parameters.
        Parameter Description
        Call other services when successful Select whether to call other cloud services when enabled. After you enable this feature, you can send execution information to other target services after the function is successfully executed.
        Destination The kubectl client is connected to the ACK cluster. For more information, see Function service. If you select Function service for the target service, you must configure the following parameters:
        • Service Name: the name of the service.
        • Version or Alias: specifies the alias or version of the service.
        • Function Name: the name of the function.
        The kubectl client is connected to the ACK cluster. For more information, see MNS. If you select MNS for the target service, you must configure the following parameters:
        • Target Type: Select a target type as needed. Valid values:
          • queue:

            A queue-based messaging model provides highly reliable and concurrent message consumption services. Each message in a queue can be consumed by only one client.

          • Topic:

            A topic-based messaging model is used to send messages from one publisher client to multiple subscriber clients. MNS topics can be pushed as messages by using multiple methods.

        • Queue: specifies the name of the MNS queue. This parameter is required when the destination type is queue.
        • Topic: Select the MNS topic name. This parameter is required when the target type is subject.
        Message Queue for Apache RocketMQ, if you select Message Queue for Apache RocketMQ for the target service, you must configure the following parameters:
        • Instance: Select the target instance.
        • Topic: Select the target topic.
        The kubectl client is connected to the ACK cluster. For more information, see EventBridge. If EventBridge is selected for the target service, you must specify a custom event bus.
      3. Click OK.
    • Configure Failed Targets
      1. In the Target section, click Edit.
      2. In the Edit Failed Target panel, configure the target cloud service that sends the execution information after the function fails to be executed.

        You can configure the parameters of a failed target by referring to the parameter description of a successful target.

      3. Click OK.
    Note After you have configured a stateful asynchronous invocation, you can view the details of the asynchronous invocation records on the Asynchronous invocation tab, such as the asynchronous invocation ID, invocation status, start and end time, execution duration, and retries. For more information about monitoring information about asynchronous calls, see View the asynchronous invocation metrics provided by CloudMonitor.

View the asynchronous invocation metrics provided by CloudMonitor

The destination for an asynchronous invocation may fail to be called in the following situations: The service role of the function does not have the permissions to call the destination service or resource, the response is too large in size, or the destination is abnormal. You can find more information by viewing the metrics that are provided by CloudMonitor.

  1. Log on to the Function Compute console.
  2. In the left-side navigation pane, click Services and Functions.
  3. In the top navigation bar, select the region where your Kubernetes cluster is deployed.
  4. On the Services page, click the target service.
  5. On the Functions page, click the name of the function that you want to manage.
  6. On the details page of the target function, click the Monitoring Metrics tab.
  7. On the Monitoring Metrics tab, set the time range and monitoring granularity as needed, and then click OK.
    On the Monitoring Metrics tab, you can click Function Metrics to view the metrics related to asynchronous calls, as shown in the following figure. yibudiaoyongzhibiaoxintu
    The monitoring metrics for asynchronous calls are described as follows:
    • Asynchronous call handling (number)
      This metric contains the following metric information:
      • Request Enqueued: the number of enqueued requests per unit time after asynchronous calls are enabled. The statistics are collected every minute or every hour.
      • Request Processing Completed: the total number of requests that are processed after asynchronous calls are enabled. The statistics are collected every minute or every hour.
        Note If the number of processed requests is much smaller than the number of enqueued requests, a message backlog occurs. You must adjust the concurrency of the function.
    • Asynchronous message processing latency (milliseconds)
      This metric item contains the following metric information:
      • Average processing latency: The average latency from the start of a message enqueuing to the end of processing when the function is called asynchronously. The average value is calculated every minute or every hour.
      • Maximum processing latency: The maximum latency from the start of a message enqueuing to the end of processing when the function is called asynchronously. The maximum value is calculated every minute or every hour.
    • Event triggered by asynchronous invocation (times)
      This metric item contains the following metric information:
      • Timeout Discarded: the total number of requests that the discarded function execution times out after the function is enabled for stateful asynchronous invocation. The statistics are collected every minute or every hour.
      • Target Triggering Failed: the number of requests that fail to trigger a target during function execution after the function is enabled for stateful asynchronous invocation. The statistics are collected every minute or every hour.
      • Target Triggered Successfully: the number of requests that successfully trigger the target in function execution after the function is enabled for stateful asynchronous invocation. The statistics are collected every minute or every hour.

References

You can configure not only synchronous calls or asynchronous calls in the Function service console, but also in the following ways:
  • Serverless Devs

    When you use Serverless Devs to manage resources, you can set the function invocation mode to asynchronous invocation and configure parameters related to asynchronous invocation. For more information about Serverless Devs, see Overview.

  • SDK
    For more information, see Supported SDKs. You can use the invokeFunction operation to specify the calling method of the function. For more information, see InvokeFunction. For more information about configuring the Asynchronous Call API operation, see the following:
    API Description
    You can call the FunctionAsyncInvokeConfig API operations to configure asynchronous invocations for a function in a service in Function Compute. Versions and aliases of services are supported.
    PutFunctionAsyncInvokeConfig Creates or modifies an asynchronous invocation configuration for a specific function in a service.
    GetFunctionAsyncInvokeConfig Queries an asynchronous invocation configuration of a specific function in a service.
    ListFunctionAsyncInvokeConfigs Queries all asynchronous invocation configurations of a specific function in a service.
    DeleteFunctionAsyncInvokeConfig Deletes an asynchronous invocation configuration of a specific function in a service.
    You can call the StatefulAsyncInvocation API operations to view specific execution information, asynchronous invocations that meet a specific condition, and terminate an asynchronous invocation.
    GetStatefulAsyncInvocation Queries the information about a stateful asynchronous invocation.
    ListStatefulAsyncInvocations Queries all stateful asynchronous invocations that meet a specific condition. Examples:
    • Queries a specified number of stateful asynchronous invocations.
    • Queries stateful asynchronous invocations whose status is Failed.
    • Queries stateful asynchronous invocations whose start time is in a specific execution period.
    StopStatefulAsyncInvocation Terminates a stateful asynchronous invocation.