Console
    Contact Us Start free

    Write event-driven functions

    In Cloud Run functions, you use event-driven functions when you want a function to be invoked automatically in response to an event that occurs in your cloud environment.

    There are two ways to implement event-driven functions. Which way you use depends on your chosen language runtime:

    CloudEvent functions

    CloudEvent functions are based on CloudEvents , an industry-standard specification for describing event data in a common way. You can learn more about the CloudEvents specification at the CloudEvents GitHub repository . The CloudEvents project also provides a set of CloudEvents SDKs to help work with CloudEvents objects in your code.

    The following example shows a basic CloudEvent function source file for each runtime. See Source directory structure for information about where to locate your source code.

    C#

     using 
  
 CloudNative.CloudEvents 
 ; 
 using 
  
 Google.Cloud.Functions.Framework 
 ; 
 using 
  
 System.Threading 
 ; 
 using 
  
 System.Threading.Tasks 
 ; 
 namespace 
  
 MyProject 
 { 
  
 // Define a class that implements the ICloudEventFunction<T> interface 
  
 public 
  
 class 
  
 MyCloudEventFunction 
  
 : 
  
 ICloudEventFunction< CloudEventDataType 
 
>  
 { 
  
 // Implement the HandleAsync() method to handle CloudEvents 
  
 public 
  
 Task 
  
 HandleAsync 
 ( 
 CloudEvent 
  
 cloudEvent 
 , 
  
  CloudEventDataType 
 
  
 data 
 , 
  
 CancellationToken 
  
 cancellationToken 
 ) 
  
 { 
  
 // Your code here 
  
 // The data argument represents the CloudEvent data payload 
  
 // Signal function completion 
  
 return 
  
 Task 
 . 
 CompletedTask 
 ; 
  
 } 
  
 } 
 }

    In .NET runtimes, you use the Functions Framework for .NET to implement a CloudEvent handler class with the ICloudEventFunction<T> interface. The HandleAsync() method accepts a CloudEvent object and the associated CloudEvent data payload as arguments.

    The type of the CloudEvent data payload argument, shown in the above example as CloudEventDataType , must correspond to the type of event the function handles. The Google CloudEvents .NET library provides data types for the various events supported by Google.

    The function entry point is the fully-qualified name of the CloudEvent handler class, including the namespace. In this example, the entry point is MyProject.MyCloudEventFunction .

    Ruby

      require 
  
 "functions_framework" 
 # Register a CloudEvent function with the Functions Framework 
 FunctionsFramework 
 . 
 cloud_event 
  
 "my_cloudevent_function" 
  
 do 
  
 | 
 cloud_event 
 | 
  
 # Your code here 
  
 # Access the CloudEvent data payload via cloud_event.data 
 end

    In Ruby, you register a CloudEvent handler function with the Functions Framework for Ruby . Your handler function must accept a CloudEvents Event object as an argument.

    The function entry point is the name with which the handler is registered with the Functions Framework. In this example, the entry point is my_cloudevent_function .

    PHP

     < ?php 
 use CloudEvents\V1\CloudEventInterface; 
 use Google\CloudFunctions\FunctionsFramework; 
 // Register a CloudEvent function with the Functions Framework 
 FunctionsFramework::cloudEvent('myCloudEventFunction', 'myCloudEventHandler'); 
 // Define your CloudEvent handler 
 function myCloudEventHandler(CloudEventInterface $event): void 
 { 
 // Your code here 
 // Access the CloudEvent data payload via $event->getData() 
 }

    In PHP, you register a CloudEvent handler function with the Functions Framework for PHP . Your handler function must accept an argument that conforms to the CloudEventInterface interface.

    The function entry point is the name with which the handler is registered with the Functions Framework. In this example, the entry point is myCloudEventFunction .

    For CloudEvent functions, event data is passed to your function in the CloudEvents format , with a CloudEvent data payload corresponding to the event type that triggers your function. See Cloud Run functions triggers for information about supported triggers, event types, and associated event data formats.

    The Google Events repository contains resources for working with CloudEvents issued by Google.

    Background functions

    Event-driven functions in the Node.js, Python, Go, and Java runtimes expect different arguments from CloudEvent functions. This older style of event-driven function is called a background function .

    The following example shows a basic background function source file for each runtime. See Source directory structure for information about where to locate your source code.

    Node.js

      // Define and export an event handler 
 exports 
 . 
 myBackgroundFunction 
  
 = 
  
 ( 
 eventData 
 , 
  
 context 
 , 
  
 callback 
 ) 
  
 = 
