他アプリからインシデントを自動起票したい（API連携）
概要
本章では、本製品のインシデント起票APIを用いて、他アプリからインシデントを自動起票する方法をご案内します。
API連携ではAPIキーを用いて、外部認証を行うため事前にAPIキーを取得が必要となります。
本製品でAPIキーを取得する
-
画面右上のログインユーザ名をク リックします。
-
個人設定をクリックします。
-
「APIキーを追加」をクリックします。
-
APIキーの確認ダイアログが表示されますので、キーを保存後にOKをクリックします。
備考
APIキーの取得は追加したときのみ可能です。保存漏れや漏洩した場合はAPIキーを再作成してください。
API仕様
チケット登録
エンドポイント
https://<テナントID>.itsm.masterscope.jp/api/v1/ticket
備考
テナントIDは払い出された環境毎に異なります。ログイン先のURL(ホスト)を確認してください。
メソッド
POST
ヘッダ
| キー | 必須 | 説明 |
|---|---|---|
| Itpm-Project | 任意 | 発行者の所属プロジェクト(起票先プロジェクト) (確認方法) |
| Itpm-Organization | 必須 | 発行者の所属組織ID(起票先組織) (確認方 法) |
| X-API-KEY | 必須 | APIキー |
| Content-Type | 必須 | application/json を指定 |
備考
- Itpm-Projectはプロジェクト追加オプション未契約の場合は指定不要です。
- Itpm-Projectを省略した場合、起票先プロジェクトはデフォルトプロジェクトに自動で指定されます。
ペイロード
| キー | 必須 | 型 | 説明 |
|---|---|---|---|
| title | 必須 | string | 件名(255文字以内) |
| summary | 必須 | string | 内容(20000文字以内) |
| status | 必須 | number | ステータスとして起票を示す1を指定してください |
| statusName | 必須 | string | ステータス名としてオープンを指定してください |
| assignOrganizationId | 必須 | string(uuid) | 担当者と指定する組織ID (確認方法) |
| assignUserId | 任意 | string(uuid) | 担当者として指定するユーザID(確認方法)。ユーザが所属する組織IDをassignOrganizationIdに指定する必要があります。 |
| priority | 必須 | number | 1: 低、2:中、3:高のいずれかを指定してください |
| dueDate | 任意 | string(ISO8601) | 期限日をISO8601フォーマットで指定してください。例：2024-08-01T00:00:00+09:00 |
| serviceCatalogFormId | 必須 | string(uuid) | インシデントのフォームID (確認方法) |
| customFields | 任意 | json(id,value) | カスタムフィールドのフィールドID (確認方法)とフィールドの値を指定してください。例："customFields":[{"customFieldId": "xxxxx","customFieldValue": "string"}] |
| watchers | 任意 | object | 起票者ウォッチャ。起票時にチケットの通知先として起票者側のウォッチャを指定できます。詳細は下記 ウォッチャの指定方法 を参照してください。 |
| assignWatchers | 任意 | object | 担当者ウォッチャ。起票時にチケットの通知先として担当者側のウォッチャを指定できます。詳細は下記 ウォッチャの指定方法 を参照してください。 |
ウォッチャの指定方法
watchers（起票者ウォッチャ）および assignWatchers（担当者ウォッチャ）は、以下の構造で指定します。
| キー | 必須 | 型 | 説明 |
|---|---|---|---|
| users | 任意 | array | ウォッチャとして指定するユーザのリスト |
| users[].id | 必須 | string(uuid) | ユーザID (確認方法) |
| users[].email | 必須 | string | ユーザのメールアドレス(256文字以内) |
| users[].watcherStatus | 必須 | number | 1(登録済み)を指定してください |
| organizations | 任意 | array | ウォッチャとして指定する組織のリスト |
| organizations[].id | 必須 | string(uuid) | 組織ID (確認方法) |
| organizations[].watcherStatus | 必須 | number | 1(登録済み)を指定してください |
指定例：
"watchers": {
"users": [
{"id": "<ユーザID>", "email": "user@example.com", "watcherStatus": 1}
],
"organizations": [
{"id": "<組織ID>", "watcherStatus": 1}
]
}
備考
watchersとassignWatchersはそれぞれ独立して指定可能です。片方のみの指定も可能です。usersとorganizationsもそれぞれ独立して指定可能です。片方のみの指定も可能です。- ウォッチャに指定するユーザおよび組織は、事前に本製品に登録されている必要があります。
レスポンス
| ステータス | 説明 |
|---|---|
| 200 | 登録完了 |
| 401 | APIキーが空または不正 |
| 403 | エンドポイントが不正 |
パラメータのID確認方法
プロジェクトIDを確認する
- 管理センターのプロジェクトを開きます。
- プロジェクト一覧から対象のプロジェクトを選択します。
- プロジェクト詳細画面の「プロジェクトID」欄からIDをコピーします。
組織IDを確認する
- 管理センターの組織を開きます。
- 組織一覧から対象の組織を選択します。
- 組織詳細画面 > 組織情報タブの「組織ID」欄からIDをコピーします。
ユーザIDを確認する
- 管理センターのユーザを開きます。
- ユーザ一覧から対象のユーザを選択します。
- ユーザ詳細画面の「ユーザID」欄からIDをコピーします。
フォームIDを確認する
- 管理センターのフォームを開きます。
- フォーム一覧から対象のフォームを選択します。
- フォーム画面 > 基本情報タブの「フォームID」欄からIDをコピーします。
カスタムフィールドのフィールドIDを確認する
- 管理センターのフォームを開きます。
- フォーム一覧から対象のフォームを選択します。
- フォーム画面 > フィールドタブ > 右セクションの「フィールドID」欄からIDをコピーします。
連携先アプリでAPIキーを利用してインシデントを起票する
コマンド実行(curl)の場合
以下のようにコマンドを実行します。
curl -X POST -H "Content-Type: application/json" -H "Itpm-Project: <プロジェクトID>" -H "Itpm-Organization: <組織ID>" -H "X-API-KEY: <APIキー>" -d "{\"serviceCatalogFormId\":\"<フォームID>\",\"title\":\"件名\",\"summary\":\"本文\",\"assignUserId\":\"<担当ユーザID>\",\"assignOrganizationId\":\"<担当組織ID>\",\"status\":1,\"statusName\":\" オープン\",\"priority\":1}" https://<テナントID>.itsm.masterscope.jp/api/v1/ticket
ウォッチャを指定する場合は、以下のようにペイロードにwatchers（起票者ウォッチャ）やassignWatchers（担当者ウォッチャ）を追加します。
curl -X POST -H "Content-Type: application/json" -H "Itpm-Project: <プロジェクトID>" -H "Itpm-Organization: <組織ID>" -H "X-API-KEY: <APIキー>" -d "{\"serviceCatalogFormId\":\"<フォームID>\",\"title\":\"件名\",\"summary\":\"本文\",\"assignUserId\":\"<担当ユーザID>\",\"assignOrganizationId\":\"<担当組織ID>\",\"status\":1,\"statusName\":\"オープン\",\"priority\":1,\"watchers\":{\"users\":[{\"id\":\"<ウォッチャユーザID>\",\"email\":\"<ウォッチャユーザメールアドレス>\",\"watcherStatus\":1}],\"organizations\":[{\"id\":\"<ウォッチャ組織ID>\",\"watcherStatus\":1}]},\"assignWatchers\":{\"users\":[{\"id\":\"<ウォッチャユーザID>\",\"email\":\"<ウォッチャユーザメールアドレス>\",\"watcherStatus\":1}]}}" https://<テナントID>.itsm.masterscope.jp/api/v1/ticket
WebSAM Cloud 通報サービス の場合
- WebSAM Cloud ITサービスマネジメント連携機能をご利用ください。設定方法はこちらを参照ください。
備考
上記設定における各種IDの取得方法はこちらを参照ください。