Lambda@Edge-Ereignisstruktur - Amazon CloudFront

Lambda@Edge-Ereignisstruktur

In den folgenden Themen werden die Anforderungs- und Antwortereignisobjekte beschrieben, die von CloudFront an eine Lambda@Edge-Funktion übergeben werden, wenn sie ausgelöst wird.

Dynamische Ursprungsauswahl

Sie können das Pfadmuster in einem Cache-Verhalten verwenden, um Anforderungen an einen Ursprung zu leiten, basierend auf dem Pfad und Namen des angeforderten Objekts, z. B. images/*.jpg. Mit Lambda@Edge können Sie Anforderungen auch auf der Grundlage anderer Merkmale, wie z. B. der Werte in Anforderungs-Headern, an einen Ursprung weiterleiten.

Es gibt eine Reihe von Möglichkeiten, wie diese dynamische Ursprungsauswahl genutzt werden kann. So können Sie z. B. Anforderungen über Ursprünge in verschiedenen geografischen Gebieten verteilen, um den globalen Lastausgleich zu unterstützen. Oder Sie können Anforderungen selektiv an verschiedene Ursprünge weiterleiten, die jeweils eine bestimmte Funktion erfüllen: Bot-Handling, SEO-Optimierung, Authentifizierung und so weiter. Code-Beispiele, die die Verwendung dieser Funktion demonstrieren, finden Sie unter Inhaltsbasierte dynamische Ursprungsauswahl –Beispiele.

Im CloudFront-Ursprungsanforderungsereignis enthält das origin-Objekt in der Ereignisstruktur Informationen über den Ursprung, an den die Anforderung auf der Grundlage des Pfadmusters weitergeleitet werden würde. Sie können die Werte im origin-Objekt aktualisieren, um eine Anforderung an eine andere Herkunft weiterzuleiten. Wenn Sie das origin-Objekt aktualisieren, müssen Sie den Ursprung in der Verteilung nicht definieren. Sie können ein Amazon S3-Ursprungsobjekt auch durch ein benutzerdefiniertes Ursprungsobjekt ersetzen und umgekehrt. Sie können jedoch nur einen einzigen Ursprung pro Anforderung angeben; entweder einen benutzerdefinierten Ursprung oder einen Amazon S3-Ursprung, aber nicht beide.

Anforderungsereignisse

Die folgenden Themen zeigen die Struktur des Objekts, das CloudFront an eine Lambda-Funktion für Betrachter- und Ursprungsanforderungsereignisse übergibt. Diese Beispiele zeigen eine GET-Anfrage ohne Körper. Im Anschluss an die Beispiele finden Sie eine Liste aller möglichen Felder in Betrachter- und Ursprungsanforderungsereignissen.

Beispiel-Betrachteranfrage

Das folgende Beispiel zeigt ein Betrachteranfrageereignisobjekt.

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-request", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.66.0" } ], "accept": [ { "key": "accept", "value": "*/*" } ] }, "method": "GET", "querystring": "", "uri": "/" } } } ] }

Beispiel-Ursprungsanforderung

Das folgende Beispiel zeigt ein Ursprungsanforderungsereignisobjekt.

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "origin-request", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "x-forwarded-for": [ { "key": "X-Forwarded-For", "value": "203.0.113.178" } ], "user-agent": [ { "key": "User-Agent", "value": "Amazon CloudFront" } ], "via": [ { "key": "Via", "value": "2.0 2afae0d44e2540f472c0635ab62c232b.cloudfront.net (CloudFront)" } ], "host": [ { "key": "Host", "value": "example.org" } ], "cache-control": [ { "key": "Cache-Control", "value": "no-cache, cf-no-cache" } ] }, "method": "GET", "origin": { "custom": { "customHeaders": {}, "domainName": "example.org", "keepaliveTimeout": 5, "path": "", "port": 443, "protocol": "https", "readTimeout": 30, "sslProtocols": [ "TLSv1", "TLSv1.1", "TLSv1.2" ] } }, "querystring": "", "uri": "/" } } } ] }

Anforderungsereignisfelder

Anforderungsereignisobjektdaten sind in zwei Unterobjekten enthalten: config (Records.cf.config) und request (Records.cf.request). In den folgenden Listen werden die Felder jedes Unterobjekts beschrieben.

Felder im Config-Objekt

Die folgende Liste beschreibt die Felder im config-Objekt (Records.cf.config).

distributionDomainName (Schreibgeschützt)

