콘텐츠로 이동

시계열 추세 그래프 가져오기



GET /api/v1/chart_image/get

개요

Client Token으로 DQL 또는 PromQL 시계열 쿼리를 실행하고 PNG 추세 그래프를 직접 다운로드합니다.

호출 전 및 사용 단계

이 API는 Client Token으로 워크스페이스를 식별하며 DF-API-KEY 또는 로그인 Token이 필요하지 않습니다. URL의 Token은 안전하게 보관하고 공개 페이지나 공유 링크에 기록하지 마세요. 데이터 액세스 주체는 워크스페이스 API Key와 다르므로 API Key의 역할 권한으로 이 API의 액세스 제어를 추론할 수 없습니다. 먼저 대상 워크스페이스에서 시계열 쿼리 문을 검증하고, 사이트 제한을 초과하지 않는 실제 데이터 시간 범위를 선택한 다음, 쿼리 파라미터를 URL 인코딩하고 이미지를 다운로드하세요. 예시 시간은 참고용일 뿐이며 호출 전에 데이터가 있는 시간 범위로 교체해야 합니다.

응답이 성공하면 원시 PNG 바이너리이며 code/content/success/traceId 등의 JSON 비즈니스 필드가 없습니다. 오류 시 JSON이 반환될 수 있으므로 클라이언트는 HTTP 상태, Content-Type 및 PNG 파일 시그니처를 함께 확인해야 하며, 임의의 200 응답을 유효한 이미지로 저장해서는 안 됩니다. 차트 그리기에 실패하면 서버 로그가 기록되지만 HTTP 200, image/png 및 빈 본문이 반환될 수 있습니다. 데이터가 비어 있어도 빈 좌표 차트가 반환될 수 있으며 이는 요청 실패를 의미하지 않습니다. 빈 본문인 경우 먼저 쿼리 문, 시간대 및 실제 데이터를 확인하고 응답 헤더의 추적 정보를 보존하여 관리자에게 전달하세요.

파라미터 표의 Query만 지원합니다. 내부적으로 showLegend 읽기가 존재하지만 공개 선언에 포함되지 않았으므로 해당 파라미터를 제출할 수 없습니다. 기본적으로 범례는 표시되지 않습니다. 결과는 캐시되지 않으며 응답에는 no-store가 설정됩니다. Token 정보는 이 프로세스가 의존하는 Redis에 60초 동안 캐시되므로, 취소 후에도 짧은 캐시 윈도우가 남을 수 있으며 즉시 무효화를 보장하지 않습니다.

Query 요청 파라미터

파라미터 이름 타입 필수 설명
clientToken string Y 필수입니다. 유효 상태가 0인 Client Token만 쿼리합니다. 앞뒤 공백은 제거됩니다. Token은 쿼리 워크스페이스를 결정합니다.
null 허용: False
예시: <CLIENT-TOKEN>
가져오기 또는 입력 방법: 현재 워크스페이스의 Client Token 관리에서 실제 Token 값을 복사합니다. token 레코드 UUID나 API Key가 아닙니다.
endTime integer Y 필수 정수입니다. 10자리 초 값은 밀리초로 변환하고 나머지는 밀리초로 간주합니다. 0이면 서버 현재 시간을 사용합니다. 최대 범위는 사이트의 ChartImageSet.maxTimeSc 제약을 받으며 코드 기본값은 3600초이고 관리자가 재정의할 수 있습니다.
null 허용: False
예시: 1785429000
가져오기 또는 입력 방법: 쿼리 종료 지점을 선택하며 startTime보다 크거나 같아야 하고 동일한 단위를 사용해야 합니다.
interval integer 선택 사항이며 기본값은 60초입니다. 내부적으로 1000을 곱해 쿼리 간격으로 사용합니다. 0이면 범위와 사이트 포인트 밀도에 따라 계산하며 최소 1밀리초입니다. 음수는 406입니다. 실제 포인트 수는 쿼리 서비스와 포인트 밀도의 제한도 받으므로 모든 포인트에 데이터가 있음을 보장하지 않습니다.
null 허용: False
예시: 60
가져오기 또는 입력 방법: 이미지에 필요한 세분성에 따라 양의 정수 초를 선택합니다. 자동 추정을 사용하려면 0을 전달합니다.
q string Y 필수 쿼리 문입니다. 시간과 값을 포함하는 시계열을 반환해야 합니다. DQL과 PromQL 구문은 함께 사용할 수 없습니다. Tag별 그룹화는 여러 라인을 생성할 수 있습니다.
null 허용: False
예시: M::cpu:(avg(usage_idle)) BY host
가져오기 또는 입력 방법: 대상 워크스페이스의 쿼리 도구에서 데이터가 있는 시계열 쿼리를 확인한 다음 Query를 URL 인코딩합니다.
qtype string 선택 사항이며 dql/promql입니다. 다운스트림의 기본값 처리에 의존하지 않도록 항상 명시적으로 전달하는 것이 좋습니다. 라우트에는 기본값이 구성되어 있지 않으므로 생략하면 쿼리 서비스에 None이 전달됩니다.
null 허용: False
선택 가능 값: ['dql', 'promql']
예시: dql
가져오기 또는 입력 방법: 쿼리 문 유형에 따라 dql 또는 promql을 명시적으로 선택합니다. DQL 및 PromQL을 참고하세요.
startTime integer Y 필수 정수입니다. 10자리 값은 내부적으로 1000을 곱하고, 다른 자릿수는 밀리초로 직접 사용합니다. 자릿수 판단에 의존하지 않도록 초 단위로 통일해 전달하는 것이 좋습니다. 0이면 endTime에서 1시간을 뺀 값으로 대체하며 Unix 에포크가 아닙니다.
null 허용: False
예시: 1785427200
가져오기 또는 입력 방법: 실제 데이터가 존재하는 쿼리 시작 지점을 Unix 초 타임스탬프로 선택합니다.
tz string 선택 사항이며 기본값은 Asia/Shanghai입니다. 쿼리 정렬과 이미지 가로축 표시를 제어하며 Unix 타임스탬프의 의미는 변경하지 않습니다. 시간대 열거형 검증은 없으며 잘못된 이름은 다운스트림 쿼리를 실패하게 하거나 이미지를 비게 만들 수 있습니다.
null 허용: False
예시: Asia/Shanghai
가져오기 또는 입력 방법: 비즈니스 표시 시간대에 따라 IANA 시간대 이름을 선택합니다.

