メインコンテンツまでスキップ

通報サービス以外から ITサービスマネジメントへ インシデント起票する

概要の説明​

WebSAM Cloud ITサービスマネジメントが提供するインシデント起票APIを使って、外部アプリから直接インシデントを自動起票する方法を説明します。

通報サービスを経由せずに、監視システムや業務アプリなど任意の外部アプリから API を呼び出して ITサービスマネジメントにインシデントを起票することができます。

外部アプリから ITサービスマネジメントにインシデントを起票する設定の流れは次の通りです。

  1. ITサービスマネジメントで API キーを取得する
  2. 起票に必要な各種 ID を確認する
  3. 外部アプリから API を呼び出してインシデントを起票する

ITサービスマネジメントで API キーを取得する​

API 経由でインシデントを起票するには、APIキーによる認証が必要です。

  1. 画面右上のログインユーザ名をクリックします。

  2. 個人設定をクリックします。

  3. 「APIキーを追加」をクリックします。

  4. APIキーの確認ダイアログが表示されますので、キーをコピーして保存後に OK をクリックします。

備考

APIキーの取得はAPIキーを追加したときのみ可能です。保存漏れや漏洩した場合はAPIキーを再作成してください。

起票に必要な各種 ID を確認する​

API のリクエストには、組織 ID・フォーム ID などの各種 ID が必要です。

プロジェクト ID を確認する​

  1. 管理センターのプロジェクトを開きます。
  2. プロジェクト一覧から対象のプロジェクトを選択します。
  3. プロジェクト詳細画面の「プロジェクト ID」欄からIDをコピーします。

組織 ID を確認する​

  1. 管理センターの組織を開きます。
  2. 組織一覧から対象の組織を選択します。
  3. 組織詳細画面 > 組織情報タブの「組織 ID」欄からIDをコピーします。

フォーム ID を確認する​

  1. 管理センターのフォームを開きます。
  2. フォーム一覧から対象のフォームを選択します。
  3. フォーム画面 > 基本情報タブの「フォーム ID」欄からIDをコピーします。

ユーザ ID を確認する（担当者を指定する場合）​

  1. 管理センターのユーザを開きます。
  2. ユーザ一覧から対象のユーザを選択します。
  3. ユーザ詳細画面の「ユーザ ID」欄からIDをコピーします。

外部アプリから API を呼び出してインシデントを起票する​

取得した API キーと各種 ID を使って、HTTP POST リクエストを送信します。

監視ツールや業務アプリなど、HTTP リクエストを送信できるアプリであれば、以下のエンドポイント・ヘッダ・ボディを設定することで ITサービスマネジメントにインシデントを起票できます。各種プログラミング言語の HTTP クライアントライブラリや、監視ツールの Webhook 機能なども同様に利用できます。

エンドポイント​

https://<テナントID>.itsm.masterscope.jp/api/v1/ticket
備考

テナントIDは払い出された環境ごとに異なります。ログイン先の URL（ホスト）を確認してください。

リクエストヘッダ​

キー必須説明
Itpm-Project任意起票先プロジェクトID（プロジェクト追加オプション契約時のみ指定）
Itpm-Organization必須発行者の所属組織ID（起票先組織）
X-API-KEY必須APIキー
Content-Type必須application/json を指定

リクエストボディ（主要パラメータ）​

キー必須型説明
title必須string件名（255文字以内）
summary必須string内容（20000文字以内）
status必須number1（オープン）を指定
statusName必須stringオープン を指定
assignOrganizationId必須string(uuid)担当組織 ID
assignUserId任意string(uuid)担当ユーザ ID
priority必須number1: 低、2: 中、3: 高
serviceCatalogFormId必須string(uuid)フォーム ID
dueDate任意string(ISO8601)期限日（例：2024-08-01T00:00:00+09:00）

curl コマンドの実行例​

以下は curl を使った実行例です。使用するアプリの HTTP クライアント機能で同様にエンドポイント・ヘッダ・ボディを設定してください。

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Itpm-Organization: <組織ID>" \
  -H "X-API-KEY: <APIキー>" \
  -d '{
    "serviceCatalogFormId": "<フォームID>",
    "title": "障害発生：Webサーバ応答なし",
    "summary": "監視システムが Webサーバの応答なしを検知しました。",
    "assignOrganizationId": "<担当組織ID>",
    "status": 1,
    "statusName": "オープン",
    "priority": 3
  }' \
  https://<テナントID>.itsm.masterscope.jp/api/v1/ticket
備考

プロジェクト追加オプションを契約している場合は、-H "Itpm-Project: <プロジェクトID>" を追加してください。

レスポンス​

ステータス説明
200起票完了
401APIキーが空または不正
403エンドポイントが不正

詳細なAPI仕様を確認する​

ウォッチャの指定方法やカスタムフィールドの設定など、詳細なAPI仕様については 他アプリからインシデントを自動起票したい（API連携） を参照してください。