# Estrutura de eventos do CloudFront Functions
<a name="functions-event-structure"></a>

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](test-function.md), 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 saber mais, consulte os seguintes tópicos:

**Topics**
+ [Campo de versão](#functions-event-structure-version)
+ [Objeto de contexto](#functions-event-structure-context)
+ [Estrutura de eventos de conexão](#functions-event-structure-connection)
+ [Objeto do visualizador](#functions-event-structure-viewer)
+ [Objeto de solicitação](#functions-event-structure-request)
+ [Objeto da resposta](#functions-event-structure-response)
+ [Código de status e corpo](#functions-event-structure-status-body)
+ [Estrutura de uma string de consulta, um cabeçalho ou um cookie](#functions-event-structure-query-header-cookie)
+ [Exemplo de objeto de resposta](#functions-response-structure-example)
+ [Exemplo de objeto de evento](#functions-event-structure-example)

## Campo de versão
<a name="functions-event-structure-version"></a>

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
<a name="functions-event-structure-context"></a>

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 padrão associada ao evento.  
O campo `distributionDomainName` aparece somente quando sua função é invocada para distribuições padrão.

**`endpoint`**  
O nome de domínio do CloudFront (por exemplo, d111111abcdef8.cloudfront.net) do grupo de conexões associado ao evento.  
O campo `endpoint` aparece somente quando sua função é invocada para distribuições multilocatário.

**`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).

## Estrutura de eventos de conexão
<a name="functions-event-structure-connection"></a>

As funções de conexão recebem uma estrutura de eventos diferente das funções de visualização. Para ter informações detalhadas sobre a estrutura de eventos de conexão, consulte [Associar uma função de conexão do CloudFront](connection-functions.md).

## Objeto do visualizador
<a name="functions-event-structure-viewer"></a>

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
<a name="functions-event-structure-request"></a>

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.   
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 ASCII no objeto do evento e 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 cada palavra nos nomes de cabeçalho é convertida em maiúscula, se ela for uma letra ASCII. O CloudFront Functions não aplica nenhuma alteração aos símbolos não ASCII nos nomes de cabeçalho. Por exemplo, `TÈst-header` se tornará `tÈst-header` dentro da função. O símbolo não ASCII `È` permanece inalterado.  
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](#functions-event-structure-query-header-cookie).

Para obter um objeto `event` de exemplo, consulte [Exemplo de objeto de evento](#functions-event-structure-example).

## Objeto da resposta
<a name="functions-event-structure-response"></a>

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 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 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](#functions-event-structure-status-body).

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](#functions-event-structure-query-header-cookie).

Para obter um objeto `response` de exemplo, consulte [Exemplo de objeto de resposta](#functions-response-structure-example).

## Código de status e corpo
<a name="functions-event-structure-status-body"></a>

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](edge-function-restrictions-all.md).

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](creating-custom-error-pages.md) que você especificou para o mesmo código de status.

## Estrutura de uma string de consulta, um cabeçalho ou um cookie
<a name="functions-event-structure-query-header-cookie"></a>

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.

**Contents**
+ [Valores de string de consulta ou objetos de string de consulta](#functions-event-structure-query)
+ [Considerações especiais sobre cabeçalhos](#functions-event-structure-headers)
+ [Duplicar cadeias de consulta, cabeçalhos e cookies (matriz `multiValue`)](#functions-event-structure-multivalue)
+ [Atributos de cookies](#functions-event-structure-cookie-attributes)

### Valores de string de consulta ou objetos de string de consulta
<a name="functions-event-structure-query"></a>

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. 

**Example 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
<a name="functions-event-structure-headers"></a>

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.

**Example 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`)
<a name="functions-event-structure-multivalue"></a>

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.

**Example 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:

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

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

**Example 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"
    }
}
```

### Atributos de cookies
<a name="functions-event-structure-cookie-attributes"></a>

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. 

**Example 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
<a name="functions-response-structure-example"></a>

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
<a name="functions-event-structure-example"></a>

O exemplo a seguir mostra um objeto `event` completo. Este é um exemplo de invocação para uma distribuição padrão, e não para uma distribuição multilocatário. Para distribuições multilocatário, é usado o campo `endpoint`, em vez de `distributionDomainName`. O valor de `endpoint` é o nome de domínio do CloudFront (por exemplo, d111111abcdef8.cloudfront.net) do grupo de conexões associado ao evento.

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