轻松通过 API 远程触发 Jenkins 任务-CSDN博客

本文链接：https://blog.csdn.net/weixin_39660059/article/details/148034623

在本文中，我将指导您轻松完成远程触发 Jenkins 构建的过程。无论您是要实现自动化部署、与其他工具集成，还是仅仅希望简化工作流程，了解如何远程执行 Jenkins 作业都能为您的工具箱锦上添花。让我们深入了解相关步骤和最佳实践，让此过程尽可能顺畅高效。

步骤 1：创建新用户

1.在 Jenkins 仪表板中，点击左侧的“管理 Jenkins”。
2.在“管理 Jenkins”页面中，点击“用户”选项。

点击“+ 创建用户”
填写必填字段：
用户名：新用户的用户名。
密码：输入一个强密码。
确认密码：再次输入密码。
全名：用户的全名。
电子邮件地址：用户的电子邮件地址。

3. 点击“创建用户”完成新用户的创建。

步骤 2：生成 API 令牌

创建用户后，请以新用户身份登录；如果您仍以管理员身份登录，请继续。
点击 Jenkins 仪表板右上角的用户名，打开选项菜单，然后选择“安全”。您也可以点击用户名前往用户个人资料，在那里您可以找到相同的选项。
点击“添加新令牌”
输入令牌的名称以便识别（例如，“我的 API 令牌”）。
点击“生成”
将生成一个新的 API 令牌。复制该令牌并将其保存在安全的位置。（注意：现在复制此令牌，因为它将来无法恢复。）

步骤 3：使用 API 令牌

现在，您可以在向 Jenkins 发出 API 调用时使用此 API 令牌作为密码。请将其与您的用户名结合使用，以验证请求。

curl JENKINS_URL/job/JOB_NAME/buildWithParameters \
--user USER:TOKEN \
--data param1=123 --data param2=value

另一个示例——发送文件参数：

curl JENKINS_URL/job/JOB_NAME/buildWithParameters \
--user USER:PASSWORD \
--form FILE_LOCATION_AS_SET_IN_JENKINS=@PATH_TO_FILE

现在，让我们快速看一个例子。在本例中，我们有一个名为“lockable-pipeline”的作业，我们希望使用 curl 通过 API 远程运行它。

如果启用CSRF保护，需要先生成一个crumb, 运行下面的命令：

curl -u admin:api_token http://localhost:8080/crumbIssuer/api/xml

<defaultCrumbIssuer _class='hudson.security.csrf.DefaultCrumbIssuer'><crumb>69bd14e04d1dedeca7efdc4bb8a5e21beba08588fbfb4618636251de0ce13006</crumb><crumbRequestField>Jenkins-Crumb</crumbRequestField></defaultCrumbIssuer>%

您还可以添加 -i 选项，告诉 curl 在响应输出中包含 HTTP 标头：

ninjamac@192 ~ % curl -i -X POST -u admin:11882dc449b5a93472513779efa9df33a0 \
     -H "Jenkins-Crumb: 69bd14e04d1dedeca7efdc4bb8a5e21beba08588fbfb4618636251de0ce13006" \
     http://localhost:8080/job/lockable-pipeline/build

运行上述命令后，您将在输出中收到包含相关信息的标头的响应。以下是响应的示例：

HTTP/1.1 201 Created
Server: Jetty(12.0.19)
Date: Sat, 17 May 2025 14:11:25 GMT
Vary: Accept-Encoding
X-Content-Type-Options: nosniff
Location: http://localhost:8080/queue/item/65/
Content-Length: 0

此标头非常重要，因为 Location 字段返回的 URL 指向 Jenkins 队列中的项目。您可以使用此链接检查队列中作业的状态。

现在，让我们看看如何在 Jenkins 构建完成后检索其相关信息。本教程的这一部分将使用本地实例 (127.0.0.1:8080)。操作方法如下：获取构建执行的标头后，我们将请求构建信息。

首先，我们需要请求一个 Crumb 来授权我们的请求：

curl -u USER_NAME:USER_TOKEN "http://127.0.0.1:8080/crumbIssuer/api/json"

如果所有设置正确，您应该会收到如下响应：

{"_class":"hudson.security.csrf.DefaultCrumbIssuer","crumb":"CRUMB_VALUE","crumbRequestField":"Jenkins-Crumb"}

Crumb，即 CSRF（跨站请求伪造）令牌，用于保护系统免受跨站请求伪造攻击。在 Jenkins 环境中，Crumb 有助于防止攻击者以经过身份验证的用户身份执行未经授权的请求。

最后，要从之前获取的标头（特别是 Location 标头）中检索生成的构建信息，请使用以下命令：

curl --user USER_NAME:USER_TOKEN \
  -H "Jenkins-Crumb: CRUMB_VALUE" \
  "http://127.0.0.1:8080/queue/item/item_id/api/json"

此响应包含 Crumb（CSRF 保护令牌）以及用于在后续请求中包含 Crumb 的字段名称。

如果一切顺利，您将看到如下响应：

{
   "_class":"hudson.model.Queue$LeftItem",
   "actions":[
      {
         "_class":"hudson.model.CauseAction",
         "causes":[
            {
               "_class":"hudson.model.Cause$UserIdCause",
               "shortDescription":"Started by user admin",
               "userId":"admin",
               "userName":"admin"
            }
         ]
      }
   ],
   "blocked":false,
   "buildable":false,
   "id":70,
   "inQueueSince":1747491888311,
   "params":"",
   "stuck":false,
   "task":{
      "_class":"org.jenkinsci.plugins.workflow.job.WorkflowJob",
      "name":"lockable-pipeline",
      "url":"http://192.168.1.2:8080/job/lockable-pipeline/",
      "color":"aborted_anime"
   },
   "url":"queue/item/70/",
   "why":null,
   "cancelled":false,
   "executable":{
      "_class":"org.jenkinsci.plugins.workflow.job.WorkflowRun",
      "number":7,
      "url":"http://192.168.1.2:8080/job/lockable-pipeline/7/"
   }
}"%"

总结：

本文详细介绍了如何远程触发Jenkins构建，以实现自动化部署、工具集成或简化工作流程。首先，需在Jenkins中创建新用户并生成API令牌，该令牌将用于验证API请求。接着，通过curl命令使用API令牌远程执行Jenkins作业，并处理CSRF保护所需的Crumb。最后，文章展示了如何检索构建信息，包括使用Crumb进行授权和从响应标头中获取构建状态。整个过程旨在确保远程触发Jenkins构建的安全性和高效性。