构建 Python 函数

Python 函数包含三部分：已类型化的输入、已类型化的输出以及将两者映射到另一个的入口点函数。本页涵盖了每项功能，以及错误处理和公开了一个项目中的多个函数。

带类型的输入和输出

将 Input 和 Output 定义为 Python 类型。使用 pydantic.dataclasses.dataclass（SDK 示例使用的内容），以便运行时验证传入的有效负载并导出干净的 JSON 架构，包括适用于可选、嵌套和自引用字段的架构。分支 BaseModel 的行为方式相同；标准库 @dataclass 也可接受，适用于简单的平面输入，但它不执行验证，并针对复杂类型导出不完整的架构。每次调用界面都会呈现该导出架构以绑定变量，其中包括 Maestro 服务任务、Orchestrator 运行作业或 Studio 的运行作业活动。入口点可以是同步 def 或 async def — 两者均受支持。

from pydantic.dataclasses import dataclass


@dataclass
class Input:
    document_id: str = ""
    amount: float = 0.0


@dataclass
class Output:
    result_id: str = ""
    status: str = ""


def main(input: Input) -> Output:
    # business logic
    return Output(result_id="123", status="success")

支持的类型

• 基元：str、int、float、bool
• 数组：list[str]、list[dict]
• 嵌套数据类或 pygantic 模型
• 可空字段：Optional[X]

为字段提供默认值，以便清晰地生成架构，并且易于使用部分输入调用函数。

入口点

uipath.json 文件声明了可调用的函数：

{
  "functions": {
    "main": "main.py:main"
  }
}

多个入口点

单个项目可以公开多个函数。列出 uipath.json 中的逐个：

{
  "functions": {
    "extract": "main.py:extract_data",
    "validate": "main.py:validate_data",
    "post_erp": "main.py:post_to_erp"
  }
}

添加入口点以重新生成输入/输出架构后运行 uipath init。

错误处理

函数可以通过两种方式发出业务错误信号。两者均受支持 — 根据调用流程处理故障的方式进行选择：

• 在输出中返回该变量。向 error_message 添加状态标志或 Output 等字段。作业成功完成，调用者（例如 Maestro 流程）在这些字段上进行分支。
• 引发异常。作业发生故障并显示 USER 类别错误，并且您的异常消息将保留在故障中，以便调用者可以在上游进行处理，例如，使用 Maestro 流程中的边界事件。

要在输出中返回错误，请添加所需字段并在故障路径中填充这些字段：

from pydantic.dataclasses import dataclass


@dataclass
class Output:
    result_id: str = ""
    status: str = ""
    error_type: str = ""
    error_message: str = ""


def main(input: Input) -> Output:
    try:
        result = process_data(input)
        return Output(result_id=result, status="success")
    except ValidationError as exc:
        return Output(status="error", error_type="VALIDATION_ERROR", error_message=str(exc))

仅捕获您能有意义描述的异常。传播意外错误，从而导致作业发生故障 — 使其在 Orchestrator 作业历史记录中完整显示原始消息。

后续步骤

• 访问平台服务— 在运行时读取资产和文件。
• 追踪和可观察性— 使执行步骤在追踪记录中可见。