APC 技術ブログ

株式会社エーピーコミュニケーションズの技術ブログです。

株式会社 エーピーコミュニケーションズの技術ブログです。

トップ > Java > 【Java】WEBアプリケーションによるBacklog課題登録実装方法の紹介

【Java】WEBアプリケーションによるBacklog課題登録実装方法の紹介

Java Backlog BacklogApi
＜ techblogAPCについて（はじめにお読み下さい） ＞

はじめに

こんにちは、エーピーコミュニケーションズiTOC事業部 BzD部 0-WANの野中です。
今回は、Javaで作成したWEBアプリケーションを経由して、Backlogに課題を登録するための実装方法を紹介します。

WEBアプリケーションとは

WEBアプリケーションとは、WEBの仕組みを利用したアプリケーションのことを指します。
一般的なWEBサイトとは異なり、HTMLだけではなく、WEBプログラムを利用するためフレームワークを使用して作成します。
また、別のWEBアプリで作成されたAPIを利用してプログラムを作成することも可能です。
www.skygroup.jp

Backlogとは

複数のメンバーが協力して作業を進めるためのプロジェクト管理ツールのことです。
開発プロジェクトを進めるために必要な機能が多数用意されており、Backlog上でのやり取りで進捗管理ができます。
ボードを使用することで、視覚的に状態を進めることができるので、開発プロジェクトではよく使用されます。

Backlog APIとは

今回は、BacklogにWEBアプリケーションを経由して新規課題を登録する手法として、BacklogAPIを使用します。
BacklogAPIを使用することで課題登録や、課題一覧取得など、backlogでできる動きのほとんどをプログラム上から実行することができます。

developer.nulab.com

今回Javaを使った理由

Javaは、オブジェクト指向プログラミング言語のことで、プラットフォームに依存しないため実行環境を選ばないという利点があります。
Javaを選定した理由は、BacklogAPIの公式ライブラリがJava版であったためで深い理由はありません。
私自身は、プログラミング言語にはこだわりはなく、作成するもの、携わるプロジェクトにふさわしいものを選定しています。
今回は、Java標準機能と公式ライブラリである「Backlog4J」を使って、新規課題登録を実施するプログラムを作成していきます。
github.com

開発環境

　Java ：amazon corretto 8 latest
　外部ライブラリ ：Backlog4J
　※IDEは、Java開発が可能なものを使用してください。

前提条件

これから簡易的なWEBアプリケーションを作成し、Backlog4Jを使用してBacklogに新規課題登録を行うサンプルプログラムを作成します。
作成にあたって、以下を前提条件とします。
　①作成するWEBアプリケーションは、単一のページのみで動作するサーブレット(※1)とする。
　　パッケージ名：example
　　ファイル名：BacklogExample.java
　②登録結果をテキストで表示するjsp2つを作成する(OK、NGの2つ作成)。
　　jspファイル名(OK)：resultOK.jsp
　　jspファイル名(NG)：resultNG.jsp
　③IDEはeclipseを使用する。(それ以外のIDEを使用することも可能です。)
　④Backlogへアクセス可能なユーザー登録があること。
　⑤プログラムを実行する環境からBacklogへのアクセスが可能であること。
　⑥今回参照するライブラリ「Backlog4J」がクラスパス参照可能な場所に配置していること。
　⑦今回はWEBアプリケーションでBacklogに新規課題を登録するプログラムの実装方法のみを紹介します。
　　APサーバに上げて動作確認までは行わないこととします。(今後、需要があれば動作確認までを投稿することとします。)

※1：サーブレットとは、WEBアプリケーションを構成する最小単位のプログラムを指します。
　　例えば、入力した文字を検索ボタンをクリックすると検索して結果を表示するWEBページがあったとします。
　　ユーザー文字を入力して、検索ボタンを押したときに一番初めに処理が走るプログラムがサーブレットです。
　　サーブレットはプログラムで情報を処理した後に、動的なWEBページを作成します。

サンプルコードおよび解説

サンプルコードを以下に展開し、必要箇所を解説していきます。

