An HTTP trigger allows you to invoke a function by using HTTP requests. HTTP triggers can be used in scenarios such as rapid development of web services. Before you use an HTTP trigger, make sure that you are familiar with limits on HTTP triggers and limits on protocols supported by HTTP triggers, including the HTTP/HTTPS, WebSocket, and gRPC protocols, to prevent function errors caused by limit exceeding. This topic describes the limits, invocation methods, and authentication methods of HTTP triggers, as well as handling of cross-origin resource sharing (CORS) requests.
Precautions
If you use an anonymous HTTP trigger whose Authentication Method is set to No Authentication, no identity authentication is required. In this case, anyone can send an HTTP request to invoke your function. This may lead to URL leakage. To avoid URL leakage, you can use the
Authorization
field of a request header to check the validity of a request. For more information, see Signature authentication.Be mindful of the virtual IP address (VIP) rotation mechanism.
To enhance system resilience and service stability, Function Compute implements a VIP rotation mechanism. Specifically, VIPs that correspond to public and internal endpoints of HTTP triggers in Function Compute are rotated from time to time. The VIP rotation mechanism constitutes an integral part of the infrastructure robustness.
Therefore, hard coding of VIPs may cause service interruptions. We recommend that you use custom domain names to ensure service robustness. Note that failures caused by improper use of VIPs are not covered by the compensation scope of Function Compute. Review your configurations and make necessary adjustments if VIPs are improperly used.
You can use a custom domain name with a CNAME to access Function Compute. For more information, see Configure a custom domain name.
Limits
Before you configure and use an HTTP trigger, make sure that you are familiar with the limits on HTTP triggers and the limits on protocols supported by HTTP triggers, including the HTTP/HTTPS, WebSocket, and gRPC protocols.
Limits on triggers
HTTP triggers cannot be created for Custom Container functions that are in non-web server mode.
After you configure an HTTP trigger for a function, you cannot configure other types of triggers for the function.
For each version or alias, you can create only one HTTP trigger at most. 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 stability of the built-in domain names is not guaranteed and may affect your online services. We recommend that you do not use built-in domain names for external online services.
NoteWebsite services can only be provided by using domain names for which ICP filing is 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
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 and use an HTTP trigger.
Limits on HTTP requests
You cannot use a custom request header that starts with x-fc- or contains the following custom fields: connection and keep-alive.
The system returns the
400
status code and theInvalidArgument
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 includes all Query Params. The total size of a Path cannot exceed 8 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.
Limits on HTTP responses
Response headers do not support custom fields that start with x-fc- or the following custom fields: connection, content-length, date, keep-alive, server, upgrade, and content-disposition:attachment.
If a response exceeds one of the following limits, the system returns the
502
code and theBadResponse
error:Headers size: The total size of all keys and values in headers cannot exceed 8 KB.
NoteFor security reasons, if you use the default domain name aliyuncs.com of Function Compute, the server forcibly adds the content-disposition: attachment field in the response header. This field is used to download returned results from browsers as attachments. If you want to remove this restriction, you can use a custom domain name. For more information, see Configure a custom domain name.
Limits on WebSocket
The GET method can be used to trigger functions. WebSocket is suitable for scenarios that require persistent connections and real-time messaging. For more information, see Configure an HTTP trigger for a function to respond to WebSocket requests.
Runtimes: Only custom runtimes and Custom Container runtimes support WebSocket.
Timeout limit: The timeout period of a WebSocket request is subject to the timeout period that is configured for a function.
Request limits for a WebSocket handshake request:
Request headers that start with x-fc- are not supported.
Headers size: The total size of all keys and values in headers cannot exceed 8 KB.
Path size: The total size of a path, including all query params, cannot exceed 8 KB.
Body: A body cannot be sent in a WebSocket handshake request. Even if a body is sent, Function Compute ignores the body.
Response limit for a WebSocket handshake request:
The total size of all keys and values in response headers cannot exceed 8 KB. Otherwise, the system returns the
502
code and theBadResponse
error.Data transmission limits for WebSocket:
After you establish a WebSocket connection, the maximum size of packets (messages) that can be sent or received at each time cannot exceed 6 MB.
Limits on gRPC
HTTP triggers can be triggered by gRPC requests. gRPC requests are suitable for scenarios that require low latency, high performance, and ProtoBuf-based multi-language communication. For more information, see Configure an HTTP trigger that invokes a function with gRPC requests.
Runtimes: Only custom runtimes and Custom Container runtimes support gRPC.
Limits:
Before you use gRPC to trigger a function, make sure that the POST method is included in Request Methods of the HTTP trigger.
Use the subdomain
fcapp.run
or a custom domain name to initiate a gRPC invocation.
Timeout period: gRPC requests are subject to the timeout period that is configured for a function. The maximum retention period of a streaming gRPC connection cannot exceed the value that is specified for the Execution Timeout Period parameter of the function.
Data transmission of gRPC requests: After you establish a gRPC streaming connection, the maximum amount of data that can be sent or received in a single packet (message) cannot exceed 6 MB.
Benefits:
Both HTTP triggers and API Gateway triggers can be used to create web applications. The following items describe benefits of HTTP triggers and API Gateway 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 also use API Gateway triggers. In this case, set Backend Service Type to Function Compute 2.0, set Function Type to HTTP Function, and then set the backend service address to implement similar features. For more information, see Function Compute.
Compared with API Gateway triggers, HTTP triggers deliver the following benefits:
HTTP triggers can be easily learned and used by developers. This simplifies the debugging process 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 features and performance in Function Compute.
You can connect HTTP triggers to other services that support webhooks with ease, such as Alibaba Cloud CDN and Message Service (MNS).
WebSocket and gRPC protocols are supported.
Invocation methods
Synchronous invocation
During a synchronous invocation, results are returned after an event is processed by a function. By default, an HTTP trigger invokes a function in synchronous mode. For more information, see Synchronous invocations.
Asynchronous invocation
During an asynchronous invocation, Function Compute persists the request and immediately returns a response without waiting for the execution of the request to complete.
Asynchronous invocation: When an HTTP function is triggered, you can add the
"X-Fc-Invocation-Type":"Async"
request header to implement asynchronous invocation at the request level.Asynchronous task: After you configure the asynchronous task mode for an HTTP function, you can add the
"X-Fc-Stateful-Async-Invocation-Id":"g6u*****iyvhd3jk8s6bhj0hh"
request header to configure the invocation ID for the asynchronous task.
For more information about request headers, see InvokeFunction.
If an asynchronous invocation is successful, Function Compute returns the 202
code, which indicates that the request is received. Then, the values of Request ID and Stateful Invocation ID are returned in the "X-Fc-Request-Id": "80bf7****281713e1", "X-Fc-Stateful-Async-Invocation-Id": "7522ba40****1c22e"
format.
If the status code returned from Function Compute is not 202
, the asynchronous invocation fails. For more information about the causes of failed invocations, see Error handling.
In specific scenarios, you may want Function Compute to defer the execution after you submit an asynchronous invocation request. If you want Function Compute to defer an execution, you can add the x-fc-async-delay
HTTP request header to your code. The value range of the header is (0,3600). Unit: seconds. Function Compute invokes the function when the period specified for x-fc-async-delay
elapses. For more information, see Deferred invocation.
Authentication
You can configure authentication for HTTP triggers. After you configure authentication for an HTTP trigger, external requests must pass the authentication before functions can process the requests. Signature authentication and JSON Web Token (JWT) authentication can be configured for HTTP triggers.
Signature authentication
If signature authentication 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 authentication. For more information, see Signature authentication.
Signature authentication provides a high level of security. However, signature algorithms must be implemented on clients and this brings higher costs. In addition, AccessKey IDs and AccessKey secrets must be stored on clients, which poses data leakage risks. Alibaba Cloud Security Token Service (STS) tokens can be used to address this issue. However, this may result in increased architectural complexity.
JWT authentication
JWT is a popular and secure mechanism for API authorization and access. JWT is suitable for low-security client scenarios such as JavaScript and web frontends. For more information, see Configure JWT authentication for an HTTP trigger.
CORS request processing
By default, Function Compute allows cross-origin access to HTTP functions. Function Compute also allows you to specify a custom processing behavior for cross-origin resource sharing (CORS) requests in function code.
Simple requests
A preflight request is not required for a simple request. You can configure a header that starts with Access-Control-Allow-*
in function code to implement access control with ease. For simple requests, Function Compute supports the following custom headers: Access-Control-Allow-Origin
, Access-Control-Allow-Headers
, Access-Control-Request-Method
, and Access-Control-Max-Age
.
If you do not configure custom headers, Function Compute fills the following response headers:
Access-Control-Allow-Origin
: the origin header of a request.Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers
: specific custom headers in Function Compute.
Non-simple requests
A preflight request is sent before a non-simple request is sent. The browser sends a preflight request by using the OPTIONS method, and then initiates the actual request to invoke a function. The rules to initiate a non-simple request are the same as the rules to initiate a simple request. If you want to specify custom responses for a preflight request, you must add the OPTIONS method to an HTTP trigger and process the OPTIONS request in function code. Specifically, you can configure headers that start with Access-Control-Allow-*
to control the cross-origin behavior of a function.
For preflight requests, Function Compute supports the following custom headers: Access-Control-Allow-Origin
, Access-Control-Allow-Headers
, Access-Control-Request-Method
, and Access-Control-Max-Age
.
In this example, Node.js is used to describe how to process preflight requests in function code:
exports.handler = (req, resp, context) => {
console.log('hello world');
if (req.method === 'OPTIONS') {
// Send response to OPTIONS requests
resp.setHeader('Access-Control-Allow-Origin', 'http://www.fc.com')
resp.setHeader('Access-Control-Allow-Methods', 'POST');
resp.setHeader('Access-Control-Allow-Headers', 'Content-Type');
resp.setHeader('Access-Control-Max-Age', '3600');
resp.setStatusCode(204)
resp.send('');
} else {
resp.send("hello world");
}
}
FAQ
More information
The handlers of functions configured with HTTP triggers are different with the handlers of event functions. Make sure that handlers are properly configured. For more information, see the following topics: