All Products
Search
Document Center

Function Compute:Overview

Last Updated:Sep 11, 2024

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.

    Note

    Website 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

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 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 the 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 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.

    • Note

      For 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.

    • If a response exceeds one of the following limits, the system returns the 502 code and the BadResponse error:

      • Headers size: The total size of all keys and values in headers cannot exceed 8 KB.

Limits on WebSocket

Note

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 the BadResponse 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

Note

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.

Note

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

Do I need to configure listening ports?

You must configure listening ports only if you create a function in a custom runtime or by using a custom container image.

Does Function Compute support a server-sent event (SSE)?

SSE is short for Server-Sent Events. The functions created by using the Use Custom Runtime and Use Container Image methods support SSE. However, functions created by using the Use Built-in Runtime method does not support SSE.

When you deploy a function by using the Use Custom Runtime or Use Container Image method, Function Compute determines whether a response is a streaming response based on whether the response header contains Transfer-Encoding:chunked. To facilitate your use, you can select the sample code of SSE in the runtime when you deploy a function by using the Use Custom Runtime method.

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

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

  • If the 499 status code is returned on a client, function instances are restarted. You can configure health checks for function instances to prevent instances from being restarted. For more information, see Why is a function instance restarted after a 499 error occurs on a client?

  • If function invocations time out on a client, you can move time-consuming logic to a new function and invoke the new function by using the asynchronous invocation feature of the function or using the asynchronous invocation mode on the client.

How do I update the configurations of a running function?

  • You can update the configurations of a running function only after the function finishes request execution. After you update the configurations of the function, the previous configurations still take effect for requests that are being executed. The updated configurations take effect for subsequent requests.

  • You can delete the current function and create another function whose configurations meet your business requirements.

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: