API Images para serviços agrupados legados

O App Engine permite manipular dados de imagem usando um serviço dedicado. O serviço de imagens pode manipular imagens, compor várias em uma única imagem, converter formatos e fornecer metadados de imagem, como formato, largura, altura e um histograma de valores de cor.

O Java 8 no App Engine é compatível com classes de manipulação de imagens nativas do Java, como AWT e Java2D, juntamente com a API Images do App Engine.

O serviço de imagens pode aceitar dados de imagem diretamente do app ou usar um valor do Cloud Storage. O serviço de imagens também pode usar um valor do Cloud Blobstore, mas recomendamos o uso do Cloud Storage.

As imagens armazenadas no Cloud Storage e no Cloud Blobstore podem atingir o valor máximo permitido para o respectivo serviço. A imagem transformada é retornada diretamente para o app e precisa ter menos de 32 megabytes.

Os buckets do Cloud Storage precisam usar listas de controle de acesso detalhadas para que a API Images funcione. Nos buckets configurados com acesso uniforme no nível do bucket, a API Images não vai conseguir buscar imagens nesse bucket e vai gerar a mensagem de erro TransformationError. Se o bucket estiver configurado dessa maneira, é possível desativar o acesso uniforme no nível do bucket.

Como transformar imagens em Java 8

A API do serviço de imagens permite aplicar transformações a imagens usando um serviço, em vez de realizar o processamento de imagens no servidor de aplicativos. O aplicativo prepara um objeto Image com os dados da imagem a serem transformados e um objeto Transform com instruções sobre como transformar a imagem. O aplicativo recebe um objeto ImagesService e chama o método applyTransform() com os objetos Image e Transform. O método retorna um objeto Image da imagem transformada.

O aplicativo recebe instâncias ImagesService, Image e Transform usando o ImagesServiceFactory.

// 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()));

Várias transformações podem ser combinadas em uma única ação por meio de uma instância CompositeTransform. Consulte a referência da API Images.

Transformações de imagens disponíveis

O serviço de imagens pode redimensionar, girar, virar e cortar imagens, além de ajustar fotografias. Ele também pode compor várias imagens em uma única.

Redimensionar

Você pode redimensionar a imagem mantendo a mesma proporção. Nem a largura nem a altura da imagem redimensionada podem exceder 4.000 pixels.

Girar

É possível girar a imagem em incrementos de 90 graus.

Virar horizontalmente

É possível virar a imagem horizontalmente.

Virar verticalmente

É possível virar a imagem verticalmente.

Cortar

Você pode cortar a imagem usando uma determinada caixa delimitadora.

Estou com sorte

A transformação "Estou com corte" melhora cores escuras e brilhantes em uma imagem, ajusta a cor e otimiza o contraste.

Formatos de imagem

O serviço aceita dados de imagem nos formatos JPEG, PNG, WEBP, GIF (inclusive GIF animado), BMP, TIFF e ICO. As imagens transformadas podem ser retornadas nos formatos JPEG, WEBP e PNG.

Se os formatos de entrada e de saída forem diferentes, o serviço converterá os dados de entrada para o formato de saída antes de realizar a transformação.

Como transformar imagens

O serviço Images usa um valor do Google Cloud Storage ou do Blobstore como origem da imagem em uma transformação. Você tem duas maneiras de transformar imagens:

  1. O uso da classe ImagesServiceFactory() permite realizar transformações simples de imagem, como cortar, inverter e girar.
  2. Usar getServingUrl() permite redimensionar e recortar dinamicamente as imagens. Dessa maneira, você não precisa armazenar tamanhos de imagem diferentes no servidor. Esse método retorna um URL que exibe a imagem e as transformações da imagem são codificadas nesse URL. Essa função presume que a imagem não muda. Se ela for modificada depois que você receber o URL, será possível conseguir resultados inesperados ao usar o URL.

Como usar a classe ImagesServiceFactory()

