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

An HTTP trigger provides an HTTP(S) endpoint for a function, referred to as a function URL, allowing you to invoke the function directly via an HTTP request. This topic describes how to use an HTTP trigger to invoke a function in a built-in runtime of Function Compute. For information on using the trigger in a custom runtime, see Web functions.

Considerations

In Function Compute 3.0, the mechanism for HTTP triggers invoking functions that run in custom runtimes or Custom Container runtimes remains the same as in Function Compute 2.0. However, there are notable differences in how HTTP triggers invoke functions that run in built-in runtimes. For more information, see the following section.

Invocation process

In a built-in runtime, when a client calls a function URL, Function Compute maps the request to an event object (event) and then passes the event object to the function. After the function execution is complete, Function Compute maps the result to an HTTP response and sends it back to the client.

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 currently supported version is v1.	v1
rawPath	The request path. For example, if the request URL is `https://{url-id}.{region}.fcapp.run/example`, the value of this parameter is `/example`. Note that this value is URL-encoded. Refer to `requestContext.http.path` for the decoded path.	/example
body	The request body. During the mapping process, Function Compute performs Base64-encoding of binary data.	Hello FC!
isBase64Encoded	Specifies whether the request body is Base64-encoded. Valid values: true and false.	false
headers	The list of request headers, displayed in key-value pairs. If a key has multiple values, those values are separated by commas (,). The mapping process in which Function Compute 3.0 transforms the HTTP request into an event object results in the first letter of each request header key being converted to uppercase, a change known as the normalization process. For more information, see Why does the first letter of the header key become uppercase when I use an HTTP trigger to invoke a function?	{"Header1": "value1", "Header2": "value1,value2"}
queryParameters	The request's query parameters. For example, if the request URL is `https://{url-id}.{region}.fcapp.run/example?key1=value1`, the value of this parameter is a JSON object with a key of key1 and a value of value1. If a key has multiple values, those values are separated by commas (,), for example, `{"key1": "value1", "key2": "value2,value3"}`.	{ "parameter1": "value1", "parameter2": "value1,value2" }
requestContext	An object that contains additional information about the request, such as the requestId, the time when the request was made, and the identity of the authorized caller.
requestContext.accountId	The ID of the Alibaba Cloud account that owns the function.	123456*********
requestContext.domainName	The domain name of the HTTP trigger.	<http-trigger-id>.<region-id>.fcapp.run
requestContext.domainPrefix	The domain prefix of the HTTP trigger.	<http-trigger-id>
requestContext.http	An object that contains detailed information about the 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 value of this parameter 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 makes the request. This IP address refers to the peer IP address (RemoteAddr) that directly establishes the connection, specifically the address of the client connecting directly to the server or the address of the last proxy that the client uses. If the request is not forwarded by a proxy, RemoteAddr is the client's IP address. If the request is forwarded by one or more proxies, RemoteAddr is the IP address of the last proxy. Note The X-Forwarded-For header contains the original IP address of the client when the request is made through one or more proxies. For more information, see How do I obtain the original IP address of a client when an HTTP trigger invokes a function that uses a built-in runtime?	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 trace 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

Request mapping logic

Function Compute maps the incoming HTTP request into an event object before passing the event object to the handler of your function. The mapping logic is as follows:

The headers of the HTTP request map to event headers.
The query parameters of the HTTP request map to queryParameters.
Contextual information about the HTTP request maps to requestContext.
The request body of a POST request maps to body.

Base64 encoding mechanism

When Function Compute maps an HTTP request to an event object (event), it checks the value of Content-Type in the request header to determine whether Base64 encoding should be performed.

If the value of Content-Type indicates a textual representation, Function Compute does not perform Base64 encoding, and the isBase64Encoded parameter in event is set to false.
Otherwise, the request body is converted into a text format using Base64 encoding, and the isBase64Encoded parameter is set to true.

The following Content-Type values indicate a textual representation:

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

Request mapping examples

GET

HTTP request

Event object

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 enter the following command in the CLI to send the HTTP request mentioned above. Replace https://example.cn-hangzhou.fcapp.run with the actual URL of your function.

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

POST

HTTP request

Event object

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 enter the following command in the CLI to send the HTTP request mentioned above. Replace https://example.cn-hangzhou.fcapp.run with the actual URL of your function.
```
curl -v -H "Content-Type: application/json"  -d '{"message": "Hello"}' "https://example.cn-hangzhou.fcapp.run"
```
If you want to encode your request into Base64 format, simply set Content-Type in the request header to application/x-www-form-urlencoded.

Response struct

Response struct format

The response struct format is as follows. Function Compute parses the output of your function, transforms it into a response struct, and maps this struct to an HTTP response.

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

Response mapping logic

After parsing the function output, Function Compute maps the response struct to an HTTP response.

If your function returns valid JSON with a statusCode, the mapping process is governed by the following rules:
- The statusCode in the JSON maps to the statusCode in the HTTP response.
- The Content-Type in the JSON maps to the Content-Type in the HTTP response. If the JSON does not contain a Content-Type parameter, default value application/json is used.
- The body in the JSON, which is the function output, maps to the HTTP response body.
- The isBase64Encoded parameter in the JSON maps to the isBase64Encoded parameter in the HTTP response. If the JSON does not contain an isBase64Encoded parameter, default value "false" is used.
If your function returns valid JSON without a statusCode, or if it returns data in a format other than JSON, Function Compute makes the following assumptions to construct the HTTP response:
- statusCode is 200.
- Content-Type is application/json.
- body is the function output.
- isBase64Encoded is false.

To conclude, Function Compute converts the data returned by your function into an HTTP response and sends it back to the client.

statusCode maps to the status code of the HTTP response.
headers map to the HTTP response headers.
body maps to the HTTP response body. If the isBase64Encoded parameter exists and its value is true, then the body data will be decoded into binary form before being mapped to the HTTP response body.

Response mapping examples

This section shows how your function output is parsed into a response struct and how that struct maps to the HTTP response on the client. When a client invokes your function through its HTTP(S) endpoint, it receives the HTTP response.

Output for a string response

Function output

Parsed function output

HTTP response (to 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!

Output for a JSON response

Function output

Parsed function output

HTTP response (to 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!"}

Output for a custom response

Function output

Parsed function output

HTTP response (to 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 your function returns valid JSON with an isBase64Encoded parameter whose value is true, Function Compute performs Base64 decoding on the JSON body and then maps the decoded data to the HTTP response body.

If the JSON body fails to be decoded, Function Compute does not report an error. Instead, it directly returns the value of the JSON body to the client.

HTTP response headers

In a function URL invocation, the response header X-Fc-Request-Id, which is automatically added by Function Compute, uniquely identifies the request that triggered the function invocation. Function Compute does not automatically add any other response headers.

You can return custom headers from your functions. Note that custom headers that start with X-Fc- are not supported. Additionally, the following response headers cannot be used as custom headers because they are reserved by Function Compute.

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

If any of these reserved headers is used as a custom header, Function Compute will simply ignore it.

Error handling

When a function invoked via an API encounters an error, the error message is returned as part of the response, and an HTTP 200 status code is returned. For example, the following sample code shows the response to a ModuleNotFound error in Python:

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

However, in the case of function URL invocations, Function Compute hides the error message and only returns Internal Server Error. The HTTP status code is 502. The following sample code shows an example:

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

You can use the X-Fc-Request-Id response header to efficiently pinpoint relevant logs and identify error messages associated with a request.

References

If you are writing code in a built-in runtime of Function Compute 3.0, you may find the following topics on handlers useful.