HTTP 访问云函数

通过配置 HTTP 访问服务，你可以让云函数像普通的 Web API 一样响应 HTTP 请求。在通过 HTTP 访问服务对接云函数时，可以支持对接普通云函数和 HTTP 云函数。

普通云函数

开发者可以通过 HTTP 调用普通云函数，并且将云函数的返回值变为 HTTP 响应体。云开发中普通云函数的入出参一般都要求是 JSON 对象，需要一定的映射规则对应到 HTTP 的请求和响应中。

工作原理

当你通过 HTTP 请求访问云函数时：

1. 请求转换：HTTP 请求会被自动转换成特定的 JSON 格式传给云函数
2. 响应转换：云函数的返回值会被转换成标准的 HTTP 响应返回给客户端

跨域配置

HTTP 访问服务天然支持跨域请求。只需要将你的域名添加到 云开发平台/环境配置/安全域名 中，该域名下的网页就可以正常访问你的云函数了。

云函数如何接收 HTTP 请求

请求参数格式

当你发送 HTTP 请求到云函数时，云函数会收到一个包含所有请求信息的对象，我们称之为集成请求：

{
    path: 'HTTP请求路径，如 /hello',
    httpMethod: 'HTTP请求方法，如 GET、POST',
    headers: {
        // HTTP请求头信息
    },
    queryStringParameters: {
        // URL查询参数，如 ?name=value
    },
    requestContext: {
        // 云开发环境相关信息
    },
    body: 'HTTP请求体内容',
    isBase64Encoded: 'true/false，表示body是否为Base64编码'
}

实际示例

假设你发送了一个 GET 请求到 https://env-id.service.tcloudbase.com/，云函数会收到这样的参数：

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

云函数如何返回 HTTP 响应

云函数有多种方式返回数据，系统会自动将这些返回值转换成标准的 HTTP 响应。

方式一：直接返回简单数据

返回字符串或数字

最简单的方式，直接返回字符串：

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

客户端会收到这样的 HTTP 响应：

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

hello gateway

返回 JSON 对象

返回对象时，会自动转换为 JSON 格式：

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

客户端会收到：

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

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

方式二：返回集成响应（高级用法）

如果你需要精确控制 HTTP 响应的状态码、响应头等信息，可以返回特殊格式的集成响应：

{
    "isBase64Encoded": true|false,  // body是否为Base64编码
    "statusCode": 200,              // HTTP状态码
    "headers": {                    // 自定义响应头
        "headerName": "headerValue"
    },
    "body": "响应内容"               // 响应体
}

示例1：返回 HTML 页面

exports.main = async function() {
    return {
        statusCode: 200,
        headers: {
            "content-type": "text/html",
        },
        body: "<h1>欢迎访问我的网站</h1><p>这是通过云函数返回的HTML页面</p>",
    };
};

浏览器会直接显示这个 HTML 页面。

示例2：返回 JavaScript 文件

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

示例3：返回图片等二进制文件

对于图片、音视频等二进制文件，需要将内容转换为 Base64 编码：

exports.main = async function() {
    return {
        isBase64Encoded: true,
        statusCode: 200,
        headers: {
            "content-type": "image/png",
        },
        body: "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAY...", // Base64编码的图片数据
    };
};

客户端会收到一张完整的 PNG 图片。

示例4：实现页面重定向

你还可以返回 302 状态码来实现页面重定向：

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

当用户访问你的云函数时，会被自动重定向到腾讯云开发官网的对应页面。

HTTP 云函数

由于 HTTP 云函数天然支持接收 HTTP 请求，因此 HTTP 访问服务会将请求直接转发至 HTTP 云函数进行处理。

HTTP 云函数中，服务在监听并接收 HTTP 请求后，直接进行请求处理并响应即可，无需类似普通云函数的集成响应处理。