
Jira REST Java Client (JRJC) 是 Atlassian 官方提供的 Java 库,用于与 Jira REST API 进行交互。它封装了底层的 HTTP 请求和 JSON 解析,使得 Java 开发者能够更便捷地执行 Jira 操作,如创建、更新、查询 Issue 等。在 Jira 中,除了标准字段(如概要、描述、报告人)之外,自定义字段(Custom Fields)允许用户根据项目和业务需求添加额外的属性,这些字段对于捕获特定信息至关重要。
使用 JRJC 创建 Issue 的基本流程通常涉及构建一个 IssueInput 对象,其中包含项目的键、Issue 类型、概要和描述等信息。以下是一个典型的 Issue 创建代码示例:
import com.atlassian.jira.rest.client.api.JiraRestClient;
import com.atlassian.jira.rest.client.api.domain.IssueType;
import com.atlassian.jira.rest.client.api.domain.input.IssueInput;
import com.atlassian.jira.rest.client.api.domain.input.IssueInputBuilder;
// 假设 jira 实例已初始化为 JiraRestClient
JiraRestClient jira = /* ... 初始化 JiraRestClient ... */;
String projectKey = "TEST"; // 替换为你的项目键
String summary = "这是我的新 Issue 概要";
String description = "这是一个通过 JRJC 创建的 Issue 描述。";
// 获取 Issue 类型 ID
Long testIssueTypeId = getTestIssueTypeId(projectKey); // 假设此方法能获取到 Issue 类型 ID
IssueInputBuilder builder = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description);
IssueInput input = builder.build();
// 执行 Issue 创建
// return jira.getIssueClient().createIssue(input).claim();
System.out.println("Issue 创建请求已构建。"); // 实际创建会调用 .claim()在上述基本流程中,如果需要设置自定义字段,开发者通常会尝试使用 IssueInputBuilder.setFieldValue() 方法。然而,在设置自定义字段时,一个常见的错误是遇到 RestClientException,状态码为 400 (Bad Request),错误信息通常类似于:Field 'Test Type' cannot be set. It is not on the appropriate screen, or unknown.
// 尝试设置自定义字段的代码示例 (可能导致错误)
// 假设 'Test Type' 是一个自定义字段,且其选项 ID 为 14314
// import com.atlassian.jira.rest.client.api.domain.CustomFieldOption; // 可能需要引入
IssueInputBuilder builderWithCustomField = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description)
// 尝试使用自定义字段名称 'Test Type'
.setFieldValue("Test Type",
new CustomFieldOption(14314L, null, "Functional", null, null));
// 当执行 createIssue(builderWithCustomField.build()).claim() 时,可能抛出 RestClientException这个错误提示非常关键,它指出了两个主要原因:
要解决上述错误,需要从 Jira 配置和 API 调用两方面入手:
这是解决“字段不在适当的屏幕上”问题的核心。
确保用于 JRJC 连接的 Jira 用户账户具有以下权限:
一旦 Jira 配置(屏幕和权限)正确,我们就可以通过 JRJC 正确设置自定义字段了。关键在于使用自定义字段的 ID 而非其名称,并根据字段类型提供正确的值格式。
在 JRJC 中设置自定义字段时,setFieldValue() 方法需要自定义字段的唯一 ID,格式通常为 customfield_XXXXX。获取这个 ID 的最可靠方法是通过 Jira REST API 浏览器或 Jira 管理界面:
例如,如果“Test Type”的 ID 是 customfield_10002,那么在 JRJC 中就应该使用这个 ID。
示例一:设置选择列表(Select List)类型的自定义字段
对于单选或多选列表,通常需要提供选项的 ID 或值。如果 JSON 示例中显示 value:"NA:12345" 和 id:"14314",这意味着你可以通过 CustomFieldOption 对象来设置。
import com.atlassian.jira.rest.client.api.domain.CustomFieldOption;
import com.atlassian.jira.rest.client.api.domain.input.IssueInputBuilder;
// 假设 customFieldIdForApplication 是 "customfield_10001"
String customFieldIdForApplication = "customfield_10001";
Long optionId = 14314L; // 选项的 ID,来自 Jira 配置或 createmeta
String optionValue = "NA:12345"; // 选项的显示值或内部值
IssueInputBuilder builder = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description)
// 正确使用自定义字段 ID,并提供 CustomFieldOption 对象
.setFieldValue(customFieldIdForApplication,
new CustomFieldOption(optionId, null, optionValue, null, null));
IssueInput input = builder.build();
// jira.getIssueClient().createIssue(input).claim();
System.out.println("已为自定义字段 'Application' 构建 Issue 创建请求。");注意事项: CustomFieldOption 构造函数中的 id 和 value 参数是关键。id 是选项的唯一标识符,value 是选项的显示文本。根据 Jira 版本和字段配置,有时只需要提供 id,有时则需要同时提供 id 和 value。通过 createmeta API 可以查看字段期望的 JSON 结构。
示例二:设置文本(Text Field)类型的自定义字段
对于单行文本、多行文本或 URL 字段,直接提供字符串值即可。
// 假设 customFieldIdForText 是 "customfield_10003"
String customFieldIdForText = "customfield_10003";
String customFieldValue = "这是一个自定义文本字段的值。";
IssueInputBuilder builder = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description)
// 直接提供字符串值
.setFieldValue(customFieldIdForText, customFieldValue);
IssueInput input = builder.build();
// jira.getIssueClient().createIssue(input).claim();
System.out.println("已为自定义文本字段构建 Issue 创建请求。");示例三:设置用户选择器(User Picker)类型的自定义字段
对于用户选择器,需要提供 BasicUser 或 User 对象。
import com.atlassian.jira.rest.client.api.domain.BasicUser;
import com.atlassian.jira.rest.client.api.domain.input.IssueInputBuilder;
// 假设 customFieldIdForUserPicker 是 "customfield_10004"
String customFieldIdForUserPicker = "customfield_10004";
String username = "jirauser"; // Jira 用户的用户名或 accountId
// 可以通过 JiraRestClient 获取 BasicUser 对象
// BasicUser assignee = jira.getUserClient().getUser(username).claim();
// 如果没有现成的 BasicUser,可以手动构造一个,但确保 username 正确
BasicUser selectedUser = new BasicUser(null, username, username, null);
IssueInputBuilder builder = new IssueInputBuilder()
.setProjectKey(projectKey)
.setIssueTypeId(testIssueTypeId)
.setSummary(summary)
.setDescription(description)
.setFieldValue(customFieldIdForUserPicker, selectedUser);
IssueInput input = builder.build();
// jira.getIssueClient().createIssue(input).claim();
System.out.println("已为自定义用户选择器字段构建 Issue 创建请求。");通过 JRJC 在 Jira Server 中设置自定义字段,核心在于理解 Jira 的屏幕配置机制、确保正确的用户权限,并使用自定义字段的唯一 ID。在编写代码之前,务必通过 Jira 管理界面或 createmeta REST API 确认自定义字段的 ID 及其期望的值格式。遵循这些最佳实践,可以有效避免常见的“字段无法设置”错误,并成功地通过编程方式管理 Jira Issue 的自定义属性。
以上就是Jira Server REST API:使用 JRJC 正确设置自定义字段的详细内容,更多请关注php中文网其它相关文章!
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移,垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是,许多工具可以让 Windows 保持平稳运行。
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号