Thanks to visit codestin.com
Credit goes to docs.cloudbase.net

跳到主要内容

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 请求后，直接进行请求处理并响应即可，无需类似普通云函数的集成响应处理。