舊版套裝組合服務的 Images API

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

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

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

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

在 Python 2 中轉換圖片

以下範例由 Cloud Datastore 載入圖片資料，然後利用「圖片」服務調整圖片大小，並以 JPEG 格式將圖片傳回瀏覽器。

from google.appengine.api import images
from google.appengine.ext import ndb

import webapp2


class Photo(ndb.Model):
    title = ndb.StringProperty()
    full_size_image = ndb.BlobProperty()


class Thumbnailer(webapp2.RequestHandler):
    def get(self):
        if self.request.get("id"):
            photo = Photo.get_by_id(int(self.request.get("id")))

            if photo:
                img = images.Image(photo.full_size_image)
                img.resize(width=80, height=100)
                img.im_feeling_lucky()
                thumbnail = img.execute_transforms(output_encoding=images.JPEG)

                self.response.headers['Content-Type'] = 'image/jpeg'
                self.response.out.write(thumbnail)
                return

        # Either "id" wasn't provided, or there was no image with that ID
        # in the datastore.
        self.error(404)

除了圖片 API 以外，您也可以使用 Python 2.7 應用程式中 Python Imaging Library (PIL) 提供的轉換功能。您只需在 app.yaml 檔案的 libraries 區段中宣告程式庫即可。不過若您希望在本機環境使用 PIL (使用開發伺服器)，也必須於本機下載及安裝 PIL 或 pillow。

可用的圖片轉換作業

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

調整大小

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

旋轉

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

水平翻轉

您可以將圖片水平翻轉。

垂直翻轉

您可以將圖片垂直翻轉。

裁剪

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

好手氣

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

圖片格式

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

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

轉換圖片

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

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

使用 Image() 類別

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

在 Python 2 轉換 Cloud Storage 或 Blobstore 圖片時，請不要以圖片資料設定 Image 建構函式的 image_data 引數，應將 blob_key 引數設為值為圖片的 Blobstore 金鑰。API 的其餘部分會如預期運作。execute_transforms() 方法會傳回轉換結果，如果結果大於 32 MB 的上限，則會傳回 LargeImageError。

from google.appengine.api import images
from google.appengine.ext import blobstore

import webapp2


class Thumbnailer(webapp2.RequestHandler):
    def get(self):
        blob_key = self.request.get("blob_key")
        if blob_key:
            blob_info = blobstore.get(blob_key)

            if blob_info:
                img = images.Image(blob_key=blob_key)
                img.resize(width=80, height=100)
                img.im_feeling_lucky()
                thumbnail = img.execute_transforms(output_encoding=images.JPEG)

                self.response.headers['Content-Type'] = 'image/jpeg'
                self.response.out.write(thumbnail)
                return

        # Either "blob_key" wasn't provided, or there was no value with that ID
        # in the Blobstore.
        self.error(404)

使用 get_serving_url()

除了圖片 API 以外，您也可以使用 Python 2.7 應用程式中 Python Imaging Library (PIL) 提供的轉換功能。如要這樣做，請在 app.yaml 檔案的「libraries」部分宣告程式庫。

如需在開發伺服器使用 PIL，請於本機下載及安裝 PIL 或 pillow。

get_serving_url() 方法可讓您針對儲存於 Cloud Storage 或 Blobstore 的圖片，產生固定的已宣告 URL，例如： 

url = images.get_serving_url(
    blob_key, size=150, crop=True, secure_url=True)

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

如果您希望停止提供 URL，請使用 delete_serving_url() 函式將其刪除。

方法傳回的 URL 以指定尺寸及裁剪引數進行編碼。如果您未指定任何引數，這個方法會傳回圖片的預設網址，例如：

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

圖片和開發伺服器

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

Python 開發伺服器可使用 Python Imaging Library (PIL) 模擬「圖片」服務。不過 Python 標準資料庫或 SDK 未包含此資料庫，因此必須另外安裝。pillow 分支也適用。如要支援 WEBP 圖片格式，請安裝適當的 PIL 解碼器外掛程式。

刪除注意事項

如需停止提供儲存於 Cloud Storage 或 Blobstore 的圖片，請呼叫 delete_serving_url() 函式。

您應避免直接在 Cloud Storage 或 Blobstore 刪除圖片，這樣可能會讓圖片仍可透過提供 URL 存取。

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

配額、限制及定價

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

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

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

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

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

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

限制 限額
傳送至服務的圖片資料大小上限 32 MB
從服務接收的圖片資料大小上限 32 MB
傳送至服務或從服務接收的圖片大小上限 5000 萬像素