Solicitações de proxy

O recurso de proxy do Managed Runtime permite rotear solicitações para APIs hospedadas em domínios diferentes pelo mesmo domínio que sua loja (virtual).

Por que usar o mesmo domínio que sua loja (virtual)? Imagine que sua loja (virtual) está hospedada e www.northerntrailoutfitters.com você deseja solicitar a B2C Commerce API ao api.commercecloud.salesforce.com. Fazer essa solicitação sem um proxy envolve etapas adicionais de configuração e não é tão rápido e evidente quanto poderia ser com um proxy. Vamos comparar as duas abordagens:

Agora que você entende a importância de usar proxies, vejamos os diversos métodos de configurá-los.

Durante o desenvolvimento local, os proxies podem ser configurados editando o array mobify.ssrParameters.proxyConfigs em <PROJECT_DIR>/config/default.js. Por exemplo, para configurar um proxy para a B2C Commerce API:

O array proxyConfigs contém objetos que definem uma configuração de proxy com as propriedades a seguir:

• host: o host de origem que recebe suas solicitações.
• path: o nome usado no caminho da solicitação para identificar esse proxy.

Para fazer uma solicitação de proxy no código do aplicativo, siga este padrão ao criar caminhos de solicitação: /mobify/proxy/<PROXY_PATH>.

Vejamos um exemplo que usa api como o valor path. Por padrão, os projetos criados com PWA Kit incluem uma configuração de proxy que associa o caminho api à B2C Commerce API.

Ao alterar a configuração de proxy durante o desenvolvimento local, você deve reiniciar o servidor de desenvolvimento local para que as alterações entrem em vigor.

O Managed Runtime ignora as definições de proxy nos arquivos de configuração. Em vez disso, os proxies devem ser configurados usando o Runtime Admin ou a Managed Runtime API.

Para configurar proxies para um ambiente do Managed Runtime usando nossa ferramenta de administração com base na Web, siga estas etapas:

1. Faça logon no Runtime Admin.
2. Clique em seu projeto.
3. Clique em um ambiente.
4. Clique em Environment Settings (Configurações do ambiente), no menu de navegação à esquerda.
5. Na seção Advanced (Avançado), clique em Edit (Editar).
6. Em Proxy Configs (Configurações de proxy), clique em Add New Proxy (Adicionar novo proxy).
7. Insira o caminho, protocolo e o host.
8. Repita com até 8 configurações de proxy.
9. Volte ao início da seção Advanced (Avançado) e clique em Update (Atualizar).
10. Espere terminar a reimplantação do pacote.
11. Verifique se a configuração de proxy esteja funcionando como esperado.

Você também pode configurar proxies para ambientes de Managed Runtime programaticamente usando endpoint projects_target_partial_update. A Managed Runtime API geralmente usa o termo “destino” em vez de “ambiente”, mas ambos os termos fazem referência à mesma coisa.

Veja aqui uma solicitação de exemplo que atualiza um ambiente para incluir uma configuração de proxy para os caminhos api e ocapi:

Ao criar ou atualizar ambientes, o corpo da solicitação JSON aceita um array de objetos de configuração de proxy de um campo denominado ssr_proxy_configs. Os objetos de configuração de proxy incluem host e path, como nos arquivos de configuração.

Para evitar tempo de inatividade, as etapas para adicionar ou remover proxies em um ambiente de Production deve ser feita em uma ordem específica.

Para adicionar um proxy a um ambiente de Production:

1. Edite as configurações do ambiente para o ambiente de Production usando o Runtime Admin ou o Managed Runtime API. (Siga as instruções descritas anteriormente.)
2. Adicione o novo proxy às configurações do ambiente e salve suas edições.
3. Atualize o código de seu PWA Kit para usar o novo proxy.
4. Envie um novo pacote com código de seu PWA Kit para o Managed Runtime.
5. Implante o novo pacote.

Para remover um proxy de um ambiente de Production:

1. Atualize o código de seu PWA Kit para usar o novo proxy.
2. Envie um novo pacote com código de seu PWA Kit para o Managed Runtime.
3. Implante o novo pacote.
4. Edite as configurações do ambiente para o ambiente de Production usando o Runtime Admin ou o Managed Runtime API. (Siga as instruções descritas anteriormente.)
5. Remova o novo proxy das configurações do ambiente e salve suas edições.

No desenvolvimento local, você pode substituir as configurações de proxy usando variáveis de ambiente.

Defina uma variável de ambiente com o nome SSR_PROXY1 para substituir o primeiro elemento no array proxyConfigs, defina outra que se chame SSR_PROXY2 para substituir o segundo elemento, e assim por diante.

