기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 프레임워크 작성자를 위한 이미지 최적화 통합
<a name="integrate-image-optimization-framework"></a>

프레임워크 작성자는 Amplify Hosting 배포 사양을 참조하여 Amplify의 이미지 최적화 기능을 통합할 수 있습니다. 이미지 최적화를 활성화하려면 배포 매니페스트에 이미지 최적화 서비스를 대상으로 지정하는 라우팅 규칙이 포함되어야 합니다. 다음 예시에서는 라우팅 규칙을 구성하는 방법을 보여줍니다.

```
// .amplify-hosting/deploy-manifest.json
 
{
  "routes": [
    {
      "path": "/images/*",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=31536000, immutable"
      }
    }
  ]
}
```

배포 사양을 참조하여 이미지 최적화 설정을 구성하는 방법에 대한 자세한 내용은 [Amplify Hosting 배포 사양을 참조하여 빌드 출력 구성](ssr-deployment-specification.md) 섹션을 참조하세요.

## 이미지 최적화 API 이해
<a name="understand-image-optimization-api"></a>

라우팅 규칙에 따라 정의된 경로에서 Amplify 앱의 도메인 URL을 통해 런타임에 이미지 최적화를 간접적으로 호출할 수 있습니다.

```
GET https://{appDomainName}/{path}?{queryParams}
```

이미지 최적화에서는 이미지에 다음과 같은 규칙이 적용됩니다.
+ Amplify는 GIF, APNG 및 SVG 형식을 최적화하거나 다른 형식으로 변환할 수 없습니다.
+ `dangerouslyAllowSVG` 설정을 활성화하지 않으면 SVG 이미지가 제공되지 않습니다.
+ 소스 이미지의 너비 또는 높이는 11MB 또는 9,000픽셀을 초과할 수 없습니다.
+ 최적화된 이미지의 크기 제한은 4MB입니다.
+ 원격 URL에서 이미지를 가져올 때 지원되는 프로토콜은 HTTPS뿐입니다.

### HTTP 헤더
<a name="http-headers"></a>

**Accept** 요청 HTTP 헤더는 클라이언트(일반적으로 웹 브라우저)에서 허용되는 이미지 형식(MIME 유형으로 표시됨)을 지정하는 데 사용합니다. 이미지 최적화 서비스에서는 이미지를 지정된 형식으로 변환하려고 시도합니다. 이 헤더에 지정된 값은 형식 쿼리 파라미터보다 우선순위가 높습니다. 예를 들면 **Accept** 헤더의 유효한 값은 `image/png, image/webp, */* `입니다. Amplify 배포 매니페스트에 지정된 형식 설정을 통해 목록에 있는 형식으로 제한됩니다. **Accept** 헤더가 특정 형식을 요청하더라도 해당 형식이 허용 목록에 없으면 요청이 무시됩니다.

### URI 요청 파라미터
<a name="uri-request-parameters"></a>

다음 테이블에서는 이미지 최적화의 URI 요청 파라미터를 설명합니다.


