阿里云Nodejs 函数作为入口——设置 HTTP 触发器参考文档

普通函数入口

处理函数入口

一个最简单的函数定义如下：

1.  `exports.handler =  function(event, context, callback)  {`
2.  `callback(null,  'hello world');`
3.  `};`

函数名

*   `exports.handler` 需要与创建函数时的 “handler” 字段相对应：例如创建函数时指定的 handler 为`index.handler`，那么函数计算会去加载 `index.js` 文件中定义的 `handler` 函数。

event 参数

*   event 参数是您调用函数时传入的数据，其类型是 `Buffer`，是函数的输入参数。
*   函数不对它的内容进行任何解释，传递给函数的 event 是 `Buffer` 类型。您在函数中可以根据实际情况对 event 进行转换：例如输入数据是一个 JSON string ，您可以把它转换成一个 `object` :例如：传入的 event :

    1.  `{`
    2.  `"key":  "value"`
    3.  `}`

函数代码：


    1.  `exports.handler =  function(event, context, callback)  {`
    2.  `var eventObj = JSON.parse(event.toString());`
    3.  `callback(null, eventObj['key']);`
    4.  `};`

返回结果为 value 。

context 参数

context 参数中包含一些函数的运行时信息（例如 request id / 临时 AK 等）。您在代码中可以使用这些信息。其类型是 object
其定义如下：

1.  `{`
2.  `'requestId':  'b1c5100f-819d-c421-3a5e-7782a27d8a33',`
3.  `'credentials':  {`
4.  `'accessKeyId':  'STS.access_key_id',`
5.  `'accessKeySecret':  'access_key_secret',`
6.  `'securityToken':  'security_token',`
7.  `},`
8.  `'function':  {`
9.  `'name':  'my-func',`
10.  `'handler':  'index.handler',`
11.  `'memory':  128,`
12.  `'timeout':  10,`
13.  `'initializer':  'index.initializer',`
14.  `'initializationTimeout':  10,`
15.  `},`
16.  `'service':  {`
17.  `'name':  'my-service',`
18.  `'logProject':  'my-log-project',`
19.  `'logStore':  'my-log-store',`
20.  `},`
21.  `'region':  'cn-shanghai',`
22.  `'accountId':  '123456'`
23.  `}`

可以看到 context 中包含了 6 个信息：

