Jira Service Management REST API を実例で解説

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

JSM API がカバーする範囲

Jira Service Management API は、コアの Jira プラットフォーム API とは別の REST の面です。Atlassian Cloud は /rest/servicedeskapi/ というベースパスで公開しており、単なる課題トラッカーとサービスデスクを分けている概念、つまり顧客リクエスト、リクエストタイプ、キュー、SLA タイマー、承認、参加者、組織、顧客をモデル化しています。通常の /rest/api/3/ の Jira エンドポイントから SLA データやキューの中身を読もうとしたことがあれば、そこには存在しないことをご存じでしょう。それらはサービスデスク API にあります。

この記事では、日々の運用でもっとも重要なエンドポイントをたどりながら、それぞれを呼び出す atlassian-cli のコマンドを具体的に示します。HTTP リクエストを手で書かずにスクリプト化できます。以下のコマンドはすべてコマンドリファレンスで確認済みです。

Atlassian 自身の CLI との違い。 atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる一次サポートが必要であれば公式の acli を使ってください。Jira、Confluence、Bitbucket、JSM をカバーし、4製品すべてで一貫したフラグ体系を持つ単一の無料 Rust バイナリが欲しい場合は atlassian-cli を選んでください。

認証

サービスデスク API の認証は、Atlassian Cloud の他の部分とまったく同じです。アカウントのメールアドレスと API トークンを、サイトのベース URL に対して HTTPS 上の Basic 認証で送ります。JSM 専用の認証情報も、専用のログインもありません。プロファイルを1つ設定すれば、すべての製品グループで使えます。

# Log in once; the same profile serves jira, confluence, bitbucket, and jsm
atlassian-cli auth login \
  --profile support \
  --base-url https://your-site.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_TOKEN \
  --default

# Confirm the credential resolves
atlassian-cli auth test --profile support

トークンは Atlassian アカウントのセキュリティ設定から生成し、シェルの履歴ではなく環境変数に保管してください。このサイトを対象にするコマンドには --profile support を付けます。複数サイトやコマンド単位の上書きを含むプロファイルの仕組み全体は、認証ガイドをご覧ください。

リクエストのエンドポイント

顧客リクエストはサービスデスク API の中心です。素の REST では /rest/servicedeskapi/request にあり、リクエストごとの詳細は .../request/{issueIdOrKey} で取得します。リクエストの実体は Jira の課題ですが、servicedeskapi のビューには、通常の課題 API が返さないポータルのフィールド、リクエストタイプ、現在のステータス、顧客のコンテキストが含まれます。

API でリクエストを作成するには2つの ID が必要です。所属するサービスデスクと、そのデスク内のリクエストタイプです。何かを作成する前に、両方を調べておきましょう。

# 1. List service desks to find the id
atlassian-cli jsm service-desk list --limit 25

# 2. List request types for service desk 10
atlassian-cli jsm request-type list --servicedesk-id 10 --limit 25

# 3. Create a request (POST /rest/servicedeskapi/request)
atlassian-cli jsm request create \
  --servicedesk-id 10 \
  --request-type-id 7 \
  --summary "VPN access issue" \
  --description "Cannot connect from the Berlin office"

リクエストができたら、そのライフサイクルを進められます。API は、利用できる遷移、コメント（公開または内部）、参加者、ステータスを、リクエストキー配下のサブリソースとしてそれぞれ公開しています。

# Inspect a single request
atlassian-cli jsm request get SD-123
atlassian-cli jsm request status SD-123

# See valid transitions, then apply one
atlassian-cli jsm request transitions SD-123
atlassian-cli jsm request transition SD-123 --transition "In Progress"

# Add a public reply the customer sees, or drop --public for an internal note
atlassian-cli jsm request add-comment SD-123 --body "Investigating now" --public

--public フラグは、コメントエンドポイントの public フィールドにそのまま対応します。省略するとコメントはエージェント内部にとどまります。顧客に見える更新と、内部の作業メモの違いはここにあります。

SLA のエンドポイント

SLA は、API に手を伸ばす理由としてもっとも多いエンドポイントです。ポータルには SLA をまとめて読み出すきれいな方法が用意されていないからです。サービスデスク API は /rest/servicedeskapi/request/{issueIdOrKey}/sla で提供し、設定済みの各指標をサイクルの状態と残り時間とあわせて返します。

# Every SLA metric on a request
atlassian-cli jsm sla list SD-123

# One specific metric by id, e.g. time to resolution
atlassian-cli jsm sla get SD-123 --sla-id time-to-resolution

これが効いてくるのは JSON 出力です。SLA データを JSON で取得すれば、違反間近のものを絞り込み、その結果をアラートや朝会のレポートに流し込めます。

# Flag requests whose resolution SLA has an ongoing (unbreached but running) cycle
atlassian-cli jsm sla list SD-123 --format json \
  | jq '.[] | select(.name == "Time to resolution")'

CLI はすべてのコマンドで単一の出力レイヤーを共有しているため、コマンドリファレンスに記載された --format json、--format csv、--envelope の各フラグは、Jira の課題検索と同じようにここでも動作します。この一貫性のおかげで、JSM だけを特別扱いせずに SLA の読み取りを大きなスクリプトへ組み込めます。

