Solicitações de proxy

Com um servidor proxy fornecido pela CDN do Managed Runtime, você pode rotear solicitações a APIs hospedadas em diferentes domínios por meio do mesmo domínio usado por sua loja virtual.

Por que usar o mesmo domínio que sua loja (virtual)? Imagine que sua loja (virtual) esteja hospedada em www.northerntrailoutfitters.com e você quer obter dados de comércio fazendo uma solicitação a 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 os dois enfoques.

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

Para o desenvolvimento local, a principal maneira de configurar proxies é editando o array mobify.ssrParameters.proxyConfigs em <PROJECT_DIR>/config/default.js:

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

• host: o host que recebe suas solicitações, incluindo domínios e subdomínios.
• path: a string usada nos caminhos da sua solicitação para acionar o proxy.
• protocol: o protocolo de rede (http ou https). Opcional (o valor padrão é https).

Para fazer uma solicitação com proxy no código do seu aplicativo, siga este padrão quando criar os caminhos da solicitação: /mobify/proxy/<PROXY_PATH>.

Vejamos um exemplo que usa api como o valor <PROXY_PATH>. Por padrão, todos os projetos criados com o PWA Kit vêm com uma configuração padrão que associa o caminho da api à B2C Commerce API.

Nossa solicitação de exemplo também apresenta duas funções auxiliares para garantir que as solicitações da API funcionem de maneira consistente:

1. getAppOrigin, do PWA Kit React SDK, retorna a origem correta tanto para o ambiente de desenvolvimento local quanto para os ambientes do Managed Runtime.
2. fetch, da bibliotecacross-fetch, lida com as diferenças entre fazer solicitações de rede em um navegador e no Node.js.

Sempre que você modifica sua configuração de proxy durante o desenvolvimento local, você tem que reiniciar o servidor de desenvolvimento local para que essas mudanças se tornem efetivas.

Você tem duas chances de configurar proxies para os ambientes Managed Runtime: usando a ferramenta Runtime Admin ou o 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 na ferramenta 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 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 do Managed Runtime de maneira programática usando o endpoint /target da Managed Runtime API. (A Managed Runtime API geralmente usa o termo “destino” em vez de “ambiente”, mas ambos os termos fazem referência à mesma coisa.

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. Esses objetos de configuração de proxy são definidos com as propriedades host, path e protocol (opcional), da mesma maneira que os arquivos de configuração.

Veja aqui uma solicitação de exemplo que atualiza um ambiente para incluir uma configuração de proxy para o caminho api:

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.

Defina variáveis de ambiente para substituir as configurações de proxy relacionadas ao desenvolvimento local.

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:

Quanto uma solicitação é encaminhada através do servidor proxy, tanto a solicitação quanto a resposta são modificadas para fazer com que funcionem de maneira mais transparente com o código do seu 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 com proxy também encaminham todos os parâmetros de cabeçalhos da string de consulta, incluindo os 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.
• Os hosts com proxy precisam usar a versão 1.2 ou mais recente do protocolo Transport Level Security (TLS) quando protocol for definido como https.
• 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.

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