Jira Service Managementのアセットで使用できるAPIについてまとめてみた

2025.08.20
こんにちは！大野です。
Atlassian社の製品である「Jira Service Management (JSM) 」では、各画面の操作において様々なAPIが用意されています。

今回はその中でも「アセット」における代表的なAPIについて、その内容と使用方法の例をご紹介させていただきます！

「アセット」のAPIでは、スキーマ、オブジェクトタイプ、属性、オブジェクトなどの要素を操作することが可能です。
 前提条件 APIトークンの取得APIの利用においては、予めAPIトークンの取得が必須となります。

以下リンク先の記事を参考に、トークンの取得をお願いいたします。

https://dev.classmethod.jp/articles/jsm-rest-api/
 workspaceIdの確認JSMでは環境ごとに固有の「workspaceId」という識別子が割り振られています。

どの環境でAPIを実行するのかを明示的に指定する必要があるため、予め対象環境のIdを確認しておきましょう。

以下手順で確認可能です。
1.対象環境のアセット画面を開く

2.ブラウザで 開発者ツール（DevTools）を開く（F12 または 右クリック → 検証）

3.「Network」タブを開く

4.ページをリロード（F5）

5.フィルターに「workspace」と入力

6.以下のようなリクエストを探す：
GET https://api.atlassian.com/jsm/assets/workspace/<workspaceId>/v1/objectschema/〇〇
この中の <workspaceId> が対象環境の固有workspaceIdです。

 よく使うスキーマAPI一覧では、ここから本題のAPIについてのご紹介となります。

全てcurl形式での記述とさせていただきます。
また、公式リファレンスではBearer認証が必須という記述がありますが、実際はBasic認証で実行可能です。

本記事ではBasic認証での実行例を記載しますのでご留意ください。
https://developer.atlassian.com/cloud/assets/rest/api-group-objectschema/#api-objectschema-list-get
 Basic認証の準備まず、予め取得したAPIトークンを使用し、Basic認証用のヘッダーを準備しておきましょう。
# 環境変数の設定
EMAIL="your-email@example.com"
API_TOKEN="your-api-token"
WORKSPACE_ID="your-workspace-id"

# Base64エンコードの生成
AUTH_STRING=$(echo -n "${EMAIL}:${API_TOKEN}" | base64)
 1. スキーマ操作 スキーマ一覧の取得（Get objectschema list）ワークスペース内のすべてのスキーマを取得します。
必須パラメーター:
なし（ワークスペースIDはURLパスで指定）
オプションパラメーター:
startAt: ページネーションの開始位置
maxResults: 取得する結果の最大数
includeCounts: カウント情報を含めるかどうか
リクエスト例:
curl -X GET \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/objectschema/list" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
レスポンス例:
{
  "values": [
    {
      "id": 1,
      "name": "Infrastructure",
      "objectSchemaKey": "INFRA",
      "description": "Infrastructure schema",
      "status": "Ok",
      "created": "2024-01-01T00:00:00.000Z",
      "updated": "2024-01-01T00:00:00.000Z",
      "objectCount": 150
    }
  ],
  "size": 1,
  "start": 0,
  "limit": 25,
  "isLast": true
}
 スキーマの作成（POST objectschema create）新しいスキーマを作成します。

スキーマキー（objectSchemaKey）は一意である必要があります。
必須パラメーター:
name: スキーマの表示名
objectSchemaKey: スキーマの一意識別子（英数字のみ）
オプションパラメーター:
description: スキーマの説明
リクエスト例:
curl -X POST \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/objectschema/create" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "人事管理システム",
    "objectSchemaKey": "HR",
    "description": "社員情報と組織構造を管理するスキーマ"
  }'
レスポンス例:
{
  "id": 2,
  "name": "Development Environment",
  "objectSchemaKey": "DEV",
  "description": "Development environment schema",
  "status": "Ok",
  "created": "2024-01-02T00:00:00.000Z",
  "updated": "2024-01-02T00:00:00.000Z"
}
 単一スキーマの詳細取得（Get objectschema {id}）指定したスキーマIDの詳細情報を取得します。スキーマの設定、状態、メタデータを確認できます。
必須パラメーター:
{id}: URLパスパラメータでスキーマIDを指定
オプションパラメーター:
なし
リクエスト例:
curl -X GET \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/objectschema/1" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
レスポンス例:
{
  "id": 1,
  "name": "Infrastructure",
  "objectSchemaKey": "INFRA",
  "description": "Infrastructure schema for managing IT assets",
  "status": "Ok",
  "created": "2024-01-01T00:00:00.000Z",
  "updated": "2024-01-01T00:00:00.000Z",
  "objectCount": 150,
  "objectTypeCount": 5,
  "canManage": true,
  "workspaceId": "2cd90823-45a5-425e-b45d-6bb92a3d5c42"
}
 2. オブジェクトタイプ操作 オブジェクトタイプ一覧の取得（GET objectschema {id} objecttypes）指定したスキーマ内のすべてのオブジェクトタイプを取得します。
必須パラメーター:
{id}: URLパスパラメータでスキーマIDを指定
オプションパラメーター:
{excludeAbstract}: true の場合、結果から抽象オブジェクトタイプを除外
リクエスト例:
curl -X GET \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/objectschema/2/objecttypes" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
レスポンス例:
{
  "values": [
    {
      "id": 1,
      "name": "Server",
      "description": "Physical and virtual servers",
      "icon": {
        "id": 1,
        "name": "Server",
        "url16": "https://example.com/icon16.png",
        "url48": "https://example.com/icon48.png"
      },
      "position": 0,
      "created": "2024-01-01T00:00:00.000Z",
      "updated": "2024-01-01T00:00:00.000Z",
      "objectCount": 25,
      "objectSchemaId": 1
    }
  ],
  "size": 1,
  "start": 0,
  "limit": 25,
  "isLast": true
}
 オブジェクトタイプの作成（POST objecttype create）新しいオブジェクトタイプを作成します。

アイコン、位置、継承設定などを指定できます。
必須パラメーター:
name: オブジェクトタイプの名称
objectSchemaId: 所属するスキーマID
iconId: 表示するアイコンID
オプションパラメーター:
description: オブジェクトタイプの説明
parentObjectTypeId: 継承元のオブジェクトタイプID（inherited=trueの場合のみ指定）
inherited: 継承タイプかどうか（true/false）
abstractObjectType: 抽象タイプかどうか（true/false）
リクエスト例:
curl -X POST \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/objecttype/create" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "社員",
    "description": "会社の社員情報",
    "iconId": 15,
    "objectSchemaId": 2,
    "inherited": false,
    "abstractObjectType": false
  }'
レスポンス例:
{
  "id": 2,
  "name": "Database",
  "description": "Database instances",
  "icon": {
    "id": 2,
    "name": "Database",
    "url16": "https://example.com/db-icon16.png",
    "url48": "https://example.com/db-icon48.png"
  },
  "position": 1,
  "created": "2024-01-02T00:00:00.000Z",
  "updated": "2024-01-02T00:00:00.000Z",
  "objectSchemaId": 1
}
 3. 属性操作 オブジェクトタイプの属性一覧取得（Get objecttype {id} attributes）指定したオブジェクトタイプに定義されているすべての属性を取得します。
必須パラメーター:
{id}: URLパスパラメータでオブジェクトタイプIDを指定
オプションパラメーター（クエリパラメーター）:
onlyValueEditable: 編集可能な属性のみを取得するか（デフォルト: false）
orderByName: 属性名で並び替えるか（デフォルト: false）
query: 属性名のフィルタークエリ
includeValuesExist: 値が存在する属性のみを含めるか（デフォルト: false）
excludeParentAttributes: 親オブジェクトタイプの属性を除外するか（デフォルト: false）
includeChildren: 子オブジェクトタイプの属性を含めるか（デフォルト: false）
orderByRequired: 必須属性順で並び替えるか（デフォルト: false）
リクエスト例:
curl -X GET \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/objecttype/3/attributes" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
レスポンス例:
{
  "values": [
    {
      "id": 1,
      "name": "Name",
      "label": "サーバー名",
      "type": "Text",
      "description": "Server name",
      "defaultType": {
        "id": 0,
        "name": "Text"
      },
      "editable": true,
      "system": false,
      "sortable": true,
      "summable": false,
      "minimumCardinality": 1,
      "maximumCardinality": 1,
      "removable": false,
      "hidden": false,
      "includeChildObjectTypes": false,
      "uniqueAttribute": false,
      "regexValidation": null,
      "iql": null,
      "options": null,
      "position": 0
    },
    {
      "id": 2,
      "name": "IP Address",
      "label": "IPアドレス",
      "type": "Text",
      "description": "Server IP address",
      "minimumCardinality": 0,
      "maximumCardinality": 1,
      "position": 1
    }
  ],
  "size": 2,
  "start": 0,
  "limit": 25,
  "isLast": true
}
 属性の作成（Post objecttypeattribute {objectTypeId}）オブジェクトタイプに新しい属性を追加します。テキスト、数値、日付、参照など様々な型の属性を作成できます。
