An HTTP trigger invokes a function through an HTTP request, which is useful for quickly building web services. Before using an HTTP trigger, review its limits and the limits of the supported HTTP/HTTPS protocols to prevent function errors caused by exceeding these limits. This topic describes the invocation methods, authentication, and cross-origin request handling for HTTP triggers.
Usage notes
If your HTTP trigger is anonymous because its Authentication Method is set to No Authentication, identity verification is not required. This means that anyone who has the URL can send HTTP requests to invoke your function, which poses a security risk. To mitigate this risk, you can authenticate requests by validating the
Authorizationfield in the request header. For more information, see Configure signature authentication for an HTTP trigger.In compliance with national cybersecurity regulations, starting from June 10, 2024, newly created HTTP triggers are prohibited from downloading APK files (MIME type: application/vnd.android.package-archive) through public network access endpoints. Attempts to download APK files will return a 400 error code. For more information, see How to ensure that a public endpoint of an HTTP trigger can return .apk files as expected.
Virtual IP address (VIP) rotation mechanism.
To enhance system resilience and service stability, Function Compute uses a virtual IP address (VIP) rotation mechanism. This means that the VIPs corresponding to the public and internal endpoints of HTTP triggers are rotated periodically to improve infrastructure robustness.
Note that hard coding VIPs may cause service interruptions. We strongly recommend that you use custom domain names to ensure business robustness. Failures caused by the improper use of VIPs are not covered by the Function Compute service level agreement (SLA). You should check your usage and adjust it to the correct method.
You can use a custom domain name with a canonical name (CNAME) record to access Function Compute. For more information, see Configure a custom domain name.
Limits
Trigger limits
For each version or alias of a function, you can create only one HTTP trigger. For more information, see Manage versions and Manage aliases.
The built-in domain names provided by HTTP triggers are for testing only. Do not use them for external online services. This practice prevents potential stability issues with the built-in domain names from affecting your online services.
NoteTo provide website services to external users, you must use a domain name that has an ICP filing. You can configure a custom domain name, bind the domain name to the function, and then use your own domain name to provide services. For more information, see Configure a custom domain name.
Limits on the HTTP/HTTPS protocol
You can use the GET, POST, PUT, DELETE, HEAD, PATCH, and OPTIONS methods to trigger functions. These methods are suitable for simple request-response scenarios. For more information, see Configure an HTTP trigger.
HTTP request limits
Request headers do not support custom fields that start with x-fc- or the following custom fields.
connection
keep-alive
If a request exceeds the following limits, a
400status code and anInvalidArgumenterror code are returned.Headers size: The total size of all keys and values in the 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 for a synchronous invocation request cannot exceed 32 MB. For the body size of an asynchronous invocation request, see Resource limits.
HTTP response limits
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
content-disposition:attachment
NoteFor security reasons, if you use the default aliyuncs.com domain name of Function Compute, the server forcibly adds the content-disposition: attachment field to the response headers. This field causes the returned result to be downloaded as an attachment in the browser. To remove this restriction, you can set a custom domain name. For more information, see Configure a custom domain name.
If a response exceeds the following limit, a
502status code and aBadResponseerror code are returned.Headers size: The total size of all keys and values in the headers cannot exceed 8 KB.
Benefits
Both HTTP triggers and API Gateway triggers can be used to create web applications. Their usage is as follows:
HTTP triggers: You can bind a custom domain name to map different HTTP access paths for an HTTP function. For more information, see Configure a custom domain name.
API Gateway triggers: You can also use API Gateway with Function Compute set as the backend service to implement similar features. For more information, see Using Function Compute as an API backend service.
Compared with API Gateway triggers, HTTP triggers have the following benefits.
HTTP triggers are easier for developers to learn and debug. This helps developers quickly build web applications and APIs using Function Compute.
HTTP triggers reduce request processing steps. They support efficient request and response formats and do not require encoding or decoding into JSON format. This results in better performance.
You can use familiar HTTP test tools to test the features and performance of Function Compute.
You can easily integrate HTTP triggers with other services that support webhook callbacks, such as CDN back-to-origin and Simple Message Queue (formerly MNS).
Invocation methods
Synchronous invocation
A synchronous call means that the result is returned immediately after an event is processed by a function. The default invocation method for an HTTP trigger is a synchronous call. For more information, see Synchronous calls.
Asynchronous invocation
In an asynchronous invocation, after Function Compute receives a request, it saves the request for persistence and immediately returns a response. It does not wait for the request to be executed before returning the result.
Asynchronous invocation: When you use an HTTP trigger to invoke a function, you can add the
"X-Fc-Invocation-Type":"Async"request header to perform a request-level asynchronous invocation.Asynchronous task: After you configure an asynchronous task for an HTTP function, you can add the
"X-Fc-Async-Task-Id":"g6u*****iyvhd3jk8s6bhj0hh"request header to specify the invocation ID for the asynchronous task.
For more information about request headers, see InvokeFunction.
After a successful asynchronous invocation, Function Compute returns the status code 202, which indicates that the request is accepted. The request ID is also returned in the request header, for example, "X-Fc-Request-Id": "80bf7****281713e1".
If Function Compute returns a status code other than 202, the invocation failed. For more information about the causes of invocation failures, see Retry mechanism.
References:
For more information about asynchronous invocations, see Asynchronous invocation.
For more information about asynchronous tasks, see Asynchronous tasks.
Authentication
Function Compute supports authentication for HTTP triggers. When a user accesses a function through an HTTP trigger, Function Compute must authenticate the user before granting access. The following authentication methods are supported:
Configure Basic authentication for an HTTP trigger
CORS request handling
By default, Function Compute allows cross-origin access to function invocation requests. It also supports custom handling of cross-origin request (CORS) behavior in your function code.
Simple requests
Simple requests do not send preflight requests. For simple access control, you can set headers that start with Access-Control-Allow-* in the function code. Function Compute supports custom headers for simple requests, such as Access-Control-Allow-Origin, Access-Control-Allow-Headers, and Access-Control-Max-Age.
If you do not set custom headers, Function Compute sets the response headers to the corresponding fields in the request by default:
Access-Control-Allow-Origin: the Origin header of the request.Access-Control-Allow-Credentials: The default value istrue.Access-Control-Expose-Headers: some custom headers of Function Compute.
Non-simple requests
Non-simple requests send a preflight request before sending the formal request. A non-simple request includes an OPTIONS method function invocation request and an actual function invocation request. The rules for formal requests are the same as for simple requests. To customize the response of a preflight request, you must add the OPTIONS method to the HTTP trigger. Then, you can process the OPTIONS request in the function code by setting headers that start with Access-Control-Allow-* to control the cross-origin behavior of the function.
For preflight requests, Function Compute supports custom headers, including Access-Control-Allow-Origin, Access-Control-Allow-Headers, Access-Control-Allow-Methods, and Access-Control-Max-Age.
The following example shows how to process a preflight request in the function code of a built-in Node.js runtime:
exports.handler = (event, context,callback) => {
console.log('hello world');
const method = JSON.parse(event).requestContext.http.method;
if (method === 'OPTIONS') {
// Set response headers to handle the preflight request.
const fcResponse = {
'statusCode': 204,
'headers': {
'Access-Control-Allow-Origin': 'http://www.fc.com',
'Access-Control-Allow-Methods': 'POST',
'Access-Control-Allow-Headers': 'Content-Type, Authorization',
'Access-Control-Max-Age':'3600'
},
'body': 'hello world'
};
callback(null, fcResponse);
} else {
callback(null, {
'statusCode': 500,
'body': 'hello world'
});
}
};