Function Compute:Handlers

What is a handler?

A handler of a function in Function Compute is the method that is used to process requests in function code. When a function is invoked, Function Compute uses the handler that you configure to process requests. You can configure a handler for a function by specifying the Handler parameter in the Function Compute console.

Handlers of Node.js functions in Function Compute follow the File name.Method name format. For example, if your file name is index.js or index.mjs and your method name is handler, the handler is index.handler.

For more information about the definitions and operations of functions in Function Compute, see Manage functions.

Configurations of handlers must conform to the configuration specifications of Function Compute. The configuration specifications vary based on the handler type.

Handler signatures

The following sample code shows a simple event handler signature:

// index.mjs
export const handler = async (event, context) => {
  console.log("receive event: \n" + event);
  return "Hello World!";
};

// index.js
exports.handler = async function(event, context) {
  console.log("receive event: \n" + event);
  return "Hello World!";
};

// index.js
exports.handler = async function(event, context, callback) {
  console.log("event: \n" + event);
  callback(null, 'hello world');
};

Parameter description:

handler indicates the method name, which corresponds to the value of the Handler parameter configured in the Function Compute console. For example, if you set Handler to index.handler when you create the function, Function Compute loads the handler method defined in index.js and starts to execute code from handler.

Function Compute runtimes pass request parameters to the handler. The first parameter is the event object, which contains the request payload information. The event object is of the Buffer data type. You can convert event to another object type based on your business requirements. The second parameter is the context object that provides context information during invocations. For more information, see Context.

Note

• We recommend that you use Async/Await instead of callback if you use Node.js 18 or later.

• Function Compute converts the returned result based on the type of the returned value.

• Buffer type: The result is directly returned without changes.

• Object type: The result is returned in the JSON format.

• Other types: The results are returned as strings.

Async/Await

We recommend that you use Async/Await in Node.js 18 or later. Async/Await is a simple and easy-to-read way to write asynchronous code in Node.js without nested callbacks or method chaining.

Compared with callback, Async/Await provides the following benefits:

• Better readability: The code in Async/Await mode is more linear and synchronous, and easier to understand and maintain. Async/Await prevents high-level nests and makes the code structure clearer.

• Easy to debug and handle errors: You can use try-catch blocks to catch and handle errors in asynchronous operations more easily. Error stacks can be easily located and traced.

• Higher efficiency: In most cases, callback functions must switch between different parts of code. Async/Await can reduce the number of context switches, thereby improving code efficiency.

Example 1: Parse JSON-formatted parameters

Sample code

When you pass JSON-formatted parameters into functions of Function Compute, Function Compute passes through the parameters, and you need to parse the parameters in the code. The following sample code provides an example on how to parse an event that is in the JSON format.

export const handler = async (event, context) => {
  var eventObj = JSON.parse(event.toString());
  return eventObj['key'];
};

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

Before you start

Create a function in a Node.js runtime. For more information, see Create a function. If you want to specify the code as an ECMAScript module, you must select Node.js 18 or Node.js 20 as the runtime when you create the function.

Procedure

1. Log on to the Function Compute console. In the left-side navigation pane, click Functions.

2. In the top navigation bar, select a region. On the Functions page, click the function that you want to manage.

3. On the function details page, click the Code tab. In the code editor, enter the preceding sample code and click Deploy.

   Note

   In the preceding sample code, the handler of the function is the handler method in index.js. If the handler of your function is different, use the actual handler configurations.

4. On the Code tab, click the icon next to Test Function, select Configure Test Parameters from the drop-down list, enter the following sample test parameters, and then click OK.

   {
     "key": "value"
   }

5. Click Test Function on the Code tab.

   After the function is executed, the execution result is returned. In this example, value is returned.

Example 2: Read and write OSS resources by using a temporary AccessKey pair

Sample code

You can use a temporary AccessKey pair that is provided by Function Compute to access Object Storage Service (OSS). The following code is used as an example:

// index.mjs
import OSSClient from 'ali-oss';

export const handler = async (event, context) => {
    console.log(event.toString());

    var ossClient = new OSSClient({
        accessKeyId: context.credentials.accessKeyId,
        accessKeySecret: context.credentials.accessKeySecret,
        stsToken: context.credentials.securityToken,
        region: 'oss-cn-shenzhen',
        bucket: 'my-bucket',
    });

    try {
      const uploadResult = await ossClient.put('myObj', Buffer.from('hello, fc', "utf-8"));
      console.log('upload success, ', uploadResult);
      return "put object"
    } catch (error) {
      throw error
    }
};

var OSSClient = require('ali-oss');

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

    var ossClient = new OSSClient({
        accessKeyId: context.credentials.accessKeyId,
        accessKeySecret: context.credentials.accessKeySecret,
        stsToken: context.credentials.securityToken,
        region: `oss-${context.region}`,
    		bucket: process.env.BUCKET_NAME,
    });

    ossClient.put('myObj', Buffer.from('hello, fc', "utf-8")).then(function (res) {
        callback(null, 'put object');
    }).catch(function (err) {
        callback(err);
    });  
};

Before you start