Você poderá transformar imagens do Cloud Storage ou do Blobstore se o tamanho da imagem for menor que o máximo permitido pelo Cloud Storage ou pelo Blobstore. O resultado da transformação é retornado diretamente para app e não pode exceder o limite de resposta da API de 32 megabytes.

Para transformar uma imagem do Cloud Storage ou do Blobstore no Java 8, crie o objeto Image chamando o método estático ImagesServiceFactory.makeImageFromBlob(), transmitindo um valor blobstore.BlobKey. O resto da API se comporta normalmente. O método applyTransform() retorna o resultado das transformações ou gera um ImagesServiceFailureException se o resultado for maior que o tamanho máximo de 32 megabytes.

// 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()));

Como usar getServingUrl()

O método getServingUrl() permite gerar um URL fixo e dedicado para uma imagem armazenada no Cloud Storage ou no Blobstore. Exemplo: 

// 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);

O URL gerado usa uma infraestrutura de exibição de imagem altamente otimizada e separada do aplicativo. Como é exibida independentemente do aplicativo, a imagem não gera carga e pode ser altamente econômica. O URL retornado por esse método é sempre acessível publicamente, mas não há como ser previsto.

Se você quiser deixar de veicular o URL, exclua-o usando o método deleteServingUrl().

O método retorna um URL codificado com os argumentos de tamanho e corte especificados. Se você não especificar argumentos, o método retornará o URL padrão da imagem. Por exemplo:

http://lhx.ggpht.com/randomStringImageId

Redimensione e recorte a imagem dinamicamente especificando os argumentos no URL. Os argumentos disponíveis são:

  • =sxx, em que xx é um número inteiro de 0 a 2.560 que representa o comprimento, em pixels, do lado maior da imagem. Por exemplo, adicionar =s32 redimensiona a imagem de modo que a dimensão maior tenha 32 pixels.
  • =sxx-c, em que xx é um número inteiro de 0 a 2.560 que representa o tamanho da imagem recortada em pixels, e -c informa ao sistema para recortar a imagem.
# 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

Imagens e o servidor de desenvolvimento

O servidor de desenvolvimento usa a máquina local para realizar os recursos do serviço de imagens.

O servidor de desenvolvimento Java usa a biblioteca ImageIO para simular o serviço de imagens. O recurso avançado de foto "Estou com sorte" não é compatível. O formato de imagem WEBP só será compatível se um plug-in decodificador apropriado tiver sido instalado. O plug-in decodificador Java VP8 pode ser usado, por exemplo. Observe que o método getServingUrl não está disponível no servidor de desenvolvimento.

Uma observação sobre exclusão

Para deixar de veicular uma imagem armazenada no Cloud Storage ou no Blobstore, chame o método deleteServingUrl().

Você precisa evitar excluir diretamente as imagens no Cloud Storage ou no Blobstore, porque isso pode deixá-las acessíveis por meio do URL de veiculação.

Os URLs de veiculação deixarão de funcionar se o aplicativo que os criou for desativado ou excluído, mesmo se a imagem subjacente permanecer disponível.

Cotas, limites e preços

Atualmente, não há cobrança adicional pelo uso da API Images. Consulte a página de preços do App Engine.

Cada solicitação da API Images conta para a cota de chamadas da API Image Manipulation. Um app pode realizar várias transformações de uma imagem em uma única chamada de API.

Os dados enviados para o serviço de imagens contam para a cota de dados enviados para a API Images. Os dados recebidos do serviço de imagens contam para a cota de dados recebidos da API Images.

Cada transformação de uma imagem conta para a cota de transformações executadas.

Para mais informações, consulte Cotas. Confira o uso atual da cota do app na guia Detalhes da cota do console do Google Cloud.

Além das cotas, os seguintes limites se aplicam ao uso do serviço de imagens:

Limite Valor
tamanho máximo de dados da imagem enviada para o serviço 32 megabytes
tamanho máximo de dados da imagem recebida do serviço 32 megabytes
tamanho máximo da imagem enviada ou recebida do serviço 50 megapixels