CloudFront Functions-Ereignisstruktur - Amazon CloudFront
Feld VersionContext-ObjektBetrachterobjektObjekt anfordernAntwortobjektStatuscode und TextStruktur von Abfragezeichenfolge, Header und CookieBeispiel für AntwortobjektBeispiel für Ereignisobjekt

CloudFront Functions-Ereignisstruktur

CloudFront Functions übergibt ein event-Objekt an Ihren Funktionscode als Eingabe, wenn es die Funktion ausführt. Wenn Sie eine Funktion testen, erstellen Sie das event-Objekt und übergeben es an Ihre Funktion. Wenn Sie ein event-Objekt zum Testen einer Funktion erstellen, können Sie die Felder distributionDomainName, distributionId und requestId im context-Objekt weglassen. Stellen Sie sicher, dass die Namen der Header in Kleinbuchstaben geschrieben sind, was bei dem event-Objekt, das CloudFront-Funktionen in der Produktion an Ihre Funktion übergeben, immer der Fall ist.

Im Folgenden wird ein Überblick über die Struktur dieses Ereignisobjekts gegeben. 

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

Weitere Informationen finden Sie unter den folgenden Themen:

Feld Version

Das Feld version enthält eine Zeichenfolge, die die Version des CloudFront-Functions -Ereignisobjekts angibt. Die aktuelle Version ist 1.0.

Context-Objekt

Das context-Objekt enthält kontextbezogene Informationen über das Ereignis. Er enthält folgende Felder:

distributionDomainName

Der CloudFront-Domainname (z. B. d111111abcdef8.cloudfront.net) der Standarddistribution, die mit dem Ereignis verknüpft ist.

Das Feld distributionDomainName wird nur angezeigt, wenn Ihre Funktion für Standarddistributionen aufgerufen wird.

endpoint

Der CloudFront-Domainname (z. B. d111111abcdef8.cloudfront.net) der Verbindungsgruppe, die mit dem Ereignis verknüpft ist.

Das Feld endpoint wird nur angezeigt, wenn Ihre Funktion für Multi-Tenant-Distributionen aufgerufen wird.

distributionId

Die ID der Verteilung (zum Beispiel EDFDVBD6EXAMPLE), die mit dem Ereignis verknüpft ist.

eventType

Der Ereignistyp, entweder viewer-request oder viewer-response.

requestId

Eine Zeichenfolge, die eine CloudFront-Anfrage (und die zugehörige Antwort) eindeutig identifiziert.

Betrachterobjekt

Das viewer-Objekt enthält ein ip-Feld, dessen Wert die IP-Adresse des Betrachters (Clients) ist, der die Anfrage gesendet hat. Wenn der Betrachter einen HTTP-Proxy oder einen Load Balancer verwendet hat, um die Anfrage zu senden, entspricht der Wert der IP-Adresse des Proxys bzw. des Load Balancers.

Objekt anfordern

Das request-Objekt enthält eine Darstellung einer Viewer-to-CloudFront-HTTP-Anfrage. Im event-Objekt, das an Ihre Funktion übergeben wird, stellt das request-Objekt die tatsächliche Anforderung dar, die CloudFront vom Viewer erhalten hat.

Wenn Ihr Funktionscode ein request-Objekt an CloudFront zurückgibt, muss es dieselbe Struktur verwenden.

Das request-Objekt enthält die folgenden Felder:

method

Die HTTP-Methode der Anforderung. Wenn Ihr Funktionscode eine request zurückgibt, kann er dieses Feld nicht ändern. Dies ist das einzige schreibgeschützte Feld im request-Objekt.

uri

Der relative Pfad des angeforderten Objekts.

Anmerkung

Wenn Ihre Funktion den uri-Wert ändert, gilt Folgendes:

  • Der neue uri-Wert muss mit einem Schrägstrich (/) beginnen (/).

  • Wenn eine Funktion den uri-Wert ändert, ändert sie auch das Objekt, das die Betrachter anfordert.

  • Wenn eine Funktion den uri-Wert ändert, wird weder das Cache-Verhalten für die Anforderung noch der Ursprung geändert, an den die Ursprungsanfrage weitergeleitet wird.

querystring

Ein Objekt, das die Abfragezeichenkette in der Anfrage darstellt. Wenn die Anfrage keine Abfragezeichenfolge enthält, enthält das request-Objekt immer noch ein leeres querystring-Objekt.

Das querystring-Objekt enthält ein Feld für jeden Abfragezeichenfolgenparameter in der Anforderung.

headers

Ein Objekt, das den HTTP-Header in der Anforderung darstellt. Wenn die Anfrage Cookie-Header enthält, sind diese Header nicht Teil des headers-Objekts. Cookies werden im cookies-Objekt separat dargestellt.