• Configure a role that has permissions to access OSS for the service. For more information, see Grant Function Compute permissions to access other Alibaba Cloud services.

• Create a function in a Node.js runtime. For more information, see Create a function. If you want to specify the code as an ECMAScript module, you must select Node.js 18 or Node.js 20 as the runtime when you create the function.

Procedure

1. Log on to the Function Compute console. In the left-side navigation pane, click Functions.

2. In the top navigation bar, select a region. On the Functions page, click the function that you want to manage.

3. (Optional) On the Function Details page, click the Code tab. In the lower part of the WebIDE page, select Terminal > New Terminal. Then, run the following command to install ali-oss dependencies:

   npm install ali-oss --save

   After the installation is complete, you can see that the node_modules folder is generated in the code directory on the left side of WebIDE. The folder contains the ali-oss directory and other dependent libraries.

4. On the Function Details page, click the Code tab. In the code editor, enter the preceding sample code, save the code, and then click Deploy.

   Note

   • In the preceding sample code, the handler for the function is the handler method in index.js or index.mjs. If the handler of your function is different, use the actual handler configurations.

   • Replace region and bucket in the preceding sample code with the actual values.

5. Click Test Function.

   After the function is executed, the execution result is returned. In this example, put object is returned.

Example 3: Call external commands

You can use a Node.js program to create a fork process to call external commands. For example, you can use the child_process module to call the ls -l command of Linux and output the list of files in the current directory. Sample code:

'use strict';

import { exec } from 'child_process';
import { promisify } from 'util';

const execPromisify = promisify(exec);
export const handler = async (event, context) => {
  try {
    const { stdout, stderr } = await execPromisify("ls -l");
    console.log(`stdout: ${stdout}`);
    if (stderr !== "") {
      console.error(`stderr: ${stderr}`);
    }
    return stdout;
  } catch (error) {
    console.error(`exec error: ${error}`);
    return error;
  }
}

'use strict';

var exec = require('child_process').exec;
exports.handler = (event, context, callback) => {
  console.log('start to execute a command');
  exec("ls -l", function(error, stdout, stderr){
    callback(null, stdout);
});
}

Example 4: Use an HTTP trigger to invoke a function

Sample code

You can use a URL that is provided by an HTTP trigger to invoke a function in Function Compute. The following sample code shows an example:

• If the Authentication Method parameter of the HTTP trigger is set to No Authentication, you can use Postman or Curl to invoke the function. For more information, see Procedure.

• If the Authentication Method parameter of the HTTP trigger is set to Signature Authentication or JWT Authentication, you can use the signature method or JWT authentication method to invoke the function. For more information, see Authentication.

For more information about formats of request payloads and response payloads of HTTP triggers, see Use an HTTP trigger to invoke a function.

'use strict';

export const handler = async (event, context) => {
  const eventObj = JSON.parse(event);
  console.log(`receive event: ${JSON.stringify(eventObj)}`);

  let body = 'Hello World!';
  // get http request body
  if ("body" in eventObj) {
    body = eventObj.body;
    if (eventObj.isBase64Encoded) {
      body = Buffer.from(body, 'base64').toString('utf-8');
    }
  }
  console.log(`receive http body: ${body}`);

  return {
    'statusCode': 200,
    'body': body
  };
}

'use strict';
exports.handler = (event, context, callback) => {
  const eventObj = JSON.parse(event);
  console.log(`receive event: ${JSON.stringify(eventObj)}`);

  let body = 'Hello World!';
  // get http request body
  if ("body" in eventObj) {
    body = eventObj.body;
    if (eventObj.isBase64Encoded) {
      body = Buffer.from(body, 'base64').toString('utf-8');
    }
  }
  console.log(`receive http body: ${body}`);

  callback(null, {
    'statusCode': 200,
    'body': body
  });
}

Before you start

Use the preceding example to create a function in a Node.js runtime. For more information, see Create a function.

Procedure

1. Log on to the Function Compute console. In the left-side navigation pane, click Functions.

2. In the top navigation bar, select a region. On the Functions page, click the function that you want to manage.

3. On the function details page, click the Configuration tab. In the left-side navigation pane, click Trigger. On the Trigger page, obtain the public endpoint of the HTTP trigger.

4. Run the following command by using the Curl tool to invoke the function:

   curl -i "https://test-nodejs-dlgxxr****.cn-shanghai.fcapp.run" -d 'Hello World!'

   In the preceding command, https://test-nodejs-dlgxxr****.cn-shanghai.fcapp.run is the obtained public endpoint of the HTTP trigger.

   The following result is returned:

   HTTP/1.1 200 OK
   Access-Control-Expose-Headers: Date,x-fc-request-id
   Content-Disposition: attachment
   Content-Length: 12
   Content-Type: text/html; charset=utf-8
   Etag: W/"c-Lve95gjOVATpfV8EL5X4nxwjKHE"
   X-Fc-Request-Id: 1-65d866a8-15d8796a-cb9b4feb69ca
   X-Powered-By: Express
   Date: Fri, 23 Feb 2024 09:34:34 GMT
   
   Hello World!curl: (3) URL using bad/illegal format or missing URL