Skip to main content

Accessing Cloud Functions Using HTTP

Developers can invoke cloud functions via HTTP and transform the return value of the cloud function into the HTTP response body. In cloud development, the input and output parameters of cloud functions are generally required to be JSON objects, requiring certain mapping rules to map to HTTP requests and responses.

Cross-Domain Handling​

The HTTP access service natively supports cross-origin requests. Add the domain to the Web Security Domain, and webpages under this domain can then access the HTTP service cross-origin.

Cloud Function Input Parameters​

When using HTTP to invoke cloud functions, the HTTP request is transformed into a special structure called integrated request, with the following structure:

{
    path: 'HTTP request path, e.g. /hello'
    httpMethod: 'HTTP request method, such as GET'
    headers: {HTTP request headers},
    queryStringParameters: {HTTP request Query string parameters, in key-value pairs},
    requestContext: {CloudBase related information},
    body: 'HTTP request body',
    isBase64Encoded: 'true or false, indicating whether the body is Base64-encoded'
}

Below is an example:

{
    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: ''
}

Cloud Function Return Value​

Cloud functions can return data of types such as string, object, number, or return an integrated response, which will then be transformed into a normal HTTP response.

Returning Strings or Numbers​

If the cloud function returns a string,

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

The final HTTP response is:

HTTP/1.1 200 OK
date: Mon, 16 Dec 2019 08:35:31 GMT
content-type: text/plain; charset=utf-8
content-length: 13

hello gateway

Returning Object​

The returned Object will be converted to JSON, and the content-type of the HTTP response will be set to application/json):

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

The final HTTP response is:

HTTP/1.1 200 OK
date: Mon, 16 Dec 2019 08:35:31 GMT
content-type: application/json; charset=utf-8
content-length: 13

{"foo":"bar"}

Returning Integrated Response​

Cloud functions can return an integrated response with the following special structure to freely control the response body:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "body": "..."
}

Returning HTML Using Integrated Response​

Set the content-type to text/html to return HTML in the body, which will be automatically parsed by the browser:

exports.main = async function () {
  return {
    statusCode: 200,
    headers: {
      "content-type": "text/html",
    },
    body: "<h1>Hello</h1>",
  };
};

The final HTTP response is:

HTTP/1.1 200 OK
date: Mon, 16 Dec 2019 08:35:31 GMT
content-type: text/html; charset=utf-8
content-length: 14

<h1>Hello</h1>

Returning JS Files Using Integrated Response​

Set the content-type to application/javascript to return JavaScript files in the body:

exports.main = async function () {
  return {
    statusCode: 200,
    headers: {
      "content-type": "application/javascript",
    },
    body: 'console.log("Hello!")',
  };
};

The final HTTP response is:

HTTP/1.1 200 OK
date: Mon, 16 Dec 2019 08:35:31 GMT
content-type: application/javascript; charset=utf-8
content-length: 21

console.log("Hello!")

Returning Binary Files Using Integrated Response​

If the response body is a binary file such as images, audio, or video, you can set isBase64Encoded to true and convert the binary file content into a Base64-encoded string, for example:

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

The final HTTP response is a PNG image:

HTTP/1.1 200 OK
date: Mon, 16 Dec 2019 08:35:31 GMT
content-type: image/png
content-length: 9897

<binary payload...>

Using Integrated Response for 302 Redirect​

Assuming a 302 redirect proxy for all paths under a specific URL path

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