Estrutura de eventos do CloudFront Functions - Amazon CloudFront

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 Além disso, 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. Para obter mais informações, consulte os tópicos a seguir.

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

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:

distributionDomainName

O nome de domínio do CloudFront (por exemplo, d111111abcdef8.cloudfront.net) da distribuição associada ao evento.

distributionId

O ID da distribuição (por exemplo, EDFDVBD6EXAMPLE) que está associado ao evento.

eventType

O tipo de evento, viewer-request ou viewer-response.

requestId

Uma cadeia de caracteres que identifica exclusivamente uma solicitação do CloudFront (e sua resposta associada).

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 sua 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.

method

O método HTTP da solicitação. Se o seu código de função retornar um request, ele não poderá modificar este campo. Este é o único campo somente leitura no objeto request.

uri

O caminho relativo do objeto solicitado. Se a sua função 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 de origem é enviada.

querystring

Um objeto que representa a cadeia de consulta na solicitação. Se a solicitação não inclui uma cadeia de consulta, o objeto request ainda incluirá um objeto querystring vazio.

O objeto querystring contém um campo para cada parâmetro de cadeia de consulta na solicitação.

headers

Um objeto que representa os cabeçalhos HTTP na solicitação. Se a solicitação contiver quaisquer cabeçalhos Cookie, esses cabeçalhos não farão parte do obejto headers. Os cookies são representados separadamente no objeto cookies.

O objeto headers contém um campo para cada cabeçalho na solicitação. Os nomes de cabeçalho são convertidos em letras minúsculas no objeto do evento, e os nomes de cabeçalho devem ser minúsculos quando são adicionados pelo código de função. Quando o CloudFront Functions converte o objeto de evento novamente em uma solicitação 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 HTTP.

cookies

Um objeto que representa os cookies na solicitação (cabeçalhos Cookie).

O objeto cookies contém um campo para cada cookie na solicitação.

Para obter mais informações sobre a estrutura de cadeias de consulta, cabeçalhos e cookies, consulte Cadeia de consulta, cabeçalho e estrutura de cookies.

Para obter um objeto event de exemplo, consulte Evento de exemplo.

Objeto da resposta

O objeto response contém uma representação de uma resposta HTTP do CloudFront-to-viewer. No objeto event passado para sua 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.

statusCode

O código de status HTTP da resposta. Esse valor é um inteiro, não uma cadeia de caracteres.

Se a função estiver associada a um tipo de evento de resposta do visualizador, seu código de função não poderá alterar o statusCode que recebeu. Se a função estiver associada a um tipo de evento de solicitação de visualizador e gerar uma resposta HTTP, seu código de função poderá definir o statusCode.

statusDescription

A descrição do status HTTP da resposta. Se o seu código de função gerar uma resposta, esse campo será opcional.

headers

Um objeto que representa os cabeçalhos HTTP na resposta. Se a resposta contiver quaisquer cabeçalhos Set-Cookie, esses cabeçalhos não farão parte do objeto headers. Os cookies são representados separadamente no objeto cookies.

O objeto headers contém um campo para cada cabeçalho na resposta. Os nomes de cabeçalho são convertidos em letras minúsculas no objeto do evento, e os nomes de cabeçalho devem ser minúsculos quando são adicionados pelo código de função. Quando o CloudFront Functions converte o objeto de evento novamente em uma 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 resposta HTTP.

cookies

Um objeto que representa os cookies na resposta (cabeçalhos Set-Cookie).

O objeto cookies contém um campo para cada cookie na resposta.

Para obter mais informações sobre a estrutura de cabeçalhos e cookies, consulte Cadeia de consulta, cabeçalho e estrutura de cookies.

Para obter um objeto event de exemplo, consulte Evento de exemplo.

As cadeias de consulta, cabeçalhos e cookies nos objetos request e response compartilham a mesma estrutura. 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.

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 ser minúsculos quando são adicionados pelo código de 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.

Por exemplo, considere o seguinte cabeçalho Host em uma solicitação HTTP:

Host: video.example.com

Esse cabeçalho é representado da seguinte forma no objeto request:

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

Para acessar o cabeçalho Host em seu código de função, use o código da seguinte maneira:

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

Para adicionar ou modificar um cabeçalho em seu código de função, use o código como a seguir (esse código adiciona um cabeçalho chamado X-Custom-Header com o valor example 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.

Por exemplo, considere uma solicitação HTTP com os seguintes cabeçalhos Accept:

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

Esses cabeçalhos são representados da seguinte forma no objeto request:

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

Observe que o primeiro valor de cabeçalho (neste caso, application/json) é repetido em ambas as propriedades value e multiValue. Isso permite que você acesse todos os valores por loop por meio da matriz multiValue.

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

  1. Se a matriz multiValue existir e tiver qualquer modificação, então essa modificação é aplicada. O primeiro elemento na propriedade value é ignorado.

  2. Caso contrário, qualquer modificação na propriedade value será aplicada e os valores subsequentes (se existirem) permanecerão inalterados.

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.

Por exemplo, considere uma solicitação com um cabeçalho Accept que contém três valores, como no exemplo a seguir:

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

Esse cabeçalho é representado da seguinte forma no objeto request:

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

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. Por exemplo:

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

No objeto response, esses atributos são representados na propriedade attributes do campo cookie. Por exemplo, o cabeçalho Set-Cookie anterior é representado da seguinte forma:

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

Evento de exemplo

O exemplo a seguir mostra um objeto event completo.

nota

O objeto event é a entrada para sua função. Sua função retorna apenas o objeto request ou response, não o 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" } ] } } } }