Das headers-Objekt enthält ein Feld für jeden Header in der Anfrage. Headernamen werden im Ereignisobjekt in ASCII-Kleinbuchstaben konvertiert und Headernamen müssen in ASCII-Kleinbuchstaben stehen, wenn sie vom Funktionscode hinzugefügt werden. Wenn CloudFront Functions das Ereignisobjekt wieder in eine HTTP-Anforderung konvertiert, wird der erste Buchstabe jedes Wortes in den Headernamen groß geschrieben, wenn es sich um einen ASCII-Buchstaben handelt. CloudFront Functions wendet keine Änderungen auf Nicht-ASCII-Symbole in Headernamen an. Beispielsweise wird TÈst-header innerhalb der Funktion zu tÈst-header. Das Nicht-ASCII-Symbol È bleibt unverändert.

Wörter werden durch einen Bindestrich () getrennt. (-). Beispiel: Wenn Ihr Funktionscode einen Header namens example-header-name hinzufügt, konvertiert CloudFront dies zu Example-Header-Name in der HTTP-Anfrage.

cookies

Ein Objekt, das die Cookies in der Anfrage darstellt (Cookie-Header).

Das cookies-Objekt enthält ein Feld für jeden Cookie in der Anfrage.

Weitere Hinweise zur Struktur von Abfragezeichenfolgen, Headern und Cookies finden Sie unter Struktur von Abfragezeichenfolge, Header und Cookie.

Ein event-Beispielobjekt finden Sie unter Beispiel für Ereignisobjekt.

Antwortobjekt

Das response-Objekt enthält eine Darstellung einer CloudFront-to-viewer-HTTP-Antwort. Im event-Objekt, das an Ihre Funktion übergeben wird, stellt das response-Objekt die tatsächliche Antwort von CloudFront auf eine Viewer-Anforderung dar.

Wenn Ihr Funktionscode ein response-Objekt zurückgibt, muss er dieselbe Struktur verwenden.

Das response-Objekt enthält die folgenden Felder:

statusCode

Den HTTP-Statuscode der Antwort. Dieser Wert ist eine Ganzzahl, keine Zeichenfolge.

Ihre Funktion kann den statusCode generieren oder ändern.

statusDescription

Die HTTP-Statusbeschreibung der Antwort. Wenn Ihr Funktionscode eine Antwort generiert, ist dieses Feld optional.

headers

Ein Objekt, das die HTTP-Header in der Antwort darstellt. Wenn die Antwort Set-Cookie Header enthält, sind diese Header nicht Teil des headers-Objekts. Cookies werden im cookies-Objekt separat dargestellt.

Das headers-Objekt enthält ein Feld für jeden Header in der Antwort. Headernamen werden im Ereignisobjekt in Kleinbuchstaben konvertiert und Headernamen müssen in Kleinbuchstaben stehen, wenn sie vom Funktionscode hinzugefügt werden. Wenn CloudFront Functions das Ereignisobjekt wieder in eine HTTP-Antwort konvertiert, wird der erste Buchstabe jedes Wortes in den Headernamen groß geschrieben. Wörter werden durch einen Bindestrich () getrennt. (-). Beispiel: Wenn Ihr Funktionscode einen Header namens example-header-name hinzufügt, konvertiert CloudFront dies zu Example-Header-Name in der HTTP-Antwort.

cookies

Ein Objekt, das die Cookies in der Antwort darstellt (Set-Cookie-Header).

Das cookies-Objekt enthält ein Feld für jedes Cookie in der Antwort.

body

Das Hinzufügen des body-Felds ist optional. Es wird im response-Objekt nur dann vorhanden sein, wenn Sie es in Ihrer Funktion angeben. Ihre Funktion hat keinen Zugriff auf den ursprünglichen Text, der vom CloudFront-Cache oder vom Ursprung zurückgegeben wird. Wenn Sie das body-Feld nicht in Ihrer Viewer-Antwortfunktion angeben, wird der ursprüngliche Text, der vom CloudFront-Cache oder Ursprung zurückgegeben wird, an den Viewer zurückgegeben.

Wenn Sie möchten, dass CloudFront benutzerdefinierten Text an den Viewer zurückgibt, geben Sie den Textinhalt im Feld data und die Textcodierung im Feld encoding an. Sie können die Codierung als Klartext ("encoding": "text") oder als Base64-codierten Inhalt ("encoding": "base64") angeben.

Als Abkürzung können Sie den Textinhalt auch direkt im Feld body angeben ("body": "<specify the body content here>"). Lassen Sie dabei die Felder data und encoding aus. CloudFront behandelt den Text in diesem Fall als Klartext.