Funciona da seguinte maneira: Se a variável de ambiente SSR_PROXY1 for definida como https://api-staging.example.com/api, ela substituirá o primeiro elemento no array proxyConfigs pelo próximo objeto de configuração de proxy:

Essas variáveis de ambiente são comumente usadas com o comando npm start durante o desenvolvimento local para usar diferentes instâncias do host da API, como as de Staging ou Production. Veja aqui um exemplo que substitui o primeiro objeto na configuração de proxy para que o caminho api encaminhe solicitações para uma instância de Staging:

Depois que as configurações do proxy tiverem sido definidas, você pode buscá-las usando a função utilitária getProxyConfigs do PWA Kit React SDK. Por exemplo, você pode usar um ID de cliente diferente, dependendo do ambiente no qual seu código é executado:

Quando uma solicitação é intermediada por proxy, tanto a solicitação para a origem quanto a resposta da origem são modificadas para que funcionem de forma transparente com o código do aplicativo.

As modificações a seguir são aplicadas à solicitação antes de enviá-la para o host:

• Remova o prefixo /mobify/proxy/<PROXY_PATH>/.
• Adicione um cabeçalho HTTP de X-Mobify: true.

As solicitações por proxy encaminham todos os parâmetros e cabeçalhos de string de consulta, incluindo cookies.

As modificações a seguir são aplicadas à resposta antes de enviá-la para o cliente:

• Adicione um cabeçalho HTTP de X-Request-Url: <URL> com o URL que foi solicitado.
• Se a resposta for um redirecionamento e o cabeçalho Location da resposta cujo host coincidir com o host do proxy, então host será prefixado com /mobify/proxy/<PROXY_PATH>/.
• Se a resposta contiver cabeçalhos Set-Cookie cujo domain coincidir com o host do proxy, eles serão atualizados para que corresponda a ele. Por exemplo, Set-Cookie: key=val; domain=api.commercecloud.com é atualizado para Set-Cookie: key=val; domain=www.northerntrailoutfitters.com.
• Se a resposta contiver um cabeçalho Access-Control-Allow-Origin cujo valor coincida com o host do proxy, ela será atualizada para Access-Control-Allow-Origin: https://www.northerntrailoutfitters.com.

Para testar suas modificações, defina uma configuração de proxy com httpbin.org como o host. Quando você faz uma solicitação por meio deste proxy, ela retorna qualquer cabeçalho que recebe.

Por padrão, as solicitações com proxy são retiradas do cache pela CDN. Esta padrão permite que as solicitações com proxy sejam usadas de maneira transparente em seu código, sem ter que se preocupar com respostas de cache incorretas.

Quando você quiser que uma solicitação com proxy seja armazenada em cache pela CDN, altere o prefixo do caminho em sua solicitação de proxy para caching:

As solicitações de proxy armazenadas em cache diferem das solicitações de proxy padrão da seguinte maneira:

• O cabeçalho HTTP Cookie é removido.

As respostas armazenadas em cache diferem das respostas padrão da seguinte maneira:

• Qualquer cabeçalho HTTP Set-Cookie é removido.

As respostas armazenadas em cache incluem os seguintes cabeçalhos HTTP para que, quando os valores desses cabeçalhos variem, as respostas sejam armazenadas em cache separadamente:

• Accept
• Accept-Charset
• Accept-Encoding
• Accept-Language
• Authorization
• Range

As respostas que incluem outros cabeçalhos HTTP não são armazenadas em cache de maneira separada quando os valores deles variam.

Proxies têm limitações diferentes das do App Server.

• O tempo de execução das solicitações de proxy está limitado a 30 segundos. Se uma resposta da origem não for concluída nesse prazo, a resposta de erro HTTP 504 é retornada.
• A origem deve fornecer um certificado válido e suporte usando TLS 1.2 ou superior, caso contrário, um HTTP 502 será retornado. Você pode verificar se suas origens TLS aceitam usar a ferramenta SSL Labs.
• Não há limite para o tamanho da solicitação ou da resposta.
• As solicitações por proxy podem usar o cabeçalho Cookie. As respostas por proxy podem incluir o cabeçalho Set-Cookie.
• O host por proxy precisa ser endereçável publicamente. Se o host por proxy só estiver acessível de dentro de uma rede privada ou bloqueado como hosts demandware.net, um erro HTTP será retornado.
• O proxy de cache aceita somente os métodos HEAD, GET e OPTIONS. As solicitações POST não são compatíveis.

Agora que você entende como e por que usar proxies em seu aplicativo de comércio, veja a documentação sobre o PWA Kit.