| 쿼리 파라미터 | Type | 필수 | 설명 | 예제 | 
| --- | --- | --- | --- | --- | 
|  url  |  문자열  |  예  |  소스 이미지에 대한 상대 경로 또는 절대 URL입니다. 원격 URL에는 https 프로토콜만 지원됩니다. 값은 URL로 인코딩해야 합니다.  |  `?url=https%3A%2F%2Fwww.example.com%2Fbuffalo.png`  | 
|  width  |  숫자  |  예  |  최적화된 이미지의 너비입니다(픽셀).  |  `?width=800`  | 
|  height  |  숫자  |  아니요  |  최적화된 이미지의 높이입니다(픽셀). 지정하지 않으면 이미지가 너비에 일치하도록 자동으로 규모가 조정됩니다.  |  `?height=600`  | 
|  fit  |  열거형 값: `cover`, `contain`, `fill`, `inside`, `outside`   |  아니요  |  지정된 너비와 높이에 알맞게 이미지 크기가 조정되는 방식입니다.  |  `?width=800&height=600&fit=cover`  | 
|  position  |  열거형 값: `center`, `top`, `right`, `bottom`, `left`   |  아니요  |  배치가 `cover` 또는 `contain`일 때 사용되는 위치입니다.  |  `?fit=contain&position=centre`  | 
|  trim  |  숫자  |  아니요  |  왼쪽 위 픽셀의 지정된 배경색과 비슷한 값이 있는 모든 가장자리에서 픽셀을 잘라냅니다.  |  `?trim=50`  | 
|  확장  |  객체  |  아니요  |  가장 가까운 가장자리 픽셀에서 나온 색상을 사용하여 이미지 가장자리에 픽셀을 추가합니다. 형식은 `{top}_{right}_{bottom}_{left}`이며 여기서 각 값은 추가할 픽셀의 수입니다.  |  `?extend=10_0_5_0`  | 
|  extract  |  객체  |  아니요  |  위쪽, 왼쪽, 너비 및 높이로 구분된 지정된 직사각형으로 이미지를 자릅니다. 형식은 \$1left\$1\$1\$1top\$1\$1\$1width\$1\$1\$1right\$1이며 여기서 각 값은 잘라낼 픽셀의 수입니다.  |  `?extract=10_0_5_0`  | 
|  형식  |  문자열  |  No  |  최적화된 이미지에 바람직한 출력 형식입니다.  |  `?format=webp`  | 
|  quality  |  숫자  |  아니요  |  이미지 품질입니다(1\$1100). 이미지 형식을 변환할 때만 사용합니다.  |  `?quality=50`  | 
|  rotate  |  숫자  |  아니요  |  지정된 각도(도)만큼 이미지를 회전합니다.  |  `?rotate=45`  | 
|  flip  |  부울  |  아니요  |  이미지를 x축에서 세로(위-아래)로 미러링합니다. 회전이 있는 경우 항상 회전 전에 발생합니다.  |  `?flip`  | 
|  flop  |  부울  |  아니요  |  이미지를 y축에서 가로(왼쪽-오른쪽)로 미러링합니다. 회전이 있는 경우 항상 회전 전에 발생합니다.  |  `?flop`  | 
|  sharpen  |  숫자  |  아니요  |  선명하게 하면 이미지 가장자리의 선명도가 향상됩니다. 유효한 값은 0.000001\$110입니다.  |  `?sharpen=1`  | 
|  median  |  숫자  |  아니요  |  중앙값 필터를 적용합니다. 그러면 노이즈가 제거되거나 이미지 가장자리가 부드러워집니다.  |  `?sharpen=3`  | 
|  blur  |  숫자  |  아니요  |  지정된 시그마의 가우스 블러를 적용합니다. 유효한 값은 0.3\$11,000입니다.  |  `?blur=20`  | 
|  gamma  |  숫자  |  아니요  |  크기가 조정된 이미지에서 인식되는 밝기를 개선하려면 감마 보정을 적용합니다. 값은 1.0\$13.0이어야 합니다.  |  `?gamma=1`  | 
|  negate  |  부울  |  아니요  |  이미지의 색상을 반전합니다.  |  `?negate`  | 
|  normalize  |  부울  |  아니요  |  전체 동적 범위를 포괄하도록 휘도를 늘려 이미지 대비를 개선합니다.  |  `?normalize`  | 
|  threshold  |  숫자  |  아니요  |  지정된 임계값보다 강도가 낮으면 이미지의 모든 픽셀을 검은색 픽셀로 대체합니다. 또는 임계값보다 높으면 흰색 픽셀로 대체합니다. 유효한 값은 0\$1255입니다.  |  `?threshold=155`  | 
|  tint  |  문자열  |  No  |  이미지 휘도를 유지하면서 제공된 RGB를 사용하여 이미지에 색조를 추가합니다.  |  `?tint=#7743CE`  | 
|  grayscale  |  부울  |  아니요  |  이미지를 회색조(흑백)로 전환합니다.  |  `?grayscale`  | 

### 응답 상태 코드
<a name="response-status-codes"></a>

다음 목록에서는 이미지 최적화의 응답 상태 코드를 설명합니다.

**Success - HTTP 상태 코드 200**  
요청이 이행되었습니다.

**BadRequest - HTTP 상태 코드 400**  
+ 입력 쿼리 파라미터가 잘못 지정되었습니다.
+ 원격 URL이 `remotePatterns` 설정에 허용된 대로 나열되어 있지 않습니다.
+ 원격 URL이 이미지로 확인되지 않습니다.
+ 요청된 너비 또는 높이가 `sizes` 설정에 허용된 대로 나열되어 있지 않습니다.
+ 요청된 이미지가 SVG인데 `dangerouslyAllowSvg` 설정이 비활성화되어 있습니다.

**Not Found - HTTP 상태 코드 404**  
소스 이미지를 찾을 수 없습니다.

**Content too large - HTTP 상태 코드 413**  
소스 이미지 또는 최적화된 이미지가 허용된 최대 크기(바이트)를 초과합니다.

### 최적화된 이미지 캐싱 이해
<a name="image-optimization-caching"></a>

Amplify Hosting에서는 동일한 쿼리 파라미터를 통해 동일한 이미지에 대한 후속 요청이 캐시에서 제공되도록 CDN에 최적화된 이미지를 캐시합니다. 캐시 TTL(Time To Live)은 `Cache-Control` 헤더에 따라 제어됩니다. 다음 목록에서는 `Cache-Control` 헤더 지정 옵션을 설명합니다.
+ 이미지 최적화를 대상으로 지정하는 라우팅 규칙 내에서 `Cache-Control` 키를 사용합니다.
+ Amplify 앱에 정의된 사용자 지정 헤더를 사용합니다.
+ 원격 이미지의 경우 원격 이미지에서 반환된 `Cache-Control` 헤더가 적용됩니다.

이미지 최적화 설정에 지정된 `minimumCacheTTL`에서는 Cache-Control max-age 지시문의 하한을 정의합니다. 예를 들어 원격 이미지 URL에서는 `Cache-Control s-max-age=10`으로 응답하는데 `minimumCacheTTL` 값이 60이면 60이 사용됩니다.