# Primeiros passos com Image Processor 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](/pt-br/documentacao/fundamentos/criar-uma-conta/). - Uma aplicação que já entrega imagens a partir de uma origem. Para criar uma, consulte [Primeiros passos com Applications](/pt-br/documentacao/plataforma/applications/primeiros-passos/). - O path de uma imagem que a aplicação serve, para que você possa requisitá-la ao final. **Console** - Acesso ao Azion Console. Para entrar, consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). **CLI** - A [Azion CLI](/pt-br/documentacao/devtools/cli/) instalada e autorizada. **API** - Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/) e o `curl`. --- ## 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. **Console** Para ativar os dois módulos pelo Azion Console: 1. **Abra a aplicação** Acesse [Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/) > **Applications** e selecione a aplicação que entrega suas imagens. 2. **Vá para a aba Main Settings** 3. **Ative Image Processor** Na seção **Modules**, ative **Image Processor**, descrito como *Enable dynamic image editing options*. 4. **Ative Application Accelerator** O switch fica na mesma seção. 5. **Selecione Save** A aplicação agora carrega os dois módulos, e o behavior **Optimize Images** fica disponível para as suas regras. **CLI** Um comando ativa os dois módulos. Substitua `` pelo [ID da sua aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/definir-configuracoes-principais/): 1. **Execute o comando de atualização** ```bash azion update application --application-id --image-processor true --application-accelerator true ``` 2. **Leia a saída** O comando confirma a aplicação que alterou: ```text Updated Application with ID ``` A aplicação agora carrega os dois módulos, e o behavior **Optimize Images** fica disponível para as suas regras. **API** Uma requisição ativa os dois módulos. Substitua `[TOKEN VALUE]` pelo seu personal token e `` pelo [ID da sua aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/definir-configuracoes-principais/): 1. **Envie a requisição de atualização** ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/applications/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "modules": { "application_accelerator": { "enabled": true }, "image_processor": { "enabled": true } } }' ``` 2. **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 { "cache": { "enabled": true }, "functions": { "enabled": false }, "application_accelerator": { "enabled": true }, "image_processor": { "enabled": true } } ``` 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. **Console** Para criar o cache setting pelo Azion Console: 1. **Vá para a aba Cache Settings** 2. **Selecione + Cache** 3. **Nomeie o cache setting** Em **Name**, digite `images`. 4. **Expanda Cache vary by Query String** O painel fica na seção **Application Accelerator**. 5. **Defina Behavior como Allowlist** 6. **Adicione o campo ims** Em **Fields**, digite `ims`. 7. **Selecione Save** A aplicação agora tem um cache setting que armazena um objeto por valor distinto de `ims`. **CLI** 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. 1. **Escreva o cache setting em um arquivo** Salve o conteúdo a seguir como `cache-setting.json`: ```json { "name": "images", "browser_cache": { "behavior": "honor" }, "modules": { "cache": { "behavior": "override", "max_age": 31536000 }, "application_accelerator": { "cache_vary_by_querystring": { "behavior": "allowlist", "fields": ["ims"], "sort_enabled": true } } } } ``` `31536000` segundos é o teto de `max_age`, o que serve bem para imagens, porque elas mudam raramente. 2. **Crie o cache setting** Substitua `` pelo [ID da sua aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/definir-configuracoes-principais/): ```bash azion create cache-setting --application-id --file cache-setting.json ``` O comando imprime o id do novo cache setting: ```text Created Cache Settings configuration with ID 123464 ``` 3. **Leia o cache setting de volta** ```bash azion describe cache-setting --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](/pt-br/documentacao/devtools/cli/recursos/). **API** Uma requisição carrega o comportamento de cache e a allowlist de query string juntos. 1. **Envie a requisição de criação** Substitua `` pelo [ID da sua aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/definir-configuracoes-principais/): ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//cache_settings \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "images", "browser_cache": { "behavior": "honor" }, "modules": { "cache": { "behavior": "override", "max_age": 31536000 }, "application_accelerator": { "cache_vary_by_querystring": { "behavior": "allowlist", "fields": ["ims"], "sort_enabled": true } } } }' ``` `31536000` segundos é o teto de `max_age`, o que serve bem para imagens, porque elas mudam raramente. 2. **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](/pt-br/documentacao/plataforma/applications/cache/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**. **Console** Para criar a regra pelo Azion Console: 1. **Vá para a aba Rules Engine** 2. **Selecione + Rule** 3. **Nomeie a regra** Em **Name**, digite `Optimize images`. 4. **Selecione Request Phase** 5. **Selecione a variável** Nos critérios, selecione `${request_uri}`. 6. **Selecione o operador matches** 7. **Digite o argumento** Digite `\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)`. 8. **Adicione o behavior Set Cache Policy** Nos behaviors, selecione **Set Cache Policy** e escolha o cache setting `images`. 9. **Selecione Add Behavior** 10. **Selecione Optimize Images** 11. **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. **CLI** Os critérios carregam `${request_uri}`, que um shell expande, e o argumento carrega barras invertidas, então a regra vai em um arquivo. 1. **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 { "name": "Optimize images", "description": "Apply the cache setting and optimize images", "active": true, "criteria": [ [ { "conditional": "if", "variable": "${request_uri}", "operator": "matches", "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)" } ] ], "behaviors": [ { "type": "set_cache_policy", "attributes": { "value": 123464 } }, { "type": "optimize_images" } ] } ``` Uma regra carrega os dois behaviors, e `optimize_images` não recebe attributes. 2. **Crie a regra** ```bash azion create rules-engine --application-id --phase request --file rule.json ``` O comando imprime o id da nova regra: ```text 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. **API** 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. 1. **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 { "name": "Optimize images", "description": "Apply the cache setting and optimize images", "active": true, "criteria": [ [ { "conditional": "if", "variable": "${request_uri}", "operator": "matches", "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)" } ] ], "behaviors": [ { "type": "set_cache_policy", "attributes": { "value": 123463 } }, { "type": "optimize_images" } ] } ``` Uma regra carrega os dois behaviors, e `optimize_images` não recebe attributes. 2. **Envie a requisição de criação** ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//request_rules \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data @rule.json ``` 3. **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](/pt-br/documentacao/plataforma/applications/image-processor/configuracoes/). --- ## 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: ```bash curl -s -o /dev/null -w "%{http_code} %{content_type} %{size_download} bytes\n" \ -H "Accept: image/webp,image/*" \ "https://www.example.com/images/photo.jpg?ims=400x" ``` A resposta informa o status, o tipo e o tamanho dela: ```text 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: ```bash 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: ```text HTTP/2 200 content-type: image/webp x-ims: Enabled x-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 Processor](/pt-br/documentacao/plataforma/applications/image-processor/parametros-de-url.md): Toda operação que a query string ims expressa, além do redimensionamento que você acabou de usar. - [Entrega de imagens](/pt-br/documentacao/plataforma/applications/image-processor/entrega-de-imagens.md): O que acontece entre a requisição e a imagem derivada, e por que a regra é necessária. - [Boas práticas de Applications](/pt-br/documentacao/plataforma/applications/boas-praticas.md#image-processor): O valor de qualidade, as escolhas de cache e os headers que mantêm uma transformação barata. - [Limites de Applications](/pt-br/documentacao/plataforma/applications/limites.md#image-processor): Os limites de uma imagem, e o que conta para o medidor mensal de Images. - [Configurar Image Processor em uma aplicação](/pt-br/documentacao/guias/performance-e-confiabilidade/otimizacao-de-entrega/processar-imagens.md): A mesma configuração com o objeto completo da API v3, quando a sua automação ainda a usa. - [Solucionar problemas de Applications](/pt-br/documentacao/plataforma/applications/solucao-de-problemas.md#image-processor): O que verificar quando uma imagem volta sem processamento ou no formato errado.