edit-icon download-icon

Handler

Last Updated: Jun 12, 2018

When creating a function, you must specify an event handler function that can be called by Function Compute (FC) during code running. The signature of the Node.js handler function is:

  1. exports.myHandler = function(event, context, callback) {
  2. ...
  3. // Use callback() to return information to the caller.
  4. }

myHandler is the name of the function called by FC. You must export this function so that it is visible to FC. For example, if your logic entrance is in helloworld.js, helloworld.myHandler ({filename}.{handlername}) is the function handler. For more information, see Create a function.

  • event: event playload in Buffer type.
  • context: object that contains useful runtime information of the called function which is in Context type.
  • callback: function that informs FC that the function call can be stopped and returns data to callers.

Function example:

  1. exports.myHandler = function(event, context, callback) {
  2. // Assume that the given event is a JSON string.
  3. var eventObj = JSON.parse(event.toString());
  4. console.log("value1 = " + eventObj.key1);
  5. console.log("value2 = " + eventObj.key2);
  6. // The first callback parameter is of the error type and null indicates that the function execution is successful.
  7. callback(null, "some success message");
  8. // or
  9. // callback("some error type");
  10. }

The preceding example shows an event handling function. The given event is converted to a JSON object first, and console.log() statement, and then stores the event data to Alibaba Cloud Log Service. When callback is called, the function exits, and “some success message” is returned.

Event format

When a function is called, FC passes the Body of InvokeFunction request to the function. FC does not restrict the event format. You can select a format such as JSON, XML, Image, or Video based on your business requirements. The interpretation of the event is completely controlled by developers.

The following example shows that if you use an OSS trigger, then the event is in JSON format.

  1. {
  2. "events": [
  3. {
  4. "eventName": "ObjectCreated:PutObject",
  5. "eventSource": "acs:oss",
  6. "eventTime": "2017-04-21T12:46:37.000Z",
  7. "eventVersion": "1.0",
  8. "oss": {
  9. "bucket": {
  10. "arn": "acs:oss:cn-shanghai:123456789:bucketname",
  11. "name": "testbucket",
  12. "ownerIdentity": "123456789",
  13. "virtualBucket": ""
  14. },
  15. "object": {
  16. "deltaSize": 122539,
  17. "eTag": "688A7BF4F233DC9C88A80BF985AB7329",
  18. "key": "image/a.jpg",
  19. "size": 122539
  20. },
  21. "ossSchemaVersion": "1.0",
  22. "ruleId": "9adac8e253828f4f7c0466d941fa3db81161e853"
  23. },
  24. "region": "cn-shanghai",
  25. "requestParameters": {
  26. "sourceIPAddress": "140.205.128.221"
  27. },
  28. "responseElements": {
  29. "requestId": "58F9FF2D3DF792092E12044C"
  30. },
  31. "userIdentity": {
  32. "principalId": "123456789"
  33. }
  34. }
  35. ]
  36. }

Callback usage

The callback parameter is used to return the function execution result to the caller. The callback function signature is defined as follows:

  1. callback(Error error, Object result)

When callback is called, the FC terminates the call.

  • error: An optional parameter which indicates that the function fails and returns the error information to the caller.

  • result: An optional parameter that returns the successful function execution result to the caller. When the error parameter is passed into callback, this parameter is ignored.

Example of callback usage.

  1. callback(); // function execution is successful with no information to return.
  2. callback(null); // function execution is successful with no information to return.
  3. callback(null, null); // function execution is successful with no information to return.
  4. callback(null, "success"); // function execution is successful with a "success" string as returned value.
  5. callback(new Error("error")); // function execution fails with an "error" message as returned value.
  6. callback(new Error("error"), "ignored message") // function execution fails with an "error" message and the second parameter is ignored.
  7. callback("error"); // function execution fails with an "error" message

Note:

  • You must call the callback function to inform FC that function execution is completed. Otherwise, the function execution cannot be finished until a timeout error occurs.
  • When an error message is returned using the callback error parameter, FC automatically records the error message in the logstore that is associated to the service. If the size of the error message is larger than 256 KB, only the first 256 KB of data is stored and “Truncated by FunctionCompute” is displayed. For more information about how to configure function log, see relevant documentation.
  • If the function is called synchronously, the error message or result data is added to the HTTP body and returned to the client. If the function is called asynchronously, the error message or result data is not returned.
Thank you! We've received your feedback.