Primeiros passos com Image Processor

Ative Image Processor, mantenha em cache cada transformação separadamente e requisite sua primeira imagem derivada pelo Console, pela CLI ou pela API.

Última atualização

Ver como Markdown Configurar agente

Este guia conduz você pela requisição da sua primeira imagem derivada a partir de uma aplicação. Ao final, você terá:

  • Image Processor ativado em uma aplicação.
  • Um cache setting que armazena cada transformação como um objeto próprio.
  • Uma regra do Rules Engine que envia requisições de imagem para o módulo.
  • Uma imagem redimensionada retornada a partir de uma URL que você escreveu.

Quatro objetos produzem esse resultado, e cada um está ligado ao anterior. A aplicação carrega o switch do módulo. O cache setting pertence à aplicação e decide que duas transformações diferentes são dois objetos diferentes em cache. A regra pertence à aplicação, corresponde a requisições de imagem e aplica tanto o cache setting quanto o behavior Optimize Images. A URL da imagem carrega então a transformação na própria query string ims. Uma requisição que nenhuma regra corresponde é entregue sem processamento, então é a regra que dá sentido à query string.

Selecione a interface que você vai usar. Os pré-requisitos e todas as etapas abaixo seguem essa escolha.

Pré-requisitos

  • Uma conta Azion.
  • Uma aplicação que já entrega imagens a partir de uma origem. Para criar uma, consulte Primeiros passos com Applications.
  • O path de uma imagem que a aplicação serve, para que você possa requisitá-la ao final.

Ative Image Processor

O módulo é um switch na aplicação, e fica desativado até você configurá-lo. Esta etapa ativa dois módulos.

Application Accelerator é o segundo por um motivo: o campo que varia o cache por uma query string pertence a ele, e o cache setting usa esse campo. Processar uma imagem não exige o módulo, mas armazenar cada transformação separadamente em cache exige.

Para ativar os dois módulos pelo Azion Console:

Abra a aplicação

Acesse Azion Console > Applications e selecione a aplicação que entrega suas imagens.

Vá para a aba Main Settings
Ative Image Processor

Na seção Modules, ative Image Processor, descrito como Enable dynamic image editing options.

Ative Application Accelerator

O switch fica na mesma seção.

Selecione Save

A aplicação agora carrega os dois módulos, e o behavior Optimize Images fica disponível para as suas regras.

Um comando ativa os dois módulos. Substitua <application_id> pelo ID da sua aplicação:

Execute o comando de atualização
azion update application --application-id <application_id> --image-processor true --application-accelerator true
Leia a saída

O comando confirma a aplicação que alterou:

Updated Application with ID <application_id>

A aplicação agora carrega os dois módulos, e o behavior Optimize Images fica disponível para as suas regras.

Uma requisição ativa os dois módulos. Substitua [TOKEN VALUE] pelo seu personal token e <application_id> pelo ID da sua aplicação:

Envie a requisição de atualização
Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/applications/<application_id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "modules": {
08 "application_accelerator": { "enabled": true },
09 "image_processor": { "enabled": true }
10 }
11}
Leia a resposta

Um 202 carrega "state": "pending", porque a alteração ainda está propagando. O objeto modules da resposta repete todos os módulos da aplicação, inclusive os que você não alterou:

JSON
01{
02 "cache": { "enabled": true },
03 "functions": { "enabled": false },
04 "application_accelerator": { "enabled": true },
05 "image_processor": { "enabled": true }
06}

A aplicação agora carrega os dois módulos, e o behavior Optimize Images fica disponível para as suas regras.

Crie um cache setting que varia pela query string ims

Sem esta etapa, o cache não consegue diferenciar uma transformação de outra, e pode responder a uma requisição de imagem de 400 pixels com uma de 200 pixels.

Para criar o cache setting pelo Azion Console:

Vá para a aba Cache Settings
Selecione + Cache
Nomeie o cache setting

Em Name, digite images.

Expanda Cache vary by Query String

O painel fica na seção Application Accelerator.

Defina Behavior como Allowlist
Adicione o campo ims

Em Fields, digite ims.

Selecione Save

A aplicação agora tem um cache setting que armazena um objeto por valor distinto de ims.

