qinglong/shell/preload/README_PYTHON_API.md

Qinglong Python API (QLAPI) Documentation

Overview

The Qinglong Python API provides a convenient way to interact with the Qinglong system from Python scripts. The QLAPI object is automatically available in your Python scripts when they run within the Qinglong environment.

Availability

The Python QLAPI is available starting from version 2.8.0+. If you're using an older version (e.g., v2.7.11), please upgrade to access these features.

Prerequisites

• Qinglong version 2.8.0 or higher
• Python 3.6 or higher
• Running within Qinglong environment (scripts executed through Qinglong task system)

Usage

The QLAPI object is automatically injected into your Python script's global namespace. You don't need to import anything - just use it directly:

# QLAPI is automatically available
result = QLAPI.getEnvs({"searchValue": "USER"})
print(result)

Available Methods

Environment Variables Management

getEnvs

Get environment variables with optional search filter.

# Get all environment variables
envs = QLAPI.getEnvs()

# Search for specific environment variables
envs = QLAPI.getEnvs({"searchValue": "USER"})

Parameters:

• searchValue (optional): String to search for in environment variable names or values

Returns: EnvsResponse with list of environment variables

createEnv

Create new environment variables.

result = QLAPI.createEnv({
    "envs": [
        {
            "name": "MY_VAR",
            "value": "my_value",
            "remarks": "My custom variable"
        }
    ]
})

Parameters:

• envs: List of environment variable objects to create

Returns: EnvsResponse

updateEnv

Update an existing environment variable.

result = QLAPI.updateEnv({
    "env": {
        "id": 123,
        "name": "MY_VAR",
        "value": "new_value",
        "remarks": "Updated variable"
    }
})

Parameters:

• env: Environment variable object with id and updated fields

Returns: EnvResponse

deleteEnvs

Delete environment variables by IDs.

result = QLAPI.deleteEnvs({"ids": [123, 456]})

Parameters:

• ids: List of environment variable IDs to delete

Returns: Response

enableEnvs

Enable environment variables.

result = QLAPI.enableEnvs({"ids": [123, 456]})

Parameters:

• ids: List of environment variable IDs to enable

Returns: Response

disableEnvs

Disable environment variables.

result = QLAPI.disableEnvs({"ids": [123, 456]})

Parameters:

• ids: List of environment variable IDs to disable

Returns: Response

updateEnvNames

Update names of multiple environment variables.

result = QLAPI.updateEnvNames({
    "ids": [123, 456],
    "name": "NEW_NAME"
})

Parameters:

• ids: List of environment variable IDs
• name: New name to set

Returns: Response

getEnvById

Get a specific environment variable by ID.

env = QLAPI.getEnvById({"id": 123})

Parameters:

• id: Environment variable ID

Returns: EnvResponse

moveEnv

Change the position/order of an environment variable.

result = QLAPI.moveEnv({
    "id": 123,
    "fromIndex": 0,
    "toIndex": 5
})

Parameters:

• id: Environment variable ID
• fromIndex: Current position index
• toIndex: Target position index

Returns: EnvResponse

Scheduled Tasks (Cron) Management

getCronDetail

Get details of a scheduled task.

cron = QLAPI.getCronDetail({"log_path": "/path/to/log"})

Parameters:

• log_path: Path to the task log file

Returns: CronResponse

createCron

Create a new scheduled task.

result = QLAPI.createCron({
    "command": "node script.js",
    "schedule": "0 0 * * *",
    "name": "Daily Task",
    "labels": ["tag1", "tag2"],
    "sub_id": None,
    "extra_schedules": [],
    "task_before": "",
    "task_after": ""
})

Parameters:

• command: Command to execute
• schedule: Cron expression
• name: Task name (optional)
• labels: List of labels (optional)
• Other optional fields

Returns: CronResponse

updateCron

Update an existing scheduled task.

result = QLAPI.updateCron({
    "id": 123,
    "command": "node updated_script.js",
    "schedule": "0 0 * * *",
    "name": "Updated Task",
    "labels": [],
    "sub_id": None,
    "extra_schedules": [],
    "task_before": "",
    "task_after": ""
})

Returns: CronResponse

deleteCrons

Delete scheduled tasks by IDs.

result = QLAPI.deleteCrons({"ids": [123, 456]})

Parameters:

• ids: List of task IDs to delete

Returns: Response

Notifications

notify

Send a notification using configured notification channels.

result = QLAPI.notify("Notification Title", "Notification Content")

Parameters:

• First argument: Notification title
• Second argument: Notification content

Returns: Notification result

systemNotify

Send a system notification with custom parameters.

result = QLAPI.systemNotify({
    "title": "System Alert",
    "content": "This is a system notification"
})

Parameters:

• title: Notification title
• content: Notification content

Returns: Response

Complete Example

"""
Example Qinglong Python script demonstrating QLAPI usage
"""

# Get environment variables
print("Fetching environment variables...")
envs = QLAPI.getEnvs({"searchValue": "TOKEN"})
print(f"Found {len(envs.get('data', []))} environment variables")

# Create a new environment variable
print("Creating new environment variable...")
result = QLAPI.createEnv({
    "envs": [
        {
            "name": "MY_TEST_VAR",
            "value": "test_value_123",
            "remarks": "Created by script"
        }
    ]
})
print(f"Create result: {result}")

# Send notification
print("Sending notification...")
QLAPI.notify("Script Completed", "The script has finished executing successfully")

# Send system notification
QLAPI.systemNotify({
    "title": "Task Report",
    "content": f"Processed {len(envs.get('data', []))} environment variables"
})

print("Done!")

Error Handling

All QLAPI methods may raise exceptions if there are errors communicating with the backend. It's recommended to use try-except blocks:

try:
    envs = QLAPI.getEnvs({"searchValue": "USER"})
    print(f"Success: {envs}")
except Exception as e:
    print(f"Error: {e}")
    QLAPI.notify("Script Error", str(e))

Troubleshooting

AttributeError: 'BaseApi' object has no attribute 'getEnvs'

This error occurs when using an older version of Qinglong (before v2.8.0). Solutions:

1. Upgrade Qinglong: Update to version 2.8.0 or higher
2. Check Installation: Ensure shell/preload/client.py exists
3. Verify Environment: Make sure scripts are running within Qinglong environment

Module Import Errors

The QLAPI is only available when scripts run within the Qinglong environment. If you're testing locally, you won't have access to QLAPI.

Technical Details

The Python QLAPI is a wrapper around the Node.js gRPC API client. When you call a method like QLAPI.getEnvs():

1. Python Client creates a temporary Node.js script
2. Executes the corresponding Node.js API method
3. Returns the JSON result back to Python

This architecture ensures consistency between JavaScript and Python APIs.

See Also

For more information and examples:

• JavaScript API Client Source - The underlying Node.js gRPC client
• Python Sample Script - Example Python script using QLAPI
• JavaScript Sample Script - Example JavaScript script for comparison

These files are located in the Qinglong repository under shell/preload/ and sample/ directories.