1.Backlog登録用サーブレットファイル(BacklogExample.java)

package example;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.nulabinc.backlog4j.BacklogClient;
import com.nulabinc.backlog4j.BacklogClientFactory;
import com.nulabinc.backlog4j.Issue;
import com.nulabinc.backlog4j.Issue.PriorityType;
import com.nulabinc.backlog4j.api.option.CreateIssueParams;
import com.nulabinc.backlog4j.conf.BacklogComConfigure;
import com.nulabinc.backlog4j.conf.BacklogConfigure;

/**
 * Servlet implementation class BacklogExample
 */
@WebServlet(name = "BacklogExample", urlPatterns = { "/BacklogExample" })
public class BacklogExample extends HttpServlet {
    private static final long serialVersionUID = 1L;

    /** Backlogスペースキー(BacklogのURL：https://XXXXX.backlog.com/の「XXXXX」部分) */
    private static final String SCPACE_KEY = "";

    /** BacklogのAPIキー(ユーザー→個人設定→APIにあるメモに任意の文字を入力して登録ボタンを押した後に発行されるランダム文字列) */
    private static final String API_KEY = "";

    /**
    * BacklogプロジェクトID
    * (Backlogの登録したいプロジェクト→課題にすすんだ時のURLにあるprojectId=XXXXXの「XXXXX」の数字)
    */
    private static final String PROJECT_ID = "";

    /**
    * Backlog課題登録時に設定する種別
    * (プロジェクト設定→種別→該当種別のリンクをクリックしてすすんだ先のURLにあるissueType.id=XXXXXの「XXXXX」の数字)
    */
    private static final String ISSUE_TYPE_ID = "";

    /**
    * Backlog課題登録する担当者
    * (Backlogの登録したいプロジェクト→課題→担当者にしたい人を上部検索担当者プルダウンリストで選択したあとのURLにあるassignerId=XXXXXの「XXXXX」の数字)
    */
    private static final String ASSIGNEE_ID = "";

    /** 登録する課題のタイトル(任意) */
    private static final String ASSIGNMENT_TITLE = "";

    /**
    * @see HttpServlet#HttpServlet()
    */
    public BacklogExample() {
        super();
        // TODO Auto-generated constructor stub
    }

    /**
    * @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse
     *      response) #ここに処理を記載していきます。
    */
    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {

        // Backlog基本情報設定
        BacklogConfigure configure = new BacklogComConfigure(SCPACE_KEY).apiKey(API_KEY);

        // Backlogクライアントの生成
        BacklogClient backlog = new BacklogClientFactory(configure).newClient();
        
        // 課題登録用パラメータの生成
        CreateIssueParams param = new CreateIssueParams(PROJECT_ID, ASSIGNMENT_TITLE, ISSUE_TYPE_ID,
                PriorityType.Normal);

        // 課題詳細
        param.description("");
        // 担当者
        param.assigneeId(ASSIGNEE_ID);

        // 課題登録を実行する
        Issue issue = backlog.createIssue(param);

        // 結果判定用
        boolean result = true;
        if (issue == null) {
            result = false;
        } // end if

        // 成功用jsp
        String jsp = "resultOK.jsp";

        if (!result) {
            // 失敗用jsp
            jsp = "resultNG.jsp";
        } // end if

        // jspの呼び出し
        request.getRequestDispatcher(jsp).forward(request, response);
    }// end method

    /**
    * @see HttpServlet#doPost(HttpServletRequest request, HttpServletResponse
     *      response)
    */
    protected void doPost(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        // TODO Auto-generated method stub
        doGet(request, response);
    }

}// end class

2.jspファイル(OKバージョン)

<%@ page language="java" contentType="text/html; charset=UTF-8"
    pageEncoding="UTF-8"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>実行結果</title>
</head>
<body>
成功！
</body>
</html>

3.jspファイル(NGバージョン)

<%@ page language="java" contentType="text/html; charset=UTF-8"
    pageEncoding="UTF-8"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>実行結果</title>
