Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# CloudFront Funzioni, struttura degli eventi
<a name="functions-event-structure"></a>

CloudFront Functions passa un `event` oggetto al codice della funzione come input quando esegue la funzione. Quando si [testa una funzione](test-function.md), si crea l'oggetto `event` e lo si passa alla funzione. Quando si crea un oggetto `event` per testare una funzione, puoi omettere i campi `distributionDomainName`, `distributionId` e `requestId` nell'oggetto `context`. Assicuratevi che i nomi delle intestazioni siano in minuscolo, come accade sempre nell'`event`oggetto che CloudFront Functions passa alla funzione in produzione.

Di seguito viene illustrata una panoramica della struttura di questo oggetto evento. 

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

Per ulteriori informazioni, consulta i seguenti argomenti:

**Topics**
+ [

## Campo Versione
](#functions-event-structure-version)
+ [

## Oggetto Context
](#functions-event-structure-context)
+ [

## Struttura degli eventi di connessione
](#functions-event-structure-connection)
+ [

## Oggetto Viewer
](#functions-event-structure-viewer)
+ [

## Oggetto Request
](#functions-event-structure-request)
+ [

## Oggetto Response
](#functions-event-structure-response)
+ [

## Codice di stato e corpo
](#functions-event-structure-status-body)
+ [

## Struttura di una stringa di query, un'intestazione o cookie
](#functions-event-structure-query-header-cookie)
+ [

## Oggetto risposta di esempio
](#functions-response-structure-example)
+ [

## Oggetto evento di esempio
](#functions-event-structure-example)

## Campo Versione
<a name="functions-event-structure-version"></a>

Il `version` campo contiene una stringa che specifica la versione dell'oggetto evento Functions. CloudFront La versione corrente è `1.0`.

## Oggetto Context
<a name="functions-event-structure-context"></a>

L'oggetto `context` contiene informazioni contestuali sull'evento. Include i seguenti campi:

**`distributionDomainName`**  
Il nome di CloudFront dominio (ad esempio, d111111abcdef8.cloudfront.net) della distribuzione standard associata all'evento.  
Il campo `distributionDomainName` viene visualizzato solo quando la funzione viene invocata per le distribuzioni standard.

**`endpoint`**  
Il nome di CloudFront dominio (ad esempio, d111111abcdef8.cloudfront.net) del gruppo di connessione associato all'evento.  
Il campo `endpoint` viene visualizzato solo quando la funzione viene invocata per le distribuzioni multi-tenant.

**`distributionId`**  
L'ID della distribuzione (ad esempio, EXAMPLE) associata all'evento. EDFDVBD6

**`eventType`**  
Il tipo di evento, `viewer-request` o `viewer-response`.

**`requestId`**  
Una stringa che identifica in modo univoco una CloudFront richiesta (e la risposta associata).

## Struttura degli eventi di connessione
<a name="functions-event-structure-connection"></a>

Le funzioni di connessione ricevono una struttura degli eventi diversa rispetto alle funzioni di visualizzazione. Per informazioni dettagliate sulla struttura degli eventi di connessione e sul formato di risposta, vedere[Associare una funzione di CloudFront connessione](connection-functions.md).

## Oggetto Viewer
<a name="functions-event-structure-viewer"></a>

L'oggetto `viewer` contiene un campo `ip` il cui valore è l'indirizzo IP del visualizzatore (client) che ha inviato la richiesta. Se il visualizzatore ha utilizzato un proxy HTTP o un sistema di bilanciamento del carico per inviare la richiesta, il valore è l'indirizzo IP del proxy o del sistema di bilanciamento del carico.

## Oggetto Request
<a name="functions-event-structure-request"></a>

L'`request`oggetto contiene una rappresentazione di una richiesta viewer-to-CloudFront HTTP. Nell'`event`oggetto passato alla funzione, l'`request`oggetto rappresenta la richiesta effettiva CloudFront ricevuta dal visualizzatore.

Se il codice della funzione restituisce un `request` oggetto a CloudFront, deve utilizzare la stessa struttura.

L'oggetto `request` include i seguenti campi:

**`method`**  
Metodo HTTP nella richiesta. Se il codice funzione restituisce `request`, non può modificare questo campo. Questo è l'unico campo di sola lettura nell'oggetto `request`.

**`uri`**  
Il percorso relativo dell'oggetto richiesto.   
Se la funzione Lambda modifica il valore `uri`, si applica quanto segue:  
+ Il nuovo valore `uri` deve iniziare con una barra (`/`).
+ Se una funzione modifica il valore di `uri`, l'oggetto richiesto dal visualizzatore viene modificato.
+ Se una funzione modifica il valore di `uri`, il comportamento della cache per la richiesta o l'origine a cui la richiesta viene inoltrata *non* viene modificato.

**`querystring`**  
Un oggetto che rappresenta la stringa di query nella richiesta. Se la richiesta non include una stringa di query, l’oggetto `request` include comunque un oggetto `querystring` vuoto.  
L'oggetto `querystring` contiene un campo per ogni parametro della stringa di query nella richiesta.

**`headers`**  
Un oggetto che rappresenta le intestazioni HTTP nella richiesta. Se la richiesta contiene intestazioni `Cookie`, queste non faranno parte dell'oggetto `headers`. I cookie sono rappresentati separatamente nell'oggetto `cookies`.  
L'oggetto `headers` contiene un campo per ogni intestazione della richiesta. I nomi delle intestazioni vengono convertiti in caratteri minuscoli ASCII nell’oggetto evento e i nomi delle intestazioni devono essere caratteri minuscoli ASCII quando vengono aggiunti dal codice della funzione. Quando CloudFront Functions riconverte l'oggetto evento in una richiesta HTTP, la prima lettera di ogni parola nei nomi delle intestazioni è in maiuscolo, se si tratta di una lettera ASCII. CloudFront Functions non applica alcuna modifica ai simboli non ASCII nei nomi delle intestazioni. Ad esempio, `TÈst-header` diventerà `tÈst-header` all’interno della funzione. Il simbolo non ASCII `È` rimane invariato.  
Le parole sono separate da un trattino (`-`). Ad esempio, se il codice della funzione aggiunge un'intestazione denominata`example-header-name`, la CloudFront converte in nella richiesta HTTP. `Example-Header-Name`

**`cookies`**  
Un oggetto che rappresenta i cookie nella richiesta (intestazioni `Cookie`).  
L'oggetto `cookies` contiene un campo per ogni cookie nella richiesta.

Per ulteriori informazioni sulla struttura delle stringhe di query, delle intestazioni e dei cookie, consulta [Struttura di una stringa di query, un'intestazione o cookie](#functions-event-structure-query-header-cookie).

Per un oggetto `event` di esempio, consulta [Oggetto evento di esempio](#functions-event-structure-example).

## Oggetto Response
<a name="functions-event-structure-response"></a>

L'`response`oggetto contiene una rappresentazione di una risposta CloudFront-to-viewer HTTP. Nell'`event`oggetto passato alla funzione, l'`response`oggetto rappresenta la risposta effettiva CloudFront di un utente a una richiesta del visualizzatore.

Se il codice funzione restituisce un oggetto `response`, deve utilizzare la stessa struttura.

L'oggetto `response` include i seguenti campi:

**`statusCode`**  
Il codice di stato HTTP per la risposta. Questo valore è un numero intero, non una stringa.  
La funzione può generare o modificare il `statusCode`.

**`statusDescription`**  
Descrizione dello stato HTTP della risposta. Se il codice funzione genera una risposta, questo campo è facoltativo.

**`headers`**  
Un oggetto che rappresenta le intestazioni HTTP nella risposta. Se la risposta contiene intestazioni `Set-Cookie`, queste non faranno parte dell'oggetto `headers`. I cookie sono rappresentati separatamente nell'oggetto `cookies`.  
L'oggetto `headers` contiene un campo per ogni intestazione della risposta. I nomi delle intestazioni vengono convertiti in minuscolo nell'oggetto evento e i nomi delle intestazioni devono essere in minuscolo quando vengono aggiunti dal codice della funzione. Quando CloudFront Functions riconverte l'oggetto evento in una risposta HTTP, la prima lettera di ogni parola nei nomi delle intestazioni viene scritta in maiuscolo. Le parole sono separate da un trattino (`-`). Ad esempio, se il codice della funzione aggiunge un'intestazione denominata`example-header-name`, la CloudFront converte in nella risposta HTTP. `Example-Header-Name`

**`cookies`**  
Un oggetto che rappresenta i cookie nella risposta (intestazioni `Set-Cookie`).  
L'oggetto `cookies` contiene un campo per ogni cookie nella risposta.

**`body`**  
L'aggiunta del campo `body` è facoltativa e non sarà presente nell'oggetto`response` a meno che non venga specificato nella funzione. La funzione non ha accesso al corpo originale restituito dalla CloudFront cache o dall'origine. Se non specificate il `body` campo nella funzione di risposta del visualizzatore, il corpo originale restituito dalla CloudFront cache o dall'origine viene restituito al visualizzatore.  
Se desideri CloudFront restituire un corpo personalizzato al visualizzatore, specifica il contenuto del corpo nel `data` campo e la codifica del corpo nel `encoding` campo. Puoi specificare la codifica come testo normale (`"encoding": "text"`) o come contenuto con codifica Base64 (`"encoding": "base64"`).  
Come scelta rapida, puoi anche specificare il contenuto del corpo direttamente nel campo `body` (`"body": "<specify the body content here>"`). Quando esegui questa operazione, ometti i campi `data` e`encoding`. CloudFront in questo caso tratta il corpo come testo semplice.    
`encoding`  
La codifica del contenuto `body` (campo `data`). Le uniche codifiche valide sono `text` e `base64`.  
Se si specifica `encoding` come `base64` ma il corpo non è valido base64, CloudFront restituisce un errore.  
`data`  
Il contenuto `body`.

Per ulteriori informazioni sui codici di stato modificati e sul contenuto del corpo, consultare [Codice di stato e corpo](#functions-event-structure-status-body).

Per ulteriori informazioni sulla struttura delle intestazioni e dei cookie, consulta [Struttura di una stringa di query, un'intestazione o cookie](#functions-event-structure-query-header-cookie).

Per un oggetto `response` di esempio, consulta [Oggetto risposta di esempio](#functions-response-structure-example).

## Codice di stato e corpo
<a name="functions-event-structure-status-body"></a>

Con CloudFront Functions, puoi aggiornare il codice di stato della risposta del visualizzatore, sostituire l'intero corpo della risposta con uno nuovo o rimuovere il corpo della risposta. Alcuni scenari comuni per l'aggiornamento della risposta del visualizzatore dopo aver valutato alcuni aspetti della risposta dalla CloudFront cache o dall'origine includono quanto segue:
+ Modifica dello stato per impostare un codice di stato HTTP 200 e creazione di contenuto di corpo statico da restituire al visualizzatore.
+ Modifica dello stato per impostare un codice di stato HTTP 301 o 302 per reindirizzare l’utente a un altro sito Web.
+ Decidere se fornire o eliminare il corpo della risposta visualizzatore.

**Nota**  
Se l'origine restituisce un errore HTTP pari o superiore a 400, la CloudFront funzione non verrà eseguita. Per ulteriori informazioni, consulta [Restrizioni su tutte le funzioni edge](edge-function-restrictions-all.md).

Quando lavori con la risposta HTTP, CloudFront Functions non ha accesso al corpo della risposta. Puoi sostituire un contenuto del corpo impostandolo sul valore desiderato oppure puoi rimuovere il corpo impostando il valore in modo da essere vuoto. Se non aggiorni il campo body della tua funzione, il corpo originale restituito dalla CloudFront cache o dall'origine viene restituito al visualizzatore.

**Suggerimento**  
Quando usi CloudFront Functions per sostituire un corpo, assicurati di allineare le intestazioni corrispondenti, ad esempio`content-encoding`, or `content-type``content-length`, al nuovo contenuto del corpo.   
Ad esempio, se l' CloudFront origine o la cache restituiscono `content-encoding: gzip` ma la funzione di risposta del visualizzatore imposta un corpo in testo semplice, la funzione deve anche modificare le `content-type` intestazioni `content-encoding` e di conseguenza.

Se la CloudFront funzione è configurata per restituire un errore HTTP pari o superiore a 400, il visualizzatore non visualizzerà una [pagina di errore personalizzata](creating-custom-error-pages.md) specificata per lo stesso codice di stato.

## Struttura di una stringa di query, un'intestazione o cookie
<a name="functions-event-structure-query-header-cookie"></a>

Le stringhe di query, le intestazioni e i cookie condividono la stessa struttura. Le stringhe di query possono apparire nelle richieste. Le intestazioni vengono visualizzate nelle richieste e nelle risposte. I cookie vengono visualizzati nelle richieste e nelle risposte.

Ogni stringa di query, intestazione o cookie è un campo univoco all'interno dell'oggetto padre `querystring`, `headers` o `cookies`. Il nome del campo è il nome della stringa di query, dell'intestazione o del cookie. Ogni campo contiene una proprietà `value` con il valore della stringa di query, dell'intestazione o del cookie.

**Contents**
+ [

### Valori stringa di query od oggetti stringa di query
](#functions-event-structure-query)
+ [

### Considerazioni speciali per le intestazioni
](#functions-event-structure-headers)
+ [

### Stringhe di query, intestazioni e cookie duplicati (array `multiValue`)
](#functions-event-structure-multivalue)
+ [

### Attributi cookie
](#functions-event-structure-cookie-attributes)

### Valori stringa di query od oggetti stringa di query
<a name="functions-event-structure-query"></a>

Oltre a un oggetto, una funzione può restituire un valore stringa di query. È possibile utilizzare il valore stringa di query per disporre i parametri della stringa di query in qualsiasi ordine personalizzato. 

**Example Esempio**  
Per modificare una stringa di query nel codice funzione, utilizza un codice come il seguente.  

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

### Considerazioni speciali per le intestazioni
<a name="functions-event-structure-headers"></a>

Solo per le intestazioni, i nomi delle intestazioni vengono convertiti in minuscolo nell'oggetto evento e i nomi delle intestazioni devono essere in minuscolo quando vengono aggiunti dal codice della funzione. Quando CloudFront Functions riconverte l'oggetto evento in una richiesta o risposta HTTP, la prima lettera di ogni parola nei nomi delle intestazioni viene scritta in maiuscolo. Le parole sono separate da un trattino (`-`). Ad esempio, se il codice della funzione aggiunge un'intestazione denominata`example-header-name`, la CloudFront converte nella richiesta o `Example-Header-Name` nella risposta HTTP.

**Example Esempio**  
Considera la seguente intestazione `Host` in una richiesta HTTP:  

```
Host: video.example.com
```
Questa intestazione è rappresentata come segue nell'oggetto `request`:  

```
"headers": {
    "host": {
        "value": "video.example.com"
    }
}
```
Per accedere all'intestazione `Host` nel codice funzione, utilizza un codice come il seguente:  

```
var request = event.request;
var host = request.headers.host.value;
```
Per aggiungere o modificare un'intestazione nel codice funzione, utilizza un codice come il seguente (questo codice aggiunge un'intestazione denominata `X-Custom-Header` con il valore `example value`):  

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

### Stringhe di query, intestazioni e cookie duplicati (array `multiValue`)
<a name="functions-event-structure-multivalue"></a>

Una richiesta o una risposta HTTP può contenere più di una stringa di query, intestazione o cookie con lo stesso nome. In questo caso, le stringhe di query, le intestazioni o i cookie duplicati vengono compressi in un campo nell'oggetto `request` o `response`, ma questo campo conterrà una proprietà aggiuntiva denominata `multiValue`. La proprietà `multiValue` contiene un array con i valori di ciascuna delle stringhe di query, intestazioni o cookie duplicati.

**Example Esempio**  
Considera una richiesta HTTP con le intestazioni `Accept` seguenti:  

```
Accept: application/json
Accept: application/xml
Accept: text/html
```
Queste intestazioni sono rappresentate come segue nell’oggetto `request`.  

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

**Nota**  
Il valore della prima intestazione (in questo caso, `application/json`) viene ripetuto in entrambe le proprietà `value` e `multiValue`. Ciò consente di accedere a *tutti* i valori di passare attraverso l'array `multiValue`.

Se il codice della funzione modifica una stringa di query, un'intestazione o un cookie con un `multiValue` array, CloudFront Functions utilizza le seguenti regole per applicare le modifiche:

1. Se l'array `multiValue` esiste e ha una qualsiasi modifica, allora tale modifica viene applicata. Il primo elemento della proprietà `value` viene ignorato.

1. In caso contrario, viene applicata qualsiasi modifica alla proprietà `value` e i valori successivi (se presenti) rimangono invariati.

La proprietà `multiValue` viene utilizzata solo quando la richiesta HTTP o la risposta contiene stringhe di query duplicate, intestazioni o cookie con lo stesso nome, come illustrato nell'esempio precedente. Tuttavia, se sono presenti più valori in una singola stringa di query, intestazione o cookie, la proprietà `multiValue` non viene utilizzata.

**Example Esempio**  
Considera una richiesta con un’intestazione `Accept` che contiene tre valori.  

```
Accept: application/json, application/xml, text/html
```
Questa intestazione è rappresentata come segue nell’oggetto `request`.  

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

### Attributi cookie
<a name="functions-event-structure-cookie-attributes"></a>

In una intestazione `Set-Cookie` in una risposta HTTP, l'intestazione contiene la coppia nome-valore per il cookie e facoltativamente un insieme di attributi separati da punto e virgola. 

**Example Esempio**  

```
Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT
```
Nell'oggetto `response`, questi attributi sono rappresentati nella proprietà `attributes` del campo cookie. Ad esempio, l'intestazione `Set-Cookie` precedente è rappresentata come segue:  

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

## Oggetto risposta di esempio
<a name="functions-response-structure-example"></a>

L'esempio seguente mostra un oggetto `response`, l'output di una funzione di risposta del visualizzatore, in cui il corpo è stato sostituito da una funzione di risposta del visualizzatore.

```
{
  "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>"
    }
  }
}
```

## Oggetto evento di esempio
<a name="functions-event-structure-example"></a>

Di seguito viene illustrato un esempio di oggetto `event` completo. Questo è un esempio di invocazione per una distribuzione standard, non per una distribuzione multi-tenant. Per le distribuzioni multi-tenant, il `endpoint` campo viene utilizzato al posto di The value of è `distributionDomainName` il nome di `endpoint` CloudFront dominio (ad esempio, d111111abcdef8.cloudfront.net) del gruppo di connessione associato all'evento.

**Nota**  
L'oggetto `event` è l'input per la tua funzione. La funzione restituisce solo l'oggetto `request` o `response`, non l'oggetto `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"
                    }
                ]
            }
        }
    }
}
```