Easy Service Development

This page aims to guide developers on how to develop Easy Service type extension packages.

About Easy Services

Easy Service is actually a Python file where developers don't need to worry about HTTP service implementation but focus on writing specific business logic. Unlike General Services, Easy Service extensions are more lightweight and typically suitable for implementing simple business operations.

Easy Service Features

• Lightweight: Only requires one Python file, directly write single methods to quickly implement functionality.
• No HTTP Implementation Required: The system automatically handles HTTP interfaces and requests, no manual configuration needed by developers.
• Quick Integration: Quickly integrate into the extension system and can be immediately used as a backend service.
• Simplified Business Logic: Developers only need to focus on core business logic implementation without handling HTTP-related parts.

Startup Requirements

When a simple service extension starts, the extension system launches a Python interpreter and automatically imports the corresponding Python file of the extension (i.e., performs the module import process).

During this process, the system waits until the Python file has been fully imported before considering the extension successfully started.

Important

• The extension only becomes callable after the Python file has been completely imported (that is, when the import statement finishes executing).
• If you perform time-consuming operations at the top level of the file (module scope), such as:
  • heavy computation,
  • long-running network requests,
  • database initialization, or
  • blocking waits,

these operations will block the module import process, causing the extension system to wait for an extended period and eventually trigger a startup timeout error.

• Therefore, place any time-consuming operations inside functions or asynchronous logic, and execute them only when actually needed.

Creating Easy Service Extension Package

In this demonstration, we will create an Easy Service type extension. The function of this extension is to provide an addition operation interface.

TIP

MathService in the following text is the name of the Easy Service extension we are about to create.

Step 1: Create Extension Folder

First, we need to create a basic extension folder that contains a config.json configuration file and a Python file. Note that in Easy Service, the Python file name must be the same as the extension name.

You can create it manually from scratch or modify the template in the "demo" directory in the extension development package repository.

Directory structure:

• MathService
  • config.json
  • MathService.py

MathService.py

# Get global logger instance, can only be used in Easy Service
logger = globals().get('logger')
if logger is None:
    # For local debugging, use built-in logging library
    import logging
    logger = logging.getLogger(__name__)

def add(a: int, b: int) -> int:
    """
    Perform addition operation on two integers

    Parameters:
    - a (int): First addend
    - b (int): Second addend

    Returns:
    - int: Addition result
    """
    try:
        result = a + b
        return result

    except Exception as ex:
        logger.error(ex)
        return 0

config.json

{
  "name": "MathService",
  "type": "easyService",
  "scriptLang": "python",
  "description": "Math Service",
  "version": "0.1"
}

Step 2: Package and Install

For extension packaging, please refer to Packaging and Installation

Step 3: Call the Interface

Below are several ways to call the previously created interface.

• Method 1: Use CALL_SERVICE instruction to call.

Please refer to related section.

• Method 2: Use JS runtime to call in Web Mini Programs.

Use the callEasyService function in Web Mini Program JS code.

import { callEasyService } from '@agilebot/extension-runtime';

callEasyService('MathService', 'add', {
  a: 1,
  b: 2
}).then(result => {
  // Output: Addition calculation result is 3
  console.log(`Addition calculation result is ${result}`);
});

For specific examples, refer to Complex Web Mini Programs

• Method 3: Directly access the interface address.

http://10.27.1.254:5616/MathService/add?a=1&b=2

In this method, URL query parameters ( a=1 and b=2 ) are automatically mapped to the parameters of the add function in the MathService extension:

• a=1 is mapped to the a parameter of function add , with value 1 .
• b=2 is mapped to the b parameter of function add , with value 2 .

Here's an example using Python to get the result:

import requests

response = requests.get('http://10.27.1.254:5616/MathService/add', {
    'a': 1,
    'b': 2
})

if response.status_code == 200:
    # Parse JSON response
    data = response.json()

    # Output result
    print(f"Result: {data['result']}")
else:
    print(f"Request failed with status code: {response.status_code}")

Parameter Mapping Relationship

Function Parameter Type	Example Parameter	Actual URI Address	Parameter Mapping Description
int	a=1	?param1=1&param2=2	param1 maps to function's int type parameter with value 1
str	name=John	?name=John	name maps to function's str type parameter with value "John"
bool	isActive=true	?isActive=true	isActive maps to function's bool type parameter with value true
List[dict]	items=[{"id":1,"name":"item1"}]	?items[0][id]=1&items[0][name]=item1 [1]	items maps to function's List[dict] type parameter, value is a dictionary list

Limitations

Although Easy Service is very convenient, its functionality also has some limitations. Here are several limitations to note when using Easy Service:

1. Only supports basic parameter types: Easy Service function parameters only support the following basic types: str , int , bool , List[dict] . If you need to handle more complex data structures or custom types, it's recommended to use General Service.
2. Limited extensibility: Easy Service is suitable for quickly developing and integrating simple business logic. For requirements involving high concurrency, complex routing, state management, etc., General Service provides higher flexibility and extensibility.
3. Functionality focused on business logic: Easy Service focuses on core business logic and doesn't involve HTTP processing, request validation, security features, etc. If you need more complex request processing (such as authentication, permission management), General Service can provide more functionality support.

---

1. In JavaScript, you can use the qs package to serialize to this format. ↩︎