</head>
<body>
失敗！！
</body>
</html>

Backlogの操作が必要な箇所もあるため詳しく見ていきます。

BacklogAPI操作用ライブラリの読み込み

BacklogExample.javaの先頭で参照するライブラリを読み込みます。
前提条件でライブラリをクラスパス参照可能な位置に配置していますが、プログラムからライブラリを呼び出すためには、下記記載で読み込みをする必要があります。

　import com.nulabinc.backlog4j.***

「**」部分は使用するクラスによって異なります。
明示的にクラス名を指定しなくてもいい場合は、「」を指定しておくことで、com.nulabinc.backlog4jに配置しているクラスはすべて使用可能になります。

定数の設定

BacklogExample.javaのクラスの中に定数を配置しました。
現在は空文字("")で設定していますが、ここにご自身の環境の設定値を入力して、サーバ上で動かせば課題登録されます。
では、一つ一つ取得方法を確認していきましょう。

SCPACE_KEY：Backlogスペースキー

　Backlogの固有識別キーとなります。
　課題登録したいBacklogをブラウザで開いたときの、URLから取得できます。
　ex：https://XXXXX.backlog.com/　の「XXXXX」部分を抜き出し、設定してください。

API_KEY：APIを使用してBacklog操作するためのAPIキー

　ユーザー用API識別キーとなります。
　APIを使用するユーザーが発行します。
　上部のユーザーのアイコンの右にある▼(下向きさんかくマーク)をクリックすると出てくる「個人設定」をクリックします。
　開いた画面の左エリアにあるAPIをクリックします。
　新しいAPIキーを発行のメモに任意の文字列を入力し、「登録」ボタンをクリックすると、下部に登録されたAPIキーが表示されます。
　APIキーの文字列をコピーして設定してください。
　

PROJECT_ID：Backlogで課題登録したいプロジェクトのID

　Backlog上で課題登録する場合プロジェクトを選択する必要があります。
　BacklogAPIの世界では、プロジェクトを識別するためにプロジェクトIDを使用します。
　プロジェクトIDは、Backlogの登録したいプロジェクトを開き、課題を選択します。
　課題一覧画面が開くので、URLのパラメータから取得します。
　ex：https://XXXXX.backlog.com/find/{project_name}?projectId=XXXXX　の「XXXXX」部分の数値を抜き出し、設定してください。 　

ISSUE_TYPE_ID:種別

　Backlog上で課題を登録する時に設定する種別(タスクやバグ、要望等)のことです。
　課題登録を行いたいプロジェクトを開き、左エリアのプロジェクト設定をクリックします。
　種別を選択し、課題登録時に選択する該当種別のリンクをクリックします。
　種別編集画面が開くので、URLのパラメータから取得します。
　ex：https://XXXXX.backlog.com/EditIssueType.action?issueType.id=XXXXX　の「XXXXX」部分の数値を抜き出し、設定してください。 　

ASSIGNEE_ID：担当者

　Backlog上で課題を登録する時に設定する担当者を設定します。
　課題登録を行いたいプロジェクトを開き、左エリアの課題をクリックします。
　課題一覧画面が開くので、担当者にしたいユーザーを検索欄の担当者プルダウンリストから選択してください。
　検索条件がURLパラメータに反映されるのでそこから取得します。
　ex:https://XXXXX.backlog.com/find/{project_name}?assignerId=XXXXX　の「XXXXX」部分の数値を抜き出し、設定してください。 　

ASSIGNMENT_TITLE：課題のタイトル

　登録する課題のタイトルを設定します。
　ここは任意の文字列を入力します。

処理プログラム

BacklogExample.javaのdoGetメソッド内にBacklog操作の処理を書いていきます。
順を追って説明してきますのでサンプルプログラムと合わせて確認してください。

①Backlog基本情報設定

　SCPACE_KEYとAPI_KEYを設定して基本情報設定オブジェクトを生成します。

       // Backlog基本情報設定
        BacklogConfigure configure = new BacklogComConfigure(SCPACE_KEY).apiKey(API_KEY);
