Trabalho com solicitações e respostas

Para usar as solicitações e as respostas do Lambda@Edge, consulte os seguintes tópicos:

Usar funções do Lambda@Edge com failover de origem

É possível usar as funções do Lambda@Edge com distribuições do CloudFront que você configurou com grupos de origens, por exemplo, para um failover de origem que você configura para ajudar a garantir a alta disponibilidade. Para usar uma função do Lambda com um grupo de origem, especifique a função em um trigger de resposta ou de solicitação de origem para um grupo de origens ao criar o comportamento de cache.

Para obter mais informações, consulte as informações a seguir.

• Criar grupos de origens: Criar um grupo de origem

• Como um failover de origem funciona com o Lambda@Edge: Uso do failover de origem com funções do Lambda@Edge

Gerar respostas de HTTP em acionadores da solicitação

Quando o CloudFront recebe uma solicitação, você pode usar uma função do Lambda para gerar uma resposta HTTP que o CloudFront retornará diretamente ao visualizador sem encaminhar a resposta para a origem. Gerar respostas HTTP reduz a carga na origem e geralmente também reduz a latência para o visualizador.

Alguns cenários comuns para gerar respostas HTTP incluem o seguinte:

• Retornar uma pequena página da web ao visualizador

• Retornar um código de status HTTP 301 ou 302 para redirecionar o usuário para outra página da web

• Retornar um código de status HTTP 401 para o visualizador quando o usuário ainda não tiver sido autenticado

Uma função do Lambda@Edge pode gerar uma resposta HTTP quando ocorrerem os seguintes eventos do CloudFront:

Eventos de solicitação de visualizador

Quando uma função for acionada por um evento de solicitação do visualizador, o CloudFront retornará a resposta ao visualizador e não a armazenará em cache.

Eventos de solicitação de origem

Quando a função for acionada por um evento de solicitação de origem, o CloudFront verificará se há uma resposta gerada anteriormente pela função no cache de borda.

• Se a resposta estiver no cache, a função não será executada e o CloudFront retornará a resposta em cache ao visualizador.

• Se a resposta não estiver no cache, a função será executada, o CloudFront retornará a resposta ao visualizador e também a armazenará em cache.

Para ver códigos de exemplo para gerar respostas HTTP, consulte Funções de exemplo do Lambda@Edge. Você também pode substituir as respostas HTTP em triggers de resposta. Para ter mais informações, consulte Atualizar respostas de HTTP em acionadores de resposta da origem.

Modelo de programação

Esta seção descreve o modelo de programação para usar o Lambda@Edge para gerar respostas HTTP.

Tópicos

• Objeto da resposta
• Erros
• Campos obrigatórios

Objeto da resposta

A resposta que você retornar como o parâmetro result do método callback deverá ter a seguinte estrutura (observe que apenas o campo status é necessário).

const response = {
    body: 'content',
    bodyEncoding: 'text' | 'base64',
    headers: {
        'header name in lowercase': [{
            key: 'header name in standard case',
            value: 'header value'
         }],
         ...
    },
    status: 'HTTP status code (string)',
    statusDescription: 'status description'
};

O objeto de resposta pode incluir os seguintes valores:

body

O corpo, se houver, que você deseja que o CloudFront retorne na resposta gerada.

bodyEncoding

A codificação para o valor que você especificou no body. As únicas codificações válidas são text e base64. Se você incluir body no objeto response, mas omitir bodyEncoding, o CloudFront tratará o corpo como texto.

Se você especificar bodyEncoding como base64, mas o corpo não for um base64 válido, o CloudFront retornará um erro.

headers

Cabeçalhos que você deseja que o CloudFront retorne na resposta gerada. Observe o seguinte:

• As chaves no objeto headers são versões em letras minúsculas de nomes de cabeçalho HTTP padrão. Usar chaves em letras minúsculas dá acesso sem diferenciar letras maiúsculas e minúsculas dos valores de cabeçalho.

• Cada cabeçalho (por exemplo, headers["accept"] ou headers["host"]) é uma matriz de pares de chave-valor. Para determinado cabeçalho, a matriz contém um par de chave-valor para cada valor na resposta gerada.

• key (opcional) é o nome com distinção entre letras maiúsculas e minúsculas do cabeçalho da forma como ele aparece em uma solicitação HTTP, por exemplo, accept ou host.

• Especifique value como valor do cabeçalho.

• Se você não incluir a parte da chave do par de chave-valor do cabeçalho, o Lambda@Edge inserirá automaticamente uma chave de cabeçalho usando o nome de cabeçalho fornecido. Independentemente de como você tiver formatado o nome do cabeçalho, a chave de cabeçalho inserida será automaticamente formatada com o uso de iniciais maiúsculas para cada parte, separada por hífen (-).

  Por exemplo, você pode adicionar um cabeçalho como o seguinte, sem uma chave de cabeçalho: 'content-type': [{ value: 'text/html;charset=UTF-8' }]

  Neste exemplo, o Lambda @ Edge cria a seguinte chave de cabeçalho: Content-Type.

