수정¶
POST /api/v1/self_built_checker/modify
개요¶
자체 호스팅 점검 제목, 함수 메타 정보 및 연결 정책을 업데이트합니다.
호출 전 및 사용 단계¶
수정 시에는 반드시 먼저 get으로 ruleUUID를 조회하여 명확히 전달해야 합니다. refKey를 제공하는 경우 UUID와 함께 매칭됩니다. 현재 구현은 어느 대상 식별자도 필수로 강제하지 않으므로, 둘 다 전달하지 않으면 워크스페이스의 첫 번째 자체 호스팅 규칙이 선택될 수 있으며, 대상을 지정하지 않은 요청을 제출해서는 안 됩니다. refKey만으로 제목을 변경할 때 중복 이름 제외 조건은 [None]을 사용하므로 NOT IN(NULL)이 형성되어 제목 중복 여부를 안정적으로 검사할 수 없습니다. 정책 참조 수정, 음소거 제목/정책 캐시 새로 고침도 여전히 원본 ruleUUID를 사용하며, 매칭된 객체의 UUID를 자동으로 채우지 않습니다. refKey만으로는 올바른 참조를 찾지 못하거나 유효한 소스가 없는 참조가 형성될 수 있습니다. 반드시 먼저 get으로 ruleUUID를 조회한 후, 특히 정책/제목을 변경할 때는 명확히 전달하여 수정해야 합니다.
제목은 생략하면 유지됩니다. refFuncInfo는 첫 번째 레벨 키를 업데이트하며, args/kwargs는 각각 전체가 교체되고 깊은 병합은 수행하지 않습니다. {}는 원래 메타 정보를 지우지 않으며, funcId는 공개 수정 허용 목록에 포함되지 않습니다. alertPolicyUUIDs는 생략하면 유지되고, []는 삭제합니다. 공개 Body에는 callKwargs/monitorUUID/dashboardUUID/extend가 선언되어 있지 않으므로 Front 또는 내부 파라미터를 그대로 사용할 수 없습니다. 공유 작업 업데이트는 기존 openPermissionSet=false, permissionSet=[]을 재설정하므로 수정 전에 권한을 확인해야 합니다.
저장 후 비동기적으로 음소거 범위의 제목을 업데이트하고 연결된 정책 캐시를 정리합니다. 오류가 발생하면 규칙이 이미 커밋되었을 수 있으므로 먼저 다시 읽어 확인한 후 재시도합니다. 본 공개 수정은 별도의 수정 감사 로그를 기록하지 않습니다.
인터페이스는 점검 메타 정보와 알림 정책 연결을 등록/수정할 뿐, 연결된 함수를 실행하지 않고 점검 결과를 생성하지 않으며, 자체 호스팅 점검을 위한 주기적 트리거 작업도 생성하지 않습니다. 실제 스케줄링과 이벤트 생성은 비즈니스 통합/함수 측에서 담당합니다. 성공 후에는 목록/get으로 설정과 상태를 확인합니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| alertPolicyUUIDs[*] | string | 비어 있지 않은 문자열을 권장하며, 이름, 알림 대상 또는 알림 정책 UUID가 아닙니다. 예: altpl_example획득 또는 입력 방법: 현재 워크스페이스의 단일 알림 정책 uuid입니다. |
|
| refFuncInfo.args[*] | JSON | 임의의 JSON 파라미터 메타 정보이며, 서버는 통일된 하위 항목 schema를 제공하지 않습니다. 원래 정의를 유지합니다. 예: service획득 또는 입력 방법: 함수 플랫폼의 단일 파라미터 메타 정보로, 함수 정의에 따라 문자열 또는 객체일 수 있습니다. |
|
| refFuncInfo.kwargs.参数名 | any | 동적 키-값으로, 모든 함수에 공통된 필수 파라미터는 없습니다. 자격 증명을 예시/로그에 전달하지 마십시오. 예: production획득 또는 입력 방법: 예를 들어 service는 비즈니스에 이미 배포된 서비스 이름을 사용하며, 구체적인 이름/유형/출처는 연결된 함수 문서를 따릅니다. |
|
| alertPolicyUUIDs | array | 선택 사항입니다. 생성 시 생략/[]는 정책 바인딩이 없고, 수정 시 생략하면 유지, []는 비웁니다. 서버는 현재 워크스페이스에서 삭제되지 않은 항목만 유지하며, 입력이 모두 유효함을 보장하지 않고 비활성화된 정책도 유지될 수 있습니다. 최종 alertPolicyInfos를 목록으로 확인해야 하며, 성공을 알림 전달 완료로 간주해서는 안 됩니다. null 허용: False 예: ["altpl_example"]획득 또는 입력 방법: 알림 정책 목록에서 현재 워크스페이스의 삭제되지 않은 정책 uuid를 획득합니다. |
|
| refFuncInfo | json | 생성 시 필수, funcId 필수입니다. 연결된 함수 자료만 등록하며, 본 요청에서 함수를 실행하거나 주기적 스케줄링을 생성하지 않습니다. 수정 시에는 이 페이지에 나열된 메타 정보 하위 필드만 허용하며, 첫 번째 레벨 키 기준으로 업데이트하고 args/kwargs는 전체 교체합니다. {} 또는 생략 시 변경되지 않습니다. funcId는 modify 허용 목록에 없으므로 수정을 통해 함수 식별자를 변경할 수 없습니다. null 허용: False 예: {"funcId": "healthcheck.main", "description": "프로덕션 서비스 상태 점검 함수.", "definition": "main(service)", "category": "custom", "args": ["service"], "kwargs": {"service": "production"}}획득 또는 입력 방법: 이미 배포되어 사용 가능한 사용자 정의 점검 함수/함수 플랫폼 설정에서 메타 정보를 획득하며, 예시 리터럴 값을 실제 함수로 간주하지 않습니다. |
|
| refFuncInfo.args | array | 선택적 배열로, 함수 플랫폼의 원래 메타 정보 규약에 따라 저장되며, 서버는 파라미터 바인딩을 실행하거나 함수 시그니처를 검증하지 않습니다. 수정 시 전체 배열을 교체합니다. null 허용: False 예: ["service"]획득 또는 입력 방법: 함수 파라미터 시그니처에서 위치 파라미터 메타 정보를 획득합니다. |
|
| refFuncInfo.category | string | 선택적 메타 정보로, 고정된 열거형이 아니며 Rule.type을 변경하지 않습니다. null 허용: False 예: custom획득 또는 입력 방법: 함수 플랫폼의 실제 분류명을 사용합니다. |
|
| refFuncInfo.definition | string | 선택적 시그니처 표시 문자열로, 본 인터페이스가 실행하는 소스 코드가 아닙니다. 빈 문자열 허용: True null 허용: False 예: main(service)획득 또는 입력 방법: 함수 정의/시그니처에서 내보낸 설명을 획득합니다. |
|
| refFuncInfo.description | string | 선택적 문자열로, 비어 있을 수 있습니다. 수정 시 명시적 빈 문자열은 삭제합니다. 빈 문자열 허용: True null 허용: False 예: 프로덕션 서비스 상태 점검 함수.획득 또는 입력 방법: 함수 설명 문서를 그대로 사용합니다. |
|
| refFuncInfo.kwargs | json | 선택적 동적 JSON 메타 정보로, 하위 값은 해당 함수 정의에 따라 해석됩니다. 본 인터페이스에서 사용 가능한 최상위 callKwargs 파라미터가 아니며, 함수를 즉시 호출하지 않습니다. 수정 시 kwargs 전체를 교체합니다. null 허용: False 예: {"service": "production"}획득 또는 입력 방법: 함수 파라미터 메타 정보 또는 비즈니스 통합 설정에서 획득합니다. |
|
| refKey | string | 생성 시 선언 필수이며 이후 수정할 수 없습니다. 비어 있지 않고 48자 이하를 권장합니다. 생성 시 현재 워크스페이스의 모든 삭제되지 않은 Rule의 refKey와 중복을 검사하며, 자체 호스팅 점검만 대상이 아닙니다. get은 refKey만으로 사용할 수 있으나, modify는 반드시 먼저 get으로 ruleUUID를 획득한 후 제출해야 하며 refKey는 추가적인 확인 조건으로만 사용됩니다. refKey만으로는 정책 참조/캐시/음소거 범위와 중복 이름 검증을 안정적으로 유지할 수 없습니다. null 허용: False 예: custom-healthcheck-production획득 또는 입력 방법: 함수/비즈니스 통합을 위한 안정적이고 고유한 키를 생성합니다. 예를 들어 동일 비즈니스 시스템의 점검 인스턴스 식별자입니다. |
|
| ruleUUID | string | 작업 대상 식별자로, 수정 시에는 특히 정책/제목을 변경할 때 반드시 먼저 get으로 명확한 ruleUUID를 획득해야 합니다. get에서 refKey도 함께 제공된 경우 ruleUUID만 사용하며, modify에서 둘 다 제공된 경우 두 조건 모두 일치해야 합니다. 함수 funcId 또는 연결 키가 아닙니다. null 허용: False 예: rul_self_example획득 또는 입력 방법: 자체 호스팅 점검 목록의 content.data[].uuid에서 현재 워크스페이스의 자체 호스팅 점검 UUID를 획득합니다. |
|
| title | string | 생성 시 필수이며, 수정 시 선택 사항으로 생략하면 유지됩니다. 비어 있지 않은 제목은 jsonScript.name으로 복사되며, 일반 trigger 및 self_built_trigger 그룹과 이름 고유성을 공유합니다. 적절한 길이를 권장하며, 공개 선언에는 상한이 없고 서버 생성에 의존하지 않습니다. 함수 funcId가 아닙니다. null 허용: False 예: 프로덕션 서비스 상태 점검획득 또는 입력 방법: 비즈니스 측에서 명명하며, 먼저 일반 모니터링 및 자체 호스팅 점검의 기존 이름을 확인합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/self_built_checker/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"ruleUUID":"rul_self_example","title":"프로덕션 서비스 상태 점검(업데이트됨)","refFuncInfo":{"description":"점검 함수 설명이 업데이트되었습니다."},"alertPolicyUUIDs":["altpl_example"]}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 레코드 번호로, 생성 제출 전 스냅샷은 null일 수 있으므로 uuid로 작업합니다. |
| content.uuid | string | rul_ 규칙 UUID. |
| content.workspaceUUID | string | 소속 워크스페이스. |
| content.monitorUUID | string | 연결된 모니터링 그룹 UUID로, 공개 생성에서 선언되지 않아 일반적으로 빈 문자열입니다. |
| content.type | string | 자체 호스팅 점검은 self_built_trigger로 고정됩니다. get은 유형을 추가로 제한하지 않으며, 본 모듈 목록의 UUID만 사용합니다. |
| content.refKey | string | 고정 비즈니스 연결 키. |
| content.secret | string 또는 null | 공유 엔터티 호환 필드로, 자체 호스팅 점검에서는 일반적으로 비어 있습니다. 생성 스냅샷은 null일 수 있으며, 호출 자격 증명으로 사용하지 않습니다. |
| content.jsonScript | object | 저장된 자체 호스팅 점검 정의로, Rule.type과 구분됩니다. |
| content.jsonScript.type | string | selfBuiltCheck로 고정. |
| content.jsonScript.title | string | 루트 비즈니스 제목. |
| content.jsonScript.name | string | 생략 가능합니다. 생성 시 title이 비어 있으면 생성되지 않으며, title이 비어 있지 않으면 name으로 복사됩니다. title을 비워 수정하면 기존 name이 유지됩니다. |
| content.jsonScript.refFuncInfo | object | 연결된 함수 자료. |
| content.jsonScript.refFuncInfo.funcId | string | 생성 시에만 필수이며 수정에서는 선언되지 않습니다. 서버 등록은 함수가 실제로 존재하거나 호출 가능함을 보장하지 않습니다. |
| content.jsonScript.refFuncInfo.description | string | 선택적 문자열로, 비어 있을 수 있습니다. 수정 시 명시적 빈 문자열은 삭제합니다. |
| content.jsonScript.refFuncInfo.definition | string | 선택적 시그니처 표시 문자열로, 본 인터페이스가 실행하는 소스 코드가 아닙니다. |
| content.jsonScript.refFuncInfo.category | string | 선택적 메타 정보로, 고정된 열거형이 아니며 Rule.type을 변경하지 않습니다. |
| content.jsonScript.refFuncInfo.args | array | 선택적 배열로, 함수 플랫폼의 원래 메타 정보 규약에 따라 저장되며, 서버는 파라미터 바인딩을 실행하거나 함수 시그니처를 검증하지 않습니다. 수정 시 전체 배열을 교체합니다. |
| content.jsonScript.refFuncInfo.kwargs | json | 선택적 동적 JSON 메타 정보로, 하위 값은 해당 함수 정의에 따라 해석됩니다. 본 인터페이스에서 사용 가능한 최상위 callKwargs 파라미터가 아니며, 함수를 즉시 호출하지 않습니다. 수정 시 kwargs 전체를 교체합니다. |
| content.jsonScript.refFuncInfo.args[] | JSON | 임의의 JSON 파라미터 메타 정보이며, 서버는 통일된 하위 항목 schema를 제공하지 않습니다. 원래 정의를 유지합니다. |
| content.jsonScript.refFuncInfo.kwargs.参数名 | any | 동적 키-값으로, 모든 함수에 공통된 필수 파라미터는 없습니다. 자격 증명을 예시/로그에 전달하지 마십시오. |
| content.jsonScript.callKwargs | object | 기록/기타 진입점에서 저장되었을 수 있는 실행 파라미터로, 공개 create/modify에서 선언되지 않아 다시 전달하여 추가할 수 없습니다. |
| content.jsonScript.callKwargs.参数名 | JSON | 구체적인 실행 파라미터는 원래 함수 정의에 따라 해석되며 존재를 보장하지 않습니다. |
| content.crontabInfo | object | 자체 호스팅 점검은 이 진입점에서 주기적 트리거 설정을 생성하지 않으므로 일반적으로 {}입니다. |
| content.crontabInfo.历史字段 | JSON | 기록에 스케줄링 자료가 남아 있을 수 있으며, 본 인터페이스에서 쓸 수 있는 설정이 아닙니다. |
| content.extend | object | 확장 메타 정보로, 공개 Body에서 선언되지 않아 생성 시 일반적으로 {}입니다. |
| content.extend.历史字段 | JSON | 기록에 저장된 확장 필드로, 본 진입점에서는 다시 전달하여 수정할 수 없습니다. |
| content.createdWay | string | 일반적으로 manual이며, 기록에 따라 import/template/빈 값일 수도 있습니다. |
| content.isLocked | integer 또는 boolean | 잠금 표시. |
| content.openPermissionSet | boolean | 사용자 정의 작업 권한 스위치로, 생성 시 false이며 modify 공유 작업 업데이트 시 false로 복원됩니다. |
| content.permissionSet | array<string> |
작업 권한 주체로, 생성 시 []이며 modify 공유 업데이트 시 []로 복원됩니다. |
| content.permissionSet[] | string | 기록된 계정/팀/역할 식별자. |
| content.status | integer | 0 활성화, 2 비활성화, 3 삭제. 최근 점검 결과와 같지 않습니다. |
| content.creator | string | 생성 주체. |
| content.updator | string | 업데이트 주체로, 초기에는 비어 있을 수 있습니다. |
| content.createAt | integer | 생성 Unix 초. |
| content.updateAt | integer | 업데이트 Unix 초, 업데이트되지 않은 경우 -1. |
| content.deleteAt | integer | 삭제 Unix 초, 삭제되지 않은 경우 -1. |
| content.declaration | object | 공개 선언. |
{
"code": 200,
"content": {
"id": 100,
"uuid": "rul_self_example",
"workspaceUUID": "wksp_example",
"monitorUUID": "",
"type": "self_built_trigger",
"refKey": "custom-healthcheck-production",
"secret": "",
"jsonScript": {
"type": "selfBuiltCheck",
"title": "프로덕션 서비스 상태 점검(업데이트됨)",
"name": "프로덕션 서비스 상태 점검(업데이트됨)",
"refFuncInfo": {
"funcId": "healthcheck.main",
"description": "점검 함수 설명이 업데이트되었습니다.",
"definition": "main(service)",
"category": "custom",
"args": [
"service"
],
"kwargs": {
"service": "production"
}
}
},
"crontabInfo": {},
"extend": {},
"createdWay": "manual",
"isLocked": 0,
"openPermissionSet": false,
"permissionSet": [],
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427300,
"deleteAt": -1,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 문법이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 406 | ft.CheckObjectNameRepeat | 제목이 현재 워크스페이스의 삭제되지 않은 일반 모니터링/자체 호스팅 점검 이름과 중복 | 검사 대상의 별칭 중복 | 이름을 변경하고, 수정 시 ruleUUID를 함께 전달하여 현재 객체를 제외합니다. |
| 500 | ft.InternalServerError | 대상 미선택, 필드 형식 또는 길이 오류, 데이터베이스/커밋 후 비동기 작업 디스패치 실패 등 | 내부 오류 | 먼저 현재 규칙을 다시 읽어 저장 여부를 확인하고, 현재 워크스페이스의 명확한 ruleUUID를 사용하여 재시도하며 traceId를 제공합니다. |
| 404 | ft.MonitorNotFound | 기록 규칙에 이미 연결된 monitorUUID가 있으나 그룹이 존재하지 않거나 삭제됨 | 규칙 그룹을 찾을 수 없음 | 먼저 원래 규칙과 그룹을 확인하고, 관리자가 기록 연결을 복구한 후 수정합니다. |
| 404 | ft.NotFoundRuleInspector | 식별 조건이 현재 워크스페이스의 삭제되지 않은 자체 호스팅 점검과 일치하지 않음 | 지정된 규칙/검사기를 찾을 수 없음 | ruleUUID 및 선택적 refKey가 동일 객체에 속하는지 확인합니다. |