JIRA REST API 集成

1. 引言

本文將快速介紹如何使用 JIRA 的 REST API 進行集成。

2. Maven 依賴

所需 Artifact 可以找到在 Atlassian 的公共 Maven 倉庫中：

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

一旦倉庫添加到 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>

你可以參考 Maven Central 獲取 core 和 fugue 依賴的最新版本。

3. 創建 Jira 客户端

首先，讓我們來了解一下連接到 Jira 實例所需的基本信息：

username – 是任何有效的 Jira 用户名
password – 是該用户的密碼
jiraUrl – 是 Jira 實例託管的 URL

一旦我們有了這些信息，就可以實例化 Jira 客户端：

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

該類的構造函數：

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

getJiraRestClient() 方法利用所有提供的信息，並返回一個 JiraRestClient 實例。這是我們與 Jira REST API 進行通信的主要接口：

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

在這裏，我們使用基本身份驗證來與API進行通信。但是，OAuth等更復雜的身份驗證機制也得到支持。

getUri()方法只是將jiraUrl轉換為java.net.URI的實例：

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

以下是翻譯後的內容：

本文檔的結尾是關於構建自定義 Jira 客户端的基礎。現在我們可以探討與 API 交互的各種方式。

3.1. 創建新問題

讓我們從創建一個新問題開始。我們將使用這個新創建的問題，並在本文檔中的所有其他示例中使用它：

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();
}

projectKey 是唯一標識您的項目的鍵。它只是所有我們 issue 的前綴。下一個參數 issueType 也取決於項目，用於標識您的 issue 的類型，例如“任務”或“故事”。issueSummary 是 issue 的標題。

issue 作為 IssueInput 的實例發送到 REST API。除了我們描述的輸入之外，分配人、報告人、受影響的版本和其他元數據也可以作為 IssueInput。

3.2. 更新問題描述

每個 Jira 問題都通過一個唯一的 String 進行標識，例如 "MYKEY-123"。我們需要此問題鍵才能與 REST API 交互並更新問題的描述：

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

一旦描述更新完畢，我們就不需要再閲讀更新後的描述：

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

Issue 實例代表由issueKey標識的問題。我們可以使用該實例來讀取該問題的描述：

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

這將把問題的描述打印到控制枱。

3.3. 投票選擇問題

一旦我們獲取到 Issue 實例，我們還可以使用它執行更新/編輯操作。現在，讓我們為該問題投票：

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

這將會為使用憑據的用户添加投票，代表該用户在問題上投票。可以通過檢查投票計數來驗證。

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

需要注意的是，我們再次獲取 Issue 的最新實例，以便反映更新後的投票數。

3.4. 添加評論

我們可以使用相同的 Issue 實例代表用户添加評論。類似於添加投票，添加評論也非常簡單：

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

我們使用 Comment 類提供的工廠方法 valueOf() 來創建一個 Comment 實例。還有其他工廠方法適用於高級用例，例如控制 Comment 的可見性。

讓我們獲取一個新的 Issue 實例並讀取所有 Comment：

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

3.5. 刪除問題

刪除問題也很簡單。只需要問題鍵來標識該問題：

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

4. 結論

在本文中，我們創建了一個簡單的 Java 客户端，該客户端與 Jira REST API 集成，並執行了一些基本操作。

知識庫 / REST RSS 訂閱