Query String 작성 가이드

Classic/VPC 환경에서 이용 가능합니다.

섬네일 호출 URL 생성 방법

• 오브젝트 스토리지 연동 시: CDN 도메인 + 오브젝트 스토리지 내 파일 경로 + 섬네일 생성 옵션 조합으로 생성합니다.
  • 형식: https://{CDN-DOMAIN}/{FILE-PATH-IN-OBJSTORAGE}?{QUERYSTRINGS}
  • 예시: https://abc123xyz.cdn.ntruss.com/a/b.jpg?type=h_wm&h=780&quality=90&autorotate=true

• HTTP URL 연동 시: CDN 도메인 + 외부 URL + 섬네일 생성 옵션 조합으로 생성합니다.
  • 형식: https://{CDN-DOMAIN}?src="{외부이미지URL}"&{QUERYSTRINGS}
  • 예시: https://abc123xyz.cdn.ntruss.com?src="{외부 이미지 URL}"&type=h_wm&h=780&quality=90&autorotate=true

Image Optimizer가 지원하는 섬네일 생성 옵션들은 Query String을 사용하여 생성됩니다.
섬네일 생성 결과는 Query String의 파라미터(옵션) 순서에 영향을 받지 않습니다.
단, 실행 결과 동일한 섬네일을 만드는 Query String이라도 파라미터 기본값의 설정 여부에 따라 새로운 변환 요청으로 인식하여 변환 횟수가 가산될 수 있으니 주의해 주십시오. 예를 들어 /a.jpg?type=f&w=40&h=40과 /a.jpg?type=f&w=40&h=40&quality=90은 완전히 동일한 섬네일을 생성하지만 개별적으로 과금될 수 있습니다.

Query String 설명

Query String을 구성하는 옵션은 크게 type 파라미터 종속 옵션과​​​ 모든 type에 공통적으로 적용될 수 있는 전역 옵션으로 나눌 수 있습니다.​

전역 옵션