encoding

Die Codierung für den body-Inhalt (Feld data). Die einzigen gültigen Codierungen sind text und base64.

Wenn Sie encoding als base64 festlegen, der Textkörper jedoch kein gültiges base64 ist, gibt CloudFront einen Fehler zurück.

data

Der body-Inhalt.

Weitere Informationen zu geänderten Statuscodes und Textinhalten finden Sie unter Statuscode und Text.

Weitere Informationen zur Struktur von Headern und Cookies finden Sie unter Struktur von Abfragezeichenfolge, Header und Cookie.

Ein response-Beispielobjekt finden Sie unter Beispiel für Antwortobjekt.

Statuscode und Text

Mit CloudFront-Funktionen können Sie den Statuscode der Viewer-Antwort aktualisieren, den gesamten Antworttext durch einen neuen ersetzen oder den Antworttext entfernen. Zu den gängigen Szenarien für die Aktualisierung der Viewer-Antwort nach der Auswertung von Aspekten der Antwort vom CloudFront-Cache oder Ursprung gehören die folgenden:

  • Ändern des Status, um einen HTTP-200-Statuscode festzulegen, und Erstellen statischer Textinhalte für die Rückgabe an den Viewer.

  • Ändern des Status, um einen HTTP-301- oder -302-Statuscode festzulegen, der den Benutzer auf eine andere Website umleitet.

  • Entscheiden, ob der Text der Viewer-Antwort weitergeleitet oder verworfen werden soll.

Anmerkung

Wenn der Ursprung den HTTP-Fehler 400 oder höher zurückgibt, wird die CloudFront-Funktion nicht ausgeführt. Weitere Informationen finden Sie unter Einschränkungen für alle Edge-Funktionen.

Wenn Sie mit der HTTP-Antwort arbeiten, haben CloudFront-Funktionen keinen Zugriff auf den Antworttext. Sie können den Textinhalt ersetzen, indem Sie ihn auf den gewünschten Wert setzen, oder den Text entfernen, indem Sie den Wert auf leer setzen. Wenn Sie das Textfeld in Ihrer Funktion nicht aktualisieren, wird der ursprüngliche Text, der vom CloudFront-Cache oder dem Ursprung zurückgegeben wird, an den Viewer zurückgegeben.

Tipp

Wenn Sie CloudFront-Funktionen verwenden, um einen Text zu ersetzen, achten Sie darauf, die entsprechenden Header wie beispielsweise content-encoding, content-type oder content-length am neuen Textinhalt auszurichten.

Wenn beispielsweise der CloudFront-Ursprung oder -Cache content-encoding: gzip zurückgibt, die Viewer-Antwortfunktion aber reinen Text für den Inhalt festlegt, muss die Funktion auch die Header content-encoding und content-type entsprechend ändern.

Wenn Ihre CloudFront-Funktion so konfiguriert ist, dass sie den HTTP-Fehler 400 oder höher zurückgibt, wird Ihrem Viewer keine benutzerdefinierte Fehlerseite angezeigt, die Sie für denselben Statuscode angegeben haben.

Abfragezeichenfolgen, Header und Cookies haben dieselbe Struktur. Abfragezeichenfolgen können in Anforderungen vorkommen. Header erscheinen in Anforderungen und Antworten. Cookies erscheinen in Anforderungen und Antworten.

Jede Abfragezeichenfolge, jeder Header oder jedes Cookie ist ein eindeutiges Feld innerhalb des übergeordneten querystring-, headers- oder cookies-Objekts. Der Feldname ist der Name der Abfragezeichenfolge, des Headers oder des Cookies. Jedes Feld enthält eine value-Eigenschaft mit dem Wert der Abfragezeichenfolge, des Headers oder des Cookies.

Werte oder Objekte von Abfragezeichenfolgen

Eine Funktion kann zusätzlich zum Objekt den Wert einer Abfragezeichenfolge zurückgeben. Der Wert der Abfragezeichenfolge kann verwendet werden, um die Parameter der Abfragezeichenfolge in beliebiger benutzerdefinierter Reihenfolge anzuordnen.

Beispiel

Um eine Abfragezeichenfolge in Ihrem Funktionscode zu ändern, verwenden Sie einen Code wie den folgenden:

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

Besondere Überlegungen für Header

Nur für Header werden Headernamen im Ereignisobjekt in Kleinbuchstaben konvertiert und Headernamen müssen Kleinbuchstaben aufweisen, wenn sie vom Funktionscode hinzugefügt werden. Wenn CloudFront Functions das Ereignisobjekt wieder in eine HTTP-Anforderung, oder -Antwort konvertiert, wird der erste Buchstabe jedes Wortes in den Headernamen groß geschrieben. Wörter werden durch einen Bindestrich () getrennt. (-). Beispiel: Wenn Ihr Funktionscode einen Header namens example-header-name hinzufügt, konvertiert CloudFront dies zu Example-Header-Name in der HTTP-Anfrage, oder -Antwort.

