«Интеграция JIRA REST API» - Spring на русском

«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. 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, также зависит от проекта и определяет тип ваших задач, например «Task» или «Story». 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();
}

Экземпляр задачи представляет собой проблема, идентифицированная issueKey. Мы можем использовать этот экземпляр для чтения описания этой проблемы:

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

Это выведет описание проблемы на консоль.

3.3. Проголосуйте за задачу

После того, как мы получим экземпляр задачи, мы также можем использовать ее для выполнения действий по обновлению/редактированию. Давайте проголосуем за проблему:

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

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

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.

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