Estrutura de eventos do Lambda@Edge - Amazon CloudFront
Seleção de origem dinâmicaEventos de solicitaçãoEventos de resposta

Estrutura de eventos do Lambda@Edge

Os tópicos a seguir descrevem os objetos de eventos de solicitação e resposta que o CloudFront passa para uma função do Lambda@Edge quando ela é acionada.

Seleção de origem dinâmica

Você pode usar o padrão do caminho em um comportamento de cache para rotear as solicitações para uma origem, de acordo com o caminho e o nome do objeto solicitado, como images/*.jpg. Usando o Lambda@Edge, você também pode rotear as solicitações para uma origem com base em outras características, como os valores nos cabeçalhos de solicitação.

Essa seleção de origem dinâmica pode ser útil de várias maneiras. Por exemplo, você pode distribuir solicitações em origens em diferentes áreas geográficas para ajudar com o balanceamento de carga global. Ou você pode seletivamente rotear solicitações para diferentes origens que cada servir uma determinada função: manuseio de bot, otimização de SEO, autenticação, e assim por diante. Para obter exemplos de código que demonstram como usar esse recurso, consulte Seleção de origem dinâmica baseada em conteúdo: exemplos.

No evento de solicitação de origem do CloudFront, o objeto origin na estrutura do evento contém informações sobre a origem para a qual a solicitação seria roteada, de acordo com o padrão de caminho. Você pode atualizar os valores no objeto origin para rotear uma solicitação para outra origem. Quando você atualiza o objeto origin, não precisa definir a origem na distribuição. Também é possível substituir um objeto de origem do Amazon S3 por um objeto de origem personalizado e vice-versa. No entanto, só é possível especificar uma única origem por solicitação; uma origem personalizada ou uma origem do Amazon S3, mas não ambas.

Eventos de solicitação

Os tópicos a seguir mostram a estrutura do objeto que o CloudFront passa para uma função do Lambda para eventos de solicitação do visualizador e da origem. Estes exemplos mostram uma solicitação GET sem corpo. Após os exemplos, está uma lista de todos os campos possíveis em eventos de solicitação de visualizador e origem.

Exemplo de solicitação de visualizador

O exemplo a seguir mostra um objeto de evento de solicitação de visualizador.

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "viewer-request",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "host": [
              {
                "key": "Host",
                "value": "d111111abcdef8.cloudfront.net"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "curl/7.66.0"
              }
            ],
            "accept": [
              {
                "key": "accept",
                "value": "*/*"
              }
            ]
          },
          "method": "GET",
          "querystring": "",
          "uri": "/"
        }
      }
    }
  ]
}

Exemplo de solicitação de origem

O exemplo a seguir mostra um objeto de evento de solicitação de origem.

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "origin-request",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "x-forwarded-for": [
              {
                "key": "X-Forwarded-For",
                "value": "203.0.113.178"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "Amazon CloudFront"
              }
            ],
            "via": [
              {
                "key": "Via",
                "value": "2.0 2afae0d44e2540f472c0635ab62c232b.cloudfront.net (CloudFront)"
              }
            ],
            "host": [
              {
                "key": "Host",
                "value": "example.org"
              }
            ],
            "cache-control": [
              {
                "key": "Cache-Control",
                "value": "no-cache"
              }
            ]
          },
          "method": "GET",
          "origin": {
            "custom": {
              "customHeaders": {},
              "domainName": "example.org",
              "keepaliveTimeout": 5,
              "path": "",
              "port": 443,
              "protocol": "https",
              "readTimeout": 30,
              "sslProtocols": [
                "TLSv1",
                "TLSv1.1",
                "TLSv1.2"
              ]
            }
          },
          "querystring": "",
          "uri": "/"
        }
      }
    }
  ]
}

Campos de eventos de solicitação

Os dados do objeto de evento de solicitação estão contidos em dois subobjetos: config (Records.cf.config) e request (Records.cf.request). As listas a seguir descrevem os campos de cada subobjeto.

