Интеграция JIRA REST API

1. Введение

В этой статье мы кратко рассмотрим, как интегрироваться с JIRA с помощью REST API.

2. Зависимость от Maven

Необходимые артефакты можно найти в общедоступном репозитории 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:

• имя пользователя — это имя пользователя любого действительного пользователя Jira.
• пароль — это пароль этого пользователя
• jiraUrl — это URL-адрес, на котором размещен экземпляр Jira.

Получив эти данные, мы можем создать экземпляр нашего клиента 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();
}

Ключ проекта — это уникальный идентификатор, определяющий ваш проект. Это не что иное, как префикс, который добавляется ко всем нашим проблемам. Следующий аргумент, issueType , также зависит от проекта и определяет тип ваших задач, таких как «Задача» или «История». The issueSummary — это название нашего выпуска.

Задача передается как экземпляр IssueInput в остальной API. Помимо входных данных, которые мы описали, такие вещи, как правопреемник, репортер, затронутые версии и другие метаданные, могут быть переданы как IssueInput .

3.2. Обновить описание проблемы

Каждая задача в Jira идентифицируется уникальной строкой , например « MYKEY-123 ». Нам нужен этот ключ задачи для взаимодействия с остальным 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));
}

Мы использовали фабричный метод valueOf() , предоставляемый классом Comment , для создания экземпляра Comment . Существуют различные другие фабричные методы для расширенных вариантов использования, таких как управление видимостью 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 и выполняет некоторые основные операции.

Полный исходный код этой статьи можно найти на GitHub .