목록 조회¶
GET /api/v1/aggs_to_metric/list
개요¶
현재 워크스페이스의 메트릭 생성 규칙, 출력 정의, 스케줄 및 활성화/비활성화 상태를 페이지 단위로 나열합니다.
호출 전 준비 및 사용 단계¶
scriptType에 따라 데이터 카테고리를 선택한 다음, metric/metricField로 검색하고 페이지별로 읽습니다. 조회는 type=aggs이고 status!=3인 항목만 대상으로 하며, 비활성화된 규칙도 포함하고 레코드 id 기준 내림차순으로 정렬합니다. RUM 애플리케이션 정보는 scriptType=rumToMetric을 명시한 경우에만 extend.sourceInfo에 보강을 시도합니다. 유형을 지정하지 않고 전체를 조회해도 각 RUM 항목에 자동으로 보강되지는 않습니다.
목록의 설정은 규칙 스냅샷이며 실행 상태나 메트릭 생성 결과가 아닙니다. 이후 수정 시에는 이 API의 쓰기 필드에 맞춰 전체 Body를 구성해야 합니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| pageIndex | integer | 선택 사항, 기본값 1, 최소 1. null 허용: False $minValue: 1 예: 1가져오기 또는 입력 방법: 1부터 시작하여 최상위 pageInfo에 따라 진행합니다. |
|
| pageSize | integer | 선택 사항, 기본값 100, 최대 100. null 허용: False $maxValue: 100 $minValue: 1 예: 100가져오기 또는 입력 방법: 페이지당 1~100 사이로 선택합니다. |
|
| scriptType | string | 선택적 유형 필터입니다. 현재 Query 열거형에는 objectToMetric/customObjectToMetric이 포함되지 않습니다. 과거 이러한 레코드는 필터링하지 않은 목록에서 볼 수 있지만, 이를 근거로 현재 생성 가능하다고 판단해서는 안 됩니다. null 허용: False 선택 가능한 값: ['rumToMetric', 'apmToMetric', 'logToMetric', 'securityToMetric', 'metricToMetric', 'dialingToMetric'] 예: logToMetric가져오기 또는 입력 방법: 여섯 가지 공개 jsonScript.type 중에서 선택합니다. 생략하면 모든 aggs를 조회합니다. |
|
| search | string | 선택 사항이며, 앞뒤 공백을 제거한 후 메저먼트 이름/메트릭 이름에 포함 일치로 검색합니다. 규칙 UUID 또는 extend는 검색하지 않습니다. 빈 문자열 허용: True null 허용: False 예: nginx_requests가져오기 또는 입력 방법: 출력 metric 또는 metricField의 키워드를 사용합니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/aggs_to_metric/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode scriptType=logToMetric \
--data-urlencode pageIndex=1 \
--data-urlencode pageSize=100
응답¶
HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.data | array<object> |
이 페이지의 규칙 배열이며, 결과가 없으면 []입니다. |
| content.data[].id | integer 또는 null | 레코드 번호입니다. 새 스냅샷은 제출 전에 생성되며 null일 수 있으므로 uuid로 작업합니다. |
| content.data[].uuid | string | rul_규칙 UUID. |
| content.data[].workspaceUUID | string | 소속 워크스페이스. |
| content.data[].monitorUUID | string | 연결된 모니터 UUID이며, 이 모듈에서는 일반적으로 빈 문자열입니다. |
| content.data[].type | string | 엔터티 유형은 aggs로 고정되며 jsonScript.type과 다릅니다. |
| content.data[].refKey | string | 연결 키이며 일반적으로 비어 있습니다. |
| content.data[].secret | string | 호환 엔터티 필드입니다. 일반적인 메트릭 생성 규칙에서는 보통 비어 있습니다. 호출 자격 증명으로 사용하거나 실제 값을 기록해서는 안 됩니다. |
| content.data[].createdWay | string | manual/import/template 또는 과거의 빈 값입니다. |
| content.data[].isLocked | integer 또는 boolean | 잠금 표시이며 일반적으로 0/false입니다. |
| content.data[].openPermissionSet | boolean | 사용자 지정 작업 권한 스위치이며, 이 모듈에서 생성 시 일반적으로 false입니다. |
| content.data[].permissionSet | array<string> |
사용자 지정 작업 주체 배열이며 일반적으로 []입니다. |
| content.data[].permissionSet[] | string | 개별 계정/팀/역할 식별자입니다. |
| content.data[].status | integer | 0은 활성화, 2는 비활성화, 3은 삭제입니다. 상태가 최근 작업 실행 성공을 의미하지는 않습니다. |
| content.data[].creator | string | 생성 주체입니다. |
| content.data[].updator | string | 최근 업데이트한 주체이며 초기에는 비어 있을 수 있습니다. |
| content.data[].createAt | integer | 생성 Unix 초. |
| content.data[].updateAt | integer | 업데이트 Unix 초, 업데이트되지 않은 경우 -1. |
| content.data[].deleteAt | integer | 삭제 Unix 초, 삭제되지 않은 경우 -1. |
| content.data[].crontabInfo | object | 스케줄 설정 요약이며 작업 실행 결과가 아닙니다. |
| content.data[].crontabInfo.id | string | 스케줄 설정 식별자로 시스템 유지 관리에 사용됩니다. 규칙 작업에는 uuid를 사용합니다. |
| content.data[].crontabInfo.crontab | string | 실제 6필드 스케줄 표현식입니다(예: 0 */5 * * * *). 요청 빈도는 여전히 metricInfo.every를 사용합니다. |
| content.data[].jsonScript | object | 저장된 설정: 필수 규칙 객체이며, 수정 시 전체를 교체하고 필드를 병합하지 않습니다. 이 페이지에 나열된 하위 필드만 제출하고, 상세 응답에서 반환된 전체 엔터티를 다시 전송하지 않습니다. |
| content.data[].jsonScript.type | string | 저장된 설정: 필수 데이터 카테고리이며 공개 선언에서는 이 여섯 가지만 허용합니다. 내부 객체 플러그인은 현재 OpenAPI에서 공개 지원되는 것과 같지 않습니다. 수정 시 카테고리를 변경할 수 없습니다. |
| content.data[].jsonScript.query | json | 저장된 설정: 필수 쿼리 객체입니다. 실제 실행은 q를 기준으로 하며 extend 필드에서 쿼리를 자동 생성하거나 수정하지 않습니다. 저장 성공이 쿼리 구문, 데이터 가용성 또는 생성 결과가 기대에 부합함을 보장하지는 않습니다. |
| content.data[].jsonScript.query.q | string | 저장된 설정: 쿼리 객체 내 필수 문자열입니다. 선택 모드에서도 전체 q를 제공해야 하며 자격 증명을 입력해서는 안 됩니다. Distribution 예시는 distribution(필드)이 아니라 histogram_auto(필드)를 사용합니다. |
| content.data[].jsonScript.query.qtype | string | 저장된 설정: 선택적 쿼리 구문이며 생략하면 실행 기본값은 dql입니다. 명시할 때는 dql/promql만 사용할 수 있고 빈 문자열이나 null을 전달할 수 없습니다. 항상 명시적으로 입력하는 것이 좋습니다. PromQL은 즉시 쿼리로 실행되며 이 객체를 통해 rangeQuery를 설정하지 않습니다. |
| content.data[].jsonScript.query.qmode | string | 저장된 설정: 선택 사항이며 명시적으로 지정하는 것이 좋습니다. selectorQuery는 extend.fieldKey/funcName을 요구하고 customQuery는 해당 에코 필드를 요구하지 않습니다. 생략하면 컨트롤러가 선택 모드 구조 검증을 트리거하지 않지만, 플러그인은 여전히 선택 모드에 따라 함수를 검증할 수 있으므로 생략으로 검증을 우회할 수 없습니다. |
| content.data[].jsonScript.metricInfo | json | 저장된 설정: 필수 출력 및 스케줄 객체입니다. 수정 시 전체를 다시 채워야 하며 metric/metricField는 수정할 수 없습니다. 단위 설명은 변경할 수 있고 생략하면 빈 문자열로 동기화됩니다. |
| content.data[].jsonScript.metricInfo.every | string | 저장된 설정: 필수 빈도이며 선행 0이 없고 60m, 0m, 초, 일 또는 Cron 표현식은 지원하지 않습니다. 스케줄 빈도 및 쿼리 윈도 길이에 사용되며 지연 시간이 아닙니다. |
| content.data[].jsonScript.metricInfo.metric | string | 저장된 설정: 필수 메저먼트 이름이며 영문자, 숫자, 밑줄만 사용할 수 있고 하이픈, 공백 또는 중국어를 포함할 수 없습니다. 수정 시 변경할 수 없습니다. |
| content.data[].jsonScript.metricInfo.metricField | string | 저장된 설정: 필수 메트릭 이름이며 명명 문자 제한은 metric과 같습니다. 수정 시 변경할 수 없으며 과거 예시의 001-test를 그대로 사용해서는 안 됩니다. |
| content.data[].jsonScript.metricInfo.unit | string | 저장된 설정: 선택적 표시 단위 문자열이며 생략하거나 빈 문자열이면 지웁니다. 단위에 따라 q의 숫자를 자동 변환하지 않으므로 쿼리 결과와 단위가 일치하도록 직접 보장해야 합니다. |
| content.data[].jsonScript.metricInfo.desc | string | 저장된 설정: 선택적 메트릭 설명이며 생략하거나 빈 문자열이면 빈 값으로 동기화됩니다. 규칙 이름이 아닙니다. |
| content.data[].jsonScript.metricInfo.delaySeconds | integer | 저장된 설정: 선택적 대기 초 수이며 기본값 0은 지연 없음입니다. 예약 트리거 후 소스 데이터가 모두 도착할 때까지 기다립니다. every에 해당하는 쿼리 윈도를 변경하지 않으며, 이 필드를 제공하지 않으면 수정 후 0으로 복원됩니다. 반드시 JSON 정수여야 하고 불리언 또는 "60" 문자열은 허용되지 않습니다. |
| content.data[].extend | object | 저장된 설정: 필수 에코 객체이며 수정 시 전체를 교체합니다. 모든 에코 옵션이 jsonScript.query를 대체하지는 않습니다. 수동 작성 모드에서 에코가 필요 없으면 {}를 제공할 수 있습니다. |
| content.data[].extend.funcName | string | 저장된 설정: selectorQuery일 때 조건부 필수인 집계 함수 이름입니다. count는 개수, count_distinct는 중복 제거 수입니다. 숫자 집계 함수에는 실제 숫자 필드가 필요합니다. distribution은 q의 histogram_auto에 대응하는 값으로 에코됩니다. |
| content.data[].extend.fieldKey | string | 저장된 설정: selectorQuery일 때 조건부 필수인 에코 집계 필드입니다. 추가 시 소스 필드 유형을 조회하여 숫자 함수 호환성을 확인하지만, 알 수 없는 필드가 거부된다고 보장하지는 않습니다. 수정 시 동일한 필드 유형 검사를 다시 수행하지 않습니다. |
| content.data[].extend.source | string | 저장된 설정: 선택적 소스 에코이며, 사용 가능한 전체 소스는 *로 표시되고 실제 범위는 여전히 q로 제한됩니다. RUM 목록 조회 시 이 값으로 sourceInfo를 추가할 수 있습니다. |
| content.data[].extend.index | string | 저장된 설정: 선택적 로그 인덱스 에코입니다. 이를 변경해도 q의 L 인덱스가 자동으로 변경되지 않습니다. |
| content.data[].extend.groupBy | array | 저장된 설정: 선택적 그룹화 에코 배열이며 생략하면 해당 에코 필드가 없습니다. 빈 배열은 그룹화하지 않습니다. 실제 그룹화는 q를 기준으로 합니다. |
| content.data[].extend.groupBy[] | string | 저장된 설정: 개별 그룹화 키입니다. |
| content.data[].extend.filterString | string | 저장된 설정: 선택적 로그 필터 에코 문자열이며 q의 자동 연결 진입점이 아닙니다. 실제 필터링은 q에 작성해야 합니다. |
| content.data[].extend.filters | array | 저장된 설정: 선택적 배열이며 values 복수형을 사용하고 다른 API의 value와 다릅니다. 실제 실행 필터링은 q를 기준으로 합니다. |
| content.data[].extend.filters[] | json | 저장된 설정: 필터 에코 객체이며 클라이언트에 이미 있는 형식을 재귀적으로 유지할 수 있습니다. 현재 에코 구조는 실행 쿼리로 변환되지 않습니다. |
| content.data[].extend.filters[].name | string | 저장된 설정: 에코되는 필드입니다. |
| content.data[].extend.filters[].condition | string | 저장된 설정: 이전 에코 조건과의 관계입니다. |
| content.data[].extend.filters[].op | string | 저장된 설정: 에코 연산자이며 이 API에서 쿼리 조건 변환을 수행하지 않습니다. |
| content.data[].extend.filters[].values | array | 저장된 설정: 에코 값 배열이며 실제 비교와 값 선택은 모두 q에 반영해야 합니다. |
| content.data[].extend.filters[].values[] | JSON | 저장된 설정: 개별 문자열, 숫자 또는 불리언 값입니다. |
| content.data[].creatorInfo | object | 연결된 ID 요약이며 일치하는 ID가 없으면 {}입니다. |
| content.data[].creatorInfo.uuid | string | ID UUID이며 생략할 수 있습니다. |
| content.data[].creatorInfo.status | integer | 계정 상태이며 생략할 수 있습니다. |
| content.data[].creatorInfo.wsAccountStatus | integer | 워크스페이스 멤버 관계 상태이며 생략할 수 있습니다. |
| content.data[].creatorInfo.name | string | 표시 이름. |
| content.data[].creatorInfo.username | string | 로그인 이름. |
| content.data[].creatorInfo.email | string | 이메일 또는 시스템 ID 식별자입니다. |
| content.data[].creatorInfo.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.data[].creatorInfo.countryCode | string | 국가/지역 코드이며 생략할 수 있습니다. |
| content.data[].creatorInfo.iconUrl | string | 프로필 이미지이며 생략할 수 있습니다. |
| content.data[].creatorInfo.acntWsNickname | string | 워크스페이스 닉네임이며 생략할 수 있습니다. |
| content.data[].updatorInfo | object | 연결된 ID 요약이며 일치하는 ID가 없으면 {}입니다. |
| content.data[].updatorInfo.uuid | string | ID UUID이며 생략할 수 있습니다. |
| content.data[].updatorInfo.status | integer | 계정 상태이며 생략할 수 있습니다. |
| content.data[].updatorInfo.wsAccountStatus | integer | 워크스페이스 멤버 관계 상태이며 생략할 수 있습니다. |
| content.data[].updatorInfo.name | string | 표시 이름. |
| content.data[].updatorInfo.username | string | 로그인 이름. |
| content.data[].updatorInfo.email | string | 이메일 또는 시스템 ID 식별자입니다. |
| content.data[].updatorInfo.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.data[].updatorInfo.countryCode | string | 국가/지역 코드이며 생략할 수 있습니다. |
| content.data[].updatorInfo.iconUrl | string | 프로필 이미지이며 생략할 수 있습니다. |
| content.data[].updatorInfo.acntWsNickname | string | 워크스페이스 닉네임이며 생략할 수 있습니다. |
| content.data[].extend.sourceInfo | object | 목록에서 scriptType=rumToMetric을 명시한 경우에만 보강을 시도하며 상세/쓰기에서는 자동으로 제공되지 않습니다. 키는 extend.source의 app_id입니다. |
| content.data[].extend.sourceInfo.应用ID | object | 해당 애플리케이션 정보이며 일치하는 항목이 없거나 조회에 실패하면 빈 객체일 수 있습니다. |
| content.data[].extend.sourceInfo.应用ID.status | integer | 애플리케이션 엔터티 상태이며 비활성 이력 레코드를 포함할 수 있습니다. |
| content.data[].extend.sourceInfo.应用ID.jsonContent | object | 표시용으로 RUM 애플리케이션에 저장된 설정 JSON입니다. 해당 애플리케이션 유형에 따라 달라지며 이 API의 쓰기 가능한 파라미터로 사용해서는 안 됩니다. |
| content.data[].extend.sourceInfo.应用ID.jsonContent.配置键 | JSON | RUM 애플리케이션 유형에 따라 반환되는 설정 필드입니다(예: name/type 등). 이 API는 통일된 애플리케이션 구조를 보장하지 않습니다. |
| content.declaration | object | 워크스페이스 공통 선언입니다. |
| pageInfo.pageIndex | integer | 현재 페이지 번호. |
| pageInfo.pageSize | integer | 페이지당 항목 수. |
| pageInfo.count | integer | 이 페이지의 실제 항목 수. |
| pageInfo.totalCount | integer | 필터링 후 전체 항목 수. |
{
"code": 200,
"content": {
"data": [
{
"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",
"pageInfo": {
"pageIndex": 1,
"pageSize": 100,
"count": 1,
"totalCount": 1
}
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반했습니다 | 파라미터 파싱 실패 | Query 파라미터 표와 예시를 확인하십시오. |
| 500 | ft.InternalServerError | 규칙 읽기 또는 응답 형식 지정 실패 | 내부 오류 | 워크스페이스와 UUID를 확인하고, 계속 실패하면 traceId를 제공하십시오. |
| 403 | ft.Forbidden | API Key 권한이 부족하거나 워크스페이스 버전에서 이 기능을 지원하지 않습니다 | 작업 권한이 없습니다 | 해당 권한이 있는 API Key와 메트릭 생성을 지원하는 워크스페이스를 사용하십시오. |