SLS에서 DQL로 변환¶
POST /api/v1/sls/convert
개요¶
Alibaba Cloud SLS 쿼리문을 로그 DQL로 변환하며, 워크스페이스의 데이터를 쿼리하지 않습니다.
호출 전 및 사용 단계¶
- Alibaba Cloud SLS 쿼리에서 쿼리 표현식을 복사합니다. 결과에 사용할 로그 인덱스를 제한해야 하는 경우, 먼저 현재 워크스페이스의 로그 인덱스 목록을 확인합니다.
- 변환 요청을 보냅니다. 이 API는 워크스페이스에서 쿼리를 실행하지 않습니다.
- status와 diagnostics를 확인합니다. 근사 변환은 차이를 수동으로 확인해야 하며, 확인 후 dql을 DQL 쿼리 API에 전달합니다.
예를 들어 query가 「* | SHOW TABLES」인 경우 unsupported가 반환될 수 있습니다. 이때 diagnostics를 기준으로 수동 조정이 필요한 부분을 판단합니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | AK 식별자, AK uuid 예시: <DF-API-KEY>확인 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 이 API 권한을 가진 Key를 생성하거나 획득합니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| query | string | Y | Alibaba Cloud SLS 쿼리문 null 허용: False 빈 문자열 허용: False 예시: status:200확인 또는 입력 방법: SLS 쿼리문에서 변환할 부분을 복사하며, JSON 문자열에는 큰따옴표를 사용합니다. |
| indexes | array | 선택 사항이며, 로그 인덱스 이름 목록입니다. 전달하지 않거나 빈 배열을 전달하면 인덱스를 제한하지 않습니다. null 허용: False 예시: ["default"]확인 또는 입력 방법: 존재하는 로그 인덱스 이름 배열을 입력합니다. 로그 인덱스 목록에서 반환된 content.data[*].name 값을 사용합니다. |
파라미터 추가 설명¶
반환된 status는 변환의 동등성 수준을 나타냅니다:
exact: 생성된 DQL이 원본 SLS 쿼리와 동등합니다.approximate: 근사 DQL이 생성되었으며, 호출자는diagnostics와 함께 차이를 확인한 후 실행해야 합니다.unsupported: 현재 SLS 구문을 지원하지 않으며dql이 비어 있을 수 있습니다.
Studio는 로그 네임스페이스 L을 고정적으로 사용합니다. indexes는 선택 사항이며, 전달하지 않거나 빈 배열을 전달하면 인덱스 제한을 추가하지 않습니다.
요청 예시¶
curl 'https://openapi.guance.com/api/v1/sls/convert' \
-H 'Content-Type: application/json' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-raw '{"query":"status:200","indexes":["default"]}'
응답¶
HTTP 200, application/json. 예시는 요청의 status:200 및 default 인덱스 조건을 유지합니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.status | string | 변환 결과입니다. exact는 정확한 변환, approximate는 근사 변환, unsupported는 지원되지 않음을 의미합니다. |
| content.dql | string | 변환된 DQL입니다. 상태가 unsupported이면 비어 있거나 생략될 수 있습니다. |
| content.diagnostics | array | 변환 진단입니다. 정확한 변환이고 진단이 없으면 []이며, 그 외 결과는 변환기가 실제 반환한 값을 따릅니다. |
| content.diagnostics[].severity | string | 진단 심각도입니다. 예: warning 또는 error. |
| content.diagnostics[].code | string | 진단 식별자입니다. |
| content.diagnostics[].message | string | 진단 설명입니다. |
| content.diagnostics[].hint | string | 선택적 수정 힌트입니다. |
| content.unsupported_class | string | 선택 사항입니다. 변환이 지원되지 않을 때의 분류입니다. |
{
"code": 200,
"content": {
"status": "exact",
"dql": "L(\"default\")::*:(*){ (`status` = 200) }",
"diagnostics": []
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 파라미터가 필드 선언을 위반함 | 메시지에 유효하지 않은 필드 또는 규칙이 표시됩니다. | 해당 파라미터 표에 따라 요청을 수정합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문 오류 | 요청 JSON 형식이 잘못되었습니다. content에는 reason, line, column이 포함됩니다. | JSON 구문을 수정한 후 다시 시도합니다. |
| 406 | ft.DqlParseError | 변환기를 사용할 수 없거나 parser 호출 시 ParserError가 발생함 | DQL parser 파싱에 실패했으며 메시지에 원인이 포함되어 있습니다. | 먼저 구문을 확인하고, 변환기를 사용할 수 없으면 서비스 관리자에게 문의합니다. |
| 406 | ft.ParameterCheckFailed | query에서 앞뒤 공백을 제거한 후 비어 있거나 indexes 멤버가 문자열이 아님 | 일반 파라미터 검증 실패 문구를 반환합니다. | 비어 있지 않은 SLS 문 및 문자열 인덱스 배열을 사용합니다. |