Invoke a function with HTTP requests - Function Compute - Alibaba Cloud Documentation Center

HTTP triggers provide dedicated HTTP and HTTPS addresses for functions, allowing direct invocation through the provided URL. This topic explains how to use HTTP triggers to invoke functions in the built-in runtime. For details on invoking functions with custom runtime HTTP triggers, see Web functions.

Notes

In Function Compute 3.0, the behavior of HTTP triggers in custom runtimes and custom image runtime environments is consistent with Function Compute 2.0. However, there are significant differences in the HTTP triggers of built-in runtime functions compared to Function Compute 2.0. For more details, see Function invocation flow.

Function invocation flow

For built-in runtime functions, when a client invokes the function URL, Function Compute maps the request to an event object event, and then passes the event to the function. After the function execution is complete, the returned response is mapped to an HTTP response. Function Compute sends the HTTP response back to the client through the function URL.

Request struct

Request struct format

The request struct format is as follows:

{
    "version": "v1",
    "rawPath": "/example",
    "body": "Hello FC!",
    "isBase64Encoded": false,
    "headers": {
        "header1": "value1",
        "header2": "value1,value2"
    },
    "queryParameters": {
        "parameter1": "value1",
        "parameter2": "value1,value2"
    },
    "requestContext": {
        "accountId": "123456*********",
        "domainName": "<http-trigger-id>.<region-id>.fcapp.run",
        "domainPrefix": "<http-trigger-id>",
        "http": {
            "method": "GET",
            "path": "/example",
            "protocol": "HTTP/1.1",
            "sourceIp": "11.11.11.**",
            "userAgent": "PostmanRuntime/7.32.3"
        },
        "requestId": "1-64f6cd87-*************",
        "time": "2023-09-05T06:41:11Z",
        "timeEpoch": "1693896071895"
    }
}

The following table describes the parameters:

Parameter	Description	Example
version	The payload format version of the event. The current version is v1.	v1
rawPath	The request path. For example, if the request URL is `https://{url-id}.{region}.fcapp.run/example`, the raw path value is `/example`. The rawPath is URL-encoded. To obtain the URL-decoded path, use the parameter `requestContext.http.path`.	/example
body	The request body. If the content of the request is of binary type, the body is Base64-encoded.	Hello FC!
isBase64Encoded	Set the value to true if the body is of binary type and Base64 encoded. Otherwise, set the value to false.	false
headers	This parameter is a list of request headers. Values of this parameter are displayed in key-value pairs. If a key has multiple values, separate the values with commas (,). When using an HTTP trigger to invoke a built-in runtime, FC3.0 transforms the HTTP request into the Event format of the HTTP trigger. The keys of the HTTP request headers are normalized, and the first letter of the keys is capitalized. For more details, see Why are the first letters of the header keys capitalized?.	{"Header1": "value1", "Header2": "value1,value2"}
queryParameters	The request query parameters. For example, if the request URL is `https://{url-id}.{region}.fcapp.run/example?key1=value1`, the queryStringParameters value is a JSON object with key key1 and value value1. If a key has multiple values, separate the values with commas, such as `{"key1": "value1", "key2": "value2,value3"}`.	{ "parameter1": "value1", "parameter2": "value1,value2" }
requestContext	An object that contains additional information about the request, such as requestId, the time of the request, and the identity of the authorized caller.
requestContext.accountId	The ID of the Alibaba Cloud account who owns the function.	123456*********
requestContext.domainName	The domain name of the function HTTP trigger.	<http-trigger-id>.<region-id>.fcapp.run
requestContext.domainPrefix	The domain prefix of the function HTTP trigger.	<http-trigger-id>
requestContext.http	An object that contains details about an HTTP request.
requestContext.http.method	The HTTP method used in the request. Valid values: GET, POST, PUT, HEAD, OPTIONS, PATCH, and DELETE.	GET
requestContext.http.path	The request path. For example, if the request URL is `https://{url-id}.{region}.fcapp.run/example?name=Jane`, the path value is `/example`.	/example
requestContext.http.protocol	The protocol of the request.	HTTP/1.1
requestContext.http.sourceIp	The source IP address of the immediate TCP connection that initiates the request. This IP address is the peer IP address (RemoteAddr) that directly establishes the connection, specifically, the address of the client that directly connects to the server, or the IP address of the last proxy. If the request is not forwarded by any proxy, RemoteAddr is the client IP address. If the request is forwarded by one or more proxies, RemoteAddr is the IP address of the last proxy. Note You can obtain the original IP address of the client through the X-Forwarded-For HTTP request header. For more information, see How to obtain the original IP address of the client when using an HTTP trigger to invoke a built-in runtime function?.	11.11.XX.XX
requestContext.http.userAgent	The value of the user-agent request header.	PostmanRuntime/7.32.3
requestContext.requestId	The request ID. You can use this ID to track invocation logs related to the function.	1-64f6cd87-*************
requestContext.time	The timestamp of the request.	2023-09-05T06:41:11Z
requestContext.timeEpoch	The timestamp of the request, in Unix time.	1693896071895