必須パラメーター:
{objectTypeId}: URLパスパラメータでオブジェクトタイプIDを指定
name: 属性の内部名
type: 属性のタイプ識別子（文字列）
オプションパラメーター:
label: 属性の表示名（ユーザー向け表示）
description: 属性の説明文
defaultTypeId: デフォルトタイプ識別子（文字列）
typeValue: 属性タイプの値を定義（文字列）
typeValueMulti: 複数値選択の設定（配列）
additionalValue: 追加設定値（文字列）
minimumCardinality: 最小入力数（デフォルト: 0）
maximumCardinality: 最大入力数（デフォルト: 1）
suffix: 属性値に追加される接尾辞（文字列）
includeChildObjectTypes: 子オブジェクトタイプを含めるか（デフォルト: false）
hidden: 非表示にするか（デフォルト: false）
uniqueAttribute: 一意制約を付けるか（デフォルト: false）
summable: 集計可能かどうか（デフォルト: false）
regexValidation: 正規表現による値の検証パターン（文字列）
qlQuery: Assets Query Language (AQL) によるクエリ（文字列）
iql: Insight Query Language によるクエリ（文字列）
options: 選択肢リスト等のオプション設定
リクエスト例:
curl -X POST \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/objecttypeattribute/3" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Department",
    "type": "0",
    "defaultTypeId": "0"
  }'
レスポンス例:
{
  "id": 3,
  "name": "OS Version",
  "label": "OS バージョン",
  "type": "Text",
  "description": "Operating system version",
  "defaultType": {
    "id": 0,
    "name": "Text"
  },
  "editable": true,
  "system": false,
  "minimumCardinality": 0,
  "maximumCardinality": 1,
  "position": 2
}
 4. オブジェクト操作（Post object aql） AQLクエリによるオブジェクト検索AQL (Assets Query Language) を使用してオブジェクトを検索できます。条件を指定して必要なオブジェクトを効率的に取得できます。
旧式の「GET /aql/objects」エンドポイントは2024年9月18日に廃止されました。

現在はPOST /object/aqlが推奨エンドポイントです。
必須パラメーター:
qlQuery: リクエストボディでAQLクエリ文字列を指定
オプションパラメーター:
startAt: ページネーションの開始位置（クエリパラメーター）
maxResults: 取得する結果の最大数（クエリパラメーター）
includeAttributes: 属性情報を含めるか（クエリパラメーター）
リクエスト例:
curl -X POST \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/object/aql?startAt=0&maxResults=10&includeAttributes=true" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "qlQuery": "objectType = 社員 AND Department LIKE 開発"
  }'
