HTTP触发器开发参考

更新时间：2025-05-30

HTTP触发器实现了将某个函数关联到一个 URL 上（包含相应的 CRUD 操作），它可以接收 HTTP 请求，根据 HTTP 方法、URL，找到匹配的函数将 HTTP 相关信息传入并执行函数，获取执行结果，将函数执行结果包装为 HTTP 返回响应。创建HTTP触发器的核心步骤包括HTTP触发器配置和用户代码配置，以下将为您分别介绍。

HTTP触发器参数配置

URL路径规则

URL参数的配置支持以下几种格式：

简单URL，不包含参数，例如：/user。
带参数的URL，使用{param}指定路径参数，例如 /user/{id}/posts 中，{id} 即为匹配参数。当请求 /user/123/posts 时，会识别参数id: 123。
带贪婪匹配路径参数的URL，使用{param+}指定贪婪匹配路径参数，它会匹配当前位置直到 URL 结尾的所有剩余部分，一个URL配置示例，如 /path/{file+},如果请求的URL路径为/file/aaa/bbb/cccddd时，会在HTTP触发器Event事件中，其pathParameters参数中识别到file字段被设置为aaa/bbb/cccddd。

HTTP方法

HTTP 触发器支持DELETE、GET、HEAD、OPTIONS、PATCH、POST、PUT方式触发函数。HTTP触发器时可以选择多个，之后触发器会匹配相应的请求方法集合。

身份验证

可以选择不验证，或者IAM验证。选择不验证时，会在最终的触发器信息显示中显示 不验证。

二进制请求 body

默认情况下，HTTP 触发器会以纯文本的形式处理 HTTP 请求体，如果请求体内包含非纯文本内容（例如二进制文件上传），并需要在函数中进行处理，可以勾选此选项。勾选后，HTTP 触发器会使用 Base64 编码 HTTP 请求体。用户代码中 event 参数中，body 项会是 Base64 编码后的请求体内容，而 isBase64Encoded 会被设为 true。

用户代码中的配置

在用户代码中需要设置响应的handler来处理由HTTP触发器转发而来的请求，HTTP触发器可以将整个客户端HTTP请求映射到后端函数的需要的输入 event 参数。参数的说明如下。

event的格式

Plain Text

1Event:
2
3{
4	"resource": "配置的HTTP触发器的资源路径",  
5	"path": "HTTP请求的URL路径",  
6	"httpMethod": "本次http触发器请求使用的HTTP方法",  
7	"headers": {请求头},  
8	"queryStringParameters": {query string 参数},  
9	"pathParameters":  {代理路径参数}，  
10	"requestContext": {请求上下文},  
11	"body": "请求体",  
12	"isBase64Encoded": "请求体是否为Base64编码，这里固定为false，暂不支持二进制格式"  
13}