*   **requestId: **本次调用请求的唯一 id，您可以把它记录下来在出现问题的时候方便调查。
*   **function: **当前调用的函数的一些基本信息如函数名 / 函数入口 / 函数内存 / 超时时间。
*   **credentials:** 函数计算服务通过扮演您提供的 [服务角色](https://help.aliyun.com/document_detail/52885.html) 获得的一组临时密钥，其有效时间是 15 分钟。您可以在代码中使用它去访问相应的服务（ 例如 OSS ），这就避免了您把自己的 AK 信息写死在函数代码里。
*   **service: **当前调用的函数所在的 service 的信息，包括 service 的名字，接入的 SLS 的 logProject 和 logStore 信息。
*   **region: **当前调用的函数所在区域，如 cn-shanghai。
*   **accountId: **当前调用函数用户的阿里云 account id。

下面的代码使用临时密钥，向 OSS 中上传了一个文件：


1.  `var  OSSClient  = require('ali-oss').Wrapper;`

3.  `exports.handler =  function  (event, context, callback)  {`
4.  `console.log(event.toString());`

6.  `var ossClient =  new  OSSClient({`
7.  `accessKeyId: context.credentials.accessKeyId,`
8.  `accessKeySecret: context.credentials.accessKeySecret,`
9.  `stsToken: context.credentials.securityToken,`
10.  `region:  'oss-cn-shanghai',`
11.  `bucket:  'my-bucket',`
12.  `});`

14.  `ossClient.put('my-object',  new  Buffer('hello, fc')).then(function  (res)  {`
15.  `callback(null,  'put object');`
16.  `}).catch(function  (err)  {`
17.  `callback(err);`
18.  `});`
19.  `};`

注意：使用临时秘钥访问 OSS 时一定要带上第三个参数 securityToken。

callback 参数

callback 参数用于返回调用函数的结果，其签名是 function(err, data)，与 Nodejs 中惯用的 callback 一样，它的第一个参数是 error ，第二个参数 data 。如果调用时 err 不为空，则函数将返回 HandledInvocationError，否则将返回 data 的内容。如果 data 是 Buffer 类型则它的数据将直接被返回，如果 data 是 object ，则会将其转换成 JSON 字符串返回，其他类型将被转换成 string 返回。

initializer 入口

一个最简单的 initializer 函数定义如下：

1.  `exports.my_initializer =  function(context, callback)  {`
2.  `console.log('hello world');`
3.  `callback(null,  "");`
4.  `};`

initializer 函数名

my_initializer 需要与添加初始化函数时的 “initializer” 字段相对应：例如创建函数时指定的 initializer 为 main.my_initializer，那么函数计算在配置初始化函数后首先会去加载 main.js 中定义的 my_initializer 函数。

initializer 特点

initializer 输入参数有 context 和 callback 两个，具体含义和上文描述的处理函数中相关参数的含义是一致的。
context 中 initializer 和 initializationTimeout 两个信息是为 initializer 设计的，当使用 initializer 功能时，会被设置为用户创建函数时所设置的值，否则为空，且不生效。

更多细节请参考 initializer 入口定义。

设置 HTTP 触发器的函数入口

注意：设置了 HTTP 触发器的函数入口与普通函数的入口不同

1.  `function(request, response, context)`

其中的 context 参数与普通函数接口的 context 接口相同。

Request 结构体

*   `headers`：map 类型，存放来自 HTTP 客户端的键值对。
*   `path`：string 类型，为 HTTP URL。
*   `queries`：map 类型，存放来自 HTTP URL 中的 query 部分的 key - value 键值对, value 的类型可以为字符串或是数组。
*   `method`：string 类型，HTTP 方法。
*   `clientIP`：string 类型，client 的 IP 地址。
*   `url`：string 类型，request 的 url。

获取 HTTP body：HTTP 触发器中的 request 兼容 HTTP request，没有提供额外的 body 字段，直接使用 HTTP request 获取 body。

1.  `// 详见示例`
2.  `var getRawBody =  require('raw-body')`
3.  `getRawBody(request,  function(err, data){`
4.  `var body = data`
5.  `})`

如果您的请求是 multipart/form-data 请求，您可以使用 multiparty 库进行处理。

> **说明**：Headers key 中包含以下字段会被忽略掉，因为 FC 默认会带以下字段，不支持用户自定义。同时以 `x-fc-` 开头的 key 也会被忽略掉。
> 
> *   `accept-encoding`
> *   `connection`
> *   `keep-alive`
> *   `proxy-authorization`
> *   `te`
> *   `trailer`
> *   `transfer-encoding`

Response 提供的方法

*   `response.setStatusCode(statusCode)` ： 设置 status code
    *   param `statusCode` : (required, type integer)
*   `response.setHeader(headerKey, headerValue)` ：设置 header
    *   param`headerKey` : (required, type string)
    *   param`headerValue` : (required, type string)
*   `response.deleteHeader(headerKey)` ：删除 header
    *   param`headerKey`: (required, type string)
*   `response.send(body)`: 发送 body
    *   param`body`: (required, type`Buffer` or a `string` or a `stream.Readable` )

说明：Headers key 中包含以下字段会被忽略掉，因为 FC 默认会带以下字段，不支持用户自定义。同时以 x-fc- 开头的 key 也会被忽略掉。

> *   `connection`
> *   `content-length`
> *   `content-encoding`
> *   `date`
> *   `keep-alive`
> *   `proxy-authenticate`
> *   `server`
> *   `trailer`
> *   `transfer-encoding`
> *   `upgrade`

限制项

Request 限制项

如果超过以下限制，会抛出 400 状态码和 InvalidArgument 错误码

*   headers 的大小：headers 中的所有 key 和 value 的大小不得超过 4 KB。
*   path 大小：包括各个 query params，path 的大小不得超过 4 KB。
*   body 大小：HTTP body 的大小不得超过 6 MB。

Response 限制项

如果超过以下限制，会抛出 502 状态码和 BadResponse 错误码。

*   headers 的大小：headers 中的所有 key 和 value 的大小不得超过 4 KB。
*   body 大小：HTTP body 的大小不得超过 6 MB。

示例

示例代码中展示了如何在函数中获取 request 详细信息。

1.  `var getRawBody =  require('raw-body')`
2.  `module.exports.handler =  function  (request, response, context)  {`
3.  `// get requset header`
4.  `var reqHeader = request.headers`
5.  `var headerStr =  ' '`
6.  `for  (var key in reqHeader)  {`
7.  `headerStr += key +  ':'  + reqHeader[key]  +  '  '`
8.  `};`

10.  `// get request info`
11.  `var url = request.url`
12.  `var path = request.path`
13.  `var queries = request.queries`
14.  `var queryStr =  ''`
15.  `for  (var param in queries)  {`
16.  `queryStr += param +  "="  + queries[param]  +  '  '`
17.  `};`
18.  `var method = request.method`
19.  `var clientIP = request.clientIP`

21.  `// get request body`
22.  `getRawBody(request,  function  (err, data)  {`
23.  `var body = data`
24.  `// you can deal with your own logic here`

26.  `// set response`
27.  `// var respBody = new Buffer('requestURI' + requestURI + ' path' + path +  ' method' + method + ' clientIP' + clientIP)`
28.  `var respBody =  new  Buffer('requestHeader:'  + headerStr +  '\n'  +  'url: '  + url +  '\n'  +  'path: '  + path +  '\n'  +  'queries: '  + queryStr +  '\n'  +  'method: '  + method +  '\n'  +  'clientIP: '  + clientIP +  '\n'  +  'body: '  + body +  '\n')`
29.  `// var respBody = new Buffer( )`
30.  `response.setStatusCode(200)`
31.  `response.setHeader('content-type',  'application/json')`

33.  `response.send(respBody)`

35.  `})`
36.  `};`

阿里云Nodejs 函数作为入口——设置 HTTP 触发器 参考文档