Estrutura de eventos do CloudFront Functions

O CloudFront Functions passa um objeto event para o seu código de função como entrada quando executa a função. Quando você testa uma função, você cria o objeto event e o passa para sua função. Quando você cria um objeto event para testar uma função, você pode omitir os campos distributionDomainName, distributionId e requestId no objeto context Certifique-se de que os nomes de cabeçalhos estejam em letras minúsculas, o que sempre é o caso no objeto event que o CloudFront Functions passa para sua função na produção.

Segue uma visão geral da estrutura desse objeto de evento.

{
    "version": "1.0",
    "context": {
        <context object>
    },
    "viewer": {
        <viewer object>
    },
    "request": {
        <request object>
    },
    "response": {
        <response object>
    }
}

Para obter mais informações, consulte os tópicos a seguir.

Campo de versão

O campo version contém uma cadeia de caracteres que especifica a versão do objeto de evento do CloudFront Functions. A versão atual é 1.0.

Objeto de contexto

O objeto context contém informações contextuais sobre o evento. Isso inclui os seguintes campos:

Objeto do visualizador

O objeto viewer contém um campo ip cujo valor é o endereço IP do visualizador (cliente) que enviou a solicitação. Se o visualizador usar um proxy HTTP ou um balanceador de carga para enviar a solicitação, o valor será o endereço IP do proxy ou do balanceador de carga.

Objeto de solicitação

O objeto request contém uma representação de uma solicitação HTTP Viewer-to-CloudFront. No objeto event passado para a função, o objeto request representa a solicitação real que o CloudFront recebeu do visualizador.

Se o código de função retornar um objeto request ao CloudFront, ele deverá usar essa mesma estrutura.

O objeto request contém os campos a seguir.

Para obter mais informações sobre a estrutura de cadeias de consulta, cabeçalhos e cookies, consulte Estrutura de uma string de consulta, um cabeçalho ou um cookie.

Para obter um objeto event de exemplo, consulte Exemplo de objeto de evento.

Objeto da resposta

O objeto response contém uma representação de uma resposta HTTP do CloudFront-to-viewer. No objeto event passado para a função, o objeto response representa a resposta real do CloudFront a uma solicitação de visualizador.

Se seu código de função retornar um objeto response, ele deverá usar essa mesma estrutura.

O objeto response contém os campos a seguir.

Para obter mais informações sobre códigos de status modificados e conteúdo do corpo, consulte Código de status e corpo.

Para obter mais informações sobre a estrutura de cabeçalhos e cookies, consulte Estrutura de uma string de consulta, um cabeçalho ou um cookie.

Para obter um objeto response de exemplo, consulte Exemplo de objeto de resposta.

Código de status e corpo

Com o CloudFront Functions, é possível atualizar o código de status da resposta do visualizador, substituir todo o corpo da resposta por um novo ou remover o corpo da resposta. Alguns cenários comuns para atualizar a resposta do visualizador após avaliar os aspectos da resposta do cache ou da origem do CloudFront incluem o seguinte:

Ao trabalhar com a resposta HTTP, o CloudFront Functions não tem acesso ao corpo da resposta. É possível substituir o conteúdo estático do corpo definindo-o como o valor desejado ou remover o corpo definindo o valor como vazio. Se você não atualizar o campo do corpo na função, o corpo original retornado pelo cache do CloudFront será retornado ao visualizador.

Se a sua função do CloudFront estiver configurada para retornar um erro HTTP de 400 ou superior, seu visualizador não verá uma página de erro personalizada que você especificou para o mesmo código de status.

Estrutura de uma string de consulta, um cabeçalho ou um cookie

Strings de consulta, cabeçalhos e cookies compartilham a mesma estrutura. As strings de consulta podem aparecer em solicitações. Os cabeçalhos aparecem em solicitações e respostas. Os cookies aparecem em solicitações e respostas.

Cada cadeia de consulta, cabeçalho ou cookie é um campo exclusivo dentro do objeto pai querystring, headers ou cookies. O nome do campo é o nome da cadeia de consulta, cabeçalho ou cookies. Cada campo contém uma propriedade value com o valor da cadeia de consulta, cabeçalho ou cookie.

Valores de string de consulta ou objetos de string de consulta

Uma função pode gerar um valor além de um objeto de string de consulta. O valor de string de consulta pode ser usado para organizar os parâmetros da string de consulta em qualquer ordem personalizada.

var request = event.request; 
request.querystring = 'ID=42&Exp=1619740800&TTL=1440&NoValue=&querymv=val1&querymv=val2,val3';

Considerações especiais sobre cabeçalhos

Somente para cabeçalhos, os nomes de cabeçalho são convertidos em letras minúsculas no objeto do evento, e os nomes de cabeçalho devem estar em letras minúsculas quando forem adicionados pelo código da função. Quando o CloudFront Functions converte o objeto de evento novamente em uma solicitação ou resposta HTTP, a primeira letra de toda palavra em nomes de cabeçalho é maiúscula. As palavras são separadas por hífen (-). Por exemplo, se o código da função adicionar um cabeçalho chamado example-header-name, o CloudFront o converterá em Example-Header-Name na solicitação ou resposta HTTP.

Host: video.example.com

"headers": {
    "host": {
        "value": "video.example.com"
    }
}

var request = event.request;
var host = request.headers.host.value;

var request = event.request;
request.headers['x-custom-header'] = {value: 'example value'};

Duplicar cadeias de consulta, cabeçalhos e cookies (matriz multiValue)

Uma solicitação ou resposta HTTP pode conter mais de uma cadeia de consulta, cabeçalho ou cookie com o mesmo nome. Nesse caso, as cadeias de consulta duplicadas, cabeçalhos ou cookies são recolhidos em um campo no objeto request ou response, mas esse campo contém uma propriedade extra chamada multiValue. A propriedade multiValue contém uma matriz com os valores de cada uma das cadeias de consulta duplicadas, cabeçalhos ou cookies.

Accept: application/json
Accept: application/xml
Accept: text/html

"headers": {
    "accept": {
        "value": "application/json",
        "multiValue": [
            {
                "value": "application/json"
            },
            {
                "value": "application/xml"
            },
            {
                "value": "text/html"
            }
        ]
    }
}

Se o código de função modificar uma string de consulta, um cabeçalho ou um cookie com uma matriz multiValue, o CloudFront Functions usará as seguintes regras para aplicar as alterações:

A propriedade multiValue é usada somente quando a solicitação ou resposta HTTP contém cadeias de consulta duplicadas, cabeçalhos ou cookies com o mesmo nome, como mostrado no exemplo anterior. No entanto, se houver vários valores em uma única cadeia de consulta, cabeçalho ou cookie, a propriedade multiValue não será usada.

Accept: application/json, application/xml, text/html

"headers": {
    "accept": {
        "value": "application/json, application/xml, text/html"
    }
}

Atributos de cookies

Em um cabeçalho Set-Cookie em uma resposta HTTP, o cabeçalho contém o par nome-valor para o cookie e, opcionalmente, um conjunto de atributos separados por ponto-e-vírgula.

Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT

"cookie1": {
    "value": "val1",
    "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
}

Exemplo de objeto de resposta

O exemplo a seguir mostra um objeto response, a saída de uma função de resposta do visualizador, no qual o corpo foi substituído por uma função de resposta do visualizador.

{
  "response": {
    "statusCode": 200,
    "statusDescription": "OK",
    "headers": {
      "date": {
        "value": "Mon, 04 Apr 2021 18:57:56 GMT"
      },
      "server": {
        "value": "gunicorn/19.9.0"
      },
      "access-control-allow-origin": {
        "value": "*"
      },
      "access-control-allow-credentials": {
        "value": "true"
      },
      "content-type": {
        "value": "text/html"
      },
      "content-length": {
        "value": "86"
      }
    },
    "cookies": {
      "ID": {
        "value": "id1234",
        "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT"
      },
      "Cookie1": {
        "value": "val1",
        "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT",
        "multiValue": [
          {
            "value": "val1",
            "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
          },
          {
            "value": "val2",
            "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT"
          }
        ]
      }
    },
    
    // Adding the body field is optional and it will not be present in the response object
    // unless you specify it in your function.
    // Your function does not have access to the original body returned by the CloudFront
    // cache or origin.
    // If you don't specify the body field in your viewer response function, the original
    // body returned by the CloudFront cache or origin is returned to viewer.

     "body": {
      "encoding": "text",
      "data": "<!DOCTYPE html><html><body><p>Here is your custom content.</p></body></html>"
    }
  }
}

Exemplo de objeto de evento

O exemplo a seguir mostra um objeto event completo.

{
    "version": "1.0",
    "context": {
        "distributionDomainName": "d111111abcdef8.cloudfront.net",
        "distributionId": "EDFDVBD6EXAMPLE",
        "eventType": "viewer-response",
        "requestId": "EXAMPLEntjQpEXAMPLE_SG5Z-EXAMPLEPmPfEXAMPLEu3EqEXAMPLE=="
    },
    "viewer": {"ip": "198.51.100.11"},
    "request": {
        "method": "GET",
        "uri": "/media/index.mpd",
        "querystring": {
            "ID": {"value": "42"},
            "Exp": {"value": "1619740800"},
            "TTL": {"value": "1440"},
            "NoValue": {"value": ""},
            "querymv": {
                "value": "val1",
                "multiValue": [
                    {"value": "val1"},
                    {"value": "val2,val3"}
                ]
            }
        },
        "headers": {
            "host": {"value": "video.example.com"},
            "user-agent": {"value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:83.0) Gecko/20100101 Firefox/83.0"},
            "accept": {
                "value": "application/json",
                "multiValue": [
                    {"value": "application/json"},
                    {"value": "application/xml"},
                    {"value": "text/html"}
                ]
            },
            "accept-language": {"value": "en-GB,en;q=0.5"},
            "accept-encoding": {"value": "gzip, deflate, br"},
            "origin": {"value": "https://website.example.com"},
            "referer": {"value": "https://website.example.com/videos/12345678?action=play"},
            "cloudfront-viewer-country": {"value": "GB"}
        },
        "cookies": {
            "Cookie1": {"value": "value1"},
            "Cookie2": {"value": "value2"},
            "cookie_consent": {"value": "true"},
            "cookiemv": {
                "value": "value3",
                "multiValue": [
                    {"value": "value3"},
                    {"value": "value4"}
                ]
            }
        }
    },
    "response": {
        "statusCode": 200,
        "statusDescription": "OK",
        "headers": {
            "date": {"value": "Mon, 04 Apr 2021 18:57:56 GMT"},
            "server": {"value": "gunicorn/19.9.0"},
            "access-control-allow-origin": {"value": "*"},
            "access-control-allow-credentials": {"value": "true"},
            "content-type": {"value": "application/json"},
            "content-length": {"value": "701"}
        },
        "cookies": {
            "ID": {
                "value": "id1234",
                "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT"
            },
            "Cookie1": {
                "value": "val1",
                "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT",
                "multiValue": [
                    {
                        "value": "val1",
                        "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
                    },
                    {
                        "value": "val2",
                        "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT"
                    }
                ]
            }
        }
    }
}