Function Compute HTTP request mapping logic

Function Compute converts the HTTP request into an Event object and forwards it to the handler (Handler). The conversion logic is as follows:

The HTTP request headers are mapped to headers in the event struct.
The HTTP request parameters are mapped to queryParameters.
The context information of the HTTP request is mapped to requestContext.
The request body of a POST request is mapped to body.

Base64 encoding mechanism

Function Compute decides whether to Base64-encode the request body by examining the Content-Type in the request headers during the conversion of an HTTP request into the event object event.

If the Content-Type indicates a text type, the request body is not Base64 encoded, and isBase64Encoded in the event struct is set to false.
Otherwise, the request body is Base64 encoded, and isBase64Encoded is set to true.

The following are the values of Content-Type that indicate text types:

text/*
application/json
application/ld+json
application/xhtml+xml
application/xml
application/atom+xml
application/javascript

Request mapping examples

GET requests

HTTP request

Event struct

GET /?parameter1=value1&parameter2=value2 HTTP/1.1

{
  "version": "v1",
  "rawPath": "/",
  "headers": {
    "Accept": "*/*",
    "User-Agent": "CurlHttpClient"
  },
  "queryParameters": {
    "parameter1": "value1",
    "parameter2": "value2"
  },
  "body": "",
  "isBase64Encoded": true,
  "requestContext": {
    "accountId": "1327************",
    "domainName": "example.cn-hangzhou.fcapp.run",
    "domainPrefix": "example",
    "requestId": "1-67aee50c-********-************",
    "time": "2025-02-14T06:39:08Z",
    "timeEpoch": "1739515148145",
    "http": {
      "method": "GET",
      "path": "/",
      "protocol": "HTTP/1.1",
      "sourceIp": "40.XX.XX.XX",
      "userAgent": "CurlHttpClient"
    }
  }
}

Note

You can use the following command on the command line to send the HTTP request above. Replace https://example.cn-hangzhou.fcapp.run with your HTTP trigger public access address.

curl -v "https://example.cn-hangzhou.fcapp.run?parameter1=value1&parameter2=value2"

POST requests

HTTP request

Event struct

POST / HTTP/1.1
Content-Type: application/json

{
  "version": "v1",
  "rawPath": "/",
  "headers": {
    "Accept": "*/*",
    "Content-Length": "20",
    "Content-Type": "application/json",
    "User-Agent": "curl/8.7.1"
  },
  "queryParameters": {},
  "body": "{\"message\": \"Hello\"}",
  "isBase64Encoded": false,
  "requestContext": {
    "accountId": "1327************",
    "domainName": "example.cn-hangzhou.fcapp.run",
    "domainPrefix": "example",
    "requestId": "1-67aee50c-********-************",
    "time": "2025-02-14T06:39:08Z",
    "timeEpoch": "1739515148145",
    "http": {
      "method": "POST",
      "path": "/",
      "protocol": "HTTP/1.1",
      "sourceIp": "40.XX.XX.XX",
      "userAgent": "CurlHttpClient"
    }
  }
}

Note

You can use the following command on the command line to send the HTTP request above. Replace https://example.cn-hangzhou.fcapp.run with your HTTP trigger public access address.
```
curl -v -H "Content-Type: application/json"  -d '{"message": "Hello"}' "https://example.cn-hangzhou.fcapp.run"
```
If you need to send a Base64-encoded request body, set the Content-Type in the request headers to application/x-www-form-urlencoded.

Response struct

Response struct format

The format of the function's response struct is outlined below. When your request handler issues a response struct, Function Compute processes this response and transforms it into an HTTP response.

{
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json",
        "Custom-Header-1": "Custom Value"
    },
    "isBase64Encoded": false,
    "body": "{\"message\":\"Hello FC!\"}"
}

Function Compute response parsing logic

Function Compute analyzes the response and constructs an HTTP response for the client.