レスポンス例:
{
  "objectEntries": [
    {
      "id": 1,
      "label": "web-server-01",
      "objectKey": "SRV-1",
      "avatar": {
        "url16": "https://example.com/avatar16.png",
        "url48": "https://example.com/avatar48.png",
        "url72": "https://example.com/avatar72.png",
        "url144": "https://example.com/avatar144.png",
        "url288": "https://example.com/avatar288.png"
      },
      "objectType": {
        "id": 1,
        "name": "Server"
      },
      "created": "2024-01-01T00:00:00.000Z",
      "updated": "2024-01-01T00:00:00.000Z",
      "hasAvatar": true,
      "timestamp": 1704067200000,
      "attributes": [
        {
          "id": 1,
          "objectTypeAttribute": {
            "id": 1,
            "name": "Name"
          },
          "objectTypeAttributeId": 1,
          "objectId": 1,
          "objectAttributeValues": [
            {
              "value": "web-server-01",
              "displayValue": "web-server-01"
            }
          ]
        }
      ]
    }
  ],
  "objectTypeAttributes": [],
  "objectTypeAttributesDeep": [],
  "totalFilterCount": 1,
  "startIndex": 0,
  "toIndex": 1,
  "pageObjectSize": 25,
  "pageNumber": 1,
  "orderWay": "ASC",
  "isLast": true
}
 オブジェクトの詳細取得（Get object {id}）指定したオブジェクトIDの詳細情報を取得します。すべての属性値と関連情報が含まれます。
必須パラメーター:
{id}: URLパスパラメータでオブジェクトIDを指定
オプションパラメーター:
なし
特定の資産の詳細情報を確認したり、データの整合性を検証したい場合に使用します。
リクエスト例:
curl -X GET \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/object/45" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
 オブジェクトの作成（POST /object/create）新しいオブジェクトを作成します。オブジェクトタイプと属性値を指定してインスタンスを生成します。
必須パラメーター:
objectTypeId: 対象のオブジェクトタイプID（文字列）
attributes: 属性の配列
objectTypeAttributeId: 属性のタイプID（数値）
objectAttributeValues: 属性値の配列
value: 実際の属性値（文字列、数値、または参照オブジェクトID）
displayValue: 表示用の値（オプション）


オプションパラメーター:
hasAvatar: オブジェクトがアバターを持つかどうか（デフォルト: false）
avatarUUID: アップロードされたアバターのUUID（文字列）
属性値の指定方法:
テキスト属性: "value": "テキスト値"
数値属性: "value": 123
日付属性: "value": "2024-01-01T00:00:00.000Z"
参照属性: "value": "対象オブジェクトのID"
複数値属性: 複数のobjectAttributeValues要素を配列で指定
リクエスト例:
curl -X POST \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/object/create" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "objectTypeId": "3",
    "attributes": [
      {
        "objectTypeAttributeId": 101,
        "objectAttributeValues": [
          {
            "value": "田中太郎"
          }
        ]
      },
      {
        "objectTypeAttributeId": 102,
        "objectAttributeValues": [
          {
            "value": "開発部"
          }
        ]
      }
    ]
  }'
レスポンス例:
{
  "id": 2,
  "label": "db-server-01",
  "objectKey": "SRV-2",
  "avatar": {
    "url16": "https://example.com/avatar16.png",
    "url48": "https://example.com/avatar48.png"
  },
  "objectType": {
    "id": 1,
    "name": "Server"
  },
  "created": "2024-01-02T00:00:00.000Z",
  "updated": "2024-01-02T00:00:00.000Z",
  "hasAvatar": true,
  "attributes": [
    {
      "id": 3,
      "objectTypeAttribute": {
        "id": 1,
        "name": "Name"
      },
      "objectAttributeValues": [
        {
          "value": "db-server-01",
          "displayValue": "db-server-01"
        }
      ]
    }
  ]
}
 オブジェクトの更新（PUT /object/{id}）既存のオブジェクトの属性値を更新します。部分的な更新が可能で、指定した属性のみが変更されます。
必須パラメーター:
{id}: URLパスパラメータで更新対象のオブジェクトIDを指定
リクエストボディ: 更新する属性の配列
objectTypeAttributeId: 更新する属性のタイプID（数値）
objectAttributeValues: 新しい属性値の配列
value: 新しい属性値


オプションパラメーター:
なし（部分更新のため、変更したい属性のみを指定）
更新時の注意点:
部分更新: 指定した属性のみが更新され、他の属性は現在の値が保持されます
配列属性: 配列全体が置き換えられるため、既存の値も含めて全て指定する必要があります
参照属性: 参照先オブジェクトのIDを正しく指定してください
必須属性: 必須属性を空にする場合はエラーが発生します
リクエスト例:
curl -X PUT \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/object/45" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "objectTypeAttributeId": 102,
      "objectAttributeValues": [
        {
          "value": "マーケティング部"
        }
      ]
    }
  ]'
 5. その他の便利なAPI グローバルアイコンの取得（Get icon global）システムで使用可能なすべてのアイコンを取得します。

