An HTTP trigger allows you to invoke a function with an HTTP request. HTTP triggers can be used in scenarios such as the fast construction of web services. This topic describes the invocation methods, protocols, benefits, cross-origin resource sharing (CORS) request processing, limits, and handler functions of HTTP triggers.

Usage notes

If you set the Authentication parameter to No in the trigger configuration, your HTTP trigger is anonymous. In this case, anyone can invoke your function by sending an HTTP request. This may leak the URL. To avoid URL leakage, you can configure the Authorization field of the request header to check the validity of a request. For more information, see Signature authentication.

Benefits

You can use HTTP triggers and API Gateway triggers to create web applications. Compared with API Gateway triggers, HTTP triggers deliver the following benefits:

  • You can use HTTP triggers to facilitate learning, simplify the debugging process, and efficiently build web applications and APIs by using Function Compute.
  • You can use HTTP triggers to optimize request processing. HTTP triggers support more 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 HTTP test tools with which you are familiar to test the features and performance of HTTP triggers 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 is supported.

Invocation methods

Synchronous invocation

By default, an HTTP trigger invokes a function synchronously.

Asynchronous invocation

You can use an HTTP trigger to invoke a function asynchronously at the request level by adding the request header "X-Fc-Invocation-Type":"Async". After you configure an asynchronous invocation task for an HTTP function, you can add the request header "X-Fc-Stateful-Async-Invocation-Id":"g6u*****iyvhd3jk8s6bhj0hh" to configure the invocation ID of the asynchronous invocation task. For more information about request headers, see InvokeFunction.

After the asynchronous invocation task succeeds, Function Compute returns the status code 202, which indicates that the request is received. In addition, the system returns the request ID and stateful invocation ID based on the request header. The format is "X-Fc-Request-Id": "80bf7****281713e1", "X-Fc-Stateful-Async-Invocation-Id": "7522ba40****1c22e".

Note If the status code returned from the Function Compute system is not 202, the asynchronous invocation task fails. For more information about the causes of a failed invocation, see Error handling.

Protocols

  • HTTP or HTTPS: You can use the protocol to trigger functions in simple request-response scenarios by using the GET, POST, PUT, DELETE, HEAD, PATCH, and OPTIONS methods.
  • WebSocket: You can use the protocol to trigger functions in persistent connection and real-time messaging scenarios by using the GET method.

CORS request processing

By default, Function Compute allows you to invoke HTTP functions across origins. You can also write code about how functions process CORS requests.

Simple requests

A preflight request is not required for a simple request. You can configure the header that starts with Access-Control-Allow-* in the function code to easily implement access control. For simple requests, Function Compute supports the following custom headers:
  • Access-Control-Allow-Origin
  • Access-Control-Allow-Headers
  • Access-Control-Request-Method
  • Access-Control-Max-Age

If a request does not include the preceding custom headers, the following response headers in Function Compute are set to the values of the corresponding headers in a request.

  • Access-Control-Allow-Origin: the origin header of the request.
  • Access-Control-Allow-Credentials: true
  • Access-Control-Expose-Headers: custom headers in Function Compute.

Not-so-simple requests

A preflight request is sent for a not-so-simple request. The browser sends a preflight request by using the OPTIONS method, and then initiates the actual request to invoke the function. The rules to initiate a not-so-simple request are the same as the rules to initiate a simple request. To customize the response of a preflight request, perform the following operations:

  1. Add the OPTIONS method to the HTTP trigger.
  2. Process the OPTIONS request in the function code. You must configure the header that starts with Access-Control-Allow-* to control the cross-origin behavior of the function.

For a preflight request, Function Compute supports the following custom headers:

  • Access-Control-Allow-Origin
  • Access-Control-Allow-Headers
  • Access-Control-Request-Method
  • Access-Control-Max-Age
In this example, Node.js is used to describe how to process preflight requests in the 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");
     }
}

Limits

Trigger limits

  • After you configure an HTTP trigger for a function, you cannot configure other types of triggers for the function.
  • You can configure only one HTTP trigger for each function.
  • For each version or alias of a service, you can create only one HTTP trigger. For more information, see Manage versions and Manage aliases.

HTTP limits

  • HTTP request limits
    • You cannot create a request header that starts with x-fc- or the following request headers:
      • connection
      • keep-alive
    • If a request exceeds one of the following limits, the system returns the status code 400 and the error InvalidArgument.
      • Header size: The total size of all keys and values in the headers cannot exceed 4 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 16 MB. The total size of the body of an asynchronous invocation request cannot exceed 128 KB.
  • HTTP response limits
    • You cannot create a response header that starts with x-fc- or the following response headers:
      • connection
      • content-length
      • date
      • keep-alive
      • server
      • upgrade
      • content-disposition:attachment
        Note For security purposes, the server forcefully adds the content-disposition: attachment field to the response header when the default domain name aliyuncs.com of Function Compute is used. This field is used to download the returned result from the browser as an attachment. To remove this limit, you must configure a custom domain name. For more information, see Configure a custom domain name.
    • If a response exceeds one of the following limits, the system returns the status code 502 and the error BadResponse.
      • Header size: The total size of all keys and values in the headers cannot exceed 4 KB.
  • Others

    You can bind a custom domain name to map different HTTP paths for HTTP functions. For more information, see Configure a custom domain name. You can also use API Gateway to implement similar features by setting the backend service type to HTTP and specifying the HTTP function path as the backend service address. For more information, see Use Function Compute as the backend service of an API operation.

WebSocket limits

  • Runtime: Only custom runtimes and custom containers 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.
    • Header size: The total size of all keys and values in the headers cannot exceed 4 KB.
    • Path size: The total size of the path, including all query parameters, cannot exceed 4 KB.
    • Body: The body cannot be sent in a WebSocket handshake request. If the body is sent, Function Compute ignores the request.
  • Response limit for a WebSocket handshake request:

    The total size of all keys and values in response headers cannot exceed 4 KB. Otherwise, the system returns the status code 502 and the error BadResponse.

  • Data transmission limit for WebSocket:

    After you establish a WebSocket connection, the maximum size of packets (messages) that can be sent or received at a time is 6 MB.

Handler functions of HTTP triggers

HTTP

The handler settings of functions with HTTP triggers are different from the settings of regular functions. The following figures compare a regular function on the left and a function with an HTTP trigger on the right in Node.js and Python. If you use the regular handler after you set an HTTP trigger, modify the handler at the earliest opportunity.
  • Node.jscode_compare_js
  • Pythoncode_compare_py

WebSocket

Only custom runtimes and custom containers support WebSocket. For more information, see Configure an HTTP trigger for a function that is triggered by WebSocket requests, Overview for custom runtimes, and Overview.