Der Domänenname der Verteilung, die der Anforderung zugeordnet ist.

distributionID (Schreibgeschützt)

Die ID der Verteilung, die der Anforderung zugeordnet ist.

eventType (Schreibgeschützt)

Der Typ des Auslösers, der der Anforderung zugeordnet ist: viewer-request oder origin-request.

requestId (Schreibgeschützt)

Eine verschlüsselte Zeichenfolge, die eine Betrachter-an-CloudFront-Anfrage eindeutig bezeichnet. Der requestId-Wert wird auch in den CloudFront-Zugriffsprotokollen als x-edge-request-id angezeigt. Weitere Informationen erhalten Sie unter Konfigurieren und Verwenden von Standardprotokollen (Zugriffsprotokolle) und Felder der Standardprotokolldatei.

Felder im Anforderungsobjekt

Die folgende Liste beschreibt die Felder im request-Objekt (Records.cf.request).

clientIp (Schreibgeschützt)

Die IP-Adresse des Betrachters, der die Anforderung gestellt 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.

Header (lesen/schreiben)

Die Header der Anforderung. Beachten Sie Folgendes:

  • Die Schlüssel im headers-Objekt sind kleingeschriebene Versionen von Standard-HTTP-Header-Namen. Über diese Kleinbuchstaben-Schlüssel haben Sie Zugriff auf die Headerwerte (ohne Berücksichtigung von Groß-/Kleinschreibung).

  • Jedes Header-Objekt (z. B. headers["accept"] oder headers["host"]) ist ein Array mit Schlüssel-Wert-Paaren. Für einen bestimmten Header enthält das Array ein Schlüssel-Wert-Paar für jeden Wert in der Anforderung.

  • key enthält den Namen des Headers unter Beachtung der Groß-/Kleinschreibung, wie er in der HTTP-Anforderung angezeigt wird, z. B. Host, User-Agent, X-Forwarded-For usw.

  • value enthält den Header-Wert, wie er in der HTTP-Anforderung angezeigt wird.

  • Wenn Ihre Lambda-Funktion Anfrage-Header hinzufügt oder ändert und Sie das key-Header-Feld nicht einschließen, fügt Lambda@Edge automatisch einen Header „key“ mit dem von Ihnen angegebenen Header-Namen ein. Unabhängig davon, wie Sie den Header-Namen formatiert haben, wird der automatisch eingefügte Header-Schlüssel mit einem großen Anfangsbuchstaben für jeden Teil formatiert, wobei die einzelnen Teile durch Bindestriche (-) getrennt werden.

    Beispielsweise können Sie einen Header wie den folgenden ohne Header hinzufügen key:

    "user-agent": [ { "value": "ExampleCustomUserAgent/1.X.0" } ]

    In diesem Beispiel fügt Lambda @Edge automatisch ein ei "key": "User-Agent".

Weitere Informationen zu Einschränkungen zur Verwendung von Headern finden Sie unter Einschränkungen für Edge-Funktionen.

method (Schreibgeschützt)

Die HTTP-Methode der Anforderung.

querystring (Lesen/Schreiben)

Die Abfragezeichenfolge, falls vorhanden, in der Anforderung. Wenn die Anfrage keine Abfragezeichenfolge enthält, umfasst das Ereignisobjekt dennoch querystring mit einem leeren Wert. Weitere Informationen zu Abfragezeichenfolgen finden Sie unter Zwischenspeichern von Inhalten auf der Grundlage von Abfragezeichenfolgeparametern.

uri (Lesen/Schreiben)

Der relative Pfad des angeforderten Objekts. Wenn Ihre Lambda-Funktion den uri-Wert ändert, beachten Sie Folgendes:

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

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

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

body (Lesen/Schreiben)

Der Hauptteil der HTTP-Anforderung. Die body-Struktur kann folgende Felder enthalten:

inputTruncated (Schreibgeschützt)

Ein boolesches Flag, das angibt, ob der Textkörper von Lambda@Edge abgeschnitten wurde. Weitere Informationen finden Sie unter Einschränkungen für Anforderungstext mit der Option „Text einschließen“.

action (Lesen/Schreiben)

Die Aktion, die Sie für den Body durchführen möchten. Für action gibt es die folgenden Optionen:

  • read-only: Dies ist die Standardeinstellung. Lambda@Edge ignoriert bei der Rückgaben der Antwort von der Lambda-Funktion alle Änderungen an action oder encoding. wenn data schreibgeschützt ist.

  • replace: Geben Sie diese Option an, wenn Sie den an den Ursprung gesendeten Textkörper ersetzen möchten.

encoding (Lesen/Schreiben)

Die Kodierung für den Body. Wenn Lambda@Edge den Textkörper der Lambda-Funktion bereitstellt, konvertiert es den Textkörper zuerst zu base64-encoding. Wenn Sie replace für die action auswählen, um den Textkörper zu ersetzen, können Sie die Kodierung base64 (Standard) oder text verwenden. Wenn Sie encoding als base64 festlegen, der Textkörper jedoch kein gültiges base64 ist, gibt CloudFront einen Fehler zurück.

data (Lesen/Schreiben)

Der Inhalt des Anforderungs-Bodys.

origin (lesen/schreiben) (nur Ursprungsereignisse)

Der Ursprung, an den die Anfrage gesendet werden soll. Die origin-Struktur muss genau einen Ursprung enthalten, der ein benutzerdefinierter Ursprung oder ein Amazon S3-Ursprung sein kann. Die Ursprungsstruktur kann folgende Felder enthalten:

customHeaders (Lesen/Schreiben) (benutzerdefinierte und Amazon S3-Ursprünge)

Sie können benutzerdefinierte Header in die Anforderung aufnehmen, indem Sie für jeden benutzerdefinierten Header einen Header-Namen und einen -Wert angeben. Sie können keine Header hinzufügen, die nicht erlaubt sind, und ein Header mit demselben Namen kann in Records.cf.request.headers nicht vorhanden sein. Die Hinweise zu Anforderungs-Headern gelten auch für benutzerdefinierte Header. Weitere Informationen erhalten Sie unter Benutzerdefinierte Header, die CloudFront nicht zu Ursprungsanforderungen hinzufügen kann und Einschränkungen für Edge-Funktionen.

domainName (Lesen/Schreiben) (benutzerdefinierte und Amazon S3-Ursprünge)

Der Domänenname des Ursprungs. Der Domänenname darf nicht leer sein.

  • Für benutzerdefinierte Ursprünge – Geben Sie einen DNS-Domänennamen an, z. B. www.example.com Der Domänenname darf keinen Doppelpunkt (:) enthalten und keine IP-Adresse sein. Der Domänenname kann bis zu 253 Zeichen lang sein.

  • Für Amazon S3-Ursprünge – Geben Sie den DNS-Domänennamen des Amazon S3-Buckets an, z. B. awsexamplebucket.s3.eu-west-1.amazonaws.com. Der Name kann bis zu 128 Zeichen lang sein und muss in Kleinbuchstaben geschrieben werden.

path (Lesen/Schreiben) (benutzerdefinierte und Amazon S3-Ursprünge)

Der Verzeichnispfad auf dem Ursprung, aus dem die Anforderung den Inhalt abrufen soll. Der Pfad sollte mit einem Schrägstrich (/) beginnen, aber nicht mit einem enden (z. B. nicht mit example-path/). Nur für benutzerdefinierte Ursprünge sollte der Pfad URL-codiert sein und eine Maximallänge von 255 Zeichen haben.

keepaliveTimeout (lesen/schreiben) (nur benutzerdefinierte Ursprünge)

Dauer in Sekunden, für die CloudFront versuchen soll, die Verbindung zum Ursprung aufrechtzuerhalten, nachdem das letzte Paket der Antwort erhalten wurde. Der Wert muss eine Zahl zwischen 1 und 60 sein.

port (lesen/schreiben) (nur benutzerdefinierte Ursprünge)

Der Port, mit dem CloudFront eine Verbindung zu Ihrem benutzerdefinierten Ursprung herstellen soll. Der Port muss 80, 443 oder 1024 bis einschließlich 65535 sein.

protocol (lesen/schreiben) (nur benutzerdefinierte Ursprünge)

Das Verbindungsprotokoll, das von CloudFront beim Herstellen einer Verbindung zu Ihrem Ursprung verwendet werden soll. Dabei kann es sich um den Wert http oder https handeln.

readTimeout (lesen/schreiben) (nur benutzerdefinierte Ursprünge)

Dauer in Sekunden, für die CloudFront auf eine Antwort warten, nachdem Sie eine Anfrage an Ihren Ursprung gesendet haben. Dies gibt auch an, wie lange CloudFront warten soll, nachdem das Paket einer Antwort empfangen wurde, bevor das nächste Paket empfangen wird. Der Wert muss eine Zahl zwischen 4 und 60 sein.

sslProtocols (lesen/schreiben) (nur benutzerdefinierte Ursprünge)

Das minimale SSL/TLS-Protokoll, das von CloudFront beim Herstellen einer HTTPS-Verbindung mit Ihrem Ursprung verwendet werden kann. Werte können einer der folgenden sein: TLSv1.2, TLSv1.1, TLSv1 oder SSLv3.

authMethod ( Lesen/Schreiben) (nur Amazon S3-Ursprünge)

Wenn Sie eine Ursprungszugriffsidentität (Origin Access Identity, OAI) verwenden, legen Sie dieses Feld auf „origin-access-identity“ fest. Legen Sie es auf „none“ fest, wenn Sie keine OAI verwenden. Wenn Sie authMethod auf „origin-access-identity“ festlegen, gibt es mehrere Anforderungen:

  • Sie müssen die region angeben (siehe das folgende Feld).

  • Sie müssen dieselbe OAI verwenden, wenn Sie die Anforderung von einem Amazon S3-Ursprung zu einem anderen ändern.

  • Sie können eine OAI nicht verwenden, wenn Sie die Anforderung von einem benutzerdefinierten Ursprung zu einem Amazon S3-Ursprung ändern.

region ( Lesen/Schreiben) (nur Amazon S3-Ursprünge)

Die AWS-Region Ihres Amazon-S3-Buckets. Dies ist nur erforderlich, wenn Sie authMethod auf „origin-access-identity“ festlegen.

Antwortereignisse

Die folgenden Themen zeigen die Struktur des Objekts, das CloudFront an eine Lambda-Funktion für Betrachter- und Ursprungsantwortereignisse übergibt. Im Anschluss an die Beispiele finden Sie eine Liste aller möglichen Felder in Betrachter- und Ursprungantwortereignissen.

Beispiel-Ursprungsantwort

Das folgende Beispiel zeigt ein Ursprungsantwortereignisobjekt.

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "origin-response", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "x-forwarded-for": [ { "key": "X-Forwarded-For", "value": "203.0.113.178" } ], "user-agent": [ { "key": "User-Agent", "value": "Amazon CloudFront" } ], "via": [ { "key": "Via", "value": "2.0 8f22423015641505b8c857a37450d6c0.cloudfront.net (CloudFront)" } ], "host": [ { "key": "Host", "value": "example.org" } ], "cache-control": [ { "key": "Cache-Control", "value": "no-cache, cf-no-cache" } ] }, "method": "GET", "origin": { "custom": { "customHeaders": {}, "domainName": "example.org", "keepaliveTimeout": 5, "path": "", "port": 443, "protocol": "https", "readTimeout": 30, "sslProtocols": [ "TLSv1", "TLSv1.1", "TLSv1.2" ] } }, "querystring": "", "uri": "/" }, "response": { "headers": { "access-control-allow-credentials": [ { "key": "Access-Control-Allow-Credentials", "value": "true" } ], "access-control-allow-origin": [ { "key": "Access-Control-Allow-Origin", "value": "*" } ], "date": [ { "key": "Date", "value": "Mon, 13 Jan 2020 20:12:38 GMT" } ], "referrer-policy": [ { "key": "Referrer-Policy", "value": "no-referrer-when-downgrade" } ], "server": [ { "key": "Server", "value": "ExampleCustomOriginServer" } ], "x-content-type-options": [ { "key": "X-Content-Type-Options", "value": "nosniff" } ], "x-frame-options": [ { "key": "X-Frame-Options", "value": "DENY" } ], "x-xss-protection": [ { "key": "X-XSS-Protection", "value": "1; mode=block" } ], "content-type": [ { "key": "Content-Type", "value": "text/html; charset=utf-8" } ], "content-length": [ { "key": "Content-Length", "value": "9593" } ] }, "status": "200", "statusDescription": "OK" } } } ] }

Beispiel-Betrachterantwort

