适用于旧版捆绑服务的 Images API

App Engine 可让您使用专门的 Images 服务来处理图片数据。Images 服务可以处理图片、将多个图片合成为单个图片、转换图片格式、提供图片元数据，如格式、宽度、高度和颜色值的直方图。

此 API 支持第一代运行时，并可在升级到相应的第二代运行时后使用。如果您要更新到 App Engine Java 11/17 运行时，请参阅迁移指南以了解旧版捆绑服务的迁移选项。

App Engine 上的 Java 8 支持 Java 的原生图片处理类（如 AWT 和 Java2D）以及 App Engine Images API。

图片服务可以直接从应用接受图片数据，也可以使用 Cloud Storage 值。（Images 服务还可以使用 Cloud Blobstore 值，但我们建议使用 Cloud Storage。）

存储在 Cloud Storage 和 Cloud Blobstore 中的图片可以达到相应服务允许的最大值。转换后的图片直接返回给应用，并且必须小于 32 MB。

Cloud Storage 存储桶必须使用精细的访问控制列表，以确保 Images API 正常工作。对于已配置为使用统一存储桶级访问权限的存储桶，Images API 将无法提取该存储桶中的图片并会抛出 TransformationError 错误消息。如果您的存储桶正是以这种方式进行配置的，您可以停用统一存储桶级访问权限。

重要提示：如果您从 Google Cloud Storage 传送图片，则无法从两个单独的应用传送同一张图片。仅第一个对图片调用 getServingUrl 的应用可以获取用于传送图片的网址，因为该应用已获取图片的所有权。因此，随后对该图片调用 getServingUrl 的任何其他应用都将失败。如果第二个应用需要传送图片，则此应用需要先复制该图片，然后对副本调用 getServingUrl。

使用 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 参考文档。

可用的图片转换

Images 服务可以调整图片大小，旋转、翻转和剪裁图片，以及提高照片质量。它还可以将多个图片合并为一个图片。

调整大小

您可以在保持宽高比不变的情况下调整图片大小。调整后图片的宽度和高度都不能超过 4000 像素。

旋转

您可以将图片旋转 90 度的倍数。

水平翻转

您可以水平翻转图片。

垂直翻转

您可以垂直翻转图片。

剪裁

您可以给定边界框来剪裁图片。

手气不错

“手气不错”转换可增强图片中的暗色和亮色，以及调整这两种颜色并优化对比度。

图片格式

该服务接受 JPEG、PNG、WEBP、GIF（包括动画 GIF）、BMP、TIFF 和 ICO 格式的图片数据。转换后的图片可以采用 JPEG、WEBP 和 PNG 格式返回。

如果输入格式和输出格式不同，该服务在执行转换之前会将输入数据转换为输出格式。

注意：Images 服务不支持多层 TIFF 图片。

转换图片

Images 服务可以使用 Google Cloud Storage 或 Blobstore 中的值作为转换的图片源。您可以通过以下两种方式来转换图片：

1. 使用 ImagesServiceFactory() 类可以执行简单的图片转换，例如剪裁、翻转和旋转。
2. 使用 getServingUrl() 可让您动态调整图片的大小和剪裁图片，因此您无需在服务器上存储不同大小的图片。该方法返回一个提供图片的网址，而且会在该网址中对图片转换进行编码。 此函数假定图片不会改变；如果在获取网址后图片被修改，则您使用该网址可能会出现意外结果。

使用 ImagesServiceFactory() 类

如果 Cloud Storage 或 Blobstore 中的图片小于 Cloud Storage 或 Blobstore 允许的最大值，则可以转换图片。请注意，转换的结果将直接返回给应用，并且不得超过 32 MB 的 API 响应限制。

要使用 Java 8 转换 Cloud Storage 或 Blobstore 中的图片，您可以通过以下方式创建 Image 对象：调用静态方法 ImagesServiceFactory.makeImageFromBlob() 并向其传递 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);

生成的网址使用高度优化、独立于您应用的图片传送基础架构。由于图片独立于您的应用进行传送，因此不会产生负载，并且经济高效。此方法返回的网址始终可公开访问，但无法推测。

如果要停止提供网址，请使用 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 服务的数据将计入发送到 (Images) API 的数据配额。从 Images 服务接收的数据将计入从 (Images) API 接收的数据配额。

每项图片转换操作都会计入执行的转换配额。

如需了解详情，请参阅配额。您可以访问 Google Cloud Console 配额详细信息标签页，查看应用的当前配额使用情况。

除了配额以外，在使用 Images 服务时，还应遵循以下限制：

限制	金额
发送到该服务的图片的最大数据大小	32 MB
从该服务接收的图片的最大数据大小	32 MB
从该服务发送或接收的图片的最大大小	50 兆像素