JIRA REST API Integrazione

1. Introduzione

In questo articolo, daremo una rapida occhiata a come eseguire l'integrazione con JIRA utilizzando la sua API REST.

2. Dipendenza da Maven

Gli artefatti richiesti possono essere trovati nel repository pubblico Maven di Atlassian:

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

Una volta che il repository è stato aggiunto a pom.xml , dobbiamo aggiungere le seguenti dipendenze:

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

Puoi fare riferimento a Maven Central per le ultime versioni delle dipendenze core e fugue .

3. Creazione di un client Jira

Per prima cosa, diamo un'occhiata ad alcune informazioni di base di cui abbiamo bisogno per poterci connettere a un'istanza Jira:

  • nome utente : è il nome utente di qualsiasi utente Jira valido
  • password - è la password di quell'utente
  • jiraUrl : è l'URL in cui è ospitata l'istanza Jira

Una volta acquisiti questi dettagli, possiamo istanziare il nostro client Jira:

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

Il costruttore di questa classe:

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

Il getJiraRestClient () utilizza tutte le informazioni fornite e restituisce un'istanza di JiraRestClient . Questa è l'interfaccia principale attraverso la quale comunicheremo con l'API REST di Jira:

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

Qui stiamo usando l'autenticazione di base per comunicare con l'API. Tuttavia, sono supportati anche meccanismi di autenticazione più sofisticati come OAuth.

Il metodo getUri () converte semplicemente jiraUrl in un'istanza di java.net.URI :

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

Questo conclude la nostra infrastruttura di creazione di un client Jira personalizzato. Ora possiamo dare un'occhiata a vari modi per interagire con l'API.

3.1. Crea un nuovo numero

Cominciamo creando un nuovo numero. Useremo questo problema appena creato per tutti gli altri esempi in questo articolo:

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

Il projectKey è l'unico che definisce il progetto. Questo non è altro che il prefisso che viene aggiunto a tutti i nostri numeri. Anche l'argomento successivo, issueType , dipende dal progetto e identifica il tipo di problemi come "Attività" o "Storia". Il issueSummary è il titolo del nostro numero.

Il problema va come istanza di IssueInput per il resto dell'API. Oltre agli input che abbiamo descritto, cose come assegnatario, reporter, versioni interessate e altri metadati possono essere considerati un IssueInput .

3.2. Descrizione del problema di aggiornamento

Ogni problema in Jira è identificato da una stringa univoca come " MYKEY-123 ". Abbiamo bisogno di questa chiave del problema per interagire con l'API rest e aggiornare la descrizione del problema:

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

Una volta aggiornata la descrizione, non rileggiamo la descrizione aggiornata:

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

L' istanza Issue rappresenta un problema identificato da issueKey . Possiamo usare questa istanza per leggere la descrizione di questo problema:

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

Questo stamperà la descrizione del problema sulla console.

3.3. Vota per un problema

Una volta ottenuta un'istanza di Problema, possiamo usarla per eseguire anche azioni di aggiornamento / modifica. Votiamo per il problema:

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

Ciò aggiungerà il voto alla questione per conto dell'utente le cui credenziali sono state utilizzate. Questo può essere verificato controllando il conteggio dei voti:

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

Una cosa da notare qui è che stiamo di nuovo recuperando una nuova istanza di Issue qui perché vogliamo che il conteggio dei voti aggiornato si rifletta.

3.4. Aggiunta di un commento

Possiamo utilizzare la stessa istanza Issue per aggiungere un commento per conto dell'utente. Come l'aggiunta di un voto, anche l'aggiunta di un commento è piuttosto semplice:

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

Abbiamo utilizzato il metodo factory valueOf () fornito dalla classe Comment per creare un'istanza di Comment . Esistono vari altri metodi predefiniti per casi d'uso avanzati, come il controllo della visibilità di un commento .

Recuperiamo una nuova istanza del problema e leggiamo tutti i commenti :

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

3.5. Elimina un problema

Anche l'eliminazione di un problema è abbastanza semplice. Abbiamo solo bisogno della chiave del problema che identifica il problema:

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

4. Conclusione

In questo rapido articolo, abbiamo creato un semplice client Java che si integra con l'API REST di Jira ed esegue alcune delle operazioni di base.

La fonte completa di questo articolo può essere trovata su GitHub.