Use an HTTP trigger to invoke a function
An HTTP trigger gives your function an HTTP(S) endpoint — called a function URL — so clients can invoke the function directly with an HTTP request. This topic covers how HTTP triggers work in built-in runtimes. For custom runtimes, see Web functions.
In Function Compute (FC) 3.0, HTTP trigger behavior for custom runtimes and Custom Container runtimes is identical to FC 2.0. However, HTTP trigger behavior for built-in runtimes differs significantly from FC 2.0, as described below.
Background information
The following topics describe HTTP triggers:
How it works
When a client calls a function URL in a built-in runtime, Function Compute maps the HTTP request to an event object (event) and passes it to your function handler. After the function completes, Function Compute maps the return value to an HTTP response and sends it back to the client.
Request struct
Request struct format
{
"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 fields:
|
Field |
Description |
Example |
|
|
Payload format version. Currently |
|
|
|
URL-encoded request path. For a request to |
|
|
|
Request body. Function Compute Base64-encodes binary data during mapping. |
|
|
|
Whether the request body is Base64-encoded. Valid values: |
|
|
|
Request headers as key-value pairs. Multiple values for the same key are comma-separated. When you use an HTTP trigger to invoke a function in a built-in runtime, Function Compute 3.0 converts the HTTP request into the event format of the HTTP trigger and normalizes header keys by converting the first letter of each key to uppercase. For details, see Why does the first letter of the header key become uppercase when I use an HTTP trigger to invoke a function? |
|
|
|
Query parameters as key-value pairs. Multiple values for the same key are comma-separated. For a request to |
|
|
|
Additional request metadata, including request ID, timestamp, and caller identity. |
— |
|
|
ID of the Alibaba Cloud account that owns the function. |
|
|
|
Domain name of the HTTP trigger. |
|
|
|
Domain prefix of the HTTP trigger. |
|
|
|
Detailed information about the HTTP request. |
— |
|
|
HTTP method. Valid values: |
|
|
|
Decoded request path. |
|
|
|
Request protocol. |
|
|
|
Peer IP address ( |
|
|
|
Value of the |
|
|
|
Request ID. Use this ID to trace invocation logs for the function. |
|
|
|
Request timestamp. |
|
|
|
Request timestamp in Unix time. |
|
Request mapping logic
Function Compute maps incoming HTTP requests to event objects as follows:
-
HTTP request headers →
event.headers -
Query parameters →
event.queryParameters -
Request context information →
event.requestContext -
POST request body →
event.body
Base64 encoding
Function Compute checks the Content-Type header to decide whether to Base64-encode the request body:
-
No encoding (
isBase64Encoded: false):Content-Typeindicates a text format. -
Base64 encoding (
isBase64Encoded: true):Content-Typeindicates a binary or non-text format.
The following Content-Type values are treated as text (no encoding):
-
text/* -
application/json -
application/ld+json -
application/xhtml+xml -
application/xml -
application/atom+xml -
application/javascript
All other Content-Type values result in Base64 encoding.
Request mapping examples
GET request
|
HTTP request |
Event object |
|
|
|
The preceding GET request has no Content-Type header, so isBase64Encoded is true. To send the GET request above, run the following command, replacing https://example.cn-hangzhou.fcapp.run with your function URL:
curl -v "https://example.cn-hangzhou.fcapp.run?parameter1=value1¶meter2=value2"POST request
Because Content-Type: application/json is a text format, isBase64Encoded is false. To send the POST request above, run the following command, replacing https://example.cn-hangzhou.fcapp.run with your function URL:
curl -v -H "Content-Type: application/json" -d '{"message": "Hello"}' "https://example.cn-hangzhou.fcapp.run"To force Base64 encoding, set Content-Type to application/x-www-form-urlencoded.
|
HTTP request |
Event object |
|
|
|
Response struct
Response struct format
Your function returns a response struct, which Function Compute parses and maps 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
Function Compute maps your function's return value to an HTTP response based on the following rules.
If the function returns valid JSON with a statusCode field:
|
JSON field |
HTTP response |
|
|
HTTP status code |
|
|
|
|
|
Response body |
|
|
Whether |
If the function returns valid JSON without a statusCode, or non-JSON output:
Function Compute constructs the HTTP response with these defaults:
|
Field |
Default value |
|
|
|
|
|
|
|
|
Function output |
|
|
|
Response mapping examples
The following table shows how function output is parsed into a response struct and mapped to the HTTP response the client receives.
|
Function output |
Parsed response struct |
HTTP response (client receives) |
|
|
|
|
|
|
|
|
|
|
|
Base64 decodingIf the function returns valid JSON with HTTP response headersFunction Compute automatically adds the Custom response headers are supported with the following restrictions:
Error handlingError behavior differs depending on how the function is invoked:
Use the ReferencesThe following handler topics are relevant if you're writing code for a built-in runtime in Function Compute 3.0: |