②Backlogクライアントの生成

　①で設定した基本情報設定オブジェクトをもとに、Backlogクライアントを新規生成します。

       // Backlogクライアントの生成
        BacklogClient backlog = new BacklogClientFactory(configure).newClient();
③課題登録用パラメータの生成

　課題登録用のパラメータオブジェクトを生成します。
　オブジェクト生成時に、以下の引数を設定します。
　　第1引数：PROJECT_ID(プロジェクトID)
　　第2引数：ASSIGNMENT_TITLE(課題タイトル)
　　第3引数：ISSUE_TYPE_ID(種別)
　　第4引数：優先度(低：PriorityType.Low、中：PriorityType.Normal、高：PriorityType.High)
　第1引数～第3引数までは、定数として設定しているため、第4引数の優先度を設定してください。

       // 課題登録用パラメータの生成
        CreateIssueParams param = new CreateIssueParams(PROJECT_ID, ASSIGNMENT_TITLE, ISSUE_TYPE_ID,
                PriorityType.Normal);
④課題登録用パラメータの設定

　③で基本情報を登録したため、そのほかに必要なパラメータを設定します。
　サンプルコードでは、課題の詳細と担当者を設定しています。
　担当者は定数として設定していますが、課題の詳細は任意の文字列として設定してください。
　もし、改行が必要な場合は、改行コードを設定してください。

       // 課題詳細
        param.description("");
        // 担当者
        param.assigneeId(ASSIGNEE_ID);
⑤課題登録の実行

　②で生成したクライアントオブジェクトから③、④で設定したパラメータ情報をもとに、新規課題登録用APIを実行します。
　BacklogAPIを経由して登録が正常に完了した場合、戻り値としてIssueオブジェクトが返却されます。
　もし、失敗した場合は、nullが返却されるため結果表示判定を行います。

       // 課題登録を実行する
        Issue issue = backlog.createIssue(param);
⑥実行結果による表示判定

　今回のプログラムでは、⑤の結果に応じて、表示する結果を分岐するため、実行結果の判定を行います。
　　成功の場合：成功表示用jsp
　　失敗の場合：失敗表示用jsp
　をそれぞれ設定します。

       // 結果判定用
        boolean result = true;
        if (issue == null) {
            result = false;
        } // end if

        // 成功用jsp
        String jsp = "resultOK.jsp";

        if (!result) {
            // 失敗用jsp
            jsp = "resultNG.jsp";
        } // end if
⑦結果表示

　⑥で設定したjspを返却し、html表示します。
　内部処理で成功失敗を条件分けすることもできますが、jspの処理が複雑となってしまうため、今回は、2つのファイルを用意し、プログラム内で判定する方法をとりました。

       // jspの呼び出し
        request.getRequestDispatcher(jsp).forward(request, response);

ここまでで、Backlogに新規課題を登録するプログラムが完成です。

まとめ

今回は、Backlog公式ライブラリである「Backlog4J」を使用した、新規課題登録をJavaプログラムで実装する方法を紹介しました。
このプログラムを動作させるためには、APサーバに載せてブラウザからURLを実行する必要がありますが、それはまた次回ご紹介させていただきます。
Backlog4JやBacklogAPIには課題登録するだけではなく、課題一覧取得や、ユーザー追加等複数の機能が提供されています。
公式ライブラリではありませんが、コミュニティでは様々なプログラミング言語に対応したライブラリも存在します。
BacklogAPIを使えば、プログラムを経由して、Backlogにかかわる様々な業務を自動化することも可能です。
もしご興味があれば、ご自身で調べて、独自のプログラムを作成してみてはいかがでしょうか。

0-WANについて

私たち0-WANは、ゼロトラスト製品を中心とした、マルチベンダーでのご提案で、お客様の経営課題解決を支援しております。 ゼロトラストってどうやるの？製品を導入したけれど使いこなせていない気がする等々、どんな内容でも支援いたします。 お気軽にご相談ください。

問い合わせ先、0-WANについてはこちら。

www.ap-com.co.jp