インシデントコメント 作成¶
POST /api/v1/incidents/comment/{incident_uuid}/add
概要¶
指定したインシデントにコメントを追加し、非同期で通知します。
呼び出し前の準備と使用手順¶
現在の Key には incidents.incidentsReplyManage が必要で、現在のワークスペースに限定されます。パス incident_uuid は、事前にインシデント詳細で現在のワークスペースに対象が存在し、削除されていないことを確認してください。本エンドポイントはまずコメントを保存し、その後でインシデントを照会して非同期通知を送信します。無効なインシデント UUID が事前の存在チェックで拒否される保証はなく、孤立したコメントが先に作成された後に 500 が返る可能性があるため、本エンドポイントでインシデントの存在を検証することはできません。コメント作成時にインシデントに担当者が設定されている場合、通知候補は担当者と有効な @ メールアドレスです。担当者がいない場合は有効な @ メールアドレスのみを使用し、どちらもない場合は送信されないことがあります。reply は現在、一致するスケジュールに基づく自動フォールバック通知を行いません。非同期チャネルやミュートなどの条件は引き続き実際の配信に影響するため、成功したからといって到達を保証するものではありません。
添付ファイル UUID は本モジュールのアップロードで取得します。今回のバインドは追加/再バインドであり、省略または [] ではバインド解除されません。既存の添付ファイルは添付ファイル削除で個別に操作する必要があります。コメント/添付ファイル/通知は段階的に送信されるため、500 やタイムアウトでもコメントや添付ファイルが保存されている可能性があります。まずページングで読み戻し、本文・作成主体・時刻を照合して、コメントや通知の重複を避けてください。コメント作成には冪等キーがなく、変更を重複送信すると更新時刻も変わります。レスポンスにはコメントエンティティと共通宣言のみが含まれ、先ほどバインドした添付ファイルの概要は含まれません。添付ファイルおよび識別情報はコメント一覧から読み取ってください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| incident_uuid | string | Y | 現在のワークスペースのインシデント UUID であり、アラートイベント ID、SLO UUID、コメント UUID ではありません。 null 許可: False 例: incident_example取得または入力方法: インシデント一覧から content.data[].uuid を取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| attachmentUUIDs[*] | string | 単一の添付ファイル UUID 文字列。 例: att_example取得または入力方法: まず添付ファイルアップロードで content.attachmentUuid を取得し、添付ファイルの所属を確認します。 |
|
| extend.members | array | 任意のアカウントメンション配列。コメント作成時に type=@ かつ uuid を持つアカウントのメールアドレスを抽出して重複排除します。アカウント照会はワークスペースで再度制約されないため、呼び出し元は検証済みの現在のワークスペースメンバーを使用する必要があります。通知の到達は保証されません。変更時は候補を計算しますが、現在は対応するメール通知を配信しません。 例: [{"type": "@", "uuid": "acnt_example", "exists": true}]取得または入力方法: 現在のワークスペースのメンバー一覧からアカウント UUID を取得し、エディタのメンションに従って構築します。 |
|
| extend.members[*] | object | 1 つのメンションオブジェクト。任意のメールアドレスで uuid を置き換えることはできません。 例: {"type": "@", "uuid": "acnt_example", "exists": true}取得または入力方法: members と同じ取得元です。 |
|
| extend.members[*].type | string | @ のみが追加のメール候補に入り、それ以外の型は入りません。 例: @取得または入力方法: エディタのアカウントメンションのマーカーです。 |
|
| extend.members[*].uuid | string | 削除されていないアカウント UUID。対応するアカウントがない場合はメール候補に入りません。 例: acnt_example取得または入力方法: 現在のワークスペースのメンバー一覧のアカウント UUID です。 |
|
| extend.members[*].exists | boolean | 任意の互換マーカー。現在の通知ロジックはこれに依存して存在判定を行いません。 例: true取得または入力方法: 呼び出し元のエディタがメンバーの存在状態に基づいて入力します。 |
|
| extend.linkList | array | 表示用リンク配列。本インターフェースは対象へのアクセス/検証を行いません。 例: [{"name": "調査手順書", "link": "https://example.com/runbook"}]取得または入力方法: 関連ドキュメントのリンクを入力します。 |
|
| extend.linkList[*] | object | 1 つのリンクオブジェクト。 例: {"name": "調査手順書", "link": "https://example.com/runbook"}取得または入力方法: linkList と同じ取得元です。 |
|
| extend.linkList[*].name | string | 文字列の表示名。 例: 調査手順書取得または入力方法: リンクの表示名を入力します。 |
|
| extend.linkList[*].link | string | URL 文字列。 例: https://example.com/runbook取得または入力方法: 顧客がアクセス可能なアドレスを入力します。 |
|
| extend.manager | array | 履歴上の外部担当者メールアドレス配列。旧 managerInfos の互換保持にのみ使用され、インシデントの担当者設定を置き換えることはありません。 例: ["xxx@guance.com"]取得または入力方法: 旧コメントの既存の extend.manager を変更前に読み取ります。 |
|
| extend.manager[*] | string | 単一の履歴メールアドレス。 例: xxx@guance.com取得または入力方法: 既存の manager 配列です。 |
|
| extend.extra | object | 任意のオブジェクト。旧 creator が存在する場合は旧値をコピーし、書き換えを避けます。パスワードやトークンをこの公開拡張に含めないでください。 例: {}取得または入力方法: 旧コメントの既存の extra 補助資料です。 |
|
| extend.extra.creator | object | 履歴上の補助識別情報。変更時に既存の旧 creator が優先され、実際のコメント作成 Key の識別情報を書き換えることはできません。 例: {}取得または入力方法: 旧 extra.creator の資料です。 |
|
| extend.extra.managerInfos | object | メールアドレスから識別情報オブジェクトへのマッピング。有効な新しいマッピングが提供されない場合は、manager 配列にまだ存在する旧項目のみを保持します。 例: {}取得または入力方法: 旧 extra.managerInfos のマッピングです。 |
|
| attachmentUUIDs | array | 省略時はバインドされません。指定された場合は 1 つずつコメントに追加/再バインドされ、[] でも既存の添付ファイルはクリアされません。無効または削除済みの UUID は 500 になる可能性があり、バインドは内部的にコミットされるため、後続の失敗時にも保存済みとなっている場合があります。自分で検証した正当な添付ファイルのみを使用し、他のリソースの添付ファイルを借用しないでください。 null 許可: False 例: ["att_example"]取得または入力方法: まず添付ファイルアップロードで content.attachmentUuid を取得し、添付ファイルの所属を確認します。 |
|
| comment | string | Y | 必須の文字列。現在の宣言では非空を強制していませんが、意味のある内容を指定することを推奨し、削除の代わりに空文字列を使用しないでください。 null 許可: False 例: データベース接続の異常を確認しました。対応中です。取得または入力方法: 現在の担当者がインシデントの進捗を入力します。 |
| extend | json | JSON オブジェクトである必要があります。作成時は {} を省略、変更時は省略で保持、指定時は全体を置換します({} でクリアされますが、旧 extra.creator/managerInfos は互換保持されます)。ルートパラメータが null/配列/文字列の場合は公開ルートが先に 406 で拒否します。内部の members:null、非オブジェクトのメンバー、extra:null など宣言されていないサブ構造は 500 になる可能性があるため、本文のサブフィールド構造に従って入力してください。 null 許可: False 例: {"members": [{"type": "@", "uuid": "acnt_example", "exists": true}], "linkList": [{"name": "調査手順書", "link": "https://example.com/runbook"}]}取得または入力方法: 呼び出し元のエディタが構築し、表示が必要なメンションとリンクを保持します。 |
パラメータ補足説明¶
添付ファイルはまず本モジュールの attachmentUpload でアップロードし、content.attachmentUuid を attachmentUUIDs に渡します。extend.members はアカウント UUID でメンションします。コメント追加時は通知が送出されますが、コメント変更時は現在そのメンション通知を再送信しません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/incidents/comment/incident_example/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"comment":"データベース接続の異常を確認しました。対応中です。"}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | データベースの行 ID。業務上の識別には uuid を使用し、送信前のスナップショットでは null になることがあります。 |
| content.uuid | string | このリソースの UUID。 |
| content.status | integer | データベースのステータス。0 は有効/3 は削除。インシデントの業務ステータス incidentsStatus とは異なります。 |
| content.creator | string | 作成主体。API Key の場合は通常 wsak_リソースUUID です。 |
| content.updator | string | 最終更新主体。未更新の場合は空になることがあります。 |
| content.createAt | integer | Unix 秒の作成時刻。 |
| content.updateAt | integer | Unix 秒の最終更新時刻。 |
| content.deleteAt | integer | Unix 秒の削除時刻。未削除の場合は -1。 |
| content.incidentsUUID | string | 所属するインシデントの UUID。 |
| content.workspaceUUID | string | 所属するワークスペース。 |
| content.comment | string | コメント本文。システム生成の操作説明を含むことがあります。本文を構造化された操作記録として扱わないでください。 |
| content.extend | object または JSON | 保存された拡張。システムコメントには operator/operator_info/operate_type/before/after などが含まれることがあります。 |
| content.extend.members | array<object> |
@ メンバーの入力記録。コメント作成時の追加メール通知候補に使用され、配信済みを意味しません。 |
| content.extend.members[].type | string | @ はアカウントメンションを表し、それ以外の値はこのメール候補に入りません。 |
| content.extend.members[].uuid | string | アカウント UUID。 |
| content.extend.members[].exists | boolean | クライアントエディタの状態。サーバー側の通知フィルタはこの値に依存しません。 |
| content.extend.linkList | array<object> |
業務リンクの表示情報。 |
| content.extend.linkList[].name | string | リンクの表示名。 |
| content.extend.linkList[].link | string | リンク URL。 |
| content.extend.manager | array<string> |
履歴上の外部担当者メールアドレス配列。変更時に旧 extra.managerInfos を保持する場合のフィルタに使用されます。インシデントの assigner とは異なります。 |
| content.extend.manager[] | string | 1 つの履歴担当者メールアドレス。 |
| content.extend.extra | object | 外部識別情報の補助資料。変更時に元の creator と、manager に残っている managerInfos が保持されることがあります。 |
| content.extend.extra.creator | JSON | 元の作成側の補助識別情報。旧値が存在する場合、変更時にこれを利用して作成者を書き換えることはできません。 |
| content.extend.extra.managerInfos | object | 履歴担当者メールアドレスから識別情報への動的マッピング。 |
| content.extend.extra.managerInfos.邮箱 | JSON | そのメールアドレスに対応する元の識別情報。 |
| content.extend.operator | string | システム操作コメントの元操作主体識別子。 |
| content.extend.operator_info | object | システム操作コメントに付随する主体概要。 |
| content.extend.operate_type | string | システム操作コメントに付随する操作タイプ。 |
| content.extend.before | JSON | システム操作の旧値。アクションによって変化します。 |
| content.extend.after | JSON | システム操作の新値。アクションによって変化します。 |
| content.extend.自定义字段 | JSON | 呼び出し元/システムが保存したその他の拡張キーと値。本インターフェースは固定構造を保証しません。 |
| content.extend.operator_info.uuid | string | 主体 UUID。システム返信の主体は空またはシステム識別子の場合があります。 |
| content.extend.operator_info.status | integer | 主体ステータス。 |
| content.extend.operator_info.wsAccountStatus | integer | ワークスペースメンバーのステータス。Key の場合は Key のステータスであり、インシデントのステータスではありません。 |
| content.extend.operator_info.username | string | ログイン名/Key 名/システム名。 |
| content.extend.operator_info.name | string | 表示名。システム AI の表示名はサイト設定を使用します。 |
| content.extend.operator_info.iconUrl | string | アバター URL。システム概要では省略されることがあります。 |
| content.extend.operator_info.email | string | 連絡先メールアドレス。Key の概要では Key UUID の場合があり、配信可能なメールアドレスではありません。 |
| content.extend.operator_info.mobile | string | 連絡先電話番号。空の場合があります。 |
| content.extend.operator_info.countryCode | string | 国番号。システム概要では省略されることがあります。 |
| content.extend.operator_info.acntWsNickname | string | ワークスペースのニックネーム。システム概要では省略されることがあります。 |
| content.declaration | object | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": 123,
"uuid": "inccmt_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"incidentsUUID": "incident_example",
"workspaceUUID": "wksp_example",
"comment": "データベース接続の異常を確認しました。対応中です。",
"extend": {},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトでない | 一部の JSON ファイル形式エラー | オブジェクトを送信してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ/キュー、無効な添付ファイル、展開されていないサブフィールド型/履歴の異常構造、または下流の未処理例外 | 内部エラー | 読み取り専用リクエストはバックオフして再試行できます。書き込みリクエストはまずインシデント/コメントの現状および通知記録を読み取り、既に送信済みの可能性があるため重複作成や重複通知を避けてください。 |