Limits on HTTP triggers and methods to use HTTP triggers to invoke functions - Function Compute

An HTTP trigger allows you to invoke a function with HTTP requests. HTTP triggers can be used in scenarios such as quick construction of web services. Before you use HTTP triggers, make sure that you are familiar with the limits on HTTP triggers and protocols such as HTTP/HTTPS, WebSocket, and gRPC to prevent function invocation failures. This topic describes how to invoke an HTTP trigger, configure authentication, and process cross-origin resource sharing (CORS) requests.

Precautions

If Authentication of an HTTP trigger is set to No, the HTTP trigger is anonymous. In this case, everyone can invoke your function by sending an HTTP request. This may cause the URL of the HTTP trigger to be leaked. To prevent URL leaks, you can use the Authorization request header to check the validity of a request. For more information, see Configure signature authentication for HTTP triggers.

Limits

Before you configure and use an HTTP trigger, make sure that you understand the limits on HTTP triggers and the limits on the HTTP/HTTPS, WebSocket, and gRPC protocols.

Limits on triggers

HTTP triggers cannot be created for functions that are in the non-web server mode and run in Custom Container runtimes.
After you configure an HTTP trigger for a function, you cannot configure other types of triggers for the function.
For each version or alias of a function, you can create only one HTTP trigger. For more information, see Manage versions and Manage aliases.
By default, the built-in domain names provided by HTTP triggers are only for tests. The built-in domain names may be unstable and affect your online services. We recommend that you do not use the built-in domain names for external online services.
Note
Website services can be provided only by using domain names for which ICP filings are obtained. You can configure a custom domain name, bind the domain name to your function, and then use the domain name to provide services. For more information, see Configure a custom domain name.

Limits on HTTP/HTTPS

Note

You can use the following methods to trigger functions: GET, POST, PUT, DELETE, HEAD, PATCH, and OPTIONS. The HTTP and HTTPS protocols are suitable for simple request-response scenarios. For more information, see Configure an HTTP trigger that invokes a function with HTTP requests.

HTTP request limits
- You cannot use a custom request header that starts with x-fc- or one of the following custom request headers:
  - connection
  - keep-alive
- The system returns the 400 status code and InvalidArgument error if a request exceeds one of the following limits:
  - Headers size: The total size of all keys and values in headers cannot exceed 8 KB.
  - Path size: The total size of the path, including all query parameters, cannot exceed 4 KB.
  - Body size: The total size of the body of a synchronous invocation request cannot exceed 32 MB. The total size of the body of an asynchronous invocation request cannot exceed 128 KB.
HTTP response limits
- You cannot use a custom response header that starts with x-fc- or one of the following custom response headers:
  - connection
  - content-length
  - date
  - keep-alive
  - server
  - upgrade
  - content-disposition:attachment
    Note
    For security reasons, if you use the default domain name aliyuncs.com of Function Compute, the server forcibly adds the content-disposition: attachment response header. The response header is used to download the returned results from the browser as an attachment. If you want to remove this restriction, you can use a custom domain name. For more information, see Configure custom domain names.
- If a response exceeds the following limit, Function Compute returns the 502 status code and the BadResponse error:
  - Headers size: The total size of all keys and values in headers cannot exceed 8 KB.

Benefits

You can use HTTP triggers and API Gateway triggers to create web applications. The following items describe each type of triggers:

HTTP triggers: You can bind a custom domain name to map different HTTP access paths to HTTP functions. For more information, see Configure a custom domain name.
API Gateway triggers: You can use API Gateway, select HTTP service as the backend service of an API, and then specify the address of the backend service for HTTP functions to implement features similar to those provided by HTTP triggers. For more information, see Function Compute.

Compared with API Gateway triggers, HTTP triggers provide the following benefits:

HTTP triggers can be easily learned and used by developers. This simplifies debugging and helps developers quickly build web applications and APIs by using Function Compute.
You can use HTTP triggers to optimize request processing. HTTP triggers support efficient request and response formats. You do not need to encode or decode requests to the JSON format. This helps deliver better performance.
You can use an HTTP test tool with which you are familiar to test the features and performance of Function Compute.
You can connect HTTP triggers to other services that support webhooks with ease, such as Alibaba Cloud CDN and Message Service (MNS).

