通过 HTTP 访问云函数

通过 HTTP 网关，您可以将云函数配置为标准的 HTTP 接口，无需 SDK 即可通过 HTTP 请求调用云函数。本文档介绍如何配置云函数的 HTTP 访问以及如何处理请求和响应。

自定义域名

如果您需要为云函数绑定自定义域名（生产环境推荐），完整的自定义域名流程（添加域名、配置 SSL 证书、CDN 选择、域名所有权校验、DNS 解析等）请参考自定义域名配置。所有通过任意入口添加的域名，都可以在 HTTP 网关中统一查看和管理。

前置条件

已创建云开发环境
已部署至少一个云函数

配置 HTTP 访问

在 HTTP 网关中统一配置域名、访问路径与关联资源。

前往 HTTP 网关
进入 路由管理，点击「新建」按钮
配置以下信息：

配置项	说明	示例
域名	选择默认域名、自定义域名或 `*`（匹配所有域名）	默认域名
触发路径	设置 HTTP 访问路径，支持 `/` 或自定义路径	`/api/hello`
关联资源类型	选择「云函数」	云函数
具体云函数实例	选择目标云函数	`hello-world`
版本	路由调用的函数版本，详见下方「绑定指定版本」	`$DEFAULT`

💡 提示：生产环境建议绑定已备案的自定义域名，以获得完整的服务能力。配置方法请参考自定义域名配置。

绑定指定版本

「版本」下拉用于指定该路由调用的函数版本：

版本选项	说明
`$DEFAULT`（跟随版本流量配置）	默认选中。不关联具体版本，按云函数的版本流量配比分配请求，与现网行为一致
`$LATEST`（最新版本）	始终使用最新版本代码，发布新版本后自动生效，不受流量配比影响
版本 N（具体已发布版本）	路由固定使用该版本快照，之后更新函数代码不影响此路由

两个预置项固定置顶，其后按版本号倒序排列已发布版本，并标注发布日期。

测试访问

配置完成后，访问 域名 + 触发路径 即可调用云函数：

# 示例：访问默认域名的云函数
curl https://your-env-id.<your-env-region>.app.tcloudbase.com/api/hello

发起 HTTP 请求

配置完成后，可以使用任何 HTTP 客户端访问云函数。

curl
JavaScript
Python

# GET 请求
curl https://your-domain/your-function-path

# POST 请求
curl -X POST https://your-domain/your-function-path \
  -H "Content-Type: application/json" \
  -d '{"name": "CloudBase", "version": "1.0"}'

// 使用 fetch API
const response = await fetch('https://your-domain/your-function-path', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'CloudBase', version: '1.0' })
});

const data = await response.json();
console.log(data);

import requests

# POST 请求
response = requests.post(
    'https://your-domain/your-function-path',
    json={'name': 'CloudBase', 'version': '1.0'}
)

data = response.json()
print(data)

在云函数中处理 HTTP 请求

接收请求信息

当通过 HTTP 访问云函数时，函数的 event 参数会包含完整的 HTTP 请求信息：

exports.main = async (event, context) => {
  // event 对象结构
  const {
    path,                      // HTTP 请求路径，如 /api/hello
    httpMethod,                // HTTP 请求方法，如 GET、POST、PUT、DELETE
    headers,                   // HTTP 请求头对象
    queryStringParameters,     // URL 查询参数对象，如 ?name=value
    body,                      // HTTP 请求体内容（字符串格式）
    isBase64Encoded,          // body 是否为 Base64 编码
    requestContext            // 云开发环境相关信息
  } = event;
  
  // 返回响应
  return { message: 'success' };
};

示例：处理不同类型的请求

GET 请求
POST 请求
RESTful API

exports.main = async (event) => {
  const { queryStringParameters } = event;
  
  // 获取查询参数
  const name = queryStringParameters?.name || 'Guest';
  
  return {
    statusCode: 200,
    body: JSON.stringify({
      message: `Hello, ${name}!`,
      timestamp: Date.now()
    })
  };
};

访问示例：

curl "https://your-domain/greet?name=CloudBase"
# 响应: {"message":"Hello, CloudBase!","timestamp":1699999999999}

exports.main = async (event) => {
  const { body } = event;
  
  // 解析 JSON 请求体
  const data = JSON.parse(body);
  
  return {
    statusCode: 200,
    body: JSON.stringify({
      received: data,
      processed: true
    })
  };
};

访问示例：

curl -X POST https://your-domain/process \
  -H "Content-Type: application/json" \
  -d '{"userId": 123, "action": "update"}'

exports.main = async (event) => {
  const { httpMethod, path, queryStringParameters, body } = event;
  
  // 路由处理
  if (path === '/users' && httpMethod === 'GET') {
    // 获取用户列表
    return {
      statusCode: 200,
      body: JSON.stringify([{ id: 1, name: 'User1' }])
    };
  }
  
  if (path.startsWith('/users/') && httpMethod === 'GET') {
    // 获取单个用户
    const userId = path.split('/')[2];
    return {
      statusCode: 200,
      body: JSON.stringify({ id: userId, name: 'User' })
    };
  }
  
  // 404
  return {
    statusCode: 404,
    body: JSON.stringify({ error: 'Not Found' })
  };
};

前置条件​

配置 HTTP 访问​

绑定指定版本​

测试访问​

发起 HTTP 请求​

在云函数中处理 HTTP 请求​

接收请求信息​

示例：处理不同类型的请求​

相关文档​