Para obter informações sobre as restrições de uso do cabeçalho, consulte Restrições das funções de borda.

status

Código de status do HTTP. Forneça o código de status como uma string. O CloudFront usa o código de status fornecido para o seguinte:

• Retornar na resposta

• Armazenar no cache de borda do CloudFront, quando a resposta tiver sido gerada por uma função acionada por um evento de solicitação de origem

• Fazer login no CloudFront Configurar e usar logs padrão (logs de acesso)

Se o valor de status não estiver entre 200 e 599, o CloudFront retornará um erro ao visualizador.

statusDescription

A descrição que você deseja que o CloudFront retorne na resposta para acompanhar o código de status HTTP. Você não precisa usar descrições padrão, como OK, para um código de status HTTP de 200.

Erros

Veja a seguir os erros possíveis das respostas HTTP geradas.

A resposta contém um corpo e especifica 204 (sem conteúdo) como status

Quando uma função for acionada por uma solicitação de visualizador, o CloudFront retornará um código de status HTTP 502 (gateway inválido) ao visualizador quando ocorrer o seguinte:

• O valor de status for 204 (sem conteúdo)

• A resposta incluir um valor para body

Isso ocorre porque o Lambda@Edge impõe a restrição opcional encontrada na RFC 2616: uma resposta HTTP 204 não precisa conter um corpo de mensagem.

Restrições ao tamanho da resposta gerada

O tamanho máximo de uma resposta gerada por uma função do Lambda depende do evento que acionou a função:

• Eventos de solicitação de visualizador: 40 KB

• Eventos de solicitação de origem: 1 MB

Se a resposta for maior que o tamanho permitido, o CloudFront retornará um código de status HTTP 502 (gateway inválido) ao visualizador.

Campos obrigatórios

O campo status é obrigatório.

Todos os demais campos são opcionais.

Atualizar respostas de HTTP em acionadores de resposta da origem

Quando o CloudFront recebe uma resposta HTTP do servidor de origem, se houver um trigger de resposta de origem associado ao comportamento de cache, você poderá modificar a resposta HTTP para substituir o que foi retornado pela origem.

Alguns cenários comuns para atualizar respostas HTTP incluem o seguinte:

• Alterar o status para definir um código de status HTTP 200 e a criação de conteúdo estático do corpo para retornar ao visualizador quando uma origem retornar um código de status de erro (4xx ou 5xx). Para obter o código de exemplo, consulte Exemplo: usar um acionador de resposta de origem para atualizar o código do status de erro para 200.

• Alterar o status para definir um código de status HTTP 301 ou 302, de forma a redirecionar o usuário para outro site quando uma origem retornar um código de status de erro (4xx ou 5xx). Para obter o código de exemplo, consulte Exemplo: usar um acionador de resposta de origem para atualizar o código do status de erro para 302.

nota

A função deve retornar um valor de status entre 200 e 599 (inclusive); do contrário, o CloudFront retornará um erro ao visualizador.

Você também pode substituir as respostas HTTP em eventos de solicitação do visualizador e da origem. Para ter mais informações, consulte Gerar respostas de HTTP em acionadores da solicitação.

Ao trabalhar com a resposta de HTTP, o Lambda@Edge não expõe o corpo retornado pelo servidor de origem ao acionador da resposta de origem. Você pode gerar um corpo de conteúdo estático definindo-o no valor desejado ou removendo o corpo de dentro da função ao definir o valor como vazio. Se você não atualizar o campo do corpo na função, o corpo original retornado pelo servidor de origem será reapresentado ao visualizador.

Acessar o corpo da solicitação escolhendo a opção de incluir o corpo

Você pode optar por fazer com que o Lambda@Edge exponha o corpo em uma solicitação para métodos HTTP graváveis (POST, PUT, DELETE e assim por diante), para que seja possível acessá-lo na função do Lambda. Você pode escolher acesso somente leitura ou especificar que substituirá o corpo.

Para ativar essa opção, escolha Include Body (Incluir corpo) ao criar um trigger do CloudFront para sua função que seja para um evento de solicitação de visualizador ou de origem. Para obter mais informações, consulte Adicionar acionadores para uma função do Lambda@Edge ou, para saber como usar a opção Include Body (Incluir corpo) com a função, consulte Estrutura de eventos do Lambda@Edge.

Os cenários em que você pode querer usar esse recurso incluem:

• Processamento de formulários da web, como formulários "entre em contato conosco", sem enviar dados de entrada do cliente de volta aos servidores de origem.

• Reunir dados de web beacons enviados por navegadores dos visualizadores e processá-los no ponto.

Para obter o código de exemplo, consulte Funções de exemplo do Lambda@Edge.

nota

Se o corpo da solicitação for grande, o Lambda@Edge o truncará. Para obter informações detalhadas sobre truncamento e tamanho máximo, consulte Restrições do corpo da solicitação com a opção de incluir corpo.