更新¶
POST /api/v1/error_track/{issue_id}/update
概要¶
エラーの担当者または対応ステータスを更新し、変更内容を記録します。
呼び出し前の確認と使用手順¶
現在の Key には errorCenter.errorTrackManage が必要です。パスには一覧の issue_id を使用する必要があります。返却されるのはローカル処理メタデータであり、元の error_stack などのテレメトリレコードは含まれません。
ローカルメタデータが見つからない場合は直近 30 日間の EH を照会し、Triage、担当者なしで初期化してから送信します。テレメトリに一致がない場合やこの照会が失敗した場合でもデフォルトオブジェクトが作成されることがあり、その場合 firstTime は現在のミリ秒、errorType は空になります。このエンドポイントで実際のエラーの存在を確認することはできず、初期化時刻を全履歴での初回発生時刻として扱うこともできません。
assigner が指定された場合はそちらが優先され、issueStatus を同時に送信しても無視されます。担当者一覧が旧値と完全に同じ場合も同様です。両方を変更する場合は 2 回に分けて呼び出し、読み戻して確認してください。assigner は全量置換で、[] はクリアを意味します。担当者がいない Triage に空でない担当者を割り当てると、自動的に Assigned に変わります。group_ は本ワークスペースのアクティブなチームを検証しますが、acnt_ はプレフィックスのみを検証するため、呼び出し側がアカウントの有効性を自身で確認する必要があります。成功してもアカウントが解決可能であることや通知を受信できることは保証されません。
ステータスの変更または担当者の変更により、システムコメントと操作履歴が生成されます。通知は最終送信前に送信準備が行われ、通常のチャネルでの例外は捕捉される可能性があるため、200 は配信を保証せず、失敗時にも通知が既に送信されている場合があります。Resolved への変更は送信後にダウンストリームへ同期され、後続の失敗があっても保存済みのステータスはロールバックされません。失敗した場合はまず詳細/操作履歴を確認し、むやみにステータス変更を繰り返さないでください。{} は担当者/ステータスを変更しませんが、初回初期化が実行される場合があります。
ルートパラメーター¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 リクエストパラメーター¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| assigner[*] | string | 単一の acnt_ または group_ 文字列。チームは本ワークスペースでアクティブである必要があり、ロール UUID/wsAdmin は使用できません。 例: group_example取得または入力方法: ワークスペースメンバーから content.data[].uuid を取得し、チーム一覧からアクティブな group_ UUID を取得します。事前に現在のワークスペースを確認してください。 |
|
| assigner | array | 任意のアカウント/チーム UUID 配列。省略時は保持、[] は全量クリア、null は拒否されます。重複は除去され先頭の順序が保たれます。issueStatus と同時に送信した場合はこのフィールドのみ処理されます。アカウントはプレフィックスチェックのみで、未知のアカウントをサーバー側で拒否することは前提としていません。 null を許可: False 例: ["acnt_example", "group_example"]取得または入力方法: ワークスペースメンバーから content.data[].uuid を取得し、チーム一覧からアクティブな group_ UUID を取得します。事前に現在のワークスペースを確認してください。 |
|
| issueStatus | string | 任意の Triage/Assigned/Working/Resolved/Ignored。省略時は保持されます。assigner キーが完全に存在しない場合にのみ有効で、状態遷移の順序は強制されません。 空文字列を許可: False null を許可: False 選択可能な値: ['Triage', 'Assigned', 'Working', 'Resolved', 'Ignored'] 例: Working取得または入力方法: エラーセンターの処理フローからステータスを選択します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/error_track/err_payment_timeout/update' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"issueStatus":"Working"}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | ローカルメタデータと計算/識別情報のサマリー。 |
| 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.issueID | string | テレメトリの issue_id 業務識別子。ローカルの uuid とは異なります。 |
| content.assigner | array<string> |
担当者のアカウント acnt_ またはチーム group_。現在の保存順序で、空配列は未割り当てです。 |
| content.assigner[] | string | 個々の担当者識別子。保存に成功しただけでアカウントが存在することや通知可能であることを判断することはできません。 |
| content.issueStatus | string | Triage/Assigned/Working/Resolved/Ignored。 |
| content.extend | object または null | ローカルメタデータの拡張。過去の異常値には寛容な処理が必要です。 |
| content.extend.errorType | string | 初期化時に照会されたエラータイプ。照会失敗/データなしの場合は空になることがあります。 |
| content.extend.firstTime | integer | 初期化時に直近 30 日間を照会した create_time(Unix ミリ秒)。照会失敗/データなしの場合は現在のミリ秒が返り、全履歴での初回発生であることは保証されません。 |
| content.extend.statusChangeRecords | array<object> |
ステータス変更記録。各項目は保存履歴の順序に従います。 |
| content.extend.statusChangeRecords[].status | string | 上記ステータスのいずれか。 |
| content.extend.statusChangeRecords[].time | integer | ステータスへの遷移時刻。Unix 秒。 |
| content.extend.statusChangeRecords[].operator | string | 操作主体の UUID/システム識別子。 |
| content.extend.その他のキー | JSON | 履歴として保存されたその他の拡張キー。固定の実行パラメーターではありません。 |
| content.duration | integer | 秒。過去の完全なサイクルの時間差の合計に、現在時刻から最後の Triage サイクル開始時刻を引いた値を加算したものです。Resolved/Ignored でも増加し続ける可能性があり、厳密な MTTR ではありません。計算異常時は欠落する場合があります。 |
| content.statusDuration | object | 直近の Triage サイクルにおける各ステータスへの遷移時刻のマッピングであり、各ステータスの継続秒数ではありません。計算異常時は省略される場合があります。 |
| content.statusDuration.ステータス | integer | Triage/Assigned/Working/Resolved/Ignored のうち実際に出現し、増加選択の条件を満たした Unix 秒時刻。 |
| content.creatorInfo | object | 作成主体のサマリー。一致なしの場合は {}。システム主体の場合はフィールドがアカウントより少なくなることがあります。 |
| content.updatorInfo | object | 更新主体のサマリー。一致なしの場合は {}。 |
| content.assignerInfo | array<object> |
解決可能な担当者のサマリー。無効なアカウントは含まれない場合があり、assigner と同じ長さであることは保証されません。 |
| content.assignerInfo[].uuid | string | アカウントまたはチームの UUID。 |
| content.assignerInfo[].name | string | 表示名。チームのサマリーは uuid/name のみです。 |
| content.creatorInfo.uuid | string | 主体の UUID。アカウント、Key、またはシステム識別子の場合があります。 |
| content.creatorInfo.status | integer | 主体のステータス。 |
| content.creatorInfo.wsAccountStatus | integer | 現在のワークスペースにおけるメンバーシップステータスのサマリー。 |
| content.creatorInfo.username | string | ログイン名または Key 名。 |
| content.creatorInfo.name | string | 表示名。 |
| content.creatorInfo.iconUrl | string | アバター URL。空になることがあります。 |
| content.creatorInfo.email | string | メールアドレス。Key 主体の場合は自身の UUID になることがあり、配信可能であることは保証されません。 |
| content.creatorInfo.mobile | string | 携帯電話番号。空になることがあります。 |
| content.creatorInfo.countryCode | string | 電話の国番号。空になることがあります。 |
| content.creatorInfo.acntWsNickname | string | 現在のワークスペースでのニックネーム。空になることがあります。 |
| content.updatorInfo.uuid | string | 主体の UUID。アカウント、Key、またはシステム識別子の場合があります。 |
| content.updatorInfo.status | integer | 主体のステータス。 |
| content.updatorInfo.wsAccountStatus | integer | 現在のワークスペースにおけるメンバーシップステータスのサマリー。 |
| content.updatorInfo.username | string | ログイン名または Key 名。 |
| content.updatorInfo.name | string | 表示名。 |
| content.updatorInfo.iconUrl | string | アバター URL。空になることがあります。 |
| content.updatorInfo.email | string | メールアドレス。Key 主体の場合は自身の UUID になることがあり、配信可能であることは保証されません。 |
| content.updatorInfo.mobile | string | 携帯電話番号。空になることがあります。 |
| content.updatorInfo.countryCode | string | 電話の国番号。空になることがあります。 |
| content.updatorInfo.acntWsNickname | string | 現在のワークスペースでのニックネーム。空になることがあります。 |
| content.assignerInfo[].status | integer | 主体のステータス。アカウントのサマリーのみで、チームにはこのキーが含まれません。 |
| content.assignerInfo[].wsAccountStatus | integer | 現在のワークスペースにおけるメンバーシップステータスのサマリー。アカウントのサマリーのみで、チームにはこのキーが含まれません。 |
| content.assignerInfo[].username | string | ログイン名または Key 名。アカウントのサマリーのみで、チームにはこのキーが含まれません。 |
| content.assignerInfo[].iconUrl | string | アバター URL。空になることがあります。アカウントのサマリーのみで、チームにはこのキーが含まれません。 |
| content.assignerInfo[].email | string | メールアドレス。Key 主体の場合は自身の UUID になることがあり、配信可能であることは保証されません。アカウントのサマリーのみで、チームにはこのキーが含まれません。 |
| content.assignerInfo[].mobile | string | 携帯電話番号。空になることがあります。アカウントのサマリーのみで、チームにはこのキーが含まれません。 |
| content.assignerInfo[].countryCode | string | 電話の国番号。空になることがあります。アカウントのサマリーのみで、チームにはこのキーが含まれません。 |
| content.assignerInfo[].acntWsNickname | string | 現在のワークスペースでのニックネーム。空になることがあります。アカウントのサマリーのみで、チームにはこのキーが含まれません。 |
| content.declaration | object または null | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": 7,
"uuid": "isset_example",
"status": 0,
"creator": "sys",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"issueID": "err_payment_timeout",
"assigner": [],
"issueStatus": "Working",
"extend": {
"errorType": "js_error",
"firstTime": 1785427200000,
"statusChangeRecords": [
{
"status": "Triage",
"time": 1785427200,
"operator": "wsak_example"
},
{
"status": "Working",
"time": 1785427260,
"operator": "wsak_example"
}
]
},
"duration": 60,
"statusDuration": {
"Triage": 1785427200,
"Working": 1785427260
},
"creatorInfo": {
"uuid": "",
"name": "SYS",
"username": "SYS",
"email": "SYS",
"status": 0,
"wsAccountStatus": 0,
"mobile": ""
},
"updatorInfo": {},
"assignerInfo": [],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
共通の認証/宣言検証に加えて、自動初期化時の EH 照会異常はデフォルトメタデータとして容錯処理されます。200 によってテレメトリの存在を判断することはできません。EH 照会のダウンストリーム業務 4xx は実際の HTTP/errorCode/message に従って返される場合があるため、traceId を保持し、照会エラーに応じて時間範囲を狭めるか conditions を修正してください。未識別/非透過の 5xx は通常 500 に統一されます。DQL 照会チェーンのみ、回復可能な 503 は ft.QueryServiceUnavailable(content.retryable=true)に正規化されます。ステータスが Resolved になった後の通常の同期呼び出しでは、同じ正規化は保証されません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメーターの解析失敗 | パラメーターの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトでない | 一部の json ファイルの形式エラー | オブジェクトを送信してください。 |
| 406 | ft.InvalidParameterV2 | assigner の子項目が文字列でない/ acnt_ または group_ で始まらない、または group_ が本ワークスペースのアクティブなチームでない | パラメーターassignerの値 group_missingが無効 |
本ワークスペースのメンバー/チーム一覧から再選択してください。初期化メタデータが既に送信されている可能性があるため、先に読み戻してください。 |
| 500 | ft.InternalServerError | データベース、履歴 JSON、添付ファイル、通知準備などの未処理例外。レスポンス構築/Resolved 同期が送信後に失敗した場合も 500 になることがある | 内部エラー | まず詳細、コメント、操作履歴を読み取って実際のステータスを確認してください。既に保存または通知されている可能性があるため、むやみな再実行は避けてください。traceId を保持して特定してください。 |
| 401 | ft.WKSPNotExistOrReleased | 担当者/ステータスの変更で通知が必要な際、受信者の準備でワークスペースの再照会に失敗した | ワークスペースが存在しない/または既に解放済み | まずワークスペースが有効かどうかを確認してください。自動初期化が既に送信されている可能性があるため、通知やステータスの結果を先に読み戻して確認し、その後管理者がワークスペースの状態を処理してください。 |