返信の変更¶
POST /api/v1/incidents/comment/{comment_uuid}/modify
概要¶
自身が作成したインシデントコメントを変更します。
呼び出し前の準備と使用手順¶
現在の API キーには incidents.incidentsReplyManage が必要で、現在のワークスペースのみを対象とします。パス comment_uuid はコメント一覧の content.data[].uuid から取得します。変更できるのは元の作成者のみで、別の API キーは同じロールでも拒否されます。同じ API キーをローテーションしてもリソース UUID は保持されます。comment は常に必須です。extend は省略時は保持され、指定時は全体が置換されます。旧 extra.creator/managerInfos が存在する場合は互換ルールに従って保持され、表示用フィールドで作成者を改ざんすることはできません。現在、変更時には新規 @ メンバーへのメールは送信されません。members フィールドの保存成功をもって通知済みと判断しないでください。
添付ファイル UUID は本モジュールのアップロードで取得します。今回のバインドは追加/再バインドであり、省略または [] ではバインド解除されません。既存の添付ファイルは添付ファイルを削除で個別に操作してください。コメント/添付ファイル/通知は段階的に送信されます。500/タイムアウトでもコメントや添付ファイルが保存されている可能性があります。まずページングで読み戻し、本文、作成者、時刻を照合して、コメントや通知の重複を避けてください。コメント作成には冪等キーがなく、変更を重複送信した場合も更新日時が更新されます。レスポンスには現在の添付ファイルの概要が含まれます。creatorInfo/updatorInfo は返されないため、コメント一覧で補完する必要があります。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| comment_uuid | string | Y | 単一コメントの UUID であり、インシデント UUID ではありません。 null を許可: False 例: inccmt_example取得または入力方法: コメント一覧の content.data[].uuid から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API キー管理から、この操作権限を持つ OpenAPI キーを取得します。 |
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 | 表示用リンク配列です。本 API はリンク先へのアクセス/検証を行いません。 例: [{"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 | 1 つの過去のメールアドレス。 例: xxx@guance.com取得または入力方法: 既存の manager 配列。 |
|
| extend.extra | object | 任意のオブジェクト。旧 creator が存在する場合は元の値がコピーされ、書き換えを防ぎます。パスワード/トークンをこの公開拡張に含めないでください。 例: {}取得または入力方法: 旧コメントに既存の extra 補助情報。 |
|
| extend.extra.creator | object | 過去の補助識別情報。変更時は既存の旧 creator が優先され、実際のコメント作成 API キーの識別情報を書き換えることはできません。 例: {}取得または入力方法: 旧 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/inccmt_example/modify' \
-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 キーの場合は通常 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 | 呼び出し元/システムが保存するその他の拡張キー値。本 API は固定構造を保証しません。 |
| content.extend.operator_info.uuid | string | 主体 UUID。システム返信の主体は空またはシステム識別子の場合があります。 |
| content.extend.operator_info.status | integer | 主体の状態。 |
| content.extend.operator_info.wsAccountStatus | integer | ワークスペースメンバーの状態。API キーの場合はキー状態を取得し、インシデント状態ではありません。 |
| content.extend.operator_info.username | string | ログイン名/キー名/システム名。 |
| content.extend.operator_info.name | string | 表示名。システム AI の表示名はサイト設定を使用します。 |
| content.extend.operator_info.iconUrl | string | アバター URL。システム概要では省略される場合があります。 |
| content.extend.operator_info.email | string | 連絡先メールアドレス。キー概要ではキー UUID の場合があり、配信可能なメールアドレスではありません。 |
| content.extend.operator_info.mobile | string | 連絡先電話番号。空の場合があります。 |
| content.extend.operator_info.countryCode | string | 国番号。システム概要では省略される場合があります。 |
| content.extend.operator_info.acntWsNickname | string | ワークスペースのニックネーム。システム概要では省略される場合があります。 |
| content.attachments | array<object> |
関連付け済み添付ファイルの概要。未関連付けの場合は []。 |
| content.attachments[].uuid | string | 添付ファイル UUID。本モジュールの downloadAttachment インターフェースでダウンロードします。 |
| content.attachments[].fileName | string | 元のファイル名。 |
| content.attachments[].fileSuffix | string | ファイル拡張子。ドットは含みません。ファイル内容/直リンクは返されません。 |
| content.declaration | object | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": 123,
"uuid": "inccmt_example",
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"deleteAt": -1,
"incidentsUUID": "incident_example",
"workspaceUUID": "wksp_example",
"comment": "已确认数据库连接异常,正在处理。",
"extend": {},
"attachments": [],
"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 ファイル形式エラー | オブジェクトを送信します。 |
| 404 | ft.ObjectNotExists | 現在のワークスペースで該当するアクティブなコメントが見つからない | 指定されたオブジェクトが存在しません | 現在のワークスペースのコメント一覧から uuid を再取得します。 |
| 400 | ft.IssueReplyNotModify | 現在の API キーのリソース UUID が元のコメントの creator と一致しない | この返信の作成者ではないため、編集は許可されていません | 元の作成時の API キーを使用してください。extend で作成者を変更して権限を回避しないでください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ/キュー、無効な添付ファイル、展開されていない子フィールド型/過去の異常構造、または下流で未処理の例外 | 内部エラー | 読み取り専用リクエストはバックオフして再試行できます。書き込みリクエストは、まずインシデント/コメントの現在状態と通知記録を読み取ってください。すでにコミットされている可能性があるため、重複作成や重複通知を避けてください。 |