Campos no objeto de configuração

A lista a seguir descreve os campos no objeto config (Records.cf.config).

distributionDomainName (somente leitura)

O nome de domínio da distribuição associada à solicitação.

distributionID (somente leitura)

O ID da distribuição associada à solicitação.

eventType (somente leitura)

O tipo de acionador associado à solicitação: viewer-request ou origin-request.

requestId (somente leitura)

Uma string criptografada que identifica exclusivamente uma solicitação do visualizador ao CloudFront. O valor de requestId também aparece nos logs de acesso do CloudFront como x-edge-request-id. Para obter mais informações, consulte Configurar e usar logs padrão (logs de acesso) e Campos padrão de arquivo de log.

Campos no objeto de solicitação

A lista a seguir descreve os campos no objeto request (Records.cf.request).

clientIp (somente leitura)

O endereço IP do visualizador que fez a solicitação. Se o visualizador usar um proxy HTTP ou um load balancer para enviar a solicitação, o valor será o endereço IP do proxy ou do load balancer.

Cabeçalhos
(leitura/gravação)

Os cabeçalhos na solicitação. 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 objeto de cabeçalho (por exemplo, headers["accept"] ou headers["host"]) é uma matriz de pares de chave-valor. Para um determinado cabeçalho, a matriz contém um par de chave-valor para cada valor na solicitação.

  • key contém o nome do cabeçalho com distinção entre maiúsculas e minúsculas conforme ele apareceu na solicitação HTTP; por exemplo, Host, User-Agent, X-Forwarded-For e assim por diante.

  • value contém o valor do cabeçalho conforme ele apareceu na solicitação HTTP.

  • Quando a função do Lambda adicionar ou modificar cabeçalhos de solicitação e você não incluir o campo key do cabeçalho, o Lambda@Edge inserirá automaticamente uma key de cabeçalho usando o nome de cabeçalho que você fornecer. Independentemente de como você tiver formatado o nome do cabeçalho, a chave de cabeçalho inserida automaticamente será formatada com inicial maiúscula para cada parte, separada por hifens (-).

    Por exemplo, você pode adicionar um cabeçalho como o seguinte, sem um key de cabeçalho:

    "user-agent": [
  {
    "value": "ExampleCustomUserAgent/1.X.0"
  }
]

    Neste exemplo, o Lambda@Edge insere automaticamente "key": "User-Agent".

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

method (somente leitura)

O método HTTP da solicitação.

querystring (leitura/gravação)

A string de consulta, se houver, na solicitação. Se a solicitação não incluir uma string de consulta, o objeto de evento ainda incluirá querystring com um valor vazio. Para obter mais informações sobre query strings, consulte Conteúdo em cache com base em parâmetros de string de consulta.

uri (leitura/gravação)

O caminho relativo do objeto solicitado. Se a função do Lambda modificar o valor uri, observe o seguinte:

  • O novo valor uri deve começar com uma barra (/).

  • Se uma função alterar o valor uri, isso alterará o objeto solicitado pelo visualizador.

  • Se uma função alterar o valor uri, isso não mudará o comportamento do cache da solicitação ou da origem para a qual a solicitação é enviada.

body (leitura/gravação)

O corpo da solicitação HTTP. A estrutura body pode conter os seguintes campos:

inputTruncated (somente leitura)

Um sinalizador booliano que indica se o corpo foi truncado pelo Lambda@Edge. Para ter mais informações, consulte Restrições do corpo da solicitação com a opção de incluir corpo.

action (leitura/gravação)

A ação que você pretende realizar com o corpo. As opções para action são as seguintes:

  • read-only: esse é o padrão. Ao retornar a resposta da função do Lambda, se action for somente leitura, o Lambda@Edge ignorará todas as alterações em encoding ou em data.

  • replace: especifique isso quando quiser substituir o corpo enviado à origem.

encoding (leitura/gravação)