>  
 { 
  
 // Your code here 
  
 // The eventData argument represents the event data payload 
  
 // Optionally signal function completion: 
  
 callback 
 (); 
 };

    In Node.js, you define and export a function that handles event data. Cloud Run functions passes your handler function the following arguments:

    • eventData : An object representing the event data payload. Its format depends on the event type.
    • context : An object containing metadata about the event.
    • callback : An optional function you can call to signal completion. The first argument to this callback is interpreted as signaling an error. Pass no arguments or a null first argument to signal success.

    The function entry point is the name of the exported event handler. In this example, the entry point is myBackgroundFunction .

    Python

      # Define an event handler 
 def 
  
 my_background_function 
 ( 
 event_data 
 , 
 context 
 ): 
 # Your code here 
 # The event_data argument represents the event data payload

    In Python, you define a function that handles event data. Cloud Run functions passes your handler function the following arguments:

    • event_data : A dictionary representing the event data payload. Its format depends on the event type.
    • context : An object containing metadata about the event.

    The function entry point is the name of the handler function. In this example, the entry point is my_background_function .

    Go

     package 
  
 mybackgroundfunction 
 import 
  
 ( 
  
 "context" 
 ) 
 // Function MyBackgroundFunction accepts and handles event data 
 func 
  
 MyBackgroundFunction 
 ( 
 ctx 
  
 context 
 . 
 Context 
 , 
  
 e 
  
  EventDataType 
 
 ) 
  
 error 
  
 { 
  
 // Your code here 
  
 // The argument e represents the event data payload 
  
 // Return nil if no error occurred 
  
 return 
  
 nil 
 }

    In Go, you define an exported function that handles event data. Cloud Run functions passes your handler function the following arguments:

    • ctx : A context.Context object containing metadata about the event. You can retrieve the metadata using the cloud.google.com/go/functions/metadata package.
    • e : An object representing the event data payload. Its type, shown in the above example as EventDataType , must be a struct corresponding to the type of event the function handles. The event data payload is unmarshaled into the struct using json.Unmarshal() .

    The function entry point is the name of the exported event handler. In this example, the entry point is MyBackgroundFunction .

    Java

     package 
  
 mybackgroundfunction 
 ; 
 import 
  
 com.google.cloud.functions.BackgroundFunction 
 ; 
 import 
  
 com.google.cloud.functions.Context 
 ; 
 // Define a class that implements the BackgroundFunction<T> interface 
 public 
  
 class 
 MyBackgroundFunction 
  
 implements 
  
 BackgroundFunction< EventDataType 
 
>  
 { 
  
 // Implement the accept() method to handle events 
  
 @Override 
  
 public 
  
 void 
  
 accept 
 ( 
  EventDataType 
 
  
 eventData 
 , 
  
 Context 
  
 context 
 ) 
  
 { 
  
 // Your code here 
  
 // The eventData argument represents the event data payload 
  
 } 
 }

    In Java, you use the Functions Framework Java API to implement an event handler class with the BackgroundFunction<T> interface. The accept() method accepts as arguments the event data payload and a Context object containing metadata about the event.

    The type of the event data payload argument, shown in the above example as EventDataType , must correspond to the type of event the function handles. The event data payload is deserialized into an instance of this class using Gson.fromJson() .

    The function entry point is the fully-qualified name of the event handler class, including the package name. In this example, the entry point is mybackgroundfunction.MyBackgroundFunction .

    For background functions, the event data payload is passed directly to your function in a format corresponding to the event type that triggers your function. See Triggers supported in Cloud Run functions (1st gen) for information about supported triggers, event types, and associated event data formats.

    Function termination

    Cloud Run functions considers event-driven function execution complete when the function returns. If the function creates background tasks (such as with threads, futures, JavaScript Promise objects, callbacks, or system processes), you must terminate or otherwise resolve these tasks before returning from your function. Any tasks not terminated before the function returns might not be completed, and might cause undefined behavior.

    Automatic retries

    Event-driven functions can be configured to automatically retry failed invocations. See Retrying event-driven functions for more information.

    Next steps
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: