JIRA REST API Integration – JIRA REST API集成

最后修改: 2017年 10月 11日

中文/混合/英文(键盘快捷键：t)

1. Introduction

1.介绍

In this article, we’ll have a quick look at how to integrate with the JIRA using its REST API.

在这篇文章中，我们将快速了解如何使用JIRA的REST API与之集成。

2. Maven Dependency

2.Maven的依赖性

The required artifacts can be found in Atlassian’s public Maven repository:

所需的工件可以在Atlassian的公共Maven资源库中找到。

<repository>
    <id>atlassian-public</id>
    <url>https://packages.atlassian.com/maven/repository/public</url>
</repository>

Once the repository is added to the pom.xml, we need to add the below dependencies:

一旦资源库被添加到pom.xml，我们需要添加以下的依赖。

<dependency>
    <groupId>com.atlassian.jira</groupId>
    <artifactId>jira-rest-java-client-core</artifactId>
    <version>4.0.0</version>
</dependency>
<dependency>
    <groupId>com.atlassian.fugue</groupId>
    <artifactId>fugue</artifactId>
    <version>2.6.1</version>
</dependency>

You can refer to Maven Central for the latest versions of core and fugue dependencies.

您可以参考Maven Central，了解core和fugue的最新依赖版本。

3. Creating a Jira Client

3.创建一个Jira客户端

First, let’s have a look at some basic information that we need to be able to connect to a Jira instance:

首先，让我们看一下我们需要的一些基本信息，以便能够连接到Jira实例。

  • username – is the username of any valid Jira user
  • password – is the password of that user
  • jiraUrl – is the URL where the Jira instance is hosted

Once we have these details, we can instantiate our Jira Client:

一旦我们有了这些细节，我们就可以实例化我们的Jira客户端。

MyJiraClient myJiraClient = new MyJiraClient(
  "user.name", 
  "password", 
  "http://jira.company.com");

The constructor of this class:

该类的构造函数。

public MyJiraClient(String username, String password, String jiraUrl) {
    this.username = username;
    this.password = password;
    this.jiraUrl = jiraUrl;
    this.restClient = getJiraRestClient();
}

The getJiraRestClient() utilizes all the information provided and returns an instance of JiraRestClient. This is the main interface through which we’ll communicate with the Jira REST API:

getJiraRestClient()利用所有提供的信息并返回JiraRestClient的实例。这是我们与Jira REST API通信的主要接口。

private JiraRestClient getJiraRestClient() {
    return new AsynchronousJiraRestClientFactory()
      .createWithBasicHttpAuthentication(getJiraUri(), this.username, this.password);
}

Here, we’re using the basic authentication to communicate with the API. However, more sophisticated authentication mechanisms like OAuth are also supported.

在这里，我们使用基本认证来与API通信。然而，也支持更复杂的认证机制，如OAuth。

The getUri() method simply converts the jiraUrl into an instance of java.net.URI:

getUri()方法只是将jiraUrl转换为java.net.URI的实例。

private URI getJiraUri() {
    return URI.create(this.jiraUrl);
}

This concludes our infrastructure of creating a custom Jira client. We can now have a look at various ways to interact with the API.

我们创建自定义Jira客户端的基础架构到此结束。我们现在可以看看与API互动的各种方式。

3.1. Create a New Issue

3.1.创建一个新问题

Let’s start by creating a new issue. We will use this newly created issue for all other examples in this article:

让我们从创建一个新问题开始。我们将在本文的所有其他例子中使用这个新创建的问题。

public String createIssue(String projectKey, Long issueType, String issueSummary) {
    IssueRestClient issueClient = restClient.getIssueClient();
    IssueInput newIssue = new IssueInputBuilder(
      projectKey, issueType, issueSummary).build();
    return issueClient.createIssue(newIssue).claim().getKey();
}

The projectKey is the unique that defines your project. This is nothing but the prefix that is appended to all of our issues. The next argument, issueType is also project dependent that identifies the type of your issues like “Task” or “Story”. The issueSummary is the title of our issue.

projectKey是定义你的项目的唯一。这只不过是附加在我们所有问题上的前缀。下一个参数，issueType也与项目有关，它确定了你的问题的类型，如 “任务 “或 “故事”。issueSummary是我们问题的标题。

The issue goes as an instance of IssueInput to the rest API. Apart from the inputs that we described, things like assignee, reporter, affected versions, and other metadata can go as an IssueInput.

问题作为IssueInput的一个实例进入其余API。除了我们描述的输入外，像受让人、报告人、受影响的版本和其他元数据也可以作为IssueInput。

3.2. Update Issue Description

3.2.更新问题描述

Each issue in Jira is identified by a unique String like “MYKEY-123“. We need this issue key to interact with the rest API and update the description of the issue:

Jira中的每个问题都由一个独特的String标识，比如”MYKEY-123“。我们需要这个问题的密钥来与其他API交互，并更新问题的描述。

public void updateIssueDescription(String issueKey, String newDescription) {
    IssueInput input = new IssueInputBuilder()
      .setDescription(newDescription)
      .build();
    restClient.getIssueClient()
      .updateIssue(issueKey, input)
      .claim();
}

Once the description is updated, let’s not read back the updated description:

一旦描述被更新，我们就不要再读回更新的描述了。

public Issue getIssue(String issueKey) {
    return restClient.getIssueClient()
      .getIssue(issueKey) 
      .claim();
}

The Issue instance represents an issue identified by the issueKey. We can use this instance to read the description of this issue:

Issue实例代表一个由issueKey标识的问题。我们可以使用这个实例来阅读这个问题的描述。

Issue issue = myJiraClient.getIssue(issueKey);
System.out.println(issue.getDescription());

This will print the description of the issue to the console.

这将把问题的描述打印到控制台。

3.3. Vote for an Issue

3.3.为一个问题投票

Once we have an instance of Issue obtained, we can use it to perform update/edit actions as well. Let’s vote for the issue:

一旦我们获得了问题的实例，我们也可以用它来执行更新/编辑的动作。让我们为这个问题投票吧。

public void voteForAnIssue(Issue issue) {
    restClient.getIssueClient()
      .vote(issue.getVotesUri())
      .claim();
}

This will add the vote to the issue on behalf of the user whose credentials were used. This can be verified by checking the vote count:

这将代表使用证书的用户将投票添加到问题中。这可以通过检查投票数来验证。

public int getTotalVotesCount(String issueKey) {
    BasicVotes votes = getIssue(issueKey).getVotes();
    return votes == null ? 0 : votes.getVotes();
}

One thing to note here is that we are again fetching a fresh instance of Issue here as we want to get the updated vote count reflected.

这里需要注意的是，我们在这里再次获取了一个新的Issue实例，因为我们希望得到更新的投票数的反映。

3.4. Adding a Comment

3.4.添加评论

We can use the same Issue instance to add a comment on behalf of the user. Like adding a vote, adding a comment is also pretty simple:

我们可以使用同一个Issue实例来代表用户添加评论。像添加投票一样，添加评论也很简单。

public void addComment(Issue issue, String commentBody) {
    restClient.getIssueClient()
      .addComment(issue.getCommentsUri(), Comment.valueOf(commentBody));
}

We used the factory method valueOf() provided by the Comment class to create an instance of a Comment. There are various other factory methods for advanced use cases, such as controlling the visibility of a Comment.

我们使用Comment类提供的工厂方法valueOf()来创建一个Comment的实例。还有其他各种工厂方法用于高级用例，例如控制Comment的可见性。

Let’s fetch a fresh instance of the Issue and read all the Comments:

让我们获取一个新的Issue实例并读取所有的Comments。

public List<Comment> getAllComments(String issueKey) {
    return StreamSupport.stream(getIssue(issueKey).getComments().spliterator(), false)
      .collect(Collectors.toList());
}

3.5. Delete an Issue

3.5.删除一个问题

Deleting an issue is also fairly simple. We only need the issue key that identifies the issue:

删除一个问题也相当简单。我们只需要识别该问题的问题键。

public void deleteIssue(String issueKey, boolean deleteSubtasks) {
    restClient.getIssueClient()
      .deleteIssue(issueKey, deleteSubtasks)
      .claim();
}

4. Conclusion

4.结论

In this quick article, we created a simple Java client that integrates with the Jira REST API and performs some of the basic operations.

在这篇快速文章中，我们创建了一个简单的Java客户端，与Jira REST API集成并执行一些基本操作。

The full source of this article can be found over on GitHub.

这篇文章的完整来源可以在GitHub上找到over。