As flags de criação não alcançam a idade máxima, então o comando envia o body inteiro a partir de um arquivo.

Escreva o cache setting em um arquivo

Salve o conteúdo a seguir como cache-setting.json:

JSON
01{
02 "name": "images",
03 "browser_cache": { "behavior": "honor" },
04 "modules": {
05 "cache": { "behavior": "override", "max_age": 31536000 },
06 "application_accelerator": {
07 "cache_vary_by_querystring": {
08 "behavior": "allowlist",
09 "fields": ["ims"],
10 "sort_enabled": true
11 }
12 }
13 }
14}

31536000 segundos é o teto de max_age, o que serve bem para imagens, porque elas mudam raramente.

Crie o cache setting

Substitua <application_id> pelo ID da sua aplicação:

azion create cache-setting --application-id <application_id> --file cache-setting.json

O comando imprime o id do novo cache setting:

Created Cache Settings configuration with ID 123464
Leia o cache setting de volta
azion describe cache-setting --application-id <application_id> --cache-setting-id 123464 --format json

A saída informa a allowlist de ims e a idade máxima que o arquivo definiu.

A aplicação agora tem um cache setting que armazena um objeto por valor distinto de ims. Registre o id que o comando imprimiu, porque a regra o aplica. Para todas as flags que o comando aceita, consulte Azion CLI create.

Uma requisição carrega o comportamento de cache e a allowlist de query string juntos.

Envie a requisição de criação

Substitua <application_id> pelo ID da sua aplicação:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/cache_settings \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "images",
08 "browser_cache": { "behavior": "honor" },
09 "modules": {
10 "cache": { "behavior": "override", "max_age": 31536000 },
11 "application_accelerator": {
12 "cache_vary_by_querystring": {
13 "behavior": "allowlist",
14 "fields": ["ims"],
15 "sort_enabled": true
16 }
17 }
18 }
19}

31536000 segundos é o teto de max_age, o que serve bem para imagens, porque elas mudam raramente.

Leia a resposta

Um 201 carrega "state": "executed" e o cache setting que ele criou. A resposta devolve modules.cache.max_age como 31536000 e repete cache_vary_by_querystring exatamente como você enviou.

Registre data.id, como 123463, porque a regra o aplica.

A aplicação agora tem um cache setting que armazena um objeto por valor distinto de ims.

Para o restante dos campos que um cache setting carrega, incluindo por quanto tempo um objeto permanece em cache, consulte Cache Settings.

Crie uma regra que envia as requisições de imagem para o módulo

A regra é o que converte a query string em uma transformação. Ela corresponde a requisições de paths de imagem, aplica o cache setting que você criou e adiciona o behavior Optimize Images.

Para criar a regra pelo Azion Console:

Vá para a aba Rules Engine
Selecione + Rule
Nomeie a regra

Em Name, digite Optimize images.

Selecione Request Phase
Selecione a variável

Nos critérios, selecione ${request_uri}.

Selecione o operador matches
Digite o argumento

Digite \.(jpg|jpeg|gif|bmp|png|ico|webp|avif).

Adicione o behavior Set Cache Policy

Nos behaviors, selecione Set Cache Policy e escolha o cache setting images.

Selecione Add Behavior
Selecione Optimize Images
Selecione Save

Toda requisição para um path terminado em uma dessas extensões agora alcança Image Processor, carrega o cache setting images e é processada quando a URL dela pede uma transformação.

Os critérios carregam ${request_uri}, que um shell expande, e o argumento carrega barras invertidas, então a regra vai em um arquivo.

Escreva a regra em um arquivo

Salve o conteúdo a seguir como rule.json, com o id do seu cache setting no behavior set_cache_policy:

JSON
01{
02 "name": "Optimize images",
03 "description": "Apply the cache setting and optimize images",
04 "active": true,
05 "criteria": [
06 [
07 {
08 "conditional": "if",
09 "variable": "${request_uri}",
10 "operator": "matches",
11 "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)"
12 }
13 ]
14 ],
15 "behaviors": [
16 { "type": "set_cache_policy", "attributes": { "value": 123464 } },
17 { "type": "optimize_images" }
18 ]
19}