参数	说明	示例
resource	配置的HTTP触发器的资源路径	/test/{proxy+}
path	HTTP请求的URL路径	/test/aaa/bbb
httpMethod	HTTP请求的方法	GET
headers	该参数为HTTP请求的请求头的列表。以键值对的形式显示，当一个键存在多个值时，值之间使用逗号分隔。	{"header1":"aaa", "header2":"bbb}
queryParameters	HTTP请求的查询参数，例如，如果请求URL为https://{id}.cfc-execute.{region}.baidubce.com/example?key1=value1，则queryStringParameters是URL中?结束的键值对，其键为key1，值为value1。当一个键存在多个值时，值之间会使用逗号分隔。	{"key1": "value1", "key2": "value2,value3"}
queryParameters	HTTP请求的Path路径参数，例如，如果请求URL为https://{id}.cfc-execute.{region}.baidubce.com/test/{id}/get?key1=value1	{"id": "1"}
requestContext	请求上下文，一个包含有关请求的附加信息的对象，例如requestId、请求的时间以及通过授权的调用者身份。
requestContext.stage	请求上下文字段，表明平台名称，默认是cfc	cfc
requestContext.requestId	请求上下文字段，表明请求id，	"f6cb833e-f818-4b80-b30c-fff437e69886"
requestContext.resourcePath	请求上下文字段，表明HTTP触发器设置的资源路径	/test/{proxy+}
requestContext.httpMethod	请求上下文字段，表明HTTP请求方法	GET
requestContext.apiId	请求上下文字段，表明HTTP请求API ID	"12345"
body	HTTP请求体	"hello world"
isBase64Encoded	请求体是否为Base64编码，这里固定为false，暂不支持二进制格式	false

其中请求头包括一个自定义头来标识请求：

                JSON
                
                {
	"X-Bce-Request-Id": "6c2d4826-xxxx-4c2b-8039-9ca98ded6954"
}

函数计算HTTP请求映射逻辑

函数计算会将HTTP请求映射成event事件对象传给请求处理程序（Handler），映射逻辑如下：

HTTP请求头映射为event结构中的headers。
HTTP的请求参数映射为queryParameters。
HTTP的路径参数映射为pathParameters。
HTTP请求的上下文信息映射为requestContext。
POST请求的请求体映射为body。

说明：用户代码可依赖Event中现有参数，但HTTP触发器在将来可能增加参数，用户代码在此处需保证开放性，并对参数数量无硬性依赖。

配置举例

1 在控制台为某个函数配置了参数为如下内容的一个HTTP触发器，拿到http触发器URL。

                JSON
                
                URL路径: "http://7grmt1xfky5jf.cfc-execute.gz.baidubce.com/test/{proxy+}"
HTTP方法: GET 
身份验证: 不验证

2 使用curl作为客户端向CFC发出HTTP请求。

Plain Text

1curl http://7grmt1xfky5jf.cfc-execute.gz.baidubce.com/test/aaa/bbb?a=111

该请求在CFC侧转换的对应的的event的内容如下

                JSON
                
            

                {
	"resource": "/test/{proxy+}",
	"path": "/test/aaa/bbb", 
	"httpMethod": "GET",
	"headers": {     
		"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
		"Accept-Encoding": "gzip, deflate, br",
		"Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
		"Connection": "close",
		"Upgrade-Insecure-Requests": "1",
		"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.67 Safari/537.36",
		"X-Bce-Request-Id": "f6cb833e-f818-4b80-b30c-fff437e69886"
    },
	"queryStringParameters": {
		"a": "111"
    },
	"pathParameters": {
		"proxy": "aaa/bbb."
    },
	"requestContext": {
		"stage": "cfc",
		"requestId": "f6cb833e-f818-4b80-b30c-fff437e69886",
		"resourcePath": "/test/{proxy+}",
		"httpMethod": "GET",
		"apiId": "7grmt1xfky5jf",
        "sourceIp": "12.34.56.78",
    },
	"body": "",
	"isBase64Encoded": false
}
            

使用 HTTP 触发器时的函数返回格式

HTTP 触发器支持两种格式的后端函数返回：简易格式和完整格式。

简易格式

HTTP 触发器会获取函数返回，并将其作为纯文本 HTTP 响应发回客户端。此时，响应状态码固定为 200，并包含 Content-Type: text/plain 响应头部。

使用简易格式时，无法在函数中自定义返回状态码和返回头部，也无法返回二进制响应，如果需要自定义这些，请使用下文描述的完整格式返回。

Node.js 范例

                Javascript
                
                exports.handler = (event, context, callback) => {
    callback(null, "Hello world!");
};

完整格式

使用完整格式定义 HTTP 响应，后端处理函数需要按照以下格式返回 JSON：

                JSON
                
            

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

isBase64Encoded：表示 body 是否进行了 Base64 编码，如果返回纯文本，则设为 false，如果需要返回二进制内容，则需要设为 true，并自行将返回 body 进行 Base64 编码后，设置到 body 字段上。
statusCode：HTTP 响应状态码，必填项，例如 200 表示 OK，404 表示 Not Found 等。
headers：以 K-V 的形式定义响应中需要的额外头部，例如 Content-Type 等。不需要额外响应头部时，可以省略。如果需要启用 CORS，必须在 headers 中添加 Access-Control-Allow-Origin:domain-name 。其中，domain-name 可以设置成通配符*。
body：返回给客户端的响应体的内容，必填项。

Node.js 范例

                Javascript
                
            

                exports.handler = (event, context, callback) => {
	callback(null, {
	    "isBase64Encoded": false,
	    "statusCode": 200,
	    "headers": { "X-Custom-Header": "headerValue" },
	    "body": "hello"
	});
};
            

Python 范例

                Python
                
            

                import json

def handler(event, context):
    resp = {
        "isBase64Encoded": False,
        "statusCode": 200,
        "headers": {
	        "X-Custom-Header": "headerValue"
        },
        "body": "hello"
    } 
    return json.dumps(resp)
            

PHP 范例

                PHP
                
            

                <?php
function handler($event, $context) {
    $resp = [
        "isBase64Encoded" => FALSE,
        "statusCode" => 200,
        "headers" => [
            "X-Custom-Header" => "headerValue",
        ],
        "body" => "hello",
    ];
    return json_encode($resp, JSON_FORCE_OBJECT);
}
            

Lua 范例

Lua

1json = require('cjson')
2
3function handler(event, context)
4    respHeaders = {}
5    respHeaders["X-Custom-Header"] = "headerValue"
6    resp = {
7        isBase64Encoded = false,
8        statusCode = 200,
9        headers = respHeaders,
10        body = "hello",
11    }
12    return json.encode(resp)
13end

PowerShell 范例

                Shell
                
            

                $respHeaders = @{}
$respHeaders["X-Custom-Header"] = "headerValue"
$resp = @{
    isBase64Encoded = $FALSE;
    statusCode = 200;
    headers = $respHeaders;
    body = "hello";
}
$respJson = $resp | ConvertTo-Json
Write-Host $respJson
            

定时任务触发器

HTTP触发器使用示例

百度智能云

函数计算 CFC