Campo de versão Objeto de contexto Objeto do visualizador Objeto de solicitação Objeto da resposta Código de status e corpo Estrutura de uma string de consulta, um cabeçalho ou um cookie Exemplo de objeto de resposta Exemplo de objeto de evento

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.

Tópicos

Campo de versão
Objeto de contexto
Objeto do visualizador
Objeto de solicitação
Objeto da resposta
Código de status e corpo
Estrutura de uma string de consulta, um cabeçalho ou um cookie
Exemplo de objeto de resposta
Exemplo de objeto de evento

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

method

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

uri

O caminho relativo do objeto solicitado.

nota

Se a sua função modificar o valor uri, o seguinte será aplicável:

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 do 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 string 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 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 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 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.

statusCode

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

Sua função pode gerar ou modificar ostatusCode.

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

body

Adicionar o campo body é opcional e ele não estará presente no objeto response, a menos que você o especifique na função. A função não tem acesso ao corpo original retornado pelo cache ou pela origem do CloudFront. Se você não especificar o campo body na função de resposta do visualizador, o corpo original retornado pelo cache do CloudFront ou pela origem será retornado ao visualizador.

Se quiser que o CloudFront retorne um corpo personalizado ao visualizador, especifique o conteúdo do corpo no campo data e a codificação do corpo no campo encoding. É possível especificar a codificação como texto simples ("encoding": "text") ou como conteúdo codificado em Base64 ("encoding": "base64").

Como atalho, também é possível especificar o conteúdo do corpo diretamente no campo body ("body": "<specify the body content here>"). Ao fazer isso, omita os campos data e encoding. Nesse caso, o CloudFront tratará o corpo como texto simples.

encoding

A codificação do conteúdo do body (campo data). As únicas codificações válidas são text e base64.

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

data

O conteúdo do body.

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:

Alterar o status para definir um código de status HTTP 200 e a criar conteúdo estático do corpo para retornar ao visualizador.
Alterar o status para definir um código de status HTTP 301 ou 302 para redirecionar o usuário para outro site.
Decidir se deseja enviar ou descartar o corpo da resposta do visualizador.

nota

Se a origem retornar um erro HTTP igual ou superior a 400, a função do CloudFront não será executada. Para obter mais informações, consulte Restrições de todas as funções de borda.

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.

dica

Ao usar o CloudFront Functions para substituir um corpo, certifique-se de alinhar os cabeçalhos correspondentes, como content-encoding, content-type ou content-length, ao novo conteúdo do corpo.

Por exemplo, se a origem ou o cache do CloudFront retornar content-encoding: gzip, mas a função de resposta do visualizador definir um corpo que seja texto simples, a função também precisará alterar os cabeçalhos content-encoding e content-type adequadamente.

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.

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.

Sumário

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.

exemplo Exemplo

Para modificar uma string de consulta no código de função, use o código da seguinte maneira:


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.

exemplo Exemplo

Pense no cabeçalho Host a seguir 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.

exemplo Exemplo

Pense em uma solicitação HTTP com os cabeçalhos Accept a seguir.


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

Esses cabeçalhos são representados da forma a seguir no objeto request.


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

nota

O primeiro valor de cabeçalho (nesse caso, application/json) é repetido nas duas 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 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:

Se a matriz multiValue existir e tiver qualquer modificação, então essa modificação é aplicada. O primeiro elemento na propriedade value é ignorado.
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.

exemplo Exemplo

Pense em uma solicitação com um cabeçalho Accept que contém três valores.


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

Esse cabeçalho é representado da forma a seguir 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.

exemplo 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"
}

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.

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"
                    }
                ]
            }
        }
    }
}

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

Determinar o propósito da função

Recursos de tempo de execução JavaScript

Estrutura de eventos do CloudFront Functions

Tópicos

Campo de versão

Objeto de contexto

Objeto do visualizador

Objeto de solicitação

nota

Objeto da resposta

Código de status e corpo

nota

dica

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

Sumário

Valores de string de consulta ou objetos de string de consulta

exemplo Exemplo

Considerações especiais sobre cabeçalhos

exemplo Exemplo

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

exemplo Exemplo

nota

exemplo Exemplo

Atributos de cookies

exemplo Exemplo

Exemplo de objeto de resposta

Exemplo de objeto de evento

nota

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