CloudFront Funzioni, struttura degli eventi

CloudFront Functions passa un event oggetto al codice della 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. Assicuratevi che i nomi delle intestazioni siano in minuscolo, come accade sempre nell'eventoggetto 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:

Campo Versione

Il version campo contiene una stringa che specifica la versione dell'oggetto evento Functions. CloudFront 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'requestoggetto contiene una rappresentazione di una richiesta da visualizzatore a HTTP. CloudFront Nell'eventoggetto passato alla funzione, l'requestoggetto 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:

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'responseoggetto contiene una rappresentazione di una risposta HTTP CloudFront -to-viewer. Nell'eventoggetto passato alla funzione, l'responseoggetto 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:

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

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.

Se la CloudFront funzione è configurata per restituire un errore HTTP pari o superiore a 400, il visualizzatore non visualizzerà una pagina di errore personalizzata specificata 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 viene scritta in maiuscolo. Le parole sono separate da un trattino (-). Ad esempio, se il codice della funzione aggiunge un'intestazione denominataexample-header-name, la CloudFront converte nella richiesta o Example-Header-Name nella 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 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:

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.

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