本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 架構作者的影像最佳化整合
<a name="integrate-image-optimization-framework"></a>

架構作者可以使用 Amplify 託管部署規格來整合 Amplify 的映像最佳化功能。若要啟用映像最佳化，您的部署資訊清單必須包含以映像最佳化服務為目標的路由規則。下列範例示範如何設定路由規則。

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

如需使用部署規格設定映像最佳化設定的詳細資訊，請參閱 [使用 Amplify 託管部署規格來設定建置輸出](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 影像。
+ 來源影像的寬度或高度不能超過 11 MB 或 9，000 像素。
+ 最佳化映像的大小限制為 4 MB。
+ HTTPS 是唯一支援使用遠端 URLs通訊協定。

### HTTP 標頭
<a name="http-headers"></a>

**Accept** 請求 HTTP 標頭用於指定用戶端 （通常是 Web 瀏覽器） 允許的影像格式，以 MIME 類型表示。映像最佳化服務會嘗試將映像轉換為指定的格式。為此標頭指定的值具有比格式查詢參數更高的優先順序。例如，**接受**標頭的有效值為 `image/png, image/webp, */* `。Amplify 部署資訊清單中指定的格式設定會將格式限制為清單中的格式。即使**接受**標頭要求特定格式，如果格式不在允許清單中，也會忽略它。

### URI 請求參數
<a name="uri-request-parameters"></a>

下表說明映像最佳化的 URI 請求參數。


| 查詢參數 | Type | 必要 | Description | 範例 | 
| --- | --- | --- | --- | --- | 
|  url  |  String  |  是  |  來源映像的相對路徑或絕對 URL。對於遠端 URL，僅支援 https 通訊協定。值必須為 URL 編碼。  |  `?url=https%3A%2F%2Fwww.example.com%2Fbuffalo.png`  | 
|  width  |  Number  |  是  |  最佳化影像的寬度，以像素為單位。  |  `?width=800`  | 
|  height  |  Number  |  否  |  最佳化影像的像素高度。如果未指定，影像將自動縮放以符合寬度。  |  `?height=600`  | 
|  適合  |  列舉值：`cover`、`contain`、`fill`、`inside`、 `outside`  |  否  |  如何調整影像大小以符合指定的寬度和高度。  |  `?width=800&height=600&fit=cover`  | 
|  position  |  列舉值：`center`、`top`、`right`、`bottom`、 `left`  |  否  |  適合時要使用的位置為 `cover`或 `contain`。  |  `?fit=contain&position=centre`  | 
|  trim  |  Number  |  否  |  從包含與左上角像素指定背景顏色類似之值的所有邊緣修剪像素。  |  `?trim=50`  | 
|  擴充  |  物件  |  否  |  使用從最接近的邊緣像素衍生的顏色，將像素新增至影像邊緣。格式為 `{top}_{right}_{bottom}_{left}` ，其中每個值為要新增的像素數。  |  `?extend=10_0_5_0`  | 
|  擷取  |  物件  |  否  |  裁切影像至以頂端、左側、寬度和高度分隔的指定矩形。格式為 \$1left\$1\$1\$1top\$1\$1\$1width\$1\$1\$1right\$1，其中每個值都是要裁切的像素數。  |  `?extract=10_0_5_0`  | 
|  格式  |  String  |  否  |  最佳化映像所需的輸出格式。  |  `?format=webp`  | 
|  quality  |  Number  |  否  |  影像的品質，從 1 到 100。僅在轉換映像的格式時使用。  |  `?quality=50`  | 
|  rotate  |  Number  |  否  |  依指定的角度旋轉影像，以度為單位。  |  `?rotate=45`  | 
|  翻轉  |  Boolean  |  否  |  在 x 軸上垂直 （向上） 鏡射影像。這一律會在輪換之前發生，如果有的話。  |  `?flip`  | 
|  flop  |  Boolean  |  否  |  在 y 軸上水平鏡射影像 （左-右）。這一律會在輪換之前發生，如果有的話。  |  `?flop`  | 
|  銳化  |  Number  |  否  |  銳化可增強影像中邊緣的定義。有效值介於 0.000001 和 10 之間。  |  `?sharpen=1`  | 
|  median  |  Number  |  否  |  套用中位數篩選條件。這可消除雜訊或平滑影像的邊緣。  |  `?sharpen=3`  | 
|  模糊  |  Number  |  否  |  套用指定標準差的高斯模糊。有效值介於 0.3 到 1，000 之間。  |  `?blur=20`  | 
|  Gamma  |  Number  |  否  |  套用伽瑪校正，以改善調整大小影像的感知亮度。值必須介於 1.0 和 3.0 之間。  |  `?gamma=1`  | 
|  否定  |  Boolean  |  否  |  反轉影像的顏色。  |  `?negate`  | 
|  標準化  |  Boolean  |  否  |  透過擴展影像亮度以涵蓋完整的動態範圍來增強影像對比度。  |  `?normalize`  | 
|  threshold  |  Number  |  否  |  如果影像中的像素強度小於指定的閾值，則以黑色像素取代影像中的任何像素。或者，如果大於閾值，則使用白色像素。有效值介於 0 到 255 之間。  |  `?threshold=155`  | 
|  色調  |  String  |  否  |  使用提供的 RGB 調整影像，同時保留影像亮度。  |  `?tint=#7743CE`  | 
|  灰階  |  Boolean  |  否  |  將影像變成灰階 （黑色和白色）。  |  `?grayscale`  | 

### 回應狀態碼
<a name="response-status-codes"></a>

以下清單說明影像最佳化的回應狀態碼。

**成功 - HTTP 狀態碼 200**  
請求已成功完成。

**BadRequest - HTTP 狀態碼 400**  
+ 輸入查詢參數的指定不正確。
+ 遠端 URL 不會列為 `remotePatterns`設定中允許的 URL。
+ 遠端 URL 不會解析為映像。
+ 請求的寬度或高度不會在 `sizes`設定中列為允許。
+ 請求的映像是 SVG，但`dangerouslyAllowSvg`設定已停用。

**找不到 - HTTP 狀態碼 404**  
找不到來源映像。

**內容太大 - HTTP 狀態碼 413**  
來源映像或最佳化映像超過允許的位元組大小上限。

### 了解最佳化映像快取
<a name="image-optimization-caching"></a>

Amplify 託管會在 CDN 上快取最佳化映像，以便從快取提供對相同映像的後續請求與相同的查詢參數。快取存留時間 (TTL) 由 `Cache-Control`標頭控制。下列清單說明您指定 `Cache-Control`標頭的選項。
+ 在以影像最佳化為目標的路由規則內使用 `Cache-Control`金鑰。
+ 使用 Amplify 應用程式中定義的自訂標頭。
+ 對於遠端映像，系統會遵守遠端映像傳回的`Cache-Control`標頭。

映像最佳化設定中`minimumCacheTTL`指定的 會定義Cache-Control max-age指令的下限。例如，如果遠端映像 URL 以 回應`Cache-Control s-max-age=10`，但 的值`minimumCacheTTL`為 60，則會使用 60。