舊版套裝組合服務的 Images API

App Engine 透過專屬的「圖片」服務，提供操縱圖片資料的功能。「圖片」服務可操縱圖片、將多張圖片組合為單一圖片、轉換圖片格式、提供格式、寬度及高度等圖片中繼資料，以及色彩值的直方圖。

App Engine 上的 Java 8 支援 Java 的原生圖片操縱類別 (例如 AWT 和 Java2D) 及 App Engine Images API。

「圖片」服務可直接由應用程式接受圖片資料，或使用 Cloud Storage 值 (「圖片」服務也可使用 Cloud Blobstore 值，但建議您使用 Cloud Storage)。

儲存於 Cloud Storage 及 Cloud Blobstore 的圖片，上限為個別服務允許的最大值。轉換後圖片將直接傳回應用程式，且必須小於 32 MB。

Cloud Storage 值區必須使用精細的存取控制清單，才能讓 Images API 正常運作。如果已為值區設定統一的值區層級存取權，Images API 就無法擷取該值區中的圖片，並擲回錯誤訊息 TransformationError。如果您的值區是採用這種方式設定，您可以停用統一值區層級存取權。

在 Java 8 中轉換圖片

Image Service API 可讓您透過服務將轉換作業應用於圖片，而非在應用程式伺服器上進行圖片處理。應用程式準備一個包含要轉換之圖片資料的 Image 物件，以及一個包含如何轉換圖片的指示的 Transform 物件。應用程式會取得 ImagesService 物件，然後使用 Image 和 Transform 物件呼叫其 applyTransform() 方法。這個方法會傳回已轉換圖片的 Image 物件。

應用程式使用 ImagesServiceFactory 取得 ImagesService、Image 和 Transform 例項。

// Get an instance of the imagesService we can use to transform images.
ImagesService imagesService = ImagesServiceFactory.getImagesService();

// Make an image directly from a byte array, and transform it.
Image image = ImagesServiceFactory.makeImage(imageBytes);
Transform resize = ImagesServiceFactory.makeResize(100, 50);
Image resizedImage = imagesService.applyTransform(resize, image);

// Write the transformed image back to a Cloud Storage object.
gcsService.createOrReplace(
    new GcsFilename(bucket, "resizedImage.jpeg"),
    new GcsFileOptions.Builder().mimeType("image/jpeg").build(),
    ByteBuffer.wrap(resizedImage.getImageData()));

您可以使用 CompositeTransform 例項將多個轉換作業合併為單一動作。請參閱 Images API 參考資料。

可用的圖片轉換作業

「圖片」服務可以調整圖片大小、旋轉圖片、翻轉圖片、裁剪圖片以及修飾相片，也能將多個圖片合成單一圖片。

調整大小

您可以在維持相同顯示比例的情況下，調整圖片的大小。調整大小後的圖片，寬度或高度都不得超過 4000 像素。

旋轉

您可以將圖片以 90 度的倍數進行旋轉。

水平翻轉

您可以將圖片水平翻轉。

垂直翻轉

您可以將圖片垂直翻轉。

裁剪

您可以將圖片裁剪為指定的方塊。

好手氣

「好手氣」轉換功能可修飾及調整圖片的暗色及亮色，並最佳化對比。

圖片格式

此服務可以接受 JPEG、PNG、WEBP、GIF (包括動畫 GIF)、BMP、TIFF 及 ICO 格式的圖片資料，轉換後的圖片可利用 JPEG、WEBP 及 PNG 格式傳回。

如果輸入格式與輸出格式不同，此服務會先將輸入資料轉換成輸出格式，然後再執行轉換作業。

轉換圖片

「圖片」服務可使用 Google Cloud Storage 或 Blobstore 的值做為轉換的圖片來源。您可利用兩種方式轉換圖片：

1. 使用 ImagesServiceFactory() 類別可讓您執行簡單的圖片轉換作業，例如裁剪、翻轉及旋轉。
2. 使用 getServingUrl() 可讓您以動態方式調整圖片大小及裁剪圖片，因此您無需在伺服器上儲存不同大小的圖片。這個方法會傳回可提供圖片的網址，而圖片轉換作業將於此網址編碼。此函式假設圖片不會變更；如果圖片在您取得網址之後遭到修改，則使用該網址可能會產生意外結果。

使用 ImagesServiceFactory() 類別

如果圖片大小小於 Cloud Storage 或 Blobstore 允許的上限，您就可以轉換 Cloud Storage 或 Blobstore 中的圖片。請注意，轉換結果會直接傳回應用程式，且不得超過 32 MB 的 API 回應限制。

