tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Serverless Cloud Function
    Documentation
    Download PDF

    Basic Concepts

    Last updated: 2024-12-02 19:46:29
    Download PDF
      Serverless Cloud Function (SCF) provides two deployment methods of code deployment and image deployment and supports two function types of event-triggered function and HTTP-triggered function. Different deployment methods and function types require different specifications during code development. This document describes the writing specifications and related concepts of event-triggered function in code deployment. For more information on image deployment and HTTP-triggered function, please see the corresponding documents.
      An SCF event-triggered function involves three basic concepts: execution method, function input parameter, and function return.
      Note:
      The above concepts correspond respectively to the following in general project development: Execution method: corresponds to the main function of the project and is the starting point of program execution. Function input parameter: refers to function input parameters in a normal sense. However, in the SCF environment, the input parameters of an entry function are fixed values. For more information, please see Function Input Parameters. Function return: corresponds to the returned value of the main function in the project. After the function returns, the code execution ends.

      Execution Method

      When the SCF platform invokes a function, it will first find an execution method as the entry point to execute your code. At this time, you need to set in the format of filename.execution method name. For example, if the user-configured execution method is index.handler, the SCF platform will first look for the index file in the code package and find the handler method in the file to start execution. In the execution method, you can process the input parameters of the entry function and call other methods in the code arbitrarily. In SCF, the completion of the execution of the entry function or the exception of the execution of the function marks the end of execution.

      Function Input Parameters

      Function input parameters refer to the content that is passed to the function when the function is triggered. Usually, there are two input parameters: event and context. However, the number of input parameters may vary by programming language and environment. For more information, please see Serverless Cloud Function.
      event
      context

      Usage

      The event parameter is of dict type and contains the basic information that triggers the function. It can be in a platform-defined or custom format. After the function is triggered, the event can be processed inside the code.

      Instructions

      There are two ways to trigger an SCF function:
      1. Trigger by calling TencentCloud API.
      2. Trigger by binding a trigger.
      These two SCF trigger methods correspond to two event formats:
      TencentCloud API: You can freely define a parameter of dict type between the invoker and the function code, where the invoker passes in the data in the format agreed upon, and the function code gets the data in the format. Sample: You can define a data structure {"key":"XXX"} of dict type, and when the invoker passes in the data {"key":"abctest"}, the function code can get the value abctest through event[key].
      Trigger: SCF can be connected with various Tencent Cloud services such as API Gateway, COS, and CKafka, so you can bind a corresponding Tencent Cloud service trigger to a function. When the function is triggered, the service will pass the event to SCF as the event parameter in a platform-predefined unchangeable format. You can write code based on this format and get information from the event parameter. Sample: When COS triggers a function, the specific information of the bucket and the file will be passed to the event parameter in JSON format. The processing of the triggering event can be completed by parsing the event information in the function code.

      Usage

      context is an input parameter provided by the SCF platform. It is passed to the execution method, by parsing which the code can get the runtime environment and related information of the current request.

      Instructions

      The fields and descriptions of the context input parameter provided by SCF are as follows:
      Field
      Description
      memory_limit_in_mb
      Configured function memory size
      time_limit_in_ms
      Timeout period for function execution
      request_id
      Function execution request ID
      environment
      Function namespace information
      environ
      Function namespace information
      function_version
      Function version information
      function_name
      Function name
      namespace
      Function namespace information
      tencentcloud_region
      Function region
      tencentcloud_appid
      Function's Tencent Cloud APPID
      tencentcloud_uin
      Function's Tencent Cloud account ID
      
      Note:
      To ensure compatibility, the descriptions of the namespace at different stages of the SCF function are retained in the context. The content of the context structure may be increased as the SCF platform is iterated.
      You can print the context information through the standard output statement in the function code. Take the python runtime environment as an example:
      # -*- coding: utf8 -*-
      import json
      def main_handler(event, context):
          print(context)
          return("Hello World")
      The following context information can be obtained:
      {"memory_limit_in_mb": 128, "time_limit_in_ms": 3000, "request_id": "f03dc946-3df4-45a0-8e54-xxxxxxxxxxxx", "environment": "{\\"SCF_NAMESPACE\\":\\"default\\"}", "environ": "SCF_NAMESPACE=default;SCF_NAMESPACE=default", "function_version": "$LATEST", "function_name": "hello-from-scf", "namespace": "default", "tencentcloud_region": "ap-guangzhou", "tencentcloud_appid": "12xxxxx384", "tencentcloud_uin": "10000xxxxx36"}
      
      After understanding the basic usage of event and context input parameters, you should pay attention to the following points when writing function code:
      To ensure uniformity for each programming language and environment, `event` and `context` should be uniformly encapsulated in the `JSON` data format.
      Different triggers pass different data structures when triggering functions. For more information, please see Trigger Overview.
      If the function does not need any input, you can ignore the `event` and `context` parameters in your code.

      Function Return

      The SCF platform will get the returned value after the function is executed and handle according to different trigger type as listed below.
      Trigger Type
      Handling Method
      Sync triggering
      If triggered by API Gateway or the TencentCloud API for sync invocation, the function will be triggered synchronously.
      For a function triggered synchronously, the SCF platform will not return the trigger result during function execution.
      After the function is executed, the SCF platform will encapsulate the returned value into JSON format and return it to the invoker.
      Async triggering
      For a function that is triggered asynchronously, the SCF will return the triggering request ID after receiving the triggering event.
      After the function is executed, the returned value will be encapsulated into JSON format and stored in the log.
      After the function execution is completed, you can query the log by the request ID in the return to get the returned value of the asynchronously triggered function.
      When the code in a function returns a specific value, it usually returns a specific data structure; for example:
      Runtime Environment
      Returned Structure Type
      Python
      Simple or dict data structure
      Node.js
      JSON Object
      PHP
      Array structure
      Go
      Simple data structure or struct with JSON description
      To ensure uniformity for different programming languages and environments, the function return will be uniformly encapsulated in the JSON data format. For example, after SCF gets the returned value of the function in the above runtime environment, it will convert the returned data structure to JSON and return it to the invoker.
      Note:
      You should ensure that the returned value of the function can be converted to JSON format. If the object is returned directly and there is no JSON conversion method, SCF will fail when executing JSON conversion and prompt an error.
      For example, the returned value in the above runtime environment does not need to be converted to JSON format before it is returned; otherwise, the output string will be converted again.

      Exception Handling

      If an exception occurs during testing and executing a function, the SCF platform will handle the exception as much as possible and write the exception information into the log. Exceptions generated by function execution include caught exceptions (handled errors) and uncaught exceptions (unhandled errors).

      Handling method

      You can log in to the SCF console and follow the steps below to test exception handling:
      1. Create a function and copy the following function code without adding any triggers.
      2. Click Test in the console and select the "Hello World" test sample for testing.
      This document provides the following three ways to throw exceptions, and you can choose how to handle exceptions in the code based on your actual needs.
      Throw exceptions explicitly
      Inherit the `Exception` class
      Use the `Try` statement to capture errors
      Sample
      def always_failed_handler(event,context):
          raise Exception('I failed!')
      Description This function will throw an exception during execution and return the following error message. The SCF platform will record this error message in the function log.
      File "/var/user/index.py", line 2, in always_failed_handler
      raise Exception('I failed!')
      Exception: I failed!
      Sample
      class UserNameAlreadyExistsException(Exception): pass
      def create_user(event):
          raise UserNameAlreadyExistsException('
              The username already exists,
              please change a name!')
      Description
      You can define how to handle errors in your code to ensure the robustness and scalability of your application.
      Sample
      def create_user(event):
          try:
              createUser(event[username],event[pwd])
          except UserNameAlreadyExistsException,e: //catch error and do something
      Description
      You can define how to handle errors in your code to ensure the robustness and scalability of your application.

      Returned error message

      If exception handling and error capture are not performed in your code logic, the SCF platform will capture errors as much as possible such as when your function suddenly crashes and exits during execution. The platform will return a general error message if it cannot capture an error that occurs. The table below lists some common errors in code execution:
      Error Scenario
      Error Message
      raise is used to throw an exception
      {File "/var/user/index.py", line 2, in always_failed_handler raise Exception('xxx') Exception: xxx}
      The handler does not exist
      {'module' object has no attribute 'xxx'}
      The dependent module does not exist
      {global name 'xxx' is not defined}
      Timed out
      {"time out"}

      Log

      The SCF platform stores all the records of function invocations and the outputs of the function code in logs. You can use the printout or log statement in the programming language to generate the output logs for debugging and troubleshooting. For more information, please see Log Search Guide.

      Notes

      Because of the nature of SCF, you must write your function code in a stateless style. State characteristics in the lifecycle of a function such as local file storage will be destroyed after the function invocation ends. Therefore, you are recommended to store persistent states in TDSQL, COS, TencentDB for Memcached, or other cloud storage services.

      Development Process

      For more information on the function development process, please see Getting Started.
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy