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

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

CloudFront Funktionen, Ereignisstruktur

CloudFront Functions übergibt ein event Objekt als Eingabe an Ihren Funktionscode, wenn die Funktion ausgeführt wird. 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 Functions in der Produktion an Ihre Funktion weitergibt, 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 version Feld 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 Domänenname (z. B. d111111abcdef8.cloudfront.net) der Distribution, die dem Ereignis zugeordnet ist.

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 Anfrage (und die zugehörige Antwort) eindeutig identifiziert. CloudFront

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 HTTP-Anfrage, die vom Betrachter empfangen wird. CloudFront In dem event Objekt, das an Ihre Funktion übergeben wird, stellt das request Objekt die tatsächliche Anfrage dar, die vom Betrachter CloudFront empfangen wurde.

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

Das request-Objekt enthält die folgenden Felder:

method

Die HTTP-Methode der Anforderung. Wenn Ihr Funktionscode a zurückgibtrequest, 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 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-Anforderung konvertiert, wird der erste Buchstabe jedes Worts in Header-Namen groß geschrieben. Wörter werden durch einen Bindestrich (-) getrennt. Wenn Ihr Funktionscode beispielsweise einen Header mit dem Namenexample-header-name, CloudFront konvertiert diesen Example-Header-Name in der HTTP-Anfrage in.

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 HTTP-Antwort CloudFront an den Betrachter. In dem event Objekt, das an Ihre Funktion übergeben wird, stellt CloudFront das response Objekt die tatsächliche Antwort auf eine Viewer-Anfrage 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 Worts in Header-Namen groß geschrieben. Wörter werden durch einen Bindestrich (-) getrennt. Wenn Ihr Funktionscode beispielsweise einen Header mit dem Namenexample-header-name, CloudFront konvertiert diesen Example-Header-Name in die 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 Originaltext, der vom CloudFront Cache oder Origin zurückgegeben wurde. Wenn Sie das body Feld in Ihrer Viewer-Antwortfunktion nicht angeben, wird der ursprüngliche Text, der vom CloudFront Cache oder Origin zurückgegeben wurde, an den Viewer zurückgegeben.

Wenn Sie einen benutzerdefinierten Text CloudFront an den Viewer zurückgeben möchten, geben Sie den Textinhalt im data Feld und die Textkodierung im encoding Feld 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>"). Wenn Sie dies tun, lassen Sie die encoding Felder data und weg. CloudFront behandelt den Hauptteil in diesem Fall als einfachen Text.

encoding

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

Wenn Sie encoding als angebenbase64, der Hauptteil aber nicht gültig ist, wird Base64 CloudFront zurückgegeben.

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 häufigsten Szenarien für die Aktualisierung der Antwort des Betrachters nach der Auswertung von Aspekten der Antwort aus dem CloudFront Cache oder dem 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 einen HTTP-Fehler von 400 und 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, hat CloudFront Functions 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 Origin zurückgegeben wurde, an den Viewer zurückgegeben.

Tipp

Wenn Sie CloudFront Funktionen verwenden, um einen Hauptteil zu ersetzen, achten Sie darauf, die entsprechenden Überschriften, z. B. content-encodingcontent-type, odercontent-length, am neuen Hauptinhalt auszurichten.

Wenn beispielsweise der CloudFront Ursprung oder der Cache zurückgegeben wird, die Antwortfunktion des Betrachters content-encoding: gzip jedoch einen Textkörper festlegt, der aus reinem Text besteht, muss die Funktion auch die content-type Überschriften content-encoding und entsprechend ändern.

Wenn Ihre CloudFront Funktion so konfiguriert ist, dass sie einen HTTP-Fehler von 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

Verwenden Sie Code wie den folgenden, um eine Abfragezeichenfolge in Ihrem Funktionscode zu ändern.

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-Anfrage oder -Antwort konvertiert, wird der erste Buchstabe jedes Worts in Header-Namen groß geschrieben. Wörter werden durch einen Bindestrich (-) getrennt. Wenn Ihr Funktionscode beispielsweise einen Header mit dem Namenexample-header-name, CloudFront konvertiert diesen Example-Header-Name in der HTTP-Anfrage oder -Antwort in.

Beispiel

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

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

Stellen Sie sich eine HTTP-Anfrage mit den folgenden Accept Headern vor.

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

Diese Header werden im Objekt wie folgt dargestellt. request

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

Der erste Header-Wert (in diesem Fallapplication/json) wird sowohl in den multiValue Eigenschaften als value auch 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 Functions 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 Anfrage 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:

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