생성¶
POST /api/v1/self_built_checker/create
개요¶
자체 구축 점검 및 관련 함수와 알림 정책을 등록합니다.
호출 전 및 사용 단계¶
먼저 함수가 배포되어 사용 가능한지 확인하고, 이 비즈니스 인스턴스에 대해 안정적이고 비어 있지 않은 refKey(권장 ≤48자)를 생성한 뒤 제목과 함수 메타 정보를 완전하게 제공합니다. refKey가 이 워크스페이스의 모든 비삭제 Rule과 중복되면 실패합니다. 제목은 일반 모니터링/자체 구축 점검과 이름 중복 검사를 공유합니다. 알림 정책은 유효한 일치 항목만 필터링하며, 입력한 UUID가 유효하지 않으면 묵시적으로 제거될 수 있으므로 목록을 읽어 확인해야 합니다. 생성은 monitorUUID, extend 또는 callKwargs 등의 내부 매개변수를 지원하지 않습니다. 기본 규칙은 정책 관계를 추가하기 전에 이미 먼저 제출되므로, 이후 실패 시 기본 규칙은 생성되었지만 정책 연결이 완료되지 않았을 수 있습니다. 먼저 refKey로 다시 읽고 목록에서 alertPolicyInfos를 확인한 뒤 재시도를 결정하여 중복 생성으로 refKey가 충돌하는 상황을 피합니다.
인터페이스는 점검 메타 정보와 알림 정책 연결을 등록/수정하며, 연관 함수를 실행하지 않고 점검 결과를 한 번도 생성하지 않으며 자체 구축 점검을 위한 주기 트리거 작업도 생성하지 않습니다. 실제 스케줄링과 이벤트 생성은 비즈니스 통합/함수 측에서 담당합니다. 성공 후에는 목록/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를 가져옵니다. |
|
| isDisabled | boolean | 생성 시에만 선택 사항이며 기본값은 false입니다. true이면 초기 status=2, false이면 0입니다. 수정 시 이 필드는 허용되지 않으며 enable/disable 인터페이스를 사용합니다. null 허용: False 예시: false가져오기 또는 입력 방법: 먼저 등록하되 활성화하지 않으려면 true로 설정합니다. |
|
| refFuncInfo | json | Y | 생성 시 필수이며 funcId도 필수입니다. 연관 함수 정보만 등록하고, 이 요청에서 함수를 실행하거나 주기 스케줄을 생성하지 않습니다. 수정 시에는 이 페이지에 나열된 메타 정보 하위 필드만 허용하며, 최상위 키 단위로 update하고 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.funcId | string | Y | 생성 시에만 필수이며 수정에서는 선언하지 않습니다. 서버 등록은 함수가 실제로 존재하거나 호출 가능함을 보장하지 않습니다. null 허용: False 예시: healthcheck.main가져오기 또는 입력 방법: 실제 배포된 함수 구성에서 전체 ID를 가져옵니다. |
| refFuncInfo.kwargs | json | 선택적 동적 JSON 메타 정보이며 하위 값은 해당 함수 정의에 따라 해석됩니다. 이 인터페이스에서 사용할 수 있는 최상위 callKwargs 매개변수가 아니며 함수를 즉시 호출하지 않습니다. 수정 시 kwargs 전체를 교체합니다. null 허용: False 예시: {"service": "production"}가져오기 또는 입력 방법: 함수 매개변수 메타 정보 또는 비즈니스 통합 구성에서 가져옵니다. |
|
| refKey | string | Y | 생성 시 선언이 필수이며 이후에는 수정할 수 없습니다. 비어 있지 않고 ≤48자를 권장합니다. 생성 시 이 워크스페이스의 모든 비삭제 Rule의 refKey와 중복 여부를 확인하며, 자체 구축 점검에만 한정되지 않습니다. get은 refKey만으로 사용할 수 있습니다. modify는 먼저 get으로 ruleUUID를 얻은 후 제출해야 하며, refKey는 추가 확인 조건으로만 사용할 수 있습니다. refKey만으로는 정책 참조/캐시/음소거 범위와 이름 중복 검증을 안정적으로 유지할 수 없습니다. null 허용: False 예시: custom-healthcheck-production가져오기 또는 입력 방법: 함수/비즈니스 통합을 위한 안정적이고 고유한 키를 생성합니다. 예를 들어 동일 비즈니스 시스템의 점검 인스턴스 식별자입니다. |
| title | string | Y | 생성 시 필수이며, 수정 시 선택 사항이고 생략하면 유지됩니다. 비어 있지 않은 제목은 jsonScript.name으로 복사되며, 일반 트리거 및 self_built_trigger 그룹과 이름 고유성을 공유합니다. 적절한 길이를 권장하며, 공개 선언에는 상한이 없고 서버 생성에 의존하지 않습니다. 함수 funcId가 아닙니다. null 허용: False 예시: 生产服务健康检查가져오기 또는 입력 방법: 비즈니스 측에서 이름을 지정하며, 먼저 일반 모니터링과 자체 구축 점검의 기존 이름을 확인합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/self_built_checker/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"refKey":"custom-healthcheck-production","title":"生产服务健康检查","refFuncInfo":{"funcId":"healthcheck.main","description":"生产服务健康检查函数。","definition":"main(service)","category":"custom","args":["service"],"kwargs":{"service":"production"}},"alertPolicyUUIDs":["altpl_example"],"isDisabled":false}'
응답¶
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": null,
"uuid": "rul_self_example",
"workspaceUUID": "wksp_example",
"monitorUUID": "",
"type": "self_built_trigger",
"refKey": "custom-healthcheck-production",
"secret": null,
"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": "",
"createAt": 1785427200,
"updateAt": -1,
"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를 제공합니다. |
| 400 | ft.SelfBuiltCheckerRefKeyExists | 이 워크스페이스의 비삭제 규칙에 동일한 refKey가 이미 있습니다 | 동일한 refKey를 가진 자체 구축 모니터링이 이미 존재합니다 | 기존 규칙 UUID를 재사용하거나 새로운 안정적인 비즈니스 키를 생성합니다. |