コンテンツにスキップ

返信の変更



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 データベース、キャッシュ/キュー、無効な添付ファイル、展開されていない子フィールド型/過去の異常構造、または下流で未処理の例外 内部エラー 読み取り専用リクエストはバックオフして再試行できます。書き込みリクエストは、まずインシデント/コメントの現在状態と通知記録を読み取ってください。すでにコミットされている可能性があるため、重複作成や重複通知を避けてください。

フィードバック

このページは役に立ちましたか?