Invocation methods

Functions can be invoked in both synchronous and asynchronous modes. During a synchronous invocation, the result is returned after an event is processed by a function. During an asynchronous invocation, Function Compute persists the request and immediately returns a response without waiting for the execution of the request to complete.

Synchronous invocation

By default, an HTTP trigger invokes a function in synchronous mode. For more information, see Synchronous invocation.

Asynchronous invocation

You can use an HTTP trigger to invoke a function in asynchronous mode at the request level by adding the "X-Fc-Invocation-Type":"Async" request header. For more information about request headers, see InvokeFunction.

If an asynchronous invocation is successful, Function Compute returns the 202 status code, which indicates that the request is received. In addition, Function Compute returns the request ID by using a request header. The format of the ID is "X-Fc-Request-Id": "80bf7****281713e1".

Note

If the status code returned from Function Compute is not 202, the asynchronous invocation fails. For information about causes of invocation failures, see Error handling.

In specific scenarios, you may want Function Compute to defer the invocation after you submit an asynchronous invocation request. To achieve this, you can add the x-fc-async-delay HTTP request header to your code. The value range of the header is 0 to 3600, in seconds. Function Compute invokes the function after the period specified by x-fc-async-delay elapses. For more information, see the Deferred invocation of a function section of the "Overview" topic.

References

For more information about asynchronous invocations, see Overview.

Authentication

You can configure authentication policies for HTTP triggers. After you configure an authentication policy for HTTP triggers, external requests must pass the authentication before they are processed by functions.

Signature authentication and JSON Web Token (JWT) authentication policies can be configured for HTTP triggers.

Signature authentication

If a signature authentication policy is configured for an HTTP trigger, requests must be signed by using the assigned AccessKey IDs and AccessKey secrets. The AccessKey IDs and AccessKey secrets are passed to Function Compute for verification. For more information, see Configure signature authentication for HTTP triggers.

This authentication method is highly secure, but the signature algorithm must be implemented on clients, which is costly. In addition, AccessKey IDs and AccessKey secrets must be stored on clients. Therefore, AccessKey IDs and AccessKey secrets may be leaked. You can use Security Token Service (STS) tokens to address this issue. However, certain architectural complexity is introduced.

JWT authentication

JWT is a popular and secure mechanism for API authorization and access. It is suitable for low-security client scenarios such as JavaScript or web frontends. For more information, see Configure JWT authentication for an HTTP trigger.

CORS request processing

By default, Function Compute allows you to invoke functions across origins. The following items describe the default configurations of response headers of Function Compute.

Access-Control-Allow-Origin: the origin header of a request.
Access-Control-Allow-Credentials: the default value is true.
Access-Control-Expose-Headers: custom headers of Function Compute.

FAQ

Do I need to configure listening ports?

You must configure listening ports only if you create a function by selecting Use Custom Runtime or Use Container Image.

What do I do if a function requires a long period of time to be invoked?

If a function is not frequently used, you must wait for a cold start of the function to complete the first time you invoke the function.
For more information, see Why do functions that are infrequently used take a longer period of time to invoke? For more information about how to prevent impacts caused by cold starts, see How to keep instances alive to eliminate the impact of cold starts?
If function invocations occasionally time out, you can adjust the execution timeout period and query logs to find the cause of the timeout. For more information, see What do I do if the function execution times out and the error "Function time out after" is reported?
If your function processes a large number of requests, we recommend that you configure instance concurrency to reduce the time required to handle requests. For more information, see Configure instance concurrency.

What do I do if the 499 status code is returned to a client and the client actively cancels requests?

If the 499 status code is returned to a client, function instances are restarted. You can configure a health check policy for function instances to prevent instances from being restarted. For more information, see Why is a function instance restarted after the 499 status code occurs on a client?
If function invocation times out on a client, you can move time-consuming logic to the code of a new function. Then, invoke the new functions in the asynchronous mode. You can also use the asynchronous invocation mode on a client.

How do I update the configurations of a running function?

You can update the configurations of a function only after the function executes existing requests. After you update the configurations of the function, the function continues to use original configurations to execute ongoing requests. The updated configurations take effect on new requests.
You can delete the current function and create and configure another function based on your business requirements.