Backlog API で課題のカスタム属性の値を更新する

はじめに

こんにちは、サービスグロースチームの筧です。

Backlog 課題では、カスタム属性を設定することで、課題に任意のフィールドを追加できます（例：下図赤枠）

カスタム属性の設定方法 – Backlog ヘルプセンター

課題に設定したカスタム属性の値は、課題情報の更新用の Backlog API で更新できます。

課題情報の更新 | Backlog Developer API | Nulab

当該 Backlog API 利用時に、カスタム属性の値の指定方法でハマりました。今回はどのように指定するかご紹介します。

カスタム属性

パラメーター名 型 内容

customField_{id} - カスタム属性の値

customField_{id}_otherValue - リスト属性のその他入力の値

ハマった箇所

カスタム属性の値の指定方法にハマりました。下図の設定の場合、hoge なら1、fuga なら2 といったように値が割り当てられるようです。

以下の API を使うことで、割り当てられた値を確認できました。調査した限り、GUI 上ではカスタム属性の値が見受けられなかったので苦労しました。

カスタム属性一覧の取得 | Backlog Developer API | Nulab

使い方

ではハマった箇所を踏まえて実際に API を利用するコードまでご紹介します。

カスタム属性の登録

以下を参考にしてカスタム属性を登録します。

カスタム属性の設定方法 – Backlog ヘルプセンター

今回は以下のようなカスタム属性を登録します。下記以外の値はデフォルトです。

• 1.カスタム属性の基本情報
  • カスタム属性の名前: テスト
• 2.カスタム属性の形式: 選択リスト
• 3.属性の設定
  • ひとつだけ選択できる
    • リスト形式
  • リストの値
    • hoge
    • fuga

登録後、対象のカスタム属性を開きます。URLの末尾にある、attribute.id={カスタム属性の ID} をメモします。今回の ID は 123456789 とします。

テスト用の課題追加

以下を参考にしてテスト用の課題を追加します。カスタム属性はブランクで結構です。

課題を追加する – Backlog ヘルプセンター

コード

コードは以下です。普段は階層ごとにファイルを分けていますが、一つのファイルにまとめています。handlers 層 → use_cases 層 → services 層 の流れで読むと分かりやすいと思います。メインのコードはハイライトの箇所です。

sample.py

import logging
import os

import requests

logger = logging.getLogger()
logger.setLevel(logging.INFO)

"""
services 層
"""


class BacklogService:
    def __init__(self, fqdn, api_key):
        self._fqdn = fqdn
        self._api_key = api_key

    def update_issue(self, issue_id: str, attribute_id: str, item_id: int):
        # refs: https://developer.nulab.com/ja/docs/backlog/api/2/update-issue/
        url = f"https://{self._fqdn}/api/v2/issues/{issue_id}?apiKey={self._api_key}"
        data = {f"customField_{str(attribute_id)}": int(item_id)}
        headers = {"Content-Type": "application/x-www-form-urlencoded"}
        return requests.patch(url, data=data, headers=headers)


"""
use_cases 層
"""


class BacklogUseCase:
    def __init__(self, backlog_service: BacklogService):
        self.backlog_service = backlog_service

    def exec(self, issue_id: str, attribute_id: str, item_id: int) -> None:
        self.backlog_service.update_issue(issue_id, attribute_id, item_id)

        return


def _init_use_case() -> BacklogUseCase:
    # SSMのパラメータストアなどを利用して機微な情報を取得
    fqdn = os.environ["BACKLOG_FQDN"]
    api_key = os.environ["BACKLOG_API_KEY"]
    backlog_service = BacklogService(fqdn, api_key)
    return BacklogUseCase(backlog_service)


def exec(issue_id: str, attribute_id: str, item_id: int) -> None:
    use_case = _init_use_case()
    return use_case.exec(issue_id, attribute_id, item_id)


"""
handlers 層
"""


def handler(event, context) -> None:
    """
    エンドポイント

    event:
    {
        "issue_id": "123", # テスト課題のID
        "attribute_id": "123456789" # カスタム属性 ID
        "item_id": 1 # カスタム属性の値
    }

    return:
    None
    """
    logger.info(f"event: {event}")

    try:
        issue_id = str(event["issue_id"])
        attribute_id = str(event["attribute_id"])
        item_id = int(event["item_id"])
        exec(issue_id, attribute_id, item_id)
        return
    except Exception as e:
        raise e

必要なインプットについてまとめておきます。

• issue_id
  • テスト課題のID
  • テスト課題のURLから取得できます
• attribute_id
  • カスタム属性 ID
  • 前述の方法で取得できます
• item_id
  • カスタム属性の値
  • ハマりどころです。今回の場合、以下の通りになります
    • hogeの場合は1
    • fugaの場合は2

なお fqdn と apiKey は、認証・認可に関わるインプットです。コードにベタ書きせず、パラメータストアなどから環境変数経由で取得する想定です。

認証と認可 | Backlog Developer API | Nulab

Slack Bolt for Python のクレデンシャル情報を AWS Systems Manager のパラメータストアに保管する

おわりに

最後まで読んでいただきありがとうございます。

今回は Backlog API で課題のカスタム属性の値を更新する方法についてご紹介しました。 今後、GUI でもカスタム属性の値が参照できると良いですね。 同じ箇所でハマった方の参考になれば嬉しいです。

それではまた！