API Images para serviços agrupados antigos

O App Engine oferece a capacidade de manipular dados de imagens através de um serviço de imagens dedicado. O serviço Images pode manipular imagens, compor várias imagens numa única imagem, converter formatos de imagem, fornecer metadados de imagens, como formato, largura, altura e um histograma de valores de cores.

O App Engine suporta as classes de manipulação de imagens nativas do Java, como AWT e Java2D, juntamente com a API Images do App Engine.

O serviço Images pode aceitar dados de imagens diretamente da app ou pode usar um valor do Cloud Storage. (O serviço Images também pode usar um valor do Cloud Blobstore, mas recomendamos a utilização do Cloud Storage.)

As imagens armazenadas no Cloud Storage e no Cloud Blobstore podem ter até ao valor máximo permitido para o respetivo serviço. A imagem transformada é devolvida diretamente à app e tem de ter menos de 32 megabytes.

Os contentores do Cloud Storage têm de usar listas de controlo de acesso detalhadas para que a API Images funcione. Para contentores que foram configurados para acesso de nível de contentor uniforme, a API Images não vai poder obter imagens nesse contentor e apresenta a mensagem de erro TransformationError. Se o seu contentor estiver configurado desta forma, pode desativar o acesso uniforme ao nível do contentor.

Quando publica imagens a partir do Cloud Storage, a Images API usa uma conta de serviço gerida pela Google, dynamic_image_service@system.gserviceaccount.com, para obter a imagem. Normalmente, isto é feito por si, mas se esta conta de serviço não tiver a função Storage Object Viewer no contentor, pode ocorrerem erros 403 Forbidden intermitentes. Isto acontece quando a imagem não está disponível na cache de publicação da Google e tem de ser obtida do contentor de origem.

Para conceder a autorização necessária, execute o seguinte comando gcloud:

gcloud storage buckets add-iam-policy-binding gs://[BUCKET_NAME] \
  --member=serviceAccount:dynamic_image_service@system.gserviceaccount.com \
  --role=roles/storage.objectViewer

API Image Service

A API Image service permite-lhe aplicar transformações a imagens, usando um serviço em vez de realizar o processamento de imagens no servidor de aplicações. A app prepara um objeto Image com os dados da imagem a transformar e um objeto Transform com instruções sobre como transformar a imagem. A app recebe um objeto ImagesService e, em seguida, chama o respetivo método applyTransform() com os objetos Image e Transform. O método devolve um objeto Image da imagem transformada.

A app recebe instâncias de ImagesService, Image e Transform através de ImagesServiceFactory.

Pode usar o seguinte exemplo do Java 8 no Java 17:

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

É possível combinar várias transformações numa única ação através de uma instância de CompositeTransform. Consulte a referência da API Images.

Transformações de imagens disponíveis

O serviço Images pode redimensionar, rodar, inverter e recortar imagens, bem como melhorar fotografias. Também pode compor várias imagens numa única imagem.

Redimensionar

Pode redimensionar a imagem mantendo o mesmo formato. Nem a largura nem a altura da imagem redimensionada podem exceder os 4000 píxeis.

Rodar

Pode rodar a imagem em incrementos de 90 graus.

Inverter horizontalmente

Pode virar a imagem na horizontal.

Virar verticalmente

Pode virar a imagem na vertical.

Recortar

Pode recortar a imagem com uma caixa delimitadora específica.

Sinto-me com sorte

A transformação "Estou com sorte" melhora as cores escuras e claras numa imagem e ajusta a cor e otimiza o contraste.

Formatos de imagem

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

Se o formato de entrada e o formato de saída forem diferentes, o serviço converte os dados de entrada no formato de saída antes de realizar a transformação.

Transformar imagens

O serviço Images pode usar um valor do Google Cloud Storage ou do Blobstore como a origem da imagem para uma transformação. Tem duas formas de transformar imagens:

  1. A classe ImagesServiceFactory() permite-lhe realizar transformações de imagens simples, como recortar, inverter e rodar.
  2. A utilização de getServingUrl() permite redimensionar e recortar imagens dinamicamente, pelo que não precisa de armazenar diferentes tamanhos de imagens no servidor. Este método devolve um URL que publica a imagem, e as transformações à imagem são codificadas neste URL. Esta função pressupõe que a imagem não se altera. Se for modificada depois de obter o URL, pode obter resultados inesperados ao usar o URL.