如要在 Java 8 中轉換 Cloud Storage 或 Blobstore 圖片，您可以透過呼叫 ImagesServiceFactory.makeImageFromBlob() 靜態方法建立 Image 物件，並傳遞 blobstore.BlobKey 值。API 的其餘部分會如預期運作。applyTransform() 方法會傳回轉換結果，如果結果大於 32 MB 的上限，則會傳回 ImagesServiceFailureException。

// Make an image from a Cloud Storage object, and transform it.
BlobstoreService blobstoreService = BlobstoreServiceFactory.getBlobstoreService();
BlobKey blobKey = blobstoreService.createGsBlobKey("/gs/" + bucket + "/image.jpeg");
Image blobImage = ImagesServiceFactory.makeImageFromBlob(blobKey);
Transform rotate = ImagesServiceFactory.makeRotate(90);
Image rotatedImage = imagesService.applyTransform(rotate, blobImage);

// Write the transformed image back to a Cloud Storage object.
gcsService.createOrReplace(
    new GcsFilename(bucket, "rotatedImage.jpeg"),
    new GcsFileOptions.Builder().mimeType("image/jpeg").build(),
    ByteBuffer.wrap(rotatedImage.getImageData()));

使用 getServingUrl()

getServingUrl() 方法可讓您針對儲存於 Cloud Storage 或 Blobstore 的圖片產生固定的專屬網址。例如：

// Create a fixed dedicated URL that points to the GCS hosted file
ServingUrlOptions options = ServingUrlOptions.Builder
        .withGoogleStorageFileName("/gs/" + bucket + "/image.jpeg")
        .imageSize(150)
        .crop(true)
        .secureUrl(true);
String url = imagesService.getServingUrl(options);

產生的網址會使用獨立於您的應用程式之外的高度最佳化圖片提供基礎架構。由於圖片是獨立於您的應用程式之外提供，因此不會產生負載，且極具成本效益。此方法傳回的 URL 一定可公開存取，但無法猜測。

如果您希望停止提供網址，請使用 deleteServingUrl() 方法將其刪除。

這個方法會傳回使用指定的大小和裁剪引數編碼的網址。如果您未指定任何引數，這個方法會傳回圖片的預設網址，例如：

http://lhx.ggpht.com/randomStringImageId

您可以在網址中指定引數，以動態方式調整圖片大小及裁剪圖片。可用的引數為：

• =sxx，其中 xx 為 0 到 2560 的整數，代表圖片最長邊的長度 (以像素為單位)。例如，加入 =s32 可調整圖片大小，使其最長尺寸成為 32 像素。
• =sxx-c，其中 xx 為 0 至 2560 的整數，代表裁剪後的圖片大小 (以像素為單位)，而 -c 則可告知系統要裁剪圖片。

# Resize the image to 32 pixels (aspect-ratio preserved)
http://lhx.ggpht.com/randomStringImageId=s32

# Crop the image to 32 pixels
http://lhx.ggpht.com/randomStringImageId=s32-c

圖片和開發伺服器

開發伺服器會使用本機電腦執行「圖片」服務的功能。

Java 程式開發伺服器會使用 ImageIO 架構模擬「圖片」服務。不支援「好手氣」相片修飾功能。只有已安裝適合的解碼器外掛程式時才支援 WEBP 圖片格式。例如，可以使用 Java VP8 解碼器外掛程式。請注意，getServingUrl 方法在開發伺服器中無法使用。

刪除注意事項

如要停止提供儲存於 Cloud Storage 或 Blobstore 的圖片，請呼叫 deleteServingUrl() 方法。

您應避免直接刪除 Cloud Storage 或 Blobstore 中的圖片，因為這樣可能會讓圖片仍可透過提供網址存取。

如果停用或刪除建立提供網址的應用程式，提供網址將會停止運作，即使基礎圖片仍可使用也一樣。

配額、限制及定價

目前使用 Images API 並不會產生額外費用。請參閱 App Engine 的定價頁面。

每個 Images API 要求都會計入 Image Manipulation API 呼叫的配額中。應用程式可在單次 API 呼叫中執行多次圖片轉換作業。

傳送至「圖片」服務的資料會計入傳送至 (Images) API 的資料配額中。從「圖片」服務接收的資料會計入從 (Images) API 接收的資料配額中。

每個圖片轉換作業都會計入已執行的轉換配額中。

詳情請參閱配額一文。您可以造訪 Google Cloud 主控台的「配額詳細資料」分頁，查看應用程式目前的配額用量。

除了配額之外，使用「圖片」服務時也需遵循下列限制：