Skip to main content

HTTP Access to Cloud Functions

By configuring the HTTP Access Service, you can make cloud functions respond to HTTP requests like regular Web APIs. When accessing cloud functions through the HTTP access service, both custom cloud functions and HTTP cloud functions are supported.

Custom Cloud Functions​

Developers can invoke custom cloud functions via HTTP and convert the cloud function's return value into an HTTP response body. In CloudBase, the input and output parameters of custom cloud functions are generally required to be JSON objects, requiring certain mapping rules to correspond to HTTP requests and responses.

How It Works​

When you access a cloud function through an HTTP request:

  1. Request Conversion: The HTTP request is automatically converted into a specific JSON format and passed to the cloud function
  2. Response Conversion: The cloud function's return value is converted into a standard HTTP response and returned to the client

CORS Configuration​

The HTTP access service natively supports cross-origin requests. Simply add your domain to CloudBase Platform / Environment Settings / Security Domains, and web pages under that domain will be able to access your cloud functions normally.

How Cloud Functions Receive HTTP Requests​

Request Parameter Format​

When you send an HTTP request to a cloud function, the cloud function receives an object containing all request information, which we call an integrated request:

{
    path: 'HTTP request path, e.g., /hello',
    httpMethod: 'HTTP request method, e.g., GET, POST',
    headers: {
        // HTTP request headers
    },
    queryStringParameters: {
        // URL query parameters, e.g., ?name=value
    },
    requestContext: {
        // CloudBase environment related information
    },
    body: 'HTTP request body content',
    isBase64Encoded: 'true/false, indicates whether body is Base64 encoded'
}

Real-world Example​

Suppose you send a GET request to https://env-id.service.tcloudbase.com/, the cloud function will receive these parameters:

{
    path: '/',
    httpMethod: 'GET',
    headers: {
        'host': 'env-id.service.tcloudbase.com',
        'connection': 'close',
        'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36',
        'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9',
        'accept-encoding': 'gzip, deflate, br',
        'accept-language': 'zh-CN,zh;q=0.9,en;q=0.8'
    },
    requestContext: {
        requestId: 'cdbb96328072184d19d3fcd243e8cc4d',
        envId: 'env-id',
        appId: 123456789,
        uin: 123456789
    },
    isBase64Encoded: false,
    body: ''
}

How Cloud Functions Return HTTP Responses​

Cloud functions have multiple ways to return data, and the system will automatically convert these return values into standard HTTP responses.

Method 1: Directly Return Simple Data​

Return String or Number​

The simplest way is to directly return a string:

exports.main = async function() {
    return "hello gateway";
};

The client will receive this HTTP response:

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8

hello gateway
Return JSON Object​

When returning an object, it will be automatically converted to JSON format:

exports.main = async function() {
    return {
        foo: "bar",
        message: "success"
    };
};

The client will receive:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

{"foo":"bar","message":"success"}

Method 2: Return Integrated Response (Advanced Usage)​

If you need precise control over the HTTP response status code, response headers, etc., you can return a specially formatted integrated response:

{
    "isBase64Encoded": true|false,  // Whether body is Base64 encoded
    "statusCode": 200,              // HTTP status code
    "headers": {                    // Custom response headers
        "headerName": "headerValue"
    },
    "body": "Response content"      // Response body
}
Example 1: Return HTML Page​
exports.main = async function() {
    return {
        statusCode: 200,
        headers: {
            "content-type": "text/html",
        },
        body: "<h1>Welcome to My Website</h1><p>This is an HTML page returned via cloud function</p>",
    };
};

The browser will directly display this HTML page.

Example 2: Return JavaScript File​
exports.main = async function() {
    return {
        statusCode: 200,
        headers: {
            "content-type": "application/javascript",
        },
        body: 'console.log("Hello from cloud function!");',
    };
};
Example 3: Return Binary Files Like Images​

For binary files such as images, audio, and video, the content needs to be converted to Base64 encoding:

exports.main = async function() {
    return {
        isBase64Encoded: true,
        statusCode: 200,
        headers: {
            "content-type": "image/png",
        },
        body: "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAY...", // Base64 encoded image data
    };
};

The client will receive a complete PNG image.

Example 4: Implement Page Redirect​

You can also return a 302 status code to implement page redirection:

exports.main = async function(event) {
    const { path } = event;
    return {
        statusCode: 302,
        headers: {
            location: `https://tcb.cloud.tencent.com${path}`,
        },
    };
};

When users access your cloud function, they will be automatically redirected to the corresponding page on the Tencent CloudBase official website.

HTTP Cloud Functions​

Since HTTP cloud functions natively support receiving HTTP requests, the HTTP access service will forward requests directly to HTTP cloud functions for processing.

In HTTP cloud functions, the service can process and respond to requests directly after listening to and receiving HTTP requests, without requiring integrated response handling like custom cloud functions.