Usar a turma ImagesServiceFactory()

Pode transformar imagens do Cloud Storage ou do Blobstore se o tamanho da imagem for inferior ao máximo permitido pelo Cloud Storage ou pelo Blobstore. Tenha em atenção que o resultado da transformação é devolvido diretamente à 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, crie o objeto Image chamando o método estático ImagesServiceFactory.makeImageFromBlob(), transmitindo-lhe um valor blobstore.BlobKey. O resto da API funciona conforme esperado. O método applyTransform() devolve o resultado das transformações ou gera um ImagesServiceFailureException se o resultado for superior ao tamanho máximo de 32 megabytes.

Pode usar o seguinte exemplo do Java 8 no Java 17:

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

Usando getServingUrl()

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

Pode usar o seguinte exemplo do Java 8 no Java 17:

// 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 publicação de imagens altamente otimizada que é separada da sua aplicação. Como a imagem é publicada independentemente da sua app, não gera carga e pode ser muito rentável. O URL devolvido por este método é sempre acessível publicamente, mas não é previsível.

Se quiser parar de publicar o URL, elimine-o através do método deleteServingUrl(). Função

O método devolve um URL codificado com os argumentos de tamanho e recorte especificados. Se não especificar nenhum argumento, o método devolve o URL predefinido da imagem, por exemplo:

http://lhx.ggpht.com/randomStringImageId

Pode redimensionar e recortar a imagem dinamicamente especificando os argumentos no URL. Os argumentos disponíveis são:

  • =sxx, onde xx é um número inteiro de 0 a 2560 que representa o comprimento, em píxeis, do lado mais longo da imagem. Por exemplo, adicionar =s32 redimensiona a imagem para que a dimensão mais longa tenha 32 píxeis.
  • =sxx-c, em que xx é um número inteiro de 0 a 2560 que representa o tamanho da imagem recortada em píxeis e -c indica ao sistema que deve 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 sua máquina local para realizar as capacidades do serviço Images.

O servidor de desenvolvimento em Java usa a estrutura ImageIO para simular o serviço de imagens. A funcionalidade de melhoramento de fotos "Sinto-me com sorte" não é suportada. O formato de imagem WEBP só é suportado se tiver sido instalado um plug-in de descodificador adequado. Por exemplo, pode usar o plug-in Java VP8 decoder. Tenha em atenção que o método getServingUrl não está disponível no servidor de desenvolvimento.

Uma nota sobre a eliminação

Para parar a publicação de uma imagem armazenada no Cloud Storage ou no Blobstore, chame o método deleteServingUrl().

Deve evitar eliminar diretamente imagens no Cloud Storage ou no Blobstore, uma vez que, ao fazê-lo, as imagens podem continuar acessíveis através do URL de publicação.

Os URLs de publicação deixam de funcionar se a aplicação que os criou for desativada ou eliminada, mesmo que a imagem subjacente permaneça disponível.

Quotas, limites e preços

Atualmente, não existe nenhum custo adicional pela utilização da API Images. Consulte a página de preços do App Engine.

Cada pedido da API Images é contabilizado na quota de chamadas da API Image Manipulation. Uma app pode realizar várias transformações de uma imagem numa única chamada de API.

Os dados enviados para o serviço Images contam para a quota da API Data Sent to (Images). Os dados recebidos do serviço Images contam para a quota da API Data Received from (Images).

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

Para mais informações, consulte o artigo Quotas. Pode ver a utilização atual da quota da sua app visitando o separador Google Cloud Detalhes da quota da consola.

Além das quotas, aplicam-se os seguintes limites à utilização do serviço Images:

Limite Montante
Tamanho máximo dos dados da imagem enviada para o serviço 32 megabytes
tamanho máximo dos dados da imagem recebida do serviço 32 megabytes
Tamanho máximo da imagem enviada ou recebida do serviço 50 megapíxeis