如何使用Jenkins REST API执行构建？能否实现带参数的SCM轮询构建？

Great question! Let's break this down step by step, covering both basic build execution and the specific scenario you're curious about.

基础构建执行方法 #

First, let's recap the standard ways to trigger builds via the Jenkins REST API, with a bit more context to your initial notes:

• 无参数构建: Send a POST request to job/<your-job-name>/build
• 带参数构建: Use the buildWithParameters endpoint, appending your parameters to the URL like this: job/<your-job-name>/buildWithParameters?param1=value1&param2=value2. For sensitive parameters, you can also pass them in the request body (as form data or JSON) instead of the URL to avoid exposure.
• SCM轮询构建: Trigger a poll for SCM changes with a POST request to job/<your-job-name>/polling. This tells Jenkins to check your source control for updates, and only start a build if changes are detected.

带参数的SCM轮询构建：可行吗？当然可以！ #

The short answer is yes, but you can't just combine the two endpoints directly (appending parameters to the polling URL won't pass them to the resulting build). Here are the most reliable ways to make this work:

方式1：用buildWithParameters强制触发轮询+传递参数 #

This is the most straightforward approach. Add the forcePolling=true (or scmPoll=true for newer Jenkins versions) parameter to your buildWithParameters request. This tells Jenkins to run an SCM poll first, then start a build with your specified parameters—you can adjust job settings to only build on changes if needed, or force a build regardless.

The request URL looks like this:

job/<your-job-name>/buildWithParameters?param1=value1&param2=value2&forcePolling=true

For example, using curl with sensitive parameters in the request body:

curl -X POST -u your-username:your-api-token "http://your-jenkins-url/job/MyJob/buildWithParameters" \
--data-urlencode "ENV=production" \
--data-urlencode "DEPLOY_VERSION=v1.2.3" \
--data-urlencode "forcePolling=true"

方式2：配置Job默认参数，再触发轮询 #

If your parameters are static (don't need to change per request), you can set default values for the build parameters in your Jenkins job configuration. Then, when you trigger the polling endpoint, Jenkins will use those default parameters for any build that starts as a result of the poll. This is ideal for fixed parameter scenarios.

方式3：先轮询，再根据结果触发带参数构建 #

If you only want to trigger a build with parameters when changes are detected, you can split this into two steps:

1. Send a POST request to job/<your-job-name>/polling to start the SCM poll
2. Call job/<your-job-name>/lastBuild/api/json to check if the poll detected changes (look at the changeSet field). If changes exist, send a buildWithParameters request with your parameters.

This requires extra logic to check the poll result, so it's more complex than the first two methods.

关键注意事项 #

• Permissions: Make sure the user account you're using has both Job/Build and Job/Poll permissions in Jenkins—missing either will result in authorization errors.
• API Tokens: Always use an API token instead of your password for authentication (you can generate one in your Jenkins user profile).

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