Struttura degli eventi di CloudFront Functions

CloudFront Functions passa un oggetto event al codice funzione come input quando esegue la funzione. Quando si testa una funzione, 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. Assicurarsi che i nomi delle intestazioni siano minuscoli (questo è sempre il caso nell'oggetto event passato da Funzioni CloudFront 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:

Campo Versione

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

Oggetto Context

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

Oggetto Viewer

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

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

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

L'oggetto request include i seguenti campi:

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.

Per un oggetto event di esempio, consulta Oggetto evento di esempio.

Oggetto Response

L'oggetto response contiene una rappresentazione di una risposta HTTP da CloudFront al visualizzatore. Nell'oggetto event passato alla funzione, l'oggetto response rappresenta la risposta effettiva di CloudFront a una richiesta visualizzatore.

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

L'oggetto response include i seguenti campi:

Per ulteriori informazioni sui codici di stato modificati e sul contenuto del corpo, consultare Codice di stato e corpo.

Per ulteriori informazioni sulla struttura delle intestazioni e dei cookie, consulta Struttura di una stringa di query, un'intestazione o cookie.

Per un oggetto response di esempio, consulta Oggetto risposta di esempio.

Codice di stato e corpo

Con Funzioni CloudFront, puoi aggiornare il codice di stato della risposta visualizzatore, sostituire l’intero corpo della risposta con uno nuovo o rimuovere il corpo della risposta. Alcuni scenari comuni per l'aggiornamento della risposta visualizzatore dopo aver valutato gli aspetti della risposta dalla cache o dall'origine CloudFront includono quanto segue:

Quando si utilizza la risposta HTTP, Funzioni CloudFront non dispone dell’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 del corpo nella funzione, il corpo originale restituito dalla cache o dall’origine CloudFront viene restituito al visualizzatore.

Se la Funzione CloudFront è configurata per restituire un errore HTTP pari o superiore a 400, il visualizzatore non vedrà la pagina di errore personalizzata che hai specificato per lo stesso codice di stato.

Struttura di una stringa di query, un'intestazione o cookie

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.

Valori stringa di query od oggetti stringa di query

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.

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

Considerazioni speciali per le intestazioni

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 è in maiuscolo. Le parole sono separate da un trattino (-). Ad esempio, se il codice funzione aggiunge un'intestazione denominata example-header-name, CloudFront la converte inExample-Header-Name nella richiesta o risposta 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'};

Stringhe di query, intestazioni e cookie duplicati (array multiValue)

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.

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 il codice funzione modifica una stringa di query, un'intestazione o un cookie avente un array multiValue, CloudFront Functions applica le modifiche utilizzando le seguenti regole:

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.

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

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

Attributi cookie

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.

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

Oggetto risposta di esempio

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

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 campo endpoint viene utilizzato al posto di distributionDomainName. Il valore di endpoint è il nome di dominio CloudFront (ad esempio, d111111abcdef8.cloudfront.net) del gruppo di connessioni associato all’evento.

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