Das folgende Beispiel zeigt ein Betrachterantwortereignisobjekt.

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-response", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.66.0" } ], "accept": [ { "key": "accept", "value": "*/*" } ] }, "method": "GET", "querystring": "", "uri": "/" }, "response": { "headers": { "access-control-allow-credentials": [ { "key": "Access-Control-Allow-Credentials", "value": "true" } ], "access-control-allow-origin": [ { "key": "Access-Control-Allow-Origin", "value": "*" } ], "date": [ { "key": "Date", "value": "Mon, 13 Jan 2020 20:14:56 GMT" } ], "referrer-policy": [ { "key": "Referrer-Policy", "value": "no-referrer-when-downgrade" } ], "server": [ { "key": "Server", "value": "ExampleCustomOriginServer" } ], "x-content-type-options": [ { "key": "X-Content-Type-Options", "value": "nosniff" } ], "x-frame-options": [ { "key": "X-Frame-Options", "value": "DENY" } ], "x-xss-protection": [ { "key": "X-XSS-Protection", "value": "1; mode=block" } ], "age": [ { "key": "Age", "value": "2402" } ], "content-type": [ { "key": "Content-Type", "value": "text/html; charset=utf-8" } ], "content-length": [ { "key": "Content-Length", "value": "9593" } ] }, "status": "200", "statusDescription": "OK" } } } ] }

Ereignisorientierter

Die Daten des Antwortereignisobjekts sind in drei Unterobjekten enthalten: config (Records.cf.config), request (Records.cf.request) und response (Records.cf.response). Weitere Hinweise zu den Feldern im Anforderungsobjekt finden Sie unter Felder im Anforderungsobjekt. In den folgenden Listen werden die Felder in den Unterobjekten config und response beschrieben.

Felder im Config-Objekt

Die folgende Liste beschreibt die Felder im config-Objekt (Records.cf.config).

distributionDomainName (Schreibgeschützt)

Der Domänenname der Verteilung, die der Antwort zugeordnet ist.

distributionID (Schreibgeschützt)

Die ID der Verteilung, die der Antwort zugeordnet ist.

eventType (Schreibgeschützt)

Der Typ des Auslösers, der der Antwort zugeordnet ist: origin-response oder viewer-response.

requestId (Schreibgeschützt)

Eine verschlüsselte Zeichenfolge, die eindeutig die Betrachter-an-CloudFront-Anforderung identifiziert, der diese Antwort zugeordnet ist. Der requestId-Wert wird auch in den CloudFront-Zugriffsprotokollen als x-edge-request-id angezeigt. Weitere Informationen erhalten Sie unter Konfigurieren und Verwenden von Standardprotokollen (Zugriffsprotokolle) und Felder der Standardprotokolldatei.

Felder im Antwortobjekt

Die folgende Liste beschreibt die Felder im response-Objekt (Records.cf.response). Hinweise zum Generieren einer HTTP-Antwort mithilfe einer Lambda@Edge-Funktion finden Sie unter Generierung von HTTP-Antworten in Anforderungsauslösern.

headers (Lesen/Schreiben)

Die Header der Antwort. Beachten Sie Folgendes:

  • Die Schlüssel im headers-Objekt sind kleingeschriebene Versionen von Standard-HTTP-Header-Namen. Über diese Kleinbuchstaben-Schlüssel haben Sie Zugriff auf die Headerwerte (ohne Berücksichtigung von Groß-/Kleinschreibung).

  • Jedes Header-Objekt (z. B. headers["content-type"] oder headers["content-length"]) ist ein Array mit Schlüssel-Wert-Paaren. Für einen bestimmten Header enthält das Array ein Schlüssel-Wert-Paar für jeden Wert in der generierten Antwort.

  • key enthält den Namen des Headers unter Beachtung der Groß-/Kleinschreibung, wie er in der HTTP-Antwort angezeigt wird z. B. Content-Type, Content-Length usw.

  • value enthält den Header-Wert, wie er in der HTTP-Antwort angezeigt wird.

  • Wenn Ihre Lambda-Funktion Antwort-Header hinzufügt oder ändert und Sie das key-Header-Feld nicht einschließen, fügt Lambda@Edge automatisch einen Header „key“ mit dem von Ihnen angegebenen Header-Namen ein. Unabhängig davon, wie Sie den Header-Namen formatiert haben, wird der automatisch eingefügte Header-Schlüssel mit einem großen Anfangsbuchstaben für jeden Teil formatiert, wobei die einzelnen Teile durch Bindestriche (-) getrennt werden.

    Beispielsweise können Sie einen Header wie den folgenden ohne Header hinzufügen key:

    "content-type": [ { "value": "text/html;charset=UTF-8" } ]

    In diesem Beispiel fügt Lambda @Edge automatisch ein ei "key": "Content-Type".

Weitere Informationen zu Einschränkungen zur Verwendung von Headern finden Sie unter Einschränkungen für Edge-Funktionen.

status

Den HTTP-Statuscode der Antwort.

statusDescription

Die HTTP-Statusbeschreibung der Antwort.