Seleção de origem dinâmica Eventos de solicitação Eventos de resposta

Estrutura de eventos do Lambda@Edge

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

Tópicos

Seleção de origem dinâmica
Eventos de solicitação
Eventos de resposta

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 CloudFront origem, o origin objeto na estrutura do evento contém informações sobre a origem para a qual a solicitação seria roteada, com base no padrão do 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 CloudFront passa para uma função Lambda para eventos de solicitação de visualização e 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 requestId também aparece nos logs de acesso do CloudFront, como x-edge-request-id. Para obter mais informações, consulte Campos padrão de arquivo de log e Configurar e usar logs padrão (logs de acesso).

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 Armazenar em cache o conteúdo 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 Restrições das funções de borda e Cabeçalhos personalizados que não CloudFront podem ser adicionados às solicitações de origem.

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)

Por quanto tempo, em segundos, ele CloudFront deve tentar manter a conexão com a origem após 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 CloudFront você 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 CloudFront deve ser usado ao se conectar à sua origem. O valor pode ser http ou https.

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

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

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

O protocolo SSL/TLS mínimo que CloudFront você pode usar ao estabelecer uma conexão HTTPS com sua 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 CloudFront passa para uma função 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.

Tópicos

Exemplo de resposta da origem
Exemplo de resposta do visualizador
Campos de evento de resposta

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 sequência de caracteres criptografada que identifica de forma exclusiva o visualizador a ser CloudFront solicitado ao qual essa resposta está associada. O requestId valor também aparece nos registros de CloudFront acesso comox-edge-request-id. Para obter mais informações, consulte Campos padrão de arquivo de log e Configurar e usar logs padrão (logs de acesso).

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 Geração de respostas de HTTP ems 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 solicitação HTTP; por exemplo, Content-Type, Content-Length 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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Exclusão de funções e réplicas

Trabalho com solicitações e respostas