キュー

キューは、エージェントが自分の作業を実際に見る場所であり、完全にサービスデスク固有の概念です。API は /rest/servicedeskapi/servicedesk/{id}/queue でキューを一覧し、そのパスに /{queueId}/issue を足したパスでキュー内の課題を返します。キューは列構成が定義された保存済みの JQL フィルターなので、API から読めば、エージェントがポータルで見ているものをそのまま、ページ送りやエクスポートができる形で取得できます。

# List queues for service desk 10 to find queue ids
atlassian-cli jsm queue list 10

# Inspect one queue's definition
atlassian-cli jsm queue get 10 5

# Page through the issues currently in queue 5
atlassian-cli jsm queue issues 10 5 --limit 25

キューを CSV にエクスポートしたいという要望は、ポータルのログインを配らずに週次レビュー用のスナップショットが欲しいチームリードからよく出てきます。

# Snapshot the triage queue for a weekly review
atlassian-cli jsm queue issues 10 5 --limit 100 --format csv > triage-queue.csv

承認と参加者

変更リクエストやアクセスリクエストは、承認ステップで止まることがよくあります。API は承認を /rest/servicedeskapi/request/{issueIdOrKey}/approval 配下でモデル化しており、CLI も list、get、approve、decline のコマンドで同じ構造を反映しています。ポータルのクリックではなく、チャットコマンドやパイプラインから承認を実行したいときに自動化する部分です。

# See pending approvals on a request
atlassian-cli jsm approval list SD-123

# Approve or decline a specific approval by id
atlassian-cli jsm approval approve SD-123 --approval-id 1
atlassian-cli jsm approval decline SD-123 --approval-id 1

参加者は、スクリプト化する価値のあるもう1つのリクエストのサブリソースです。アカウント ID で参加者を追加すると、別のエージェントや関係者に通知が届き、内容を確認できるようになります。専門家を引き込む必要のあるリクエストで便利です。

atlassian-cli jsm request participants SD-123
atlassian-cli jsm request add-participant SD-123 --account-id 5f0a1b2c3d4e

同じ API は、そもそも誰がリクエストを起票できるかも管理します。顧客は /rest/servicedeskapi/customer、組織は /rest/servicedeskapi/organization にあり、どちらもそのままスクリプト化できます。たとえば新しいチームのオンボーディングは、作成してから紐付けるパターンになります。組織を作り、それを担当するサービスデスクに追加します。

# Create an organization and attach it to service desk 10
atlassian-cli jsm organization create --name "ACME Ops"
atlassian-cli jsm service-desk add-organization 10 --org-id 42

# Create a customer account for the portal
atlassian-cli jsm customer create --email new@customer.com --display-name "New Customer"

API のレベルで顧客を組織にまとめておくと、アカウントを1件ずつではなくチーム単位でアクセスを管理できます。デスクが少数を超える外部ユーザーに対応するようになると、この差が効いてきます。

エンドポイントとコマンドの対応表

すでに REST のパスで考えているなら、この表が CLI の対応コマンドを見つけるいちばん早い方法です。どのコマンドもリファレンスに載っている実在のサブコマンドで、自分で用意するラッパーではありません。

実用的なトリアージスクリプト

個々のコマンドも便利ですが、スクリプト可能な API の本当の価値は組み合わせにあります。次に示すのは、リードが毎朝実行できる小さなトリアージチェックです。キュー内の未対応リクエストを一覧し、最新のリクエストの SLA 状況を読み取り、内部メモを投稿します。使っているのは上で取り上げたエンドポイントだけです。

#!/bin/bash
# Morning JSM triage snapshot
set -euo pipefail

PROFILE="support"
DESK=10
QUEUE=5

# 1. How many issues are sitting in the triage queue right now?
COUNT=$(atlassian-cli jsm queue issues "$DESK" "$QUEUE" \
  --profile "$PROFILE" --format json | jq 'length')
echo "Triage queue has $COUNT open requests."

# 2. Grab the most recent request key from that queue
KEY=$(atlassian-cli jsm queue issues "$DESK" "$QUEUE" \
  --profile "$PROFILE" --limit 1 --format json | jq -r '.[0].key')

# 3. Read its SLA metrics so the lead sees any pressure early
atlassian-cli jsm sla list "$KEY" --profile "$PROFILE"

# 4. Drop an internal note that triage has started
atlassian-cli jsm request add-comment "$KEY" \
  --profile "$PROFILE" \
  --body "Picked up in morning triage."

echo "Triage snapshot complete for $KEY."

重要なのは、どのステップもサービスデスク API を通じて読み書きしているにもかかわらず、スクリプトが素の URL にも Basic 認証ヘッダーにもページネーションのカーソルにも触れていない点です。それらは CLI が処理し、JSON 出力はそのまま jq に渡せます。同じパターンを広げて複数のキューをループしたり、スケジューラーに組み込んで日次ダイジェストにしたりできます。

よくある質問

関連リソース