• quality: 원본 이미지가 JPEG 형식인 경우에만 해당되며 1~100 범위의 정수로 설정(기본값: 90)
• autorotate: 문자열 true/false로 설정하며 EXIF 회전 정보를 토대로 결과 섬네일을 자동 회전(기본값: true)
• anilimit: GIF 형식에 여러 장의 프레임이 존재할 경우 일정 프레임 이후는 제거. 앞에서부터 노출될 프레임 개수 1~100(기본값: 1)
• ttype: 섬네일의 포맷 타입 설정(jpg, gif, png), 설정하지 않는 경우 원본 포맷과 동일
• src
  • 썸네일을 생성하기 위한 원본이 되는 외부 이미지 URL 정보를 입력
  • URL 내 ?, & 와 같은 구분자가 존재하는 경우 %22 (") 로 URL을 감싸서 URL 퍼센트 인코딩 하여 입력
  • "가 없으면 decode 되지 않으며 "로 감싸진 URL은 1번 decode가 됨
  • 이미지 파일크기는 30MB로 제한되며 HTTP Redirect는 1번까지 허용

type 파라미터와 종속 옵션

크기

• 리사이즈 및 크롭(type=f): 원본 비율을 유지하면서 이미지 크기를 축소 또는 확대한 후 남는 영역 크롭

  • w: 가로 길이, 1 이상의 정수, 필수 입력
  • h: 세로 길이, 1 이상의 정수, 필수 입력
     - align: 크롭하여 남길 위치, 9분할 위치, 0~8, 기본값 4(중앙)
  • faceopt: 얼굴 인식 적용 여부, 문자열 true/false, 기본값 "false"

• 리사이즈(type=m): 설정한 가로, 세로 크기 안에 들어오도록 이미지 크기 변경

  • w: 가로 길이, 1 이상의 정수, 필수 입력
  • h: 세로 길이, 1 이상의 정수, 필수 입력
  • bgcolor: 위아래 혹은 양옆에 넣고자 하는 색상, 존재하지 않는 경우 가로나 세로 값이 무시됨.(16진수 RGB 색상값, 문자열 6자)
  • extopt: 섬네일이 원본보다 작은 경우 확대할지에 대한 여부, 정수 3인 경우 확대, 기본값 0(원본 크기 유지)

• 가로 변환(type=w): 원본 비율을 유지하면서 가로 길이를 기준으로 이미지 크기 변경

  • w: 가로 길이, 1 이상의 정수, 필수 입력
  • extopt: 섬네일이 원본보다 작은 경우 확대할지에 대한 여부, 정수 3인 경우 확대, 기본값 0(원본 크기 유지)

• 세로 변환(type=h): 원본 비율을 유지하면서 세로 길이를 기준으로 이미지 크기 변경

  • h: 세로 길이, 1 이상의 정수, 필수 입력

• 강제 변환(type=u): 원본 비율을 무시하고 원하는 사이즈로 강제 변경

  • w: 가로 길이, 1 이상의 정수, 필수 입력
  • h: 세로 길이, 1 이상의 정수, 필수 입력

워터마크

• 워터마크(type=wm)
  • wm_path: 워터마크로 찍을 이미지 URL(HTTP 포함 필수). 워터마크 이미지가 기본 이미지보다 작아야 함.
  • wm_align: 워터마크 위치를 지정할 때 기준점. 각 9분할 영역의 왼쪽 위 지점. 0~8, 기본값 4.
  • wm_offx: 기준점에서 오른쪽으로 떨어진 거리. 0 이상의 정수, 기본값 0.
  • wm_offy: 기준점으로 아래로 떨어진 거리. 0 이상의 정수, 기본값 0.

필터

• Sharpen(type=sh): 이미지를 선명하게 보여주는 효과

  • sharp_amt: 윤곽선의 밝기 대비를 주는 정도, 필수 입력

• Blur(type=bl): 이미지를 흐릿하게 만드는 효과

  • blur_rad: 효과를 적용하기 위한 마스크 사이즈(픽셀 반경)
  • blur_sig: 블러 마스크 내에서 적용시킬 분산의 정도, 필수 입력

• Black & White(type=bw): 이미지의 색상을 흑백으로 변경

다중 type 파라미터

크기, 워터마크, 필터는 구분자인 _를 기준으로 첫 번째부터 차례대로 적용됩니다.
예: f_wm(리사이즈 및 크롭 처리 후 워터마크 적용), bw_wm(흑백 처리 후 워터마크 적용)

예제

• 리사이즈 및 크롭

  • 가로 100, 세로 100으로 줄인 후 넘치는 부분은 크롭
  • /파일명.jpg?type=f&w=100&h=100

• 리사이즈

  • 회전 정보가 있을 경우 회전하고 "가로 320, 세로 320" 프레임 안에 들어가도록 비율 유지 축소, 여백을 FFFFFA 색상으로 채우고 JPGE quality 95로 압축
  • /파일명.jpg?type=m&w=320&h=320&autorotate=true&bgcolor=FFFFFA&quality=95

• 리사이즈 후 워터마크

  • 원본이 섬네일보다 작은 경우 확대, 512x1024로 축소하거나 확대한 후, 여백을 000011 색상으로 채움
  • 그 후 특정 이미지 URL을 이용하여 우측 상단을 기준 가로 11픽셀, 세로 10픽셀 이동하여 워터마크를 찍음
  • GIF 애니메이션인 경우 최대 100장에 대해 같은 작업 수행
  • /파일명.jpg?type=m_wm&w=512&h=1024&bgcolor=000011&wm_path=http://watermark_URL&wm_offx=11&wm_offy=10&wm_align=2&anilimit=100&extopt=3​

• 리사이즈 후 sharpen 필터 적용, 이미지 포맷을 png로 변경

  • /파일명.jgp?m_sh&w=512&h=256&ttype=png