Uma regra carrega os dois behaviors, e optimize_images não recebe attributes.

Crie a regra
azion create rules-engine --application-id <application_id> --phase request --file rule.json

O comando imprime o id da nova regra:

Created Rules Engine with ID 234571

Toda requisição para um path terminado em uma dessas extensões agora alcança Image Processor, carrega o cache setting images e é processada quando a URL dela pede uma transformação.

Os critérios carregam ${request_uri}, que um shell expande, e o argumento carrega barras invertidas, então o body é enviado a partir de um arquivo.

Escreva a regra em um arquivo

Salve o conteúdo a seguir como rule.json, com o id do seu cache setting no behavior set_cache_policy:

JSON
01{
02 "name": "Optimize images",
03 "description": "Apply the cache setting and optimize images",
04 "active": true,
05 "criteria": [
06 [
07 {
08 "conditional": "if",
09 "variable": "${request_uri}",
10 "operator": "matches",
11 "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)"
12 }
13 ]
14 ],
15 "behaviors": [
16 { "type": "set_cache_policy", "attributes": { "value": 123463 } },
17 { "type": "optimize_images" }
18 ]
19}

Uma regra carrega os dois behaviors, e optimize_images não recebe attributes.

Envie a requisição de criação
Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/request_rules \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data @rule.json
Leia a resposta

Um 202 carrega "state": "pending", porque a regra ainda está propagando. Ela repete os critérios e os dois behaviors, e carrega o order que a regra ocupa entre as regras da aplicação.

Toda requisição para um path terminado em uma dessas extensões agora alcança Image Processor, carrega o cache setting images e é processada quando a URL dela pede uma transformação.

nota — Esta parte é opcional. Converter uma imagem para WEBP ou AVIF exige que a requisição carregue Accept: image/webp ou Accept: image/avif. O behavior Add Request Header o adiciona à mesma regra, então a conversão deixa de depender do que o navegador enviou. Na Azion CLI e na API, é um behavior do tipo add_request_header, cujos attributes carregam "value": "Accept: image/webp". Para os campos do behavior, consulte Configurações do Image Processor.

Requisite uma imagem derivada

Peça uma largura e veja a resposta mudar.

Requisite uma das suas imagens com uma query string ims, substituindo o host e o path pelos seus próprios:

Shell
01curl -s -o /dev/null -w "%{http_code} %{content_type} %{size_download} bytes\n" \
02 -H "Accept: image/webp,image/*" \
03 "https://www.example.com/images/photo.jpg?ims=400x"

A resposta informa o status, o tipo e o tamanho dela:

200 image/webp 8312 bytes

Requisite a mesma imagem sem query string e compare o tamanho. A resposta processada é menor, e também pode carregar um formato diferente do arquivo na sua origem, porque Image Processor entrega WEBP para os navegadores que o aceitam.

Para confirmar que foi o módulo, e não a origem, que processou a resposta, leia os headers:

curl -sI -H "Accept: image/webp" "https://www.example.com/images/photo.jpg?ims=400x"

Uma resposta processada carrega x-ims: Enabled e o tamanho da imagem de origem antes da transformação:

Texto
01HTTP/2 200
02content-type: image/webp
03x-ims: Enabled
04x-original-image-size: 484156

Agora você tem uma aplicação que transforma imagens sob demanda, e uma URL que descreve a transformação.

dica — Mantenha ims= como o último parâmetro na URL. Uma requisição que carrega outro parâmetro de query string depois dele pode retornar um erro 504.

Próximos passos

Parâmetros de URL do Image ProcessorToda operação que a query string ims expressa, além do redimensionamento que você acabou de usar.Entrega de imagensO que acontece entre a requisição e a imagem derivada, e por que a regra é necessária.Boas práticas de ApplicationsO valor de qualidade, as escolhas de cache e os headers que mantêm uma transformação barata.Limites de ApplicationsOs limites de uma imagem, e o que conta para o medidor mensal de Images.Configurar Image Processor em uma aplicaçãoA mesma configuração com o objeto completo da API v3, quando a sua automação ainda a usa.Solucionar problemas de ApplicationsO que verificar quando uma imagem volta sem processamento ou no formato errado.