When your function returns valid JSON that includes the statusCode field, Function Compute interprets the logic as follows:
- statusCode: The value of statusCode in the JSON returned by the function.
- Content-Type: The value of Content-Type in the JSON returned by the function. If Content-Type is not present in the JSON, the Content-Type defaults to application/json.
- body: The function response, which is the value of body in the JSON returned by the function.
- isBase64Encoded: The value of isBase64Encoded in the JSON returned by the function. If isBase64Encoded is not present in the JSON, it defaults to false.
If your function returns valid JSON without the statusCode field, or the return is not valid JSON, Function Compute will make certain assumptions to construct the response struct.
- statusCode: Defaults to 200.
- Content-Type: Defaults to application/json.
- body: The function response, which is the data returned in the code.
- isBase64Encoded: Defaults to false.

Function Compute converts the function's response struct into an HTTP response for the client. The conversion process is outlined as follows:

statusCode is mapped to the status code of the HTTP response.
headers is mapped to the HTTP response headers.
body is mapped to the HTTP response body. If isBase64Encoded is present and true, the body is first Base64 decoded before being mapped to the HTTP response body.

Response mapping examples

This section provides examples of mapping function outputs to function response structs and HTTP responses. When a client invokes the function HTTP trigger, the HTTP response is returned.

Output of string responses

Function output

Parse function output

HTTP response (content seen by the client)

Hello World!

{
  "statusCode": 200,
  "body": "Hello World!",
  "headers": {
    "content-type": "application/json"
  },
  "isBase64Encoded": false
}

HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Length: 12
Content-Type: application/json
X-Fc-Request-Id: 1-64f6d6e7-e01edb1cce58240ed59b59d9
Date: Tue, 05 Sep 2023 07:21:11 GMT

Hello World!

JSON outputs

Function output

Parse function output

HTTP response (content seen by the client)

{"message": "Hello World!"}

{
  "statusCode": 200,
  "body": "{\"message\": \"Hello World!\"}",
  "headers": {
    "content-type": "application/json"
  },
  "isBase64Encoded": false
}

HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Length: 27
Content-Type: application/json
X-Fc-Request-Id: 1-64f6d867-7302fc1ac6338b6fd2adb782
Date: Tue, 05 Sep 2023 07:27:35 GMT

{"message": "Hello World!"}

Custom response output

Function output

Parse function output

HTTP response (content seen by the client)

{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": {
        "message": "Hello, world!"
    },
    "isBase64Encoded": false
}

{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": {
        "message": "Hello, world!"
    },
    "isBase64Encoded": false
}

HTTP/1.1 201 OK
Content-Disposition: attachment
Content-Length: 27
Content-Type: application/json
Custom-Header-1: Custom Value
X-Fc-Request-Id: 1-64f6dcb3-e787580749d3ba13b047ce14
Date: Tue, 05 Sep 2023 07:45:55 GMT

{"message": "Hello world!"}

Base64 decoding mechanism

If the function output is valid JSON and the isBase64Encoded field is set to true, Function Compute will decode the body field using Base64 and deliver the decoded data as the HTTP response body to the client.

If the body field cannot be decoded, Function Compute will not generate an error message; instead, it returns the original body value to the client.

Response headers (HTTP response header)

When you invoke a function using an HTTP trigger, the response headers will include the default X-Fc-Request-Id header, which Function Compute adds as a unique identifier for the request. Other than X-Fc-Request-Id, Function Compute does not automatically add any other response headers.

You can include custom response headers in your code; however, headers that begin with X-Fc- and certain reserved response headers from Function Compute are not supported.

connection
content-length
date
keep-alive
server
content-disposition

Should you assign any reserved words to the response headers, Function Compute will automatically disregard the headers you have specified.

Error handling

When a function error occurs, the API call returns specific error messages, and the HTTP return code is 200. For example, the response to the ModuleNotFound error in Python is as follows:

{
    "errorMessage": "Unable to import module 'index'",
    "errorType": "ImportModuleError",
    "stackTrace": [
        "ModuleNotFoundError: No module named 'not_exist_module'"
    ]
}

However, when using an HTTP trigger, Function Compute conceals these error messages and simply returns an Internal Server Error message, accompanied by an HTTP status code of 502. Below is a sample code snippet demonstrating an HTTP response:

HTTP/1.1 502 Bad Gateway
Content-Disposition: attachment
Content-Type: application/json
X-Fc-Request-Id: 1-64f6df91-fe144d52e4fd27afe3d8dd6f
Date: Tue, 05 Sep 2023 07:58:09 GMT
Content-Length: 21

Internal Server Error

At this point, you can look up the specific error message in the logs using the X-Fc-Request-Id returned by the request.

Code development

When writing code using the FC 3.0 built-in runtime, consult the following documents for guidance on the runtime request handler (Handler).