コメントを追加¶
POST /api/v1/error_track/comment/{issue_id}/add
概要¶
エラーコメントを追加し、担当者および今回の @ 対象に通知します。
呼び出し前の準備と使用手順¶
現在の Key には errorCenter.errorTrackManage が必要です。パスには実際の issue_id を使用します。親のローカルメタデータが存在しない場合は先に初期化してコミットします。テレメトリが実際に存在するかどうかは検証しません。新しいコメントは先にコミットされ、その後で添付ファイルのバインド、サマリーの構築、通知が行われます。失敗しても保存済みである可能性があります。冪等キーがないため、500 やタイムアウトを理由に直接リプレイしないでください。成功時は true のみを返し、新しいコメントの UUID は返しません。コメント一覧から読み戻してください。
通知先は既存の担当者に、今回のリクエストの extend.members のうち type=@ かつ uuid が空でない対象を加えたものです。チームはメンバーに展開され、利用可能な通知方法で配信されます。一致するスケジュールがない場合は自動的にフォールバックします。通常のチャネルの例外は多くが捕捉されるため、200 でも配信を保証しません。通知の準備に失敗すると 500 になる可能性があり、その場合もコメントはすでに保存されています。
extend はオブジェクトを指定するか省略してください。attachmentUUIDs は配列を指定するか省略してください。明示的な null は公開宣言を通過しますが、コミット後に 500 になる可能性があります。members の子構造には完全な検証がないため、オブジェクト配列を自身で構築する必要があります。添付ファイルの [] はバインド解除ではなく、置換リストでもありません。添付ファイルを再利用するとバインドが変更されるため、先にすべての UUID を確認してください。失敗した場合はまずコメント/添付ファイルと実際の通知を読み戻し、コメントやリマインダーの重複を防いでください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| issue_id | string | Y | エラー集約のビジネス識別子です。そのまま渡してください。refData.uuid(isset_)やコメント UUID ではありません。パスは URL エンコードで処理されます。詳細インターフェースでテレメトリの存在を検証しないでください。 空文字列を許可: False 例: err_payment_timeout取得または入力方法: エラートラッキング一覧 から content.data[].issue_id を取得するか、現在のワークスペースのエラーセンターのテレメトリレコードの issue_id を使用します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報です。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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": "@"}]}取得または入力方法: 呼び出し元が本文を作成します。エラーセンターのエディタと取り決めた表示拡張を保存します。 |
パラメータ補足説明¶
リクエストパラメータ説明
| パラメータ名 | パラメータ型 | 必須 | パラメータ説明 |
|---|---|---|---|
| attachmentUUIDs | array | N | 対象の Issue への返信の添付ファイル一覧 uuid。事前に /api/v1/attachment/upload インターフェースでアップロードする必要があります。 |
| comment | string | Y | コメント内容 |
| extend | json | N | 拡張フィールド。デフォルトでは {} を渡します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/error_track/comment/err_payment_timeout/add' \
-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 | boolean | 成功時は true。コメント UUID/オブジェクトや declaration は含みません。 |
{
"code": 200,
"content": true,
"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 ファイルの形式エラー | コメントパラメータのオブジェクトを送信してください。 |
| 401 | ft.WKSPNotExistOrReleased | 担当者または今回の @ 対象が存在し、受信者の準備でワークスペースの再クエリに失敗しました | ワークスペースが存在しない、またはすでに解放されています | ワークスペースがまだ有効か確認してください。コメント/親メタデータはすでにコミットされている可能性があるため、先に読み戻し、コメントやリマインダーの重複を避けてください。 |
| 500 | ft.InternalServerError | データベース、履歴 JSON、添付ファイル、通知準備などの未処理例外。レスポンス構築/Resolved 同期がコミット後に失敗しても 500 になる可能性があります | 内部エラー | まず詳細、コメント、操作記録を読み取り、実際の状態を確認してください。保存済みまたは通知済みの可能性があるため、盲目的なリプレイを避けてください。traceId を保持して特定してください。 |