A codificação do corpo. Ao expor o corpo à função do Lambda, o Lambda@Edge primeiro converte o corpo em base64-encoding. Se você escolher replace para action substituir o corpo, poderá optar por usar a codificação base64 (padrão) ou text. Se você especificar encoding como base64, mas o corpo não for um base64 válido, o CloudFront retornará um erro.

data (leitura/gravação)

O conteúdo do corpo da solicitação.

origin (leitura/gravação) (somente eventos de origem)

A origem para a qual enviar a solicitação. A estrutura de origin deve conter exatamente uma origem, que pode ser uma origem personalizada ou uma origem do Amazon S3. A estrutura de origem pode conter os seguintes campos:

customHeaders (leitura/gravação) (origens personalizadas e do Amazon S3)

Você pode incluir os cabeçalhos personalizados com a solicitação ao especificar o par de nome e valor do cabeçalho para cada cabeçalho personalizado. Não é possível adicionar cabeçalhos não permitidos, e não pode haver um cabeçalho com o mesmo nome em Records.cf.request.headers. As notas sobre cabeçalhos de solicitação também se aplicam a cabeçalhos personalizados. Para obter mais informações, consulte Cabeçalhos personalizados que o CloudFront não pode adicionar às solicitações da origem e Restrições das funções de borda.

domainName (leitura/gravação) (origens personalizadas e do Amazon S3)

O nome de domínio da origem. O nome de domínio não pode estar vazio.

  • Para origens personalizadas — especifique um nome de domínio DNS, como www.example.com. O nome de domínio não pode incluir dois-pontos (:) e não pode ser um endereço IP. O nome de domínio pode ter até 253 caracteres.

  • Para origens do Amazon S3: especifique o nome de domínio DNS do bucket do Amazon S3, como awsexamplebucket.s3.eu-west-1.amazonaws.com. O nome pode ter até 128 caracteres e deve ser todo em minúsculas.

path (leitura/gravação) (origens personalizadas e do Amazon S3)

O caminho do diretório na origem em que a solicitação deve localizar o conteúdo. O caminho deve começar com uma barra (/), mas não deve terminar com uma (por exemplo, não deve terminar com example-path/). Apenas para origens personalizadas, o caminho deve ser codificado por URL e ter um comprimento máximo de 255 caracteres.

keepaliveTimeout (leitura/gravação) (somente origens personalizadas)

O tempo, em segundos, durante o qual o CloudFront deve tentar manter a conexão com a origem depois de receber o último pacote da resposta. O valor deve ser um número de 1 a 60, inclusive.

port (leitura/gravação) (somente origens personalizadas)

A porta à qual o CloudFront deve se conectar em sua origem personalizada. A porta deve ser 80, 443 ou um número no intervalo de 1024 a 65535, inclusive.

protocol (leitura/gravação) (somente origens personalizadas)

O protocolo de conexão que o CloudFront deve usar ao se conectar à sua origem. O valor pode ser http ou https.

readTimeout (leitura/gravação) (somente origens personalizadas)

O tempo, em segundos, que o CloudFront deve esperar por uma resposta depois de enviar uma solicitação à origem. Isso também especifica o tempo que o CloudFront deve aguardar depois de receber um pacote de resposta antes de receber o próximo pacote. O valor deve ser um número de 4 a 60, inclusive.

Se seu caso de uso exigir mais de 60 segundos, você poderá solicitar uma cota maior para Response timeout per origin. Para ter mais informações, consulte Cotas gerais para distribuições.

sslProtocols (leitura/gravação) (somente origens personalizadas)

O protocolo SSL/TLS mínimo que o CloudFront pode usar ao estabelecer uma conexão HTTPS com a origem. Os valores podem ser qualquer um dos seguintes: TLSv1.2, TLSv1.1, TLSv1 ou SSLv3.

authMethod (leitura/gravação) (somente origens do Amazon S3)

