使用Python构建Jenkins任务：复选框参数Topo_Traffic_Type传递失败排查

问题场景 #

使用Python的jenkins库触发Jenkins任务构建，代码如下：

jenkins_server = jenkins.Jenkins(project_path, username="moyemoye", password=password, timeout=120)
parameters = {
    'IMG_PATH': "IMG_PATH",
    'vcpu': "2",
    'Topo_Traffic_Type': "imix,1518/1400",
    'RUN_CEF_SUITE_FEATURE_LIST': "all",
    'clean_reload': True,
}
jenkins_server.build_job(f"{project_name}", parameters=parameters, token=password)

其中RUN_CEF_SUITE_FEATURE_LIST和Topo_Traffic_Type均为Jenkins「Basic Parameter Types」下的复选框类型参数。目前RUN_CEF_SUITE_FEATURE_LIST（单选项勾选）可正常填充，但Topo_Traffic_Type参数始终为空，导致任务执行失败。

已尝试的参数格式 #

以下几种参数格式均未解决问题：

'Topo_Traffic_Type': ["imix", "1518/1400"]
'Topo_Traffic_Type': "imix,1518/1400"
'Topo_Traffic_Type': [{"imix": True}, {"1518/1400": True}]
'Topo_Traffic_Type': {"imix": True, "1518/1400": True},

原因分析 #

1. 复选框显示值与实际提交值不匹配：代码中使用的imix、1518/1400可能只是Jenkins界面上的显示名称，而非选项对应的实际提交值。Jenkins复选框的每个选项都有「显示名称」和「值」两个字段，若两者不一致，传递显示名称会导致参数无法被识别。
2. python-jenkins库版本兼容问题：旧版本的python-jenkins库对多值复选框参数的处理存在缺陷，无法正确解析列表格式的参数，导致传递内容失效。
3. 参数编码逻辑问题：部分场景下build_job方法会自动对参数进行编码，把列表格式转成字符串，不符合Jenkins API对多值参数的识别要求。

解决方法 #

方法1：确认Jenkins复选框的实际参数值 #

进入Jenkins任务的「配置」页面，找到Topo_Traffic_Type复选框参数，查看每个选项的「值」字段：

• 若选项的「值」和显示名称一致，跳过此步；
• 若不一致，将代码中的参数值替换为Jenkins配置里的实际「值」。

方法2：升级python-jenkins库并使用列表格式传递 #

执行命令升级库：

pip install --upgrade python-jenkins

修改参数为列表格式：

parameters = {
    # 其他参数保持不变
    'Topo_Traffic_Type': ["imix", "1518/1400"]
}

新版本库会自动将列表格式的参数转换为Jenkins API可识别的多值格式。

方法3：直接调用Jenkins API传递参数（绕过库封装） #

如果升级库后仍无效，可直接构造API请求：

import requests
from requests.auth import HTTPBasicAuth

# 构建符合Jenkins API规范的请求参数
payload = {
    'json': {
        'parameter': [
            {'name': 'IMG_PATH', 'value': 'IMG_PATH'},
            {'name': 'vcpu', 'value': '2'},
            {'name': 'Topo_Traffic_Type', 'value': ["imix", "1518/1400"]},
            {'name': 'RUN_CEF_SUITE_FEATURE_LIST', 'value': 'all'},
            {'name': 'clean_reload', 'value': True}
        ]
    },
    'token': password
}

# 发送POST请求触发构建
response = requests.post(
    f"{project_path}/job/{project_name}/build",
    auth=HTTPBasicAuth("moyemoye", password),
    data=payload,
    timeout=120
)
response.raise_for_status()  # 检查请求是否成功

这种方式直接遵循Jenkins API的参数规范，避免库封装带来的兼容性问题。

内容的提问来源于stack exchange，提问作者Akshay J