コメントの変更¶
POST /api/v1/error_track/comment/{comment_uuid}/modify
概要¶
自分が作成したエラーコメントを変更し、再度通知します。
呼び出し前と使用手順¶
現在の Key には errorCenter.errorTrackManage が必要です。変更できるのは、現在の同一の Key リソースで作成されたアクティブコメントのみです。システムコメントや他の Key で作成されたコメントは編集できません。comment は完全に置き換えます。extend は省略時は保持され、指定時は全体を置き換え、{} でクリアされます。添付ファイルのバインドは共有セッションを先にコミットする可能性があり、後続の失敗時に本文のロールバックは保証されません。
通知先は、既存の担当者に加えて、今回のリクエストの extend.members のうち type=@ かつ uuid が空でない対象です。チームはメンバーに展開され、利用可能な通知方法で配信されます。一致するスケジュールがない場合は自動的にフォールバックします。変更時も担当者および今回の @ 対象に再度通知されます。extend を省略した場合は、既存の members を使用して再度 @ しませんが、担当者には依然として通知される可能性があります。通常のチャネルで発生する例外はほとんど捕捉され、200 は配信を保証しません。通知準備の失敗により 500 となる可能性があり、コメントはすでに保存されています。
extend はオブジェクトまたは省略を使用し、attachmentUUIDs は配列または省略を使用してください。明示的な null は公開宣言を通過しますが、コミット後に 500 となる可能性があります。members のサブ構造には完全な検証がないため、オブジェクト配列を自身で構築する必要があります。添付ファイルの [] はバインドを解除せず、置き換えリストとも異なります。添付ファイルを再利用するとバインドが変更されるため、先にすべての UUID を確認してください。失敗時は先にコメント/添付ファイルと実際の通知を読み戻し、重複コメントや重複リマインダーを防いでください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| comment_uuid | string | Y | 現在のワークスペースのアクティブコメント UUID。現在の同一の Key リソースで作成されている必要があり、同じロール/同じワークスペースであるだけでは編集できません。 空文字列を許可: False 例: issetcomment_example取得または入力方法: コメント一覧 から content.data[].uuid を取得します。issue_id や isset_ メタデータ UUID は使用できません。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| extend.members | array | オプションのオブジェクト配列。type=@ かつ uuid が空でない項目のみ通知されます。省略または [] の場合、今回の @ 対象は追加されません。子オブジェクトには完全な宣言検証がないため、null や不正な形状は 500 となる可能性があります。保存に成功しても、対象が有効または配信可能であることは保証されません。 例: [{"uuid": "acnt_example", "type": "@"}]取得または入力方法: ワークスペースメンバー または チーム一覧 から本ワークスペースの有効な主体を選択し、エディターの @ 内容に合わせて構築します。 |
|
| extend.members[*] | json | 1 つの @ 対象オブジェクト。 例: {"uuid": "acnt_example", "type": "@"}取得または入力方法: 現在のワークスペースの実際の @ 対象から構築します。 |
|
| extend.members[*].uuid | string | 対象主体の識別子。acnt_ または group_ を推奨します。異なる主体は通知受信者リゾルバーで処理され、未知の値でもエラーになることは保証されません。 例: acnt_example取得または入力方法: 現在のワークスペースのメンバー/チーム一覧から取得し、ロール UUID は使用しません。 |
|
| extend.members[*].type | string | 値が @ の場合は通知に参加し、その他の値は保存できても @ 対象として送信されません。 例: @取得または入力方法: コメントエディターの @ マークプロトコル。 |
|
| extend.カスタムキー | any | 任意の JSON 値(オブジェクト/配列/数値/文字列/ブール/null)。追加のサーバー実行パラメータではありません。 例: incident-123取得または入力方法: 呼び出し元が自身のコメント表示情報を保存します。 |
|
| attachmentUUIDs[*] | string | 単一の添付ファイル UUID 文字列であり、URL やファイル名ではありません。バインドすると添付ファイルのソースが更新されるため、他のコメントの添付ファイルを再利用しないでください。 例: att_example取得または入力方法: 現在のワークスペースにアップロード済みの添付ファイルの uuid。 |
|
| attachmentUUIDs | array | オプションの添付ファイル UUID 配列。省略時はバインドしません。[] は古い添付ファイルをクリアせず、列挙された有効な添付ファイルのみを追加/再バインドします。宣言では null を許可していますが、走査時に 500 となるため、クライアントは null を送信しないでください。存在しない/非アクティブな UUID でも 500 となる可能性があります。サーバーは項目ごとに結果を返したり、バッチ全体の原子性を保証したりしません。 null を許可: True 例: ["att_example"]取得または入力方法: まず現在のワークスペースの添付ファイルアップロードで content.attachmentUuid を取得し、自分で利用可能と確認した添付ファイルのみを使用します。 |
|
| comment | string | Y | 必須の文字列です。現在の宣言では空でないことを強制していませんが、呼び出し元は理解可能な空でない本文を提供する必要があります。変更時は本文を完全に置き換えます。 null を許可: False 例: タイムアウトの原因を特定しました。対応中です。取得または入力方法: 呼び出し元が本文を作成します。エラーセンターエディターとの取り決めに従って表示拡張を保存します。 |
| extend | json | オプションの JSON オブジェクト。指定時は全体を置き換え、変更時に省略した場合は保持されます。作成時に省略した場合は {} です。宣言では null を許可していますが、通知が extend.get を読み取ると 500 となり、コメントがすでに保存されている可能性があります。クライアントは省略するか {} を渡し、null を渡さないでください。ルート配列/文字列は事前に 406 で拒否されます。 null を許可: True 例: {"members": [{"uuid": "acnt_example", "type": "@"}]}取得または入力方法: 呼び出し元が本文を作成します。エラーセンターエディターとの取り決めに従って表示拡張を保存します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/error_track/comment/issetcomment_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"comment":"タイムアウトの原因を特定しました。対応中です。","extend":{"members":[{"uuid":"acnt_example","type":"@"}]}}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 保存後のコメントエンティティ、添付ファイル、エラー種別。本ページには creatorInfo/updatorInfo は含まれません。 |
| content.id | integer または null | データベースの行 ID。パス特定には使用しません。コミット前のスナップショットでは null となる可能性があります。 |
| content.uuid | string | ローカルリソース UUID。詳細メタデータは isset_、操作記録は issetoper_、コメントは issetcomment_ です。 |
| content.status | integer | リソース状態。通常は 0 で、論理削除の 3 はクエリから除外されます。 |
| content.creator | string | 作成主体。自動初期化メタデータは sys、Key 書き込み主体は wsak_ です。 |
| content.updator | string | 最終更新主体。未更新の場合は空になる可能性があります。 |
| content.createAt | integer | Unix 秒の作成時刻。 |
| content.updateAt | integer | Unix 秒の更新時刻。未更新の場合は -1 になることがあります。同じ値での状態/担当者の更新では必ずしも更新されません。 |
| content.deleteAt | integer | Unix 秒の削除時刻。未削除の場合は通常 -1 です。 |
| content.workspaceUUID | string | 現在の Key が属するワークスペース。 |
| content.issueUUID | string | ローカルメタデータの isset_ UUID。パスの issue_id としては使用できません。 |
| content.issueID | string | テレメトリ issue_id のビジネス識別子。 |
| content.comment | string | コメント本文、またはローカライズされたシステム変更文言。 |
| content.extend | object または null | 保存されたコメント拡張。新規リクエストではオブジェクトを使用し、null による後続エラーを回避してください。 |
| content.extend.members | array<object> |
今回の編集時の @ 対象リスト(任意)。常にオブジェクト配列にすることを推奨します。 |
| content.extend.members[].uuid | string | @ 対象主体の UUID。現在のワークスペースのメンバー/チーム一覧から有効な acnt_/group_ を取得することを推奨します。 |
| content.extend.members[].type | string | 値が @ かつ uuid が空でない項目のみ通知に参加します。 |
| content.extend.カスタムキー | JSON | 呼び出し元が保存するその他の JSON 拡張。固定の実行セマンティクスはありません。 |
| content.attachments | array<object> |
このコメントにバインド済みの有効な添付ファイルの概要。ダウンロード URL/ファイル内容は含みません。添付ファイルがない場合は [] です。 |
| content.attachments[].uuid | string | 添付ファイル UUID。権限付きの添付ファイル読み取り/管理に使用します。 |
| content.attachments[].fileName | string | ファイル名。 |
| content.attachments[].fileSuffix | string | 最後のドット以降の拡張子。ドットがない場合は名前全体になることがあります。 |
| content.errorType | string | 親ローカルメタデータの extend.errorType。空になる可能性があります。 |
| content.declaration | object または null | 現在のワークスペースの公開宣言。 |
{
"code": 200,
"content": {
"id": 7,
"uuid": "issetcomment_example",
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"issueUUID": "isset_example",
"issueID": "err_payment_timeout",
"comment": "タイムアウトの原因を特定しました。対応中です。",
"extend": {
"members": [
{
"uuid": "acnt_example",
"type": "@"
}
]
},
"attachments": [],
"errorType": "js_error",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
業務主体/添付ファイルは、後続の通知やレスポンスより先にコミットが完了する場合があります。HTTP の失敗は、コメントや通知が存在しないことを意味しません。共通の認証/宣言エラーは共通エラー説明に従って処理され、ルート extend がオブジェクトでないかつ null でない場合は 406 で拒否されます。null および無効なサブ構造/添付ファイルの後続例外は通常、一律で 500 になります。
| 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 | コメントの作成主体が現在の Key リソースでない | この返信の作成者ではないため、編集は許可されていません | 元の作成 Key を使用するか、許可された製品フローで処理してください。同じロールの別の Key では代理変更できません。 |
| 401 | ft.WKSPNotExistOrReleased | 担当者または今回の @ 対象が存在し、受信者の準備でワークスペースの再クエリに失敗した | ワークスペースが存在しない、または解放済み | ワークスペースがまだ有効か確認してください。コメント/親メタデータはすでにコミットされている可能性があるため、先に読み戻し、重複コメントやリマインダーを避けてください。 |
| 500 | ft.InternalServerError | データベース、履歴 JSON、添付ファイル、通知準備などの未処理例外。レスポンス構築/Resolved 同期がコミット後に失敗した場合も 500 となる可能性があります | 内部エラー | 先に詳細、コメント、操作記録を読み取って実際の状態を確認してください。すでに保存または通知されている可能性があるため、盲目的な再実行を避けてください。traceId を保持して調査してください。 |