Se você estiver usando uma identidade do acesso de origem (OAI), defina esse campo como origin-access-identity. Se você não estiver usando uma OAI, defina-o como none. Se você definir authMethod como origin-access-identity, haverá vários requisitos:

  • Você deve especificar region (consulte o campo a seguir).

  • Use o mesmo OAI ao alterar a solicitação de uma origem do Amazon S3 para outra.

  • Não é possível usar uma OAI ao alterar a solicitação de uma origem personalizada para uma origem do Amazon S3.

nota

Esse campo não aceita controle de acesso à origem (OAC).

region (leitura/gravação) (somente origens do Amazon S3)

A região da AWS do bucket do Amazon S3. Isso é necessário apenas quando você define authMethod como origin-access-identity.

Eventos de resposta

Os tópicos a seguir mostram a estrutura do objeto que o CloudFront passa para uma função do Lambda para eventos de resposta do visualizador e da origem. Após os exemplos, está uma lista de todos os campos possíveis em eventos de resposta do visualizador e da origem.

Exemplo de resposta da origem

O exemplo a seguir mostra um objeto de evento de resposta da origem.

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "origin-response",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "x-forwarded-for": [
              {
                "key": "X-Forwarded-For",
                "value": "203.0.113.178"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "Amazon CloudFront"
              }
            ],
            "via": [
              {
                "key": "Via",
                "value": "2.0 8f22423015641505b8c857a37450d6c0.cloudfront.net (CloudFront)"
              }
            ],
            "host": [
              {
                "key": "Host",
                "value": "example.org"
              }
            ],
            "cache-control": [
              {
                "key": "Cache-Control",
                "value": "no-cache"
              }
            ]
          },
          "method": "GET",
          "origin": {
            "custom": {
              "customHeaders": {},
              "domainName": "example.org",
              "keepaliveTimeout": 5,
              "path": "",
              "port": 443,
              "protocol": "https",
              "readTimeout": 30,
              "sslProtocols": [
                "TLSv1",
                "TLSv1.1",
                "TLSv1.2"
              ]
            }
          },
          "querystring": "",
          "uri": "/"
        },
        "response": {
          "headers": {
            "access-control-allow-credentials": [
              {
                "key": "Access-Control-Allow-Credentials",
                "value": "true"
              }
            ],
            "access-control-allow-origin": [
              {
                "key": "Access-Control-Allow-Origin",
                "value": "*"
              }
            ],
            "date": [
              {
                "key": "Date",
                "value": "Mon, 13 Jan 2020 20:12:38 GMT"
              }
            ],
            "referrer-policy": [
              {
                "key": "Referrer-Policy",
                "value": "no-referrer-when-downgrade"
              }
            ],
            "server": [
              {
                "key": "Server",
                "value": "ExampleCustomOriginServer"
              }
            ],
            "x-content-type-options": [
              {
                "key": "X-Content-Type-Options",
                "value": "nosniff"
              }
            ],
            "x-frame-options": [
              {
                "key": "X-Frame-Options",
                "value": "DENY"
              }
            ],
            "x-xss-protection": [
              {
                "key": "X-XSS-Protection",
                "value": "1; mode=block"
              }
            ],
            "content-type": [
              {
                "key": "Content-Type",
                "value": "text/html; charset=utf-8"
              }
            ],
            "content-length": [
              {
                "key": "Content-Length",
                "value": "9593"
              }
            ]
          },
          "status": "200",
          "statusDescription": "OK"
        }
      }
    }
  ]
}

Exemplo de resposta do visualizador

