Integração da API JIRA REST

1. Introdução

Neste artigo, daremos uma olhada rápida em como se integrar ao JIRA usando sua API REST.

2. Dependência do Maven

Os artefatos necessários podem ser encontrados no repositório Maven público da Atlassian:


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

Depois que o repositório é adicionado apom.xml, precisamos adicionar as dependências abaixo:


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


    com.atlassian.fugue
    fugue
    2.6.1

Você pode consultar o Maven Central para obter as versões mais recentes das dependênciascoreefugue.

3. Criando um cliente Jira

Primeiro, vamos dar uma olhada em algumas informações básicas de que precisamos para nos conectar a uma instância Jira:

username - é o nome de usuário de qualquer usuário Jira válido
password - é a senha desse usuário
jiraUrl - é o URL onde a instância Jira está hospedada

Quando tivermos esses detalhes, podemos instanciar nosso cliente Jira:

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

O construtor desta classe:

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

OgetJiraRestClient() utiliza todas as informações fornecidas e retorna uma instância deJiraRestClient. Esta é a interface principal por meio da qual nos comunicaremos com a API Jira REST:

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

Aqui, estamos usando a autenticação básica para nos comunicarmos com a API. No entanto, mecanismos de autenticação mais sofisticados como o OAuth também são suportados.

O métodogetUri() simplesmente convertejiraUrl em uma instância dejava.net.URI:

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

Isso conclui nossa infraestrutura de criação de um cliente Jira personalizado. Agora podemos ver várias maneiras de interagir com a API.

3.1. Criar um novo problema

Vamos começar criando um novo problema. Usaremos esse problema recém-criado para todos os outros exemplos neste artigo:

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

OprojectKey é o único que define seu projeto. Este é apenas o prefixo anexado a todos os nossos problemas. O próximo argumento,issueType também é dependente do projeto que identifica o tipo de seus problemas como “Tarefa” ou “História”. OissueSummary é o título do nosso problema.

O problema vai como uma instância deIssueInput para a API restante. Além das entradas que descrevemos, coisas como destinatário, relator, versões afetadas e outros metadados podem ir comoIssueInput.

3.2. Atualizar descrição do problema

Cada problema em Jira é identificado por umString exclusivo, como “MYKEY-123“. Precisamos desta chave do problema para interagir com a API restante e atualizar a descrição do problema:

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

Depois que a descrição for atualizada, não vamos reler a descrição atualizada:

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

A instânciaIssue representa um problema identificado porissueKey. Podemos usar esta instância para ler a descrição desse problema:

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

Isso imprimirá a descrição do problema no console.

3.3. Vote em um problema

Depois de obter uma instância do problema, também podemos usá-la para executar ações de atualização / edição. Vamos votar no problema:

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

Isso adicionará o voto aissue em nome do usuário cujas credenciais foram usadas. Isso pode ser verificado verificando a contagem de votos:

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

Uma coisa a observar aqui é que estamos novamente buscando uma nova instância deIssue aqui, pois queremos que a contagem de votos atualizada seja refletida.

3.4. Adicionando um Comentário

Podemos usar a mesma instânciaIssue para adicionar um comentário em nome do usuário. Como adicionar um voto, adicionar um comentário também é bastante simples:

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

Usamos o método de fábricavalueOf() fornecido pela classeComment para criar uma instância deComment. Existem vários outros métodos de fábrica para casos de uso avançados, como controlar a visibilidade de aComment.

Vamos buscar uma nova instância deIssuee ler todos osComments:

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

3.5. Excluir um problema

Excluir um problema também é bastante simples. Precisamos apenas da chave do problema que identifica o problema:

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

4. Conclusão

Neste artigo rápido, criamos um cliente Java simples que se integra à API REST do Jira e executa algumas das operações básicas.

A fonte completa deste artigo pode ser encontradaover on GitHub.

TOC

Integração da API JIRA REST