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

1. Вступление

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

2. Maven Dependency

Необходимые артефакты можно найти в публичном репозитории Maven Atlassian:


    atlassian-public
    https://packages.atlassian.com/maven/repository/public

Как только репозиторий добавлен вpom.xml, нам нужно добавить следующие зависимости:


    com.atlassian.jira
    jira-rest-java-client-core
    4.0.0


    com.atlassian.fugue
    fugue
    2.6.1

Вы можете обратиться к Maven Central за последними версиями зависимостейcore иfugue.

3. Создание клиента Jira

Во-первых, давайте взглянем на некоторую основную информацию, которая нам нужна для подключения к экземпляру Jira:

username - имя любого действующего пользователя Jira
password - пароль этого пользователя
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();
}

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

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

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

Каждая проблема в 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();
}

После обновления описания не будем зачитывать обновленное описание:

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

Это добавит голосissue от имени пользователя, учетные данные которого были использованы. Это можно проверить, проверив количество голосов:

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.

Давайте возьмем новый экземплярIssue и прочитаем всеComments:

public List 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 и выполняет некоторые основные операции.

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

TOC

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