배경

올해 Redmine REST API 를 사용해 아래와 같은 일을 할 기회가 있었습니다.

진행 관리를 Excel에서 Redmine으로 migration

CI의 리그레션 테스트로 Fail한 테스트 케이스를 Redmine에 자동 기표

목적

지금까지 Redmine REST API 는 사용한 적이 없고, 구현하면서 배워 갔습니다. 그 중에서 빠진 것을 중심으로 여러분에게 공유하고, 저는 빠진 함정을 회피해 주셨으면 합니다.

전제

자바를 거기서 이해하고있다

Redmine의 기능을 알고 있습니다

환경

Redmine Version

Environment:
  Redmine version                3.4.6.stable

java Version

java version "1.8.0_221"
Java(TM) SE Runtime Environment (build 1.8.0_221-b11)
Java HotSpot(TM) 64-Bit Server VM (build 25.221-b11, mixed mode)

pom.xml

        <dependency>
            <groupId>com.taskadapter</groupId>
            <artifactId>redmine-java-api</artifactId>
            <version>4.0.0.preview.1</version>
        </dependency>

빠진 것

1. 사용자에게 부여된 권한으로 API의 기능도 제한된다

Redmine REST API를 사용하기 위해 먼저 RedmineManager 클래스를 생성합니다. 이 때 API KEY 라는 것을 사용합니다.

RedmineManager manager = RedmineManagerFactory.createWithApiKey(REDMINE_URL, API_KEY);

이 API KEY는 Redmine 사용자 한 사람 한 사람에게 부여됩니다. 당시 자신의 사용자 권한은 관리자 권한이 아니 었습니다. API의 메소드에 따라 Redmine의 시스템 관리자 권한이 필요한 경우가 있습니다.

모든 사용자 얻기

    /**
     * Load list of users from the server.
     * <p><strong>This operation requires "Redmine Administrator" permission.</strong>
     * <p>
     * This method calls Redmine with "include = memberships,groups" parameter.
     *
     * @return list of User objects
     * @throws RedmineAuthenticationException invalid or no API access key is used with the server, which
     *                                 requires authorization. Check the constructor arguments.
     * @throws NotFoundException
     * @throws RedmineException
     */
    public List<User> getUsers() throws RedmineException {
        return transport.getObjectsList(User.class, new BasicNameValuePair(
                "include", "memberships,groups"));
    }

유연하게 사용하려면 시스템 관리자 권한이 되는 것이 좋습니다.

2. Transport 필요

redmine-java-api 의 version4 이후로부터 받아들여진 개념인 것 같습니다. RedmineManager 클래스에서 얻을 수 있습니다.

RedmineManager redmineManager = RedmineManagerFactory.createWithApiKey(REDMINE_URL, API_KEY);
Transport transport = redmineManager.getTransport();

Transport 가 없으면 티켓 작성·갱신시에 「Transport가 미설정이다!」라고 하는 예외가 슬로우 됩니다. 그러므로 작성·갱신 전에 Issue 의 인스턴스에 Transport 를 설정해 주세요.

신규 티켓 작성

// Transportをセット
Issue issue = new Issue(manager.getTransport());
// （中略）
issue = issue.create();

기존 티켓 업데이트

Issue issue = manager.getIssueManager().getIssueById(fetchedIssue.getTicketId());
// Transportをセット
issue.setTransport(manager.getTransport());
// （中略）
issue.update();

3. Params 사용법

기존 티켓에 갱신을 걸 때, 「이 조건에 있던 티켓」을 취득하고 싶을 때가 있습니다. 그 때는 Params 를 사용하는 것으로 「이 조건」을 표현할 수 있습니다.

티켓 제목이 "actual.getFileName"과 일치하는 조건

Params().add("set_filter", "1")
        .add("f[]", "subject")
        .add("op[subject]", "=")
        .add("v[subject][]", actual.getFileName());

빠진 것은 아래 3점입니다.

제목 이외(예: 담당자) 때의 키값은?

문서를 찾을 수 없었기 때문에 역기로 식별했습니다. 티켓 목록 필터에서 원하는 조건을 설정하면 URL의 매개 변수로 필터 조건이 표시됩니다. 매개 변수를 디코딩하면 키 값을 확인할 수 있습니다.

일치 이외(예: 일치하지 않음, 포함)일 때는?

위의 방법으로 분석.

티켓 전부 취득하고 싶기 때문에 조건없이 취득하면 500건밖에 취득할 수 없다

현재 알 수 없음. 방법을 아는 분이 있으면 가르쳐 주세요.

4. 기존 티켓의 사용자 지정 필드를 업데이트할 때는 한 번 clear

일단 기존 티켓의 사용자 지정 필드를 가져와 값을 업데이트합니다. 그 후 기존 티켓의 사용자 지정 필드를 clearCustomFields 하고 추가하지 않으면 성공적으로 업데이트되지 않았습니다.

// この処理で既存チケットからカスタムフィールドを取得して更新して、返却している
Collection<CustomField> customFieldCollection = setEachCustomField(issue, fetchedIssue);
issue.clearCustomFields();
issue.addCustomFields(customFieldCollection);

5. 날짜 형식의 사용자 지정 필드에 값을 설정할 때 형식

yyyy-MM-dd 선택입니다. 그렇지 않으면 parse 오류가 발생합니다.

이상 (생각하면 추가하겠습니다.)

참고

Redmine이란?

Redmine REST API