O exemplo a seguir mostra um objeto de evento de resposta do visualizador.

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "viewer-response",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "host": [
              {
                "key": "Host",
                "value": "d111111abcdef8.cloudfront.net"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "curl/7.66.0"
              }
            ],
            "accept": [
              {
                "key": "accept",
                "value": "*/*"
              }
            ]
          },
          "method": "GET",
          "querystring": "",
          "uri": "/"
        },
        "response": {
          "headers": {
            "access-control-allow-credentials": [
              {
                "key": "Access-Control-Allow-Credentials",
                "value": "true"
              }
            ],
            "access-control-allow-origin": [
              {
                "key": "Access-Control-Allow-Origin",
                "value": "*"
              }
            ],
            "date": [
              {
                "key": "Date",
                "value": "Mon, 13 Jan 2020 20:14:56 GMT"
              }
            ],
            "referrer-policy": [
              {
                "key": "Referrer-Policy",
                "value": "no-referrer-when-downgrade"
              }
            ],
            "server": [
              {
                "key": "Server",
                "value": "ExampleCustomOriginServer"
              }
            ],
            "x-content-type-options": [
              {
                "key": "X-Content-Type-Options",
                "value": "nosniff"
              }
            ],
            "x-frame-options": [
              {
                "key": "X-Frame-Options",
                "value": "DENY"
              }
            ],
            "x-xss-protection": [
              {
                "key": "X-XSS-Protection",
                "value": "1; mode=block"
              }
            ],
            "age": [
              {
                "key": "Age",
                "value": "2402"
              }
            ],
            "content-type": [
              {
                "key": "Content-Type",
                "value": "text/html; charset=utf-8"
              }
            ],
            "content-length": [
              {
                "key": "Content-Length",
                "value": "9593"
              }
            ]
          },
          "status": "200",
          "statusDescription": "OK"
        }
      }
    }
  ]
}

Campos de evento de resposta

Os dados do objeto de evento de resposta estão contidos em três subobjetos: config (Records.cf.config), request (Records.cf.request) e response (Records.cf.response). Para obter mais informações sobre os campos no objeto da solicitação, consulte Campos no objeto de solicitação. As listas a seguir descrevem os campos nos subobjetos config e response.

Campos no objeto de configuração

A lista a seguir descreve os campos no objeto config (Records.cf.config).

distributionDomainName (somente leitura)

O nome de domínio da distribuição associada à resposta.

distributionID (somente leitura)

O ID da distribuição associada à resposta.

eventType (somente leitura)

O tipo de acionador associado à resposta: origin-response ou viewer-response.

requestId (somente leitura)

Uma string criptografada que identifica exclusivamente a solicitação do visualizador ao CloudFront à qual esta resposta está associada. O valor de requestId também aparece nos logs de acesso do CloudFront como x-edge-request-id. Para obter mais informações, consulte Configurar e usar logs padrão (logs de acesso) e Campos padrão de arquivo de log.

Campos no objeto de resposta

A lista a seguir descreve os campos no objeto response (Records.cf.response). Para obter informações sobre como usar uma função do Lambda@Edge para gerar uma resposta HTTP, consulte Gerar respostas de HTTP em acionadores da solicitação.

headers (leitura/gravação)

Os cabeçalhos na resposta. 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 objeto de cabeçalho (por exemplo, headers["content-type"] ou headers["content-length"]) é 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.

  • key contém o nome do cabeçalho com distinção entre maiúsculas e minúsculas conforme aparece na resposta HTTP; por exemplo, Content-Type, Content-Length, Cookie, e assim por diante.

  • value contém o valor do cabeçalho como ele aparece na resposta HTTP.

  • Quando a função do Lambda adicionar ou modificar cabeçalhos de resposta e você não incluir o campo key do cabeçalho, o Lambda@Edge inserirá automaticamente uma key de cabeçalho usando o nome de cabeçalho que você fornecer. Independentemente de como você tiver formatado o nome do cabeçalho, a chave de cabeçalho inserida automaticamente será formatada com inicial maiúscula para cada parte, separada por hifens (-).

    Por exemplo, você pode adicionar um cabeçalho como o seguinte, sem um key de cabeçalho:

    "content-type": [
  {
    "value": "text/html;charset=UTF-8"
  }
]

    Neste exemplo, o Lambda@Edge insere automaticamente "key": "Content-Type".

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

status

O código de status HTTP da resposta.

statusDescription

A descrição do status HTTP da resposta.