オブジェクトタイプ作成時にアイコンIDを指定する際に便利です。
必須パラメーター:
なし（ワークスペースIDはURLパスで指定）
オプションパラメーター:
なし
リクエスト例:
curl -X GET \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/icon/global" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
 オブジェクトタイプの位置更新（Post objecttype {id} position）オブジェクトタイプの表示順序を変更します。

スキーマ内でのオブジェクトタイプの並び順を制御できます。
必須パラメーター:
{id}: URLパスパラメータでオブジェクトタイプIDを指定
オプションパラメーター:
toObjectTypeId: オブジェクトタイプの新しい親として指定したい対象（文字列）
position: 並び順（整数値）
リクエスト例:
curl -X POST \
  "https://api.atlassian.com/jsm/assets/workspace/${WORKSPACE_ID}/v1/objecttype/3/position" \
  -H "Authorization: Basic ${AUTH_STRING}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 1
  }'
 6. その他注意事項など レート制限対策AtlassianAPIには呼び出し頻度の制限（1分あたり1,000リクエストまで）が設定されています。

https://developer.atlassian.com/cloud/assets/#assets-rest-api

大量のデータ処理を実行する際は、処理ごとに余裕値を持たせた待機時間を設定するなどの対策を推奨いたします。
 エラーレスポンスの処理API呼び出しが失敗した場合は、HTTPステータスコードとレスポンスボディを確認してください。
一般的なエラーコード:
400: リクエストパラメータが不正
401: 認証に失敗（APIトークンまたは権限の問題）
403: アクセス権限が不足
404: 指定したリソースが存在しない
429: レート制限に到達
500: サーバー内部エラー
エラーレスポンス例:
{
  "error": "Bad Request",
  "message": "Object type with id '999' does not exist",
  "code": 400
}
 パフォーマンス最適化のTipsページネーション活用: 大量データの取得時はmaxResultsとstartAtを適切に設定
必要最小限のフィールド取得: includeAttributesなど、不要なデータは除外
バッチ処理: 可能な場合は複数の操作をまとめて実行
キャッシュ活用: スキーマ情報など変更頻度の低いデータはローカルキャッシュを活用
 まとめAPIを使用することで、アセット管理の自動化や、スクリプトによるマイグレーションの簡易化などが可能になります。

本記事でご紹介した内容をご活用いただければ幸いです！
また、今回紹介したもの以外にもいくつかのAPIエンドポイントが用意されています。

気になる方はぜひ、詳細な仕様確認も兼ねて Atlassian公式リファレンス をご参照ください！
Jira Service Managementのアセットで使用できるAPIについてまとめてみた

前提条件

APIトークンの取得

workspaceIdの確認

よく使うスキーマAPI一覧

Basic認証の準備

1. スキーマ操作

スキーマ一覧の取得（Get objectschema list）

スキーマの作成（POST objectschema create）

単一スキーマの詳細取得（Get objectschema {id}）

2. オブジェクトタイプ操作

オブジェクトタイプ一覧の取得（GET objectschema {id} objecttypes）

オブジェクトタイプの作成（POST objecttype create）

3. 属性操作

オブジェクトタイプの属性一覧取得（Get objecttype {id} attributes）

属性の作成（Post objecttypeattribute {objectTypeId}）

4. オブジェクト操作（Post object aql）

AQLクエリによるオブジェクト検索

オブジェクトの詳細取得（Get object {id}）

オブジェクトの作成（POST /object/create）

オブジェクトの更新（PUT /object/{id}）

5. その他の便利なAPI

グローバルアイコンの取得（Get icon global）

オブジェクトタイプの位置更新（Post objecttype {id} position）

6. その他注意事項など

レート制限対策

エラーレスポンスの処理

パフォーマンス最適化のTips

まとめ

主なカテゴリ

AWSで探す

注目のテーマ

プロダクトやサービスで探す

特集やシリーズから探す

お問い合わせ

運営会社
