조회¶
GET /api/v1/aggs_to_metric/{rule_uuid}/get
개요¶
지정한 메트릭 생성 규칙의 전체 저장 구성과 생성/업데이트 주체 정보를 조회합니다.
호출 전 확인 및 사용 단계¶
메트릭 생성 목록에서 현재 워크스페이스의 uuid를 가져와 규칙과 두 가지 주체 요약을 조회하며, 실행 결과는 조회하지 않습니다. 상세 정보는 RUM 유형 필터 목록처럼 sourceInfo를 자동으로 추가하지 않습니다. 과거 extend에 해당 필드가 이미 저장되어 있으면 여전히 반환될 수 있습니다.
이러한 진입점은 공통 규칙 처리를 공유하며, 일부 대상 쿼리에는 type=aggs 추가 제한이 없습니다. 이 모듈 목록에서 반환된 UUID만 사용하여 다른 규칙을 잘못 읽거나 변경하지 않도록 하십시오.
라우팅 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| rule_uuid | string | Y | 경로 규칙 UUID이며 메트릭 이름, 메저먼트 이름 또는 스케줄 id가 아닙니다. 일반 모니터의 rul_ UUID를 전달하지 마십시오. 예시: rul_aggs_example가져오기 또는 입력 방법: 메트릭 생성 규칙 목록의 content.data[].uuid에서만 현재 워크스페이스의 aggs 규칙을 가져옵니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/aggs_to_metric/rul_aggs_example/get' \
-H 'DF-API-KEY: <DF-API-KEY>'
응답¶
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 | 엔터티 유형으로 aggs로 고정되며 jsonScript.type과 구분됩니다. |
| content.refKey | string | 연결 키이며 보통 비어 있습니다. |
| content.secret | string | 엔터티 호환 필드이며 일반 메트릭 생성 규칙에서는 보통 비어 있습니다. 호출 자격 증명으로 사용하거나 실제 값을 기록하지 마십시오. |
| content.createdWay | string | manual/import/template 또는 과거의 빈 값입니다. |
| content.isLocked | integer 또는 boolean | 잠금 표시이며 보통 0/false입니다. |
| content.openPermissionSet | boolean | 사용자 지정 작업 권한 스위치이며, 이 모듈에서 생성 시 보통 false입니다. |
| content.permissionSet | array<string> |
사용자 지정 작업 주체 배열이며 보통 []입니다. |
| 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.crontabInfo | object | 스케줄 구성 요약이며 작업 실행 결과가 아닙니다. |
| content.crontabInfo.id | string | 스케줄 구성 식별자로 시스템 유지 관리용이며, 규칙 작업에는 uuid를 사용합니다. |
| content.crontabInfo.crontab | string | 실제 6세그먼트 스케줄 표현식이며 예: 0 */5 * * * *. 요청 빈도는 여전히 metricInfo.every를 사용합니다. |
| content.jsonScript | object | 저장된 구성: 필수 규칙 객체이며, 수정 시 전체를 교체하고 필드 병합은 하지 않습니다. 이 페이지에 나열된 하위 필드만 제출하고, 상세에서 반환된 전체 엔터티를 그대로 다시 전송하지 마십시오. |
| content.jsonScript.type | string | 저장된 구성: 필수 데이터 카테고리이며, 공개 선언에서는 이 여섯 가지 유형만 허용합니다. 내부 객체 플러그인이 현재 OpenAPI에서 공개 지원된다는 의미는 아닙니다. 수정 시 카테고리를 변경할 수 없습니다. |
| content.jsonScript.query | json | 저장된 구성: 필수 쿼리 객체이며, 실제 실행은 q를 기준으로 하고 extend 필드에서 쿼리를 자동 생성하거나 수정하지 않습니다. 저장 성공이 쿼리 구문, 데이터 가용성 또는 생성 결과가 기대에 부합함을 보장하지는 않습니다. |
| content.jsonScript.query.q | string | 저장된 구성: 쿼리 객체 내 필수 문자열입니다. 선택 모드에서도 전체 q를 제공해야 하며 자격 증명을 입력하지 마십시오. Distribution 예시는 distribution(필드)가 아니라 histogram_auto(필드)를 사용합니다. |
| content.jsonScript.query.qtype | string | 저장된 구성: 선택적 쿼리 구문이며, 생략 시 실행 기본값은 dql입니다. 명시적으로는 dql/promql만 사용할 수 있고 빈 문자열이나 null을 전달할 수 없습니다. 항상 명시적으로 작성하는 것이 좋습니다. PromQL은 즉시 쿼리로 실행되며 이 객체를 통해 rangeQuery를 설정하지 않습니다. |
| content.jsonScript.query.qmode | string | 저장된 구성: 선택 사항이며 명시적으로 지정하는 것이 좋습니다. selectorQuery는 extend.fieldKey/funcName을 요구하고 customQuery는 해당 에코 필드 요구 사항이 없습니다. 생략하면 컨트롤러가 선택 모드 구조 검증을 트리거하지 않지만, 플러그인은 여전히 선택 모드로 함수를 검증할 수 있으므로 생략으로 검증을 우회할 수 없습니다. |
| content.jsonScript.metricInfo | json | 저장된 구성: 필수 출력 및 스케줄 객체입니다. 수정 시 전체를 다시 채우며 metric/metricField는 변경할 수 없습니다. 단위 설명은 변경할 수 있고, 생략하면 빈 문자열로 동기화됩니다. |
| content.jsonScript.metricInfo.every | string | 저장된 구성: 필수 빈도이며 선행 0이 없고 60m, 0m, 초, 일 또는 Cron 표현식을 지원하지 않습니다. 스케줄 빈도 및 쿼리 윈도 길이에 사용되며 지연 시간이 아닙니다. |
| content.jsonScript.metricInfo.metric | string | 저장된 구성: 필수 메저먼트 이름이며 영문자, 숫자, 밑줄만 허용하고 하이픈, 공백 또는 중국어를 포함할 수 없습니다. 수정 시 변경이 허용되지 않습니다. |
| content.jsonScript.metricInfo.metricField | string | 저장된 구성: 필수 메트릭 이름이며 명명 문자 제한은 metric과 동일합니다. 수정 시 변경이 허용되지 않습니다. 과거 예시의 001-test를 그대로 사용하지 마십시오. |
| content.jsonScript.metricInfo.unit | string | 저장된 구성: 선택적 표시 단위 문자열이며 생략/빈 문자열이면 지웁니다. 단위에 따라 q의 값을 자동 변환하지 않으므로 쿼리 결과와 단위가 일치하도록 직접 보장해야 합니다. |
| content.jsonScript.metricInfo.desc | string | 저장된 구성: 선택적 메트릭 설명이며 생략/빈 문자열이면 빈 값으로 동기화됩니다. 규칙 이름이 아닙니다. |
| content.jsonScript.metricInfo.delaySeconds | integer | 저장된 구성: 선택적 대기 초 수이며 기본값 0으로 지연하지 않습니다. 정기 트리거 후 소스 데이터가 도착할 때까지 대기합니다. every에 해당하는 쿼리 윈도를 변경하지 않으며, 이 필드를 제공하지 않으면 수정 후 0으로 복원됩니다. 반드시 JSON 정수여야 하며 불리언이나 "60" 문자열은 허용되지 않습니다. |
| content.extend | object | 저장된 구성: 필수 에코 객체이며 수정 시 전체를 교체합니다. 모든 에코 옵션은 jsonScript.query를 대체하지 않습니다. 수동 작성 모드에서 에코가 필요 없으면 {}를 제공할 수 있습니다. |
| content.extend.funcName | string | 저장된 구성: selectorQuery일 때 조건부 필수인 집계 함수 이름입니다. count는 개수, count_distinct는 중복 제거 수이며, 숫자 집계 함수는 실제 숫자 필드가 필요합니다. distribution은 q의 histogram_auto에 대응하는 에코입니다. |
| content.extend.fieldKey | string | 저장된 구성: selectorQuery일 때 조건부 필수인 에코 집계 필드입니다. 추가 시 소스 필드 유형을 조회하여 숫자 함수 호환성을 검사하지만, 알 수 없는 필드가 반드시 거부된다고 보장하지는 않습니다. 수정 시 동일한 필드 유형 검사를 반복하지 않습니다. |
| content.extend.source | string | 저장된 구성: 선택적 소스 에코이며 전체 사용 가능을 *로 표시하고, 실제 범위는 여전히 q에 의해 제한됩니다. RUM 목록을 조회할 때 이 값으로 sourceInfo를 추가할 수 있습니다. |
| content.extend.index | string | 저장된 구성: 선택적 로그 인덱스 에코이며, 이를 변경해도 q의 L 인덱스가 자동으로 변경되지 않습니다. |
| content.extend.groupBy | array | 저장된 구성: 선택적 그룹화 에코 배열이며 생략하면 해당 에코 필드가 없습니다. 빈 배열은 그룹화하지 않습니다. 실제 그룹화는 q를 기준으로 합니다. |
| content.extend.groupBy[] | string | 저장된 구성: 단일 그룹화 키입니다. |
| content.extend.filterString | string | 저장된 구성: 선택적 로그 필터링 에코 문자열이며 q의 자동 결합 진입점이 아닙니다. 실제 필터링은 q에 기록해야 합니다. |
| content.extend.filters | array | 저장된 구성: 선택적 배열이며 다른 인터페이스의 value와 달리 values 복수형을 사용합니다. 실제 실행 필터링은 q를 기준으로 합니다. |
| content.extend.filters[] | json | 저장된 구성: 필터 에코 객체이며 클라이언트에 이미 있는 형식을 재귀적으로 유지할 수 있습니다. 현재 에코 구조는 실행 쿼리로 변환되지 않습니다. |
| content.extend.filters[].name | string | 저장된 구성: 에코 필드입니다. |
| content.extend.filters[].condition | string | 저장된 구성: 이전 에코 조건과의 관계입니다. |
| content.extend.filters[].op | string | 저장된 구성: 에코 연산자이며 이 인터페이스에서 쿼리 조건 변환을 수행하지 않습니다. |
| content.extend.filters[].values | array | 저장된 구성: 에코 값 배열이며, 실제 비교와 값 적용은 모두 q에 반영해야 합니다. |
| content.extend.filters[].values[] | JSON | 저장된 구성: 단일 문자열, 숫자 또는 불리언 값입니다. |
| content.creatorInfo | object | 연결된 주체 요약이며 일치하는 주체가 없으면 {}입니다. |
| content.creatorInfo.uuid | string | 주체 UUID이며 생략할 수 있습니다. |
| content.creatorInfo.status | integer | 계정 상태이며 생략할 수 있습니다. |
| content.creatorInfo.wsAccountStatus | integer | 워크스페이스 멤버 관계 상태이며 생략할 수 있습니다. |
| content.creatorInfo.name | string | 표시 이름입니다. |
| content.creatorInfo.username | string | 로그인 이름입니다. |
| content.creatorInfo.email | string | 이메일 또는 시스템 주체 식별자입니다. |
| content.creatorInfo.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.creatorInfo.countryCode | string | 국가/지역 코드이며 생략할 수 있습니다. |
| content.creatorInfo.iconUrl | string | 아바타이며 생략할 수 있습니다. |
| content.creatorInfo.acntWsNickname | string | 워크스페이스 닉네임이며 생략할 수 있습니다. |
| content.updatorInfo | object | 연결된 주체 요약이며 일치하는 주체가 없으면 {}입니다. |
| content.updatorInfo.uuid | string | 주체 UUID이며 생략할 수 있습니다. |
| content.updatorInfo.status | integer | 계정 상태이며 생략할 수 있습니다. |
| content.updatorInfo.wsAccountStatus | integer | 워크스페이스 멤버 관계 상태이며 생략할 수 있습니다. |
| content.updatorInfo.name | string | 표시 이름입니다. |
| content.updatorInfo.username | string | 로그인 이름입니다. |
| content.updatorInfo.email | string | 이메일 또는 시스템 주체 식별자입니다. |
| content.updatorInfo.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.updatorInfo.countryCode | string | 국가/지역 코드이며 생략할 수 있습니다. |
| content.updatorInfo.iconUrl | string | 아바타이며 생략할 수 있습니다. |
| content.updatorInfo.acntWsNickname | string | 워크스페이스 닉네임이며 생략할 수 있습니다. |
| content.declaration | object | 공개 선언입니다. |
{
"code": 200,
"content": {
"id": 101,
"uuid": "rul_aggs_example",
"workspaceUUID": "wksp_example",
"monitorUUID": "",
"type": "aggs",
"refKey": "",
"secret": "",
"jsonScript": {
"type": "logToMetric",
"query": {
"q": "L('default')::`nginx`:(count(`*`)) BY `host`",
"qtype": "dql",
"qmode": "selectorQuery"
},
"metricInfo": {
"every": "5m",
"metric": "recording_rules",
"metricField": "nginx_requests",
"unit": "custom/[\"custom\",\"次\"]",
"desc": "按host统计nginx请求数。",
"delaySeconds": 60
}
},
"extend": {
"funcName": "count",
"fieldKey": "*",
"source": "nginx",
"index": "default",
"groupBy": [
"host"
],
"filters": [],
"filterString": ""
},
"crontabInfo": {
"id": "cron_example",
"crontab": "0 */5 * * * *"
},
"createdWay": "manual",
"isLocked": 0,
"openPermissionSet": false,
"permissionSet": [],
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"creatorInfo": {},
"updatorInfo": {},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 404 | ft.NotFoundRuleInspector | 워크스페이스 내에 지정한 비삭제 규칙이 없음(삭제되었거나 다른 워크스페이스의 UUID 포함) | 지정한 규칙/검사기를 찾을 수 없음 | 이 모듈 목록에서 유효한 aggs UUID를 다시 가져옵니다. |
| 500 | ft.InternalServerError | 규칙 조회 또는 응답 형식 지정 실패 | 내부 오류 | 워크스페이스와 UUID를 확인하고, 계속 실패하면 traceId를 제공합니다. |
| 403 | ft.Forbidden | API Key 권한 부족 또는 워크스페이스 버전이 이 기능을 지원하지 않음 | 작업 권한이 없음 | 해당 권한이 있는 API Key와 메트릭 생성을 지원하는 워크스페이스를 사용합니다. |