생성¶
POST /api/v1/incidents/schedule/add
개요¶
인시던트 온콜 및 알림 에스컬레이션 설정을 생성합니다.
호출 전 및 사용 단계¶
현재 Key에는 incidents.incidentsSchedule 권한이 필요하며 현재 워크스페이스만 대상으로 합니다. name/start/end/notifyTargets는 필수이며, 알림 대상은 비워 둘 수 있지만 이를 근거로 담당자가 자동 보충되지는 않습니다. tagFilter 입력은 태그 이름이며 응답에서는 UUID로 변환됩니다. dimensionFilter는 쿼리 문자열을 사용하며, 태그 또는 차원 중 하나만 일치해도 됩니다. 둘 다 비어 있으면 모든 인시던트가 대상입니다.
생성에는 멱등 키가 없으며 같은 이름은 거부됩니다. 타임아웃/500 발생 시 먼저 이름 목록으로 조회하고 중복 생성하지 마세요.
일 내 start/end는 온콜 일정 timezone에 따라 해석되며 날짜를 넘지 않습니다. effectiveTime.start/end는 Unix 초 단위 날짜 경계입니다. 로테이션은 notifyTargets 순서와 캘린더 주기에 따르며 고정된 초 길이가 아닙니다. 현재 생성 시 rotationUpdateAt은 기본값 -1이며 계산 체인은 이를 유효한 0이 아닌 앵커로 간주합니다. 따라서 로테이션을 바로 켜도 생성 당일 첫 번째 대상부터 시작한다고 보장할 수 없습니다. 공개적으로 rotationUpdateAt을 전달해 수정할 수 없으므로, 생성 후 상세/캘린더에서 실제 교대조를 확인하세요. 이후 유효한 의미 변경이 있을 때만 코드에 따라 앵커가 재설정됩니다. customDay/customWeek/rotationInterval/workTime은 현재 과거 응답에만 나타날 수 있으며, 공개 요청에서는 사전에 406이 발생합니다.
scheduleStrategy는 하위 객체를 완전하게 검증하지 않으므로 연속된 level=배열 인덱스, 실제 등급/대상, 양의 반복 간격을 사용해야 합니다. 생성 알림은 0 계층 notifyConfig에서 대상을 가져오며, [] 정책은 생성 시 모든 notifyTargets로 알림을 보내는 동작으로 자동 폴백하지 않습니다. watchkeeper는 notifyObject에 명시적으로 넣어야 합니다. 인시던트 operate=update는 온콜 일정 유효 시간 및 필터가 일치한 후 설정된 notifyTargets의 모든 대상을 사용하며, watchkeeper 로테이션/대체 근무에 따라 현재 교대조로 축소하지 않습니다. 담당자가 있으면 먼저 담당자에게 알리고, 그다음 온콜 일정 대상에 대해 중복을 제외합니다. 담당자에게만 알리는 것이 아닙니다. 음소거, 채널 가용성 등은 여전히 실제 전송에 영향을 주며, 저장 성공이 전송을 보장하지 않습니다.
온콜 일정/새 태그가 먼저 제출된 후 인시던트 매칭 큐가 비동기로 업데이트됩니다. 전송 실패 시 500이 발생할 수 있지만 본문은 이미 저장되었을 수 있습니다. 수정 시 필터만 변경된 경우 해당 큐를 업데이트하며, HTTP 200을 모든 캐시가 즉시 갱신되었다는 의미로 해석해서는 안 됩니다. 실패 시 먼저 설정과 캘린더를 다시 읽어 중복 생성/중복 전환을 피하세요. 변경 전에 전체 공개 설정을 백업하고, 롤백은 다시 제출해야 하며 이미 발송된 알림이 자동으로 취소된다고 보장하지 않습니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| tagFilter[*] | any | 단일 비어 있지 않은 태그 이름입니다. 기존 태그 참조로 tag_ UUID를 전달하면 새 이름으로 처리되므로 전달하면 안 됩니다. 하위 항목은 강제 검증되지 않으므로 클라이언트는 문자열을 사용해야 합니다. 예: production획득 또는 입력 방법: 태그 목록의 name 또는 새 이름. |
|
| notifyTargets[*] | string | 단일 acnt_/group_/notify_ 문자열 또는 이메일입니다. 역할 ID/Key UUID는 사용할 수 없으며, 문자열이 아니면 명확한 파라미터 오류 대신 500이 발생할 수 있습니다. 예: acnt_example획득 또는 입력 방법: 워크스페이스 멤버에서 acnt_를, 팀 목록에서 group_를, 알림 대상 목록에서 notify_를 가져오거나 허용된 유효 이메일을 입력합니다. |
|
| extend.effectiveTime.start | integer | 선택적 정수 Unix 초입니다. 생략하거나 0이면 시작 경계를 설정하지 않습니다. 일일 start의 일 내 시각과 다릅니다. 예: 1785369600획득 또는 입력 방법: 온콜 일정 timezone 기준으로 대상 날짜 시작점의 Unix 초를 계산합니다. |
|
| extend.effectiveTime.end | integer | 선택적 정수 Unix 초입니다. 생략하거나 0이면 종료 경계를 설정하지 않습니다. 일일 end와 다릅니다. 예: 1785455999획득 또는 입력 방법: 온콜 일정 timezone 기준으로 종료 시각의 Unix 초를 계산합니다. |
|
| extend.effectiveTime.기타 키 | any | 유효 기간 객체에는 키별 화이트리스트가 없으며, 다른 값은 저장될 수 있지만 추가 실행 계약을 제공하지 않습니다. 예: value획득 또는 입력 방법: 일반적으로 이러한 키는 필요하지 않으며 start/end만 사용합니다. |
|
| scheduleStrategy[*] | json | 단일 정책 객체입니다. 정책 uuid는 알림 중복 제거 캐시에 사용되며 온콜 일정 UUID가 아닙니다. 예: {"uuid": "strategy_payment", "name": "支付通知", "strategy": []}획득 또는 입력 방법: 호출자가 정책별로 안정적이고 고유한 정책 식별자와 이름을 할당하여 정책 간 uuid 재사용을 피합니다. |
|
| scheduleStrategy[*].uuid | string | 인시던트/정책 기준 중복 제거 캐시에 사용됩니다. 비워 두거나 여러 정책에서 같은 값을 재사용하지 마세요. 예: strategy_payment획득 또는 입력 방법: 호출자가 워크스페이스 내에서 충돌하지 않고 안정적인 정책 UUID 문자열을 생성합니다. |
|
| scheduleStrategy[*].name | string | 정책 이름으로, 알림 에스컬레이션 기록 표시에 사용됩니다. 예: 支付通知획득 또는 입력 방법: 호출자가 정책 표시 이름을 입력합니다. |
|
| scheduleStrategy[*].strategy | array | 계층 객체 배열입니다. level은 0부터 연속으로 배열 인덱스와 일치해야 합니다. 실행 체인이 level을 직접 인덱스로 사용할 수 있으므로 건너뛰기/음수를 허용하지 않습니다. 예: []획득 또는 입력 방법: 호출자가 알림 에스컬레이션 순서에 따라 구성합니다. |
|
| scheduleStrategy[*].strategy[*] | json | 단일 계층 알림 설정입니다. 현재 저장 시 리프 유형을 강하게 검증하지 않습니다. 예: {"level": 0, "notifyConfig": [{"notifyObject": ["watchkeeper"]}], "ifRepeatNotify": false}획득 또는 입력 방법: 인시던트 생성/에스컬레이션 요구 사항에 맞게 구성합니다. |
|
| scheduleStrategy[*].strategy[*].level | integer | 0은 생성 알림, 이후 양의 정수는 에스컬레이션 계층입니다. 번호를 건너뛰거나 배열 인덱스와 맞지 않게 재정렬하면 안 됩니다. 예: 0획득 또는 입력 방법: 0부터 배열 순서대로 연속 번호를 지정합니다. |
|
| scheduleStrategy[*].strategy[*].levelUpTime | integer | 양의 계층에서 인시던트 상태 변경 시간 기준 대기 초입니다. 생략하거나 0이면 기본 0 계층 선택으로 처리되며 무한 대기로 간주할 수 없습니다. 예: 600획득 또는 입력 방법: 인시던트가 미처리 상태로 얼마나 지속되면 에스컬레이션할지에 따라 초를 선택합니다. |
|
| scheduleStrategy[*].strategy[*].incidentsLevel | array | 에스컬레이션이 적용되는 등급 UUID 배열이며, 양의 levelUpTime 분기에서 일치해야 합니다. P1 표시 이름이 아닙니다. 예: ["system_level_1"]획득 또는 입력 방법: 인시던트 등급 목록에서 uuid를 가져와 현재 유효한 설정인지 확인합니다. |
|
| scheduleStrategy[*].strategy[*].incidentsLevel[*] | string | 단일 등급 UUID입니다. 예: system_level_1획득 또는 입력 방법: 인시던트 등급 목록의 uuid. |
|
| scheduleStrategy[*].strategy[*].incidentsStatus | array | 에스컬레이션 적용 상태 배열이며, 일반적으로 open/working을 사용합니다. 양의 levelUpTime 분기에서는 상태가 일치해야 합니다. 예: ["open", "working"]획득 또는 입력 방법: 인시던트 목록의 incidentsStatus 비즈니스 상태를 사용합니다. |
|
| scheduleStrategy[*].strategy[*].incidentsStatus[*] | string | 상태 문자열 하나입니다. 예: open획득 또는 입력 방법: 인시던트 비즈니스 상태이며 데이터베이스의 0/2/3이 아닙니다. |
|
| scheduleStrategy[*].strategy[*].ifRepeatNotify | boolean | 생략 시 false입니다. true이면 유효한 양의 repeatNotifyInterval을 제공해야 하며, 기본 계층 계산에서 간격에 대해 나머지 연산을 수행할 수 있으므로 0이면 작업에서 실패합니다. 예: false획득 또는 입력 방법: 같은 계층에서 반복 알림을 보낼지 결정합니다. |
|
| scheduleStrategy[*].strategy[*].repeatNotifyInterval | integer | 반복 간격(초)이며 60초 이상이면서 정수 분 단위인 값을 권장합니다. 반복이 켜진 경우에만 의미가 있고 0/음수는 전달할 수 없습니다. 예: 600획득 또는 입력 방법: 알림 빈도에 따라 양의 정수 초를 선택하며 60초의 양의 정수 배수를 권장합니다. |
|
| scheduleStrategy[*].strategy[*].notifyConfig | array | 알림 설정 객체 배열입니다. watchkeeper는 런타임에 현재 유효한 온콜 담당자(대체 근무 포함)로 치환되며 고정 계정이 아닙니다. 예: [{"notifyObject": ["watchkeeper"]}]획득 또는 입력 방법: 수신 대상과 알림 방식에 따라 구성합니다. |
|
| scheduleStrategy[*].strategy[*].notifyConfig[*] | json | 알림 대상과 선택적 알림 방식의 집합입니다. 예: {"notifyObject": ["watchkeeper"]}획득 또는 입력 방법: 실제 알림 대상에 맞게 구성합니다. |
|
| scheduleStrategy[*].strategy[*].notifyConfig[*].notifyObjectType | string | 선택적 표시 분류입니다. 실행 체인은 주로 notifyObject와 notifyMethod를 기준으로 하며 이 필드로 대상을 검증하지 않습니다. 예: member획득 또는 입력 방법: 편집기의 표시 분류 member/object/group을 그대로 사용할 수 있습니다. |
|
| scheduleStrategy[*].strategy[*].notifyConfig[*].notifyObject | array | 대상 식별자 배열입니다. 빈 []는 모든 온콜 담당자를 자동으로 사용하지 않으며 watchkeeper를 명시해야 합니다. 예: ["watchkeeper"]획득 또는 입력 방법: 워크스페이스 멤버에서 acnt_를, 팀 목록에서 group_를, 알림 대상 목록에서 notify_를 가져오거나 허용된 유효 이메일을 입력합니다. 현재 교대조는 리터럴 값 watchkeeper를 사용합니다. |
|
| scheduleStrategy[*].strategy[*].notifyConfig[*].notifyObject[*] | string | 단일 대상 또는 watchkeeper 자리 표시자입니다. 예: watchkeeper획득 또는 입력 방법: 워크스페이스 멤버에서 acnt_를, 팀 목록에서 group_를, 알림 대상 목록에서 notify_를 가져오거나 허용된 유효 이메일을 입력합니다. |
|
| scheduleStrategy[*].strategy[*].notifyConfig[*].notifyMethod | array | 생략하거나 []이면 공용 대상 전송을 사용하며 notify_ 객체는 해당 설정에 따릅니다. 명시적 배열은 방식을 선택하지만, 대상에 관련 연락처가 설정되어 있거나 사이트에 유료 채널이 개통되어 있음을 보장하지 않습니다. 예: ["email"]획득 또는 입력 방법: 대상이 사용할 수 있는 알림 채널에 따라 email 이메일/mobile 전화/message 문자 메시지를 선택합니다. |
|
| scheduleStrategy[*].strategy[*].notifyConfig[*].notifyMethod[*] | string | 단일 방식입니다(예: email/mobile/message). 배포 환경에서 실제 사용 가능한 기능을 기준으로 검증합니다. 예: email획득 또는 입력 방법: 개통된 알림 방식을 사용합니다. |
|
| dimensionFilter | string | 선택적 쿼리 문자열이며 JSON/SQL/DQL이 아닙니다. 프로젝트 쿼리 구문을 지원하고, 구문 분석이 유효하지 않으면 400입니다. 생성 시 생략하면 비어 있고, 수정 시 생략해도 비워집니다. 태그와 차원 필터는 실행 체인에서 매칭되며, 태그 중 하나가 일치하거나 차원 표현식이 일치하면 됩니다. 둘 다 비어 있으면 모두 일치하므로 반드시 동시에 충족해야 한다고 오해하지 마세요. 허용 null: False 예: service:payment획득 또는 입력 방법: 인시던트 dimensionTag의 실제 차원 필드와 값으로 쿼리 문자열을 구성합니다. |
|
| end | string | Y | 필수 HH:MM이며 start보다 늦어야 하고 최대 23:59입니다. 실제 근무 시간에는 종료 분의 59초까지 포함됩니다. 허용 null: False 최대 길이: 48 예: 18:00획득 또는 입력 방법: 온콜 일정 timezone에 따라 일일 종료 시각을 선택합니다. |
| extend | json | 선택적 JSON 객체이며 생략 시 {}입니다. 수정 시 기존 공개 확장을 전체 교체합니다. 현재 enableRotateNotification, rotationCycle, effectiveTime 세 가지 선언 키만 허용되며, workTime/rotationInterval/agentUUIDs 등 읽힌 키는 다시 전달할 수 없고 먼저 406이 발생합니다. 수정 시 기존 Agent 연결은 유지되지만 기존 workTime 등 비공개 확장은 제거되므로 백업하고 평가한 후 작업하세요. 허용 null: False 예: {"enableRotateNotification": false}획득 또는 입력 방법: 교대 방식과 유효 날짜에 따라 구성합니다. |
|
| extend.effectiveTime | json | 선택적 객체이며 생략하거나 {}이면 유효 날짜 제한이 없습니다. 밀리초가 아니며 이전 설명의 11자리 요구 사항도 아닙니다. start/end는 각각 생략할 수 있고 0이 아니어야 적용됩니다. 둘 다 0이 아니고 end<start이면 400입니다. 내부 하위 필드는 유형 검증이 선언되어 있지 않으므로 반드시 정수 초를 사용하고 문자열/null 또는 임의 구조를 사용하지 마세요. 허용 null: False 예: {"start": 1785369600, "end": 1785455999}획득 또는 입력 방법: 온콜 일정 유효 날짜 경계를 Unix 초로 변환하며 시간대 도구로 계산할 수 있습니다. |
|
| extend.enableRotateNotification | boolean | 선택적 불리언이며 생략 시 false입니다. true이면 rotationCycle을 명시해야 하며 그렇지 않으면 400 MissingCustomParameters입니다. 허용 null: False 예: false획득 또는 입력 방법: 모든 대상이 동시에 온콜이면 false, notifyTargets 순서대로 교대하면 true를 사용합니다. |
|
| extend.rotationCycle | string | 선택적 열거형 day/week/month/workDay/weekend이며 로테이션을 켜면 필수입니다. 온콜 일정 timezone의 캘린더 주기를 따르며 고정 초 수가 아닙니다. week는 월요일에 전환, month는 자연월 기준 전환, workDay/weekend는 요일만 기준으로 하며 법정 공휴일은 인식하지 않습니다. 현재 공개 선언에서는 customDay/customWeek를 허용하지 않으며 과거 응답에 있더라도 다시 전달할 수 없습니다. 이전 호환 근무 시간은 workDay가 월요일~금요일만, weekend가 토요일~일요일만이며, 로테이션을 켜지 않아도 근무일에 영향을 줍니다. 허용 null: False 선택 값: ['day', 'week', 'month', 'workDay', 'weekend'] 예: day획득 또는 입력 방법: 교대에 따라 day 일/week 주/month 월/workDay 근무일/weekend 주말을 선택합니다. |
|
| name | string | Y | 필수 비어 있지 않은 문자열입니다. 선언상 최대 256자이지만 엔터티 컬럼은 128자이므로 1~128자로 제한하는 것이 좋습니다. 같은 워크스페이스에서 삭제되지 않은 온콜 일정과 이름이 중복될 수 없습니다. 수정 시에도 필수입니다. 빈 문자열 허용: False 허용 null: False 최대 길이: 256 예: 支付服务值班획득 또는 입력 방법: 온콜 유지 관리자가 워크스페이스 내에서 고유한 이름을 입력합니다. |
| notifyTargets | array | Y | 필수 배열이며 []도 허용되지만 알림 대상이 없을 수 있습니다. 원래 순서대로 저장되며 로테이션을 켜면 순서가 교대에 영향을 줍니다. acnt_/notify_/group_은 접두사만으로 이메일 검증을 건너뛰며 대상 존재/유효/전송 가능 여부를 보장하지 않으므로 반드시 원본 목록에서 확인해야 합니다. 일반 이메일은 형식을 검사하며 체험/무료 워크스페이스에서는 워크스페이스 멤버가 아닌 이메일을 허용하지 않습니다. 수정 시 전체 교체됩니다. 허용 null: False 예: ["acnt_example"]획득 또는 입력 방법: 워크스페이스 멤버에서 acnt_를, 팀 목록에서 group_를, 알림 대상 목록에서 notify_를 가져오거나 허용된 유효 이메일을 입력합니다. |
| scheduleStrategy | array | 선택적 정책 객체 배열입니다. 생성 시 생략하면 []이고, 수정 시 생략하거나 []이면 기존 정책을 비웁니다. 현재 저장 측에는 완전한 하위 항목 검증이 없으므로 성공이 알림 설정의 실행 가능성을 보장하지 않습니다. 배열과 내부 계층 구조가 올바르게 구성되어야 하며, 먼저 최소 설정으로 검증하는 것이 좋습니다. 예: []획득 또는 입력 방법: 현재 워크스페이스의 온콜 정책 편집기에서 구성하고 JSON 구조를 확인하거나 아래 필드에 따라 구성할 수 있습니다. |
|
| start | string | Y | 필수 HH:MM 일 내 시각이며 날짜나 Unix 시간이 아닙니다. end보다 빨라야 하고 자정을 넘지 않습니다. 24:00을 전달하지 말고, 날짜를 넘는 요구 사항은 일정을 분할하거나 제품이 지원하는 다른 관리 방식을 사용하세요. 허용 null: False 최대 길이: 48 예: 09:00획득 또는 입력 방법: 온콜 일정 timezone에 따라 일일 시작 시각을 선택합니다. |
| tagFilter | array | 선택적 태그 이름 배열입니다. 생성 시 생략하면 태그가 없고, 수정 시 생략하거나 []이면 비웁니다. 컨트롤러가 태그 UUID로 변환해 응답 tagFilter에 저장합니다. 새 태그는 all 스코프로 생성되고 기존 이름은 그대로 재사용됩니다. 현재 체인은 monitor 스코프 검증을 전달하지 않으므로 인시던트 쓰기 태그의 충돌 규칙을 적용하지 마세요. 단일 이름 컨트롤러는 최대 128자이지만 엔터티 컬럼은 64자이므로 1~64자를 권장합니다. 허용 null: False 예: ["production"]획득 또는 입력 방법: 태그 목록에서 name(uuid 아님)을 가져오거나 새 태그 이름을 입력합니다. |
|
| timezone | string | 선택적 문자열이며 최대 48자입니다. 생략 시 Asia/Shanghai입니다. 수정 시 생략하면 이 기본값으로 재설정되며 기존 값이 유지되지 않습니다. 잘못된 timezone은 포맷팅/읽기 시 500이 발생할 수 있으므로 저장 전에 검증해야 합니다. 허용 null: False 최대 길이: 48 예: Asia/Shanghai획득 또는 입력 방법: IANA timezone 데이터베이스 식별자(예: Asia/Shanghai 또는 UTC)를 사용합니다. |
파라미터 추가 설명¶
요청은 이 페이지의 공개 파라미터를 기준으로 합니다. 일 내 start/end는 HH:MM이고, 유효 기간과 대체 근무 시간은 Unix 초입니다. 전체 필드, 값 출처, 응답 분기 및 실패 처리는 아래를 참조하세요.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/incidents/schedule/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"支付服务值班","timezone":"Asia/Shanghai","start":"09:00","end":"18:00","notifyTargets":["acnt_example"],"dimensionFilter":"service:payment","extend":{"enableRotateNotification":false},"scheduleStrategy":[]}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object | 제출 전에 조립된 온콜 일정 엔터티 스냅샷입니다. 목록/상세의 동적 온콜 요약은 포함하지 않습니다. |
| content.id | integer 또는 null | 데이터베이스 행 ID입니다. 비즈니스 식별에는 uuid를 사용하며, 제출 전 스냅샷에서는 null일 수 있습니다. |
| content.uuid | string | 온콜 일정 UUID이며 incsch_ 접두사를 사용합니다. |
| content.status | integer | 데이터베이스 상태이며 일반적으로 0은 활성, 3은 삭제입니다. 인시던트의 open/working이 아닙니다. |
| content.creator | string | 생성 주체입니다. API Key는 일반적으로 wsak_ 리소스 UUID입니다. |
| content.updator | string | 최근 수정 주체이며 수정되지 않았으면 비어 있을 수 있습니다. |
| content.createAt | integer | Unix 초 생성 시간입니다. |
| content.updateAt | integer | Unix 초 최근 수정 시간입니다. |
| content.deleteAt | integer | Unix 초 삭제 시간이며 삭제되지 않았으면 -1입니다. |
| content.workspaceUUID | string | 소속 워크스페이스입니다. |
| content.name | string | 온콜 이름입니다. |
| content.timezone | string | IANA timezone입니다. |
| content.start | string | 호환용 일일 근무 시작 시각 HH:MM이며 일정 timezone에 따라 해석되고 날짜나 Unix 시간이 아닙니다. |
| content.end | string | 호환용 일일 근무 종료 시각 HH:MM이며 유효 날짜 경계는 extend.effectiveTime을 참조하세요. |
| content.tagFilter | array<string> |
매칭된 태그 UUID 배열입니다. |
| content.tagFilter[] | string | 태그 UUID입니다. |
| content.dimensionFilter | string | 차원 매칭 쿼리 표현식입니다. |
| content.notifyTargets | array<string> |
알림 대상 식별자 목록입니다. |
| content.notifyTargets[] | string | 계정/그룹/알림 대상 등의 대상 식별자입니다. |
| content.strategyConfig | array<object> |
에스컬레이션 정책 설정이며 워크스페이스에 저장된 버전에 따라 읽습니다. |
| content.strategyConfig[] | object | 설정 정책 하나입니다. 인시던트 읽기 인터페이스에서는 실행 미리보기를 펼치지 않습니다. |
| content.strategyConfig[].사용자 정의 필드 | JSON | 기타 저장된 정책 키이며 공개된 고정 실행 의미는 없습니다. |
| content.extend | object | 온콜 일정 확장 객체입니다. 공개 요청은 enableRotateNotification/rotationCycle/effectiveTime 세 가지 선언 키만 허용하며, 과거 읽기에는 더 많을 수 있습니다. |
| content.extend.사용자 정의 필드 | JSON | 저장된 온콜 확장 키-값이며 이 인터페이스로 수정할 수 없습니다. |
| content.isDefault | boolean | 기본 온콜 여부입니다. |
| content.rotationUpdateAt | integer | 로테이션 앵커 Unix 초입니다. 생성 시 기본값은 -1이며 현재 계산에서는 생성 시간으로 자동 폴백하지 않습니다. 첫 로테이션이 첫 번째 대상부터 시작한다고 보장하지 않으며, 의미 변경 후 재설정될 수 있습니다. |
| content.agentUUIDs | array<string> |
확장에 포함된 연결 Agent UUID 배열입니다. |
| content.agentUUIDs[] | string | Agent UUID 하나입니다. |
| content.strategyConfig[].uuid | string | 정책 UUID입니다. |
| content.strategyConfig[].name | string | 정책 이름입니다. |
| content.strategyConfig[].strategy | array<object> |
해당 정책의 에스컬레이션 계층 설정 배열입니다. |
| content.strategyConfig[].strategy[].level | integer | 계층 번호이며 일반적으로 0부터 시작합니다. |
| content.strategyConfig[].strategy[].levelUpTime | integer | 인시던트 상태 트리거 시간부터의 에스컬레이션 대기 초입니다. |
| content.strategyConfig[].strategy[].incidentsLevel | array<string> |
적용 인시던트 등급 UUID 목록입니다. |
| content.strategyConfig[].strategy[].incidentsLevel[] | string | 등급 UUID 하나입니다. |
| content.strategyConfig[].strategy[].incidentsStatus | array<string> |
적용 인시던트 상태 목록입니다(예: open/working). |
| content.strategyConfig[].strategy[].incidentsStatus[] | string | 인시던트 상태 하나입니다. |
| content.strategyConfig[].strategy[].ifRepeatNotify | boolean | 반복 알림 여부입니다. |
| content.strategyConfig[].strategy[].repeatNotifyInterval | integer | 반복 알림 간격(초)입니다. |
| content.strategyConfig[].strategy[].notifyConfig | array<object> |
해당 계층의 알림 설정 배열입니다. |
| content.strategyConfig[].strategy[].notifyConfig[].notifyObjectType | string | 알림 대상 분류입니다(예: member/object/group). 저장된 버전에 따라 읽습니다. |
| content.strategyConfig[].strategy[].notifyConfig[].notifyObject | array<string> |
알림 대상 식별자입니다. watchkeeper는 런타임의 현재 온콜 담당자를 의미하며 고정 계정 UUID가 아닙니다. |
| content.strategyConfig[].strategy[].notifyConfig[].notifyObject[] | string | 대상 계정/그룹/알림 대상 식별자 또는 watchkeeper 하나입니다. |
| content.strategyConfig[].strategy[].notifyConfig[].notifyMethod | array<string> |
알림 방식입니다. 일반적으로 mobile 전화/message 문자/email 이메일이며, 객체 채널은 객체 설정에 따라 실행됩니다. |
| content.strategyConfig[].strategy[].notifyConfig[].notifyMethod[] | string | 알림 방식 하나입니다. |
| content.extend.enableRotateNotification | boolean | 알림 대상 순환 여부입니다. |
| content.extend.rotationCycle | string | day/week/month/workDay/weekend/customDay/customWeek 중 하나이며 과거에는 생략될 수 있습니다. |
| content.extend.rotationInterval | integer | customDay 로테이션 간격 일수 1~31, customWeek 주수 1~4입니다. |
| content.extend.effectiveTime | object | 일정 유효 기간 설정입니다. |
| content.extend.effectiveTime.start | integer | 저장된 유효 시작 Unix 초이며, 없으면 시작 제한을 설정하지 않습니다. |
| content.extend.effectiveTime.end | integer | 저장된 유효 종료 Unix 초이며, 없으면 종료 제한을 설정하지 않습니다. |
| content.extend.workTime | object | 근무 시간 설정이며, 없으면 호환 start/end와 로테이션 주기에서 유추됩니다. |
| content.extend.workTime.mode | string | allDay 종일 또는 specificTimes 지정 시간입니다. |
| content.extend.workTime.periods | array<object> |
지정 근무 시간대 배열입니다. |
| content.extend.workTime.periods[].weekdays | array<integer> |
적용 요일이며 1은 월요일, 7은 일요일입니다. |
| content.extend.workTime.periods[].weekdays[] | integer | 1~7 중 하나입니다. |
| content.extend.workTime.periods[].start | string | 현지 일자 시작 HH:MM입니다. |
| content.extend.workTime.periods[].end | string | 현지 일자 종료 HH:MM입니다. |
| content.extend.agentUUIDs | array<string> |
연결 Agent UUID이며 엔터티에는 별도로 최상위 agentUUIDs 프로젝션이 있습니다. |
| content.extend.agentUUIDs[] | string | Agent UUID 하나입니다. |
| content.strategyConfig[].strategy[].notifyConfig[].notifyType | JSON | 이전 편집기에서 유지될 수 있는 표시 분류입니다. 실행 체인은 주로 notifyObject/notifyMethod를 읽으며 이 필드로 전송을 제어할 수 없습니다. |
| content.extend.effectiveTime.기타 키 | JSON | 선언되지 않은 유효 기간 확장은 그대로 저장되며 클라이언트는 start/end만 사용합니다. |
| content.effectiveTimeInfos | object | 생성/관리 목록에 추가되는 유효 기간 표시입니다. get/modify에서는 이 필드가 보장되지 않습니다. |
| content.effectiveTimeInfos.timeStr | string | 온콜 일정 timezone에 따라 포맷된 start~end이며 비어 있을 수 있습니다. |
| content.effectiveTimeInfos.expired | boolean | 유효 기간 end가 있고 현재 시간이 end보다 클 때만 true입니다. false라고 해서 현재 근무 중이라는 의미는 아닙니다. |
| content.declaration | object 또는 null | 현재 워크스페이스의 공용 선언입니다. |
{
"code": 200,
"content": {
"id": null,
"uuid": "incsch_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"name": "支付服务值班",
"timezone": "Asia/Shanghai",
"start": "09:00",
"end": "18:00",
"tagFilter": [],
"dimensionFilter": "service:payment",
"notifyTargets": [
"acnt_example"
],
"strategyConfig": [],
"extend": {
"enableRotateNotification": false,
"agentUUIDs": []
},
"isDefault": false,
"rotationUpdateAt": -1,
"agentUUIDs": [],
"effectiveTimeInfos": {
"timeStr": "",
"expired": false
},
"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 파일 형식 오류 | 전체 온콜 일정 파라미터 객체를 제출합니다. |
| 400 | ft.InvalidStartEndTimeFromat | 일 내 시간 형식/범위가 유효하지 않거나 start>=end | 유효하지 않은 시간대 형식 | 같은 날짜의 유효한 HH:MM을 사용하고 start를 end보다 빠르게 지정합니다. |
| 400 | ft.InvalidEffectiveTime | 0이 아닌 유효 기간 end가 start보다 빠름 | 유효하지 않은 적용 시간 | Unix 초와 timezone을 확인하고 밀리초를 혼용하지 마세요. |
| 400 | ft.MissingCustomParameters | extend.enableRotateNotification=true이나 rotationCycle 누락 | rotationCycle 필드 누락 | 공개 지원 주기를 제공합니다. |
| 406 | ft.InvalidEmail | notifyTargets가 계정/팀/알림 대상 접두사가 아니고 이메일 형식 오류 | 유효하지 않은 이메일 주소 | 원본 목록에서 식별자를 선택하거나 유효한 이메일을 사용합니다. |
| 400 | ft.UnsupportExternalEmail | 체험/무료 워크스페이스에서 해당 워크스페이스 멤버가 아닌 이메일 사용 | 체험 버전 워크스페이스, 외부 이메일을 알림 대상으로 지원하지 않음 | 워크스페이스 멤버 이메일을 선택하거나 관리자가 제품 버전 제한을 확인합니다. |
| 400 | ft.scheduleSameNameExists | 같은 워크스페이스에서 삭제되지 않은 온콜 일정 이름 중복 | 동일 이름 일정이 이미 존재 | 고유 이름을 사용하고, 네트워크 실패 시 먼저 목록을 조회해 중복 생성을 피합니다. |
| 400 | ft.ParamsValidateError | dimensionFilter 구문 분석 실패 | 파라미터 검증 실패: Field dimensionFilter is fault |
service:payment와 같은 유효한 차원 쿼리 문자열로 변경합니다. |
| 406 | ft.ExceedMaxCharacterLimit | tagFilter 태그 이름이 컨트롤러 128자 제한 초과 | {} 최대 문자 길이 제한 초과 | 짧은 비어 있지 않은 태그 이름을 사용하고 엔터티 컬럼 호환을 위해 <=64를 권장합니다. |
| 500 | ft.InternalServerError | 데이터베이스/태그 잠금 캐시, 알림 하위 구조, 잘못된 timezone 또는 제출 후 큐 전송 등 처리되지 않은 예외 | 내부 오류 | 먼저 온콜 일정/태그의 실제 상태를 다시 읽습니다. 본문은 이미 제출되었을 수 있으며 큐가 수렴하지 않았더라도 중복 생성하지 마세요. traceId를 보존해 처리하고 수정 전에 전체 설정을 백업합니다. |