Beispiel

Betrachten Sie den folgenden Host-Header in einer HTTP-Anforderung.

Host: video.example.com

Dieser Header wird im request-Objekt wie folgt dargestellt:

"headers": {
    "host": {
        "value": "video.example.com"
    }
}

Um auf den Host-Header in Ihrem Funktionscode zuzugreifen, verwenden Sie Code wie den folgenden:

var request = event.request;
var host = request.headers.host.value;

Um einen Header in Ihrem Funktionscode hinzuzufügen oder zu ändern, verwenden Sie Code wie den folgenden (dieser Code fügt einen Header mit Namen X-Custom-Header und Wert example value hinzu):

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

Doppelte Abfragezeichenfolgen, Header und Cookies (multiValue-Array)

Eine HTTP-Anfrage oder Antwort kann mehr als eine Abfragezeichenfolge, einen Header oder ein Cookie mit demselben Namen enthalten. In diesem Fall sind die doppelten Abfragezeichenfolgen, -Header oder -Cookies in einem Feld im request- oder response-Objekt zusammengefasst, aber dieses Feld enthält eine zusätzliche Eigenschaft namens multiValue. Die multiValue-Eigenschaft enthält ein Array mit den Werten der doppelten Abfragezeichenfolgen, Header oder Cookies.

Beispiel

Betrachten Sie eine HTTP-Anforderung mit den folgenden Accept-Headern.

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

Diese Header werden im request-Objekt wie folgt dargestellt.

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

Der erste Headerwert (in diesem Fall application/json) wird sowohl in der Eigenschaft value als auch in der Eigenschaft multiValue wiederholt. Auf diese Weise können Sie auf alle Werte zugreifen, indem Sie das multiValue-Array durchlaufen.

Wenn Ihr Funktionscode eine Abfragezeichenfolge, einen Header oder ein Cookie mit einem multiValue Array ändert, verwendet CloudFront-Funktionen die folgenden Regeln, um die Änderungen anzuwenden:

  1. Wenn das multiValue-Array existiert und Änderungen hat, wird diese Änderung angewendet. Das erste Element in der value-Eigenschaft wird ignoriert.

  2. Andernfalls wird jede Änderung der value-Eigenschaft angewendet, und nachfolgende Werte (falls vorhanden) bleiben unverändert.

Die multiValue-Eigenschaft wird nur verwendet, wenn die HTTP-Anfrage oder Antwort doppelte Abfragezeichenfolgen, Header oder Cookies mit demselben Namen enthält, wie im vorherigen Beispiel gezeigt. Wenn jedoch mehrere Werte in einer einzelnen Abfragezeichenfolge, einem Header oder einem Cookie vorhanden sind, wird die multiValue-Eigenschaft nicht verwendet.

Beispiel

Stellen Sie sich eine Anforderung mit einem Accept-Header vor, der drei Werte enthält.

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

Dieser Header wird im request-Objekt wie folgt dargestellt.

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

In einem Set-Cookie-Header in einer HTTP-Antwort enthält der Header das Name-Wert-Paar für das Cookie und optional eine Reihe von durch Semikolons getrennten Attributen.

Beispiel

Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT

In dem response-Objekt werden diese Attribute in der attributes-Eigenschaft des Cookie-Feldes dargestellt. Der vorangehende Set-Cookie-Header wird beispielsweise wie folgt dargestellt:

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

Beispiel für Antwortobjekt

Das folgende Beispiel zeigt ein response-Objekt – die Ausgabe einer Viewer-Antwortfunktion –, in dem der Text durch eine Viewer-Antwortfunktion ersetzt wurde.

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

Beispiel für Ereignisobjekt

Das folgende Beispiel zeigt ein vollständiges event-Objekt: Dies ist ein Beispielaufruf für eine Standarddistribution und nicht für eine Multi-Tenant-Distribution. Bei Multi-Tenant-Distributionen wird das Feld endpoint anstelle von distributionDomainName verwendet. Der Wert von endpoint ist der CloudFront-Domainname (z. B. d111111abcdef8.cloudfront.net) der Verbindungsgruppe, die mit dem Ereignis verknüpft ist.

Anmerkung

Das event-Objekt ist die Eingabe für Ihre Funktion. Ihre Funktion gibt nur das request- oder response-Objekt zurück, nicht das vollständige event-Objekt.

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