업데이트¶
POST /api/v1/error_track/{issue_id}/update
개요¶
오류 담당자 또는 처리 상태를 업데이트하고 변경 사항을 기록합니다.
호출 전 및 사용 단계¶
현재 Key에는 errorCenter.errorTrackManage 권한이 필요합니다. 경로에는 목록의 issue_id를 사용해야 하며, 반환값은 로컬 처리 메타데이터로 원본 error_stack 등 텔레메트리 레코드는 포함하지 않습니다.
로컬 메타데이터를 찾지 못하면 최근 30일 EH를 조회하고 Triage, 빈 담당자로 초기화한 후 제출합니다. 텔레메트리가 일치하지 않거나 해당 조회가 실패하더라도 기본 객체가 생성될 수 있으며, firstTime은 현재 밀리초로, errorType은 비어 있습니다. 이 진입점으로 실제 오류의 존재 여부를 탐지할 수 없으며, 초기화 시간을 전체 이력의 최초 시간으로 간주해서도 안 됩니다.
assigner가 있으면 우선하며, issueStatus를 함께 전달해도 무시됩니다. 담당자 목록이 기존 값과 완전히 동일한 경우도 마찬가지입니다. 두 항목을 모두 변경하려면 두 번으로 나누어 호출하고 조회하여 확인해야 합니다. assigner는 전체 교체이며, []는 비웁니다. 담당자가 없는 Triage에 비어 있지 않은 담당자를 할당하면 자동으로 Assigned로 변경됩니다. group_은 현재 워크스페이스의 활성 팀을 검증하지만, acnt_는 접두사만 검증하므로 호출자가 해당 계정이 실제로 현재 워크스페이스의 유효한 멤버인지 직접 확인해야 합니다. 성공 응답이 계정 조회 가능 여부나 알림 수신을 보장하지는 않습니다.
상태 변경 또는 담당자 변경 시 시스템 코멘트와 작업 기록이 생성됩니다. 알림은 최종 제출 전에 전송 준비되며 일반 채널 예외는 포착될 수 있으므로 200 응답이 전달을 보장하지 않고, 실패한 경우에도 이미 알림이 발송되었을 수 있습니다. Resolved 전환은 제출 후 다운스트림과 동기화되며, 후속 실패가 이미 저장된 상태를 롤백하지 않습니다. 실패 시 먼저 상세/작업 기록을 조회하고, 상태 전환을 무작정 반복하지 마십시오. {}는 담당자/상태를 변경하지 않지만 최초 초기화를 여전히 트리거할 수 있습니다.
경로 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| issue_id | string | Y | 오류 집계 비즈니스 식별자로, 원본 그대로 전달합니다. refData.uuid(isset_) 또는 코멘트 UUID가 아닙니다. 경로는 URL 인코딩으로 처리됩니다. 상세 API로 텔레메트리 존재 여부를 검증하지 마십시오. 빈 문자열 허용: 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 | 로컬 메타데이터와 계산/ID 요약입니다. |
| 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 | 담당자/상태 변경에 알림이 필요할 때 수신자 준비가 워크스페이스 재조회에 실패함 | 워크스페이스가 존재하지 않음/또는 이미 해제됨 | 먼저 워크스페이스가 여전히 유효한지 확인하십시오. 자동 초기화가 이미 제출되었을 수 있으므로 알림 또는 상태 결과를 다시 조회하여 확인한 뒤 관리자가 워크스페이스 상태를 처리하도록 하십시오. |