파라미터 추가 설명

쿼리 설명

참고: 현재 API는 clientToken으로 인증합니다. clientToken이 유효할 때만 동작합니다. 현재 API는 요청 헤더 DF-API-KEY를 추가하지 않아도 됩니다.

요청 예시

curl --get 'https://openapi.guance.com/api/v1/chart_image/get' \
  --data-urlencode 'clientToken=<CLIENT-TOKEN>' \
  --data-urlencode qtype=dql \
  --data-urlencode 'q=M::cpu:(avg(usage_idle)) BY host' \
  --data-urlencode startTime=1785427200 \
  --data-urlencode endTime=1785429000 \
  --data-urlencode interval=60 \
  --data-urlencode tz=Asia/Shanghai \
  --output chart.png

응답

HTTP 200은 원시 PNG 이미지 스트림입니다. 오류는 일반적으로 JSON이며, 차트 그리기 실패 시에도 200과 빈 본문이 반환될 수 있으므로 상태/유형/파일 시그니처를 반드시 확인해야 합니다.

응답 헤더 타입 설명
Content-Type string 성공 시 image/png이며, 비정상 시 실제 JSON 또는 프록시 응답 유형에 따라 처리합니다.
Cache-Control string 성공 시 no-store, max-age=0이며 이미지 응답을 캐시하지 않습니다.
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: no-store, max-age=0

<PNG 바이너리, 파일 헤더 16진수는 89 50 4e 47 0d 0a 1a 0a>

오류 응답

이 엔드포인트는 requireSignIn=false이며 DF-API-KEY 인증/역할 오류를 적용하지 않습니다. 요청 검증은 여전히 적용됩니다. 쿼리 서비스는 쿼리 문, 데이터 소스, 용량 또는 네트워크와 관련된 동적 오류를 반환할 수 있으며 HTTP 및 오류 코드는 실제 응답을 기준으로 합니다. 차트 그리기 오류는 200과 빈 PNG 본문만 반환될 수 있으며 항상 JSON 오류가 있음을 보장하지 않습니다.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드 누락, 또는 필드 값이 선언된 검증 조건 위반 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다.
406 ft.DqlParseError DQL 문 구문 또는 구문 분석 구조가 유효하지 않음 dql parser 파싱 실패: {} 먼저 쿼리 도구에서 문을 검증하고 올바르게 URL 인코딩한 뒤 실제 파싱 원인을 보존합니다.
406 ft.NotSupportedByGroupQuery BY index 그룹화 사용 index 필드를 by 그룹화 쿼리에 사용하는 것은 지원되지 않음 index 그룹화 필드를 제거하고 실제 비즈니스 Tag 그룹화로 변경합니다.
503 ft.QueryServiceUnavailable 쿼리 업스트림 HTTP 503이 통합 매핑됨 쿼리 서비스가 일시적으로 사용할 수 없습니다. 나중에 다시 시도하세요 오류 본문 content.retryable을 확인하고 백오프 후 재시도하며 빈번한 재시도를 피합니다.
404 ft.ClientTokenNotExistOrDelete Client Token 공백 제거 후 비어 있음, 또는 캐시 미스이며 유효한 Token 레코드가 없음 지정한 Client Token이 존재하지 않거나 삭제됨 실제 Token 값과 대상 사이트를 확인하고 유효한 Token을 사용하며 레코드 UUID로 대체해서는 안 됩니다.
400 ft.IllegalStartOrEndTime 종료 지점이 시작 지점보다 이르거나, 범위가 사이트 최대값을 초과 잘못된 시작/종료 타임스탬프 동일한 단위의 타임스탬프를 사용하고 허용 범위로 줄입니다.
406 ft.InvalidParameter interval이 0보다 작음 파라미터 interval이 유효하지 않음 양의 정수 초 또는 0(자동 추정)으로 변경합니다.
500 ft.InternalServerError 캐시/데이터베이스 사용 불가, 반환 데이터 구조 이상 또는 기타 처리되지 않은 오류 내부 오류 반환된 Content-Type과 본문을 확인하고 traceId를 보존하여 관리자에게 문의하세요. 오류 JSON을 PNG로 처리하지 마세요.

문서 평가

이 페이지가 도움이 되었나요?