Hilfsmethoden für die Änderung des Ursprungs

Dieser Abschnitt gilt, wenn Sie den für die Anfrage verwendeten Ursprung in Ihrem CloudFront Functions-Code dynamisch aktualisieren oder ändern. Sie können den Ursprung nur auf Anfrage des Betrachters aktualisieren ( CloudFront Funktionen). CloudFront Functions verfügt über ein Modul, das Hilfsmethoden zur dynamischen Aktualisierung oder Änderung des Ursprungs bereitstellt.

Um dieses Modul zu verwenden, erstellen Sie eine CloudFront Funktion mit JavaScript Runtime 2.0 und fügen Sie die folgende Anweisung in die erste Zeile des Funktionscodes ein:

import cf from 'cloudfront';

Weitere Informationen finden Sie unter JavaScript Runtime 2.0-Funktionen für CloudFront Funktionen.

Anmerkung

Auf den Seiten Test-API und Testkonsole wird nicht getestet, ob eine Ursprungsänderung stattgefunden hat. Durch das Testen wird jedoch sichergestellt, dass der Funktionscode fehlerfrei ausgeführt wird.

Wählen Sie zwischen CloudFront Functions und Lambda @Edge

Sie können Ihre Ursprünge aktualisieren, indem Sie entweder CloudFront Functions oder Lambda @Edge verwenden.

Wenn Sie CloudFront Functions verwenden, um Ursprünge zu aktualisieren, verwenden Sie den Viewer-Request-Event-Trigger, was bedeutet, dass diese Logik bei jeder Anfrage ausgeführt wird, wenn diese Funktion verwendet wird. Bei der Verwendung von Lambda @Edge befinden sich die Funktionen zur Aktualisierung des Ursprungs auf dem Trigger des Origin-Request-Ereignisses, was bedeutet, dass diese Logik nur bei Cache-Fehlschlägen ausgeführt wird.

Ihre Wahl hängt weitgehend von Ihrer Arbeitslast und der bestehenden Nutzung von CloudFront Functions und Lambda @Edge in Ihren Distributionen ab. Die folgenden Überlegungen können Ihnen bei der Entscheidung helfen, ob Sie CloudFront Functions oder Lambda @Edge verwenden möchten, um Ihre Ursprünge zu aktualisieren.

CloudFront Functions ist in den folgenden Situationen am nützlichsten:

• Wenn Ihre Anfragen dynamisch sind (was bedeutet, dass sie nicht zwischengespeichert werden können) und immer an den Ursprung weitergeleitet werden. CloudFront Functions bietet eine bessere Leistung und niedrigere Gesamtkosten.

• Wenn Sie bereits über eine CloudFront Viewer-Anforderungsfunktion verfügen, die bei jeder Anfrage ausgeführt wird, können Sie die ursprüngliche Aktualisierungslogik zur vorhandenen Funktion hinzufügen.

Informationen zur Verwendung von CloudFront Funktionen zur Aktualisierung von Ursprüngen finden Sie in den folgenden Themen in den Hilfsmethoden.

Lambda @Edge ist in den folgenden Situationen am nützlichsten:

• Wenn Sie Inhalte haben, die in hohem Maße zwischengespeichert werden können, kann Lambda @Edge kostengünstiger sein, da es nur bei Cache-Fehlern ausgeführt wird, während CloudFront Functions bei jeder Anfrage ausgeführt wird.

• Wenn Sie bereits über eine Lambda @Edge -Funktion für Ursprungsanfragen verfügen, können Sie die Origin-Aktualisierungslogik zur vorhandenen Funktion hinzufügen.

• Wenn Ihre Origin-Aktualisierungslogik das Abrufen von Daten aus Datenquellen von Drittanbietern wie Amazon DynamoDB oder Amazon S3 erfordert.

Weitere Informationen zu Lambda @Edge finden Sie unterPersonalisieren Sie am Rand mit Lambda @Edge.

updateRequestOrigin() -Methode

Verwenden Sie die updateRequestOrigin() Methode, um die Ursprungseinstellungen für eine Anfrage zu aktualisieren. Sie können diese Methode verwenden, um bestehende Ursprungseigenschaften für Ursprünge zu aktualisieren, die bereits in Ihrer Distribution definiert sind, oder um einen neuen Ursprung für die Anfrage zu definieren. Geben Sie dazu die Eigenschaften an, die Sie ändern möchten.

Wichtig

Alle Einstellungen, die Sie nicht in der angebenupdateRequestOrigin(), erben dieselben Einstellungen aus der Konfiguration des vorhandenen Ursprungs.

Der von der updateRequestOrigin() Methode festgelegte Ursprung kann ein beliebiger HTTP-Endpunkt sein und muss kein vorhandener Ursprung in Ihrer CloudFront Distribution sein.

Hinweise

• Wenn Sie einen Ursprung aktualisieren, der Teil einer Ursprungsgruppe ist, wird nur der primäre Ursprung der Ursprungsgruppe aktualisiert. Der sekundäre Ursprung bleibt unverändert. Jeder Antwortcode des geänderten Ursprungs, der den Failover-Kriterien entspricht, löst einen Failover zum sekundären Ursprung aus.

• Wenn Sie den Quelltyp ändern und OAC aktiviert haben, stellen Sie sicher, dass der Eingangstyp mit dem neuen Originstyp originAccessControlConfig übereinstimmt.

• Sie können die updateRequestOrigin() Methode nicht verwenden, um VPC-Ursprünge zu aktualisieren. Die Anfrage wird fehlschlagen.

Anforderung

updateRequestOrigin({origin properties})

Die origin properties kann Folgendes enthalten:

domainName (optional)

Der Domänenname des Ursprungs. Wenn dies nicht angegeben wird, wird stattdessen der Domainname des zugewiesenen Ursprungs verwendet.

Für benutzerdefinierte Ursprünge

Geben Sie einen DNS-Domainnamen an, z. www.example.com B. Der Domainname darf keinen Doppelpunkt (:) enthalten und darf keine IP-Adresse sein. Der Domänenname kann bis zu 253 Zeichen lang sein.

Für S3-Ursprünge

Geben Sie den DNS-Domainnamen des Amazon S3 S3-Buckets an, z. amzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com B. Der Name kann bis zu 128 Zeichen lang sein und muss in Kleinbuchstaben geschrieben werden.

originPath (optional)

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. Zum Beispiel sollte er nicht mit example-path/ enden. Wenn dies nicht angegeben ist, wird der Quellpfad vom zugewiesenen Ursprung verwendet.

Für benutzerdefinierte Ursprünge

Der Pfad sollte URL-kodiert sein und eine maximale Länge von 255 Zeichen haben.

customHeaders (optional)

Sie können benutzerdefinierte Header in die Anforderung aufnehmen, indem Sie für jeden benutzerdefinierten Header einen Header-Namen und einen -Wert angeben. Das Format unterscheidet sich von dem der Anfrage- und Antwortheader in der Ereignisstruktur. Verwenden Sie die folgende Syntax für Schlüssel-Wert-Paare:

{"key1": "value1", "key2": "value2", ...}

Sie können keine unzulässigen Header hinzufügen, und ein Header mit demselben Namen darf nicht auch in der eingehenden Anfrage enthalten sein. headers Der Header-Name muss in Ihrem Funktionscode in Kleinbuchstaben geschrieben werden. Wenn CloudFront Functions das Ereignisobjekt wieder in eine HTTP-Anforderung konvertiert, wird der erste Buchstabe jedes Worts in Header-Namen groß geschrieben und die Wörter werden durch einen Bindestrich getrennt.

Wenn der Funktionscode beispielsweise einen Header namensexample-header-name, CloudFront konvertiert diesen in der HTTP-Anfrage Example-Header-Name in einen Header hinzufügt. Weitere Informationen erhalten Sie unter Benutzerdefinierte Header, die nicht zu CloudFront ursprünglichen Anfragen hinzugefügt werden können und Einschränkungen für Edge-Funktionen.

Wenn dies nicht angegeben wird, werden alle benutzerdefinierten Header aus dem zugewiesenen Ursprung verwendet.

Verbindungsversuche (optional)

Die Häufigkeit, mit der CloudFront versucht wird, eine Verbindung zum Ursprung herzustellen. Das Minimum ist 1 und das Maximum ist 3. Wenn dies nicht angegeben ist, werden die Verbindungsversuche vom zugewiesenen Ursprung verwendet.

OriginShield (optional)

Dadurch wird CloudFront Origin Shield aktiviert oder aktualisiert. Die Verwendung von Origin Shield kann dazu beitragen, die Belastung Ihres Ursprungs zu reduzieren. Weitere Informationen finden Sie unter Amazon CloudFront Origin Shield verwenden. Wenn dies nicht angegeben ist, werden die Origin Shield-Einstellungen des zugewiesenen Ursprungs verwendet.

aktiviert (erforderlich)

Boolescher Ausdruck zur Aktivierung oder Deaktivierung von Origin Shield. Akzeptiert einen true Oder-Wertfalse.

Region (erforderlich, wenn aktiviert)

Das AWS-Region für Origin Shield. Geben Sie die AWS-Region an, die die niedrigste Latenz zu Ihrem Ursprung aufweist. Verwenden Sie den Regionalcode, nicht den Namen der Region. Verwenden Sie dies beispielsweise, us-east-2 um die Region USA Ost (Ohio) anzugeben.

Wenn du CloudFront Origin Shield aktivierst, musst du das AWS-Region dafür angeben. Eine Liste der verfügbaren Regionen AWS-Regionen und Hilfe bei der Auswahl der besten Region für deine Herkunft findest du unterAuswahl der AWS Region für Origin Shield.

originAccessControlConfig (optional)

Die eindeutige Kennung einer Origin Access Control (OAC) für diesen Ursprung. Dies wird nur verwendet, wenn der Ursprung ein CloudFront OAC unterstützt, z. B. Amazon S3, Lambda-Funktion URLs und MediaStore MediaPackage V2. Wenn dies nicht angegeben ist, werden die OAC-Einstellungen des zugewiesenen Ursprungs verwendet.

Dies unterstützt die ältere Origin Access Identity (OAI) nicht. Weitere Informationen finden Sie unter Zugriff auf einen AWS Ursprung einschränken.

aktiviert (erforderlich)

Boolescher Ausdruck zum Aktivieren oder Deaktivieren von OAC. Akzeptiert einen Oder-Werttrue. false

SigningBehavior (erforderlich, wenn aktiviert)

Gibt an, welche Anfragen CloudFront signiert werden (fügt Authentifizierungsinformationen hinzu). Geben Sie always für den häufigsten Anwendungsfall an. Weitere Informationen finden Sie unter Erweiterte Einstellungen für die Ursprungszugriffssteuerung.

Folgende Werte sind in diesem Feld möglich:

• always— CloudFront signiert alle ursprünglichen Anfragen und überschreibt dabei den Authorization Header der Viewer-Anfrage, falls vorhanden.

• never— signiert CloudFront keine ursprünglichen Anfragen. Dieser Wert deaktiviert die Ursprungszugriffskontrolle für den Ursprung.

• no-override— Wenn die Viewer-Anfrage den Authorization Header nicht enthält, wird die ursprüngliche Anfrage CloudFront signiert. Wenn die Viewer-Anfrage den Authorization Header enthält, wird die ursprüngliche Anfrage CloudFront nicht signiert und stattdessen der Authorization Header aus der Viewer-Anfrage weitergegeben.

  Warnung

  Um den Authorization Header aus der Viewer-Anfrage weiterzugeben, müssen Sie ihn zu einer Quellanforderungsrichtlinie für alle Cache-Verhaltensweisen hinzufügen, die Ursprünge verwenden, die mit dieser ursprünglichen Zugriffskontrolle verknüpft sind. Weitere Informationen finden Sie unter Kontrollieren Sie Herkunftsanfragen mit einer Richtlinie.

SigningProtocol (erforderlich, wenn aktiviert)

Das Signaturprotokoll des OAC, das festlegt, wie Anfragen CloudFront signiert (authentifiziert) werden. Der einzige gültige Wert ist sigv4.

OriginType (erforderlich, wenn aktiviert)

Der Typ des Ursprungs für dieses OAC. Gültige Werte sind: s3, mediapackagev2, mediastore und lambda.

Timeouts (optional)

Timeouts, die Sie angeben können, wie lange versucht CloudFront werden soll, auf die Antwort von Origins zu warten oder Daten zu senden. Wenn dies nicht angegeben ist, werden die Timeout-Einstellungen des zugewiesenen Ursprungs verwendet.

readTimeout (optional)

Timeouts gelten nur für benutzerdefinierte Ursprünge, nicht für Amazon S3 S3-Ursprünge. (Bei S3-Ursprungskonfigurationen werden diese Einstellungen ignoriert.) readTimeoutgilt für die beiden folgenden Werte:

• Wie lange (in Sekunden) auf eine Antwort gewartet wird, nachdem eine Anfrage an den Ursprung weitergeleitet CloudFront wurde.

• Wie lange (in Sekunden) nach dem Empfang eines Antwortpakets vom Ursprung und vor dem Empfang des nächsten Pakets CloudFront gewartet wird.

Das minimale Timeout beträgt 1 Sekunde und das Maximum 60 Sekunden. Weitere Informationen finden Sie unter Antwort-Timeout (nur benutzerdefinierte und VPC-Ursprünge).

keepAliveTimeout (Optional)

Timeouts gelten nur für benutzerdefinierte Ursprünge, nicht für Amazon S3 S3-Ursprünge. (Bei S3-Ursprungskonfigurationen werden diese Einstellungen ignoriert.) keepAliveTimeoutgibt an, wie lange versucht CloudFront werden soll, die Verbindung zum Ursprung aufrechtzuerhalten, nachdem das letzte Paket der Antwort empfangen wurde. Das minimale Timeout beträgt 1 Sekunde und das Maximum 60 Sekunden. Weitere Informationen finden Sie unter Keep-Alive-Timeout (nur benutzerdefinierte und VPC-Ursprünge).

ConnectionTimeout (optional)

Die Anzahl der Sekunden, die CloudFront gewartet wird, wenn versucht wird, eine Verbindung zum Ursprung herzustellen. Das minimale Timeout beträgt 1 Sekunde und das Maximum 10 Sekunden. Weitere Informationen finden Sie unter Verbindungstimeout.

customOriginConfig (Optional)

Wird verwendetcustomOriginConfig, um Verbindungseinstellungen für Ursprünge anzugeben, die kein Amazon S3 S3-Bucket sind. Es gibt eine Ausnahme: Sie können diese Einstellungen angeben, wenn der S3-Bucket mit statischem Website-Hosting konfiguriert ist. (Bei anderen Arten von S3-Bucket-Konfigurationen werden diese Einstellungen ignoriert.) Wenn customOriginConfig nicht angegeben, werden die Einstellungen des zugewiesenen Ursprungs verwendet.

Port (erforderlich)

Der HTTP-Port, der für die Verbindung zum Ursprung CloudFront verwendet wird. Geben Sie den HTTP-Port an, den der Ursprung überwacht.

Protokoll (erforderlich)

Gibt das Protokoll (HTTP oder HTTPS) an, das für die Verbindung zum Ursprung CloudFront verwendet wird. Gültige Werte sind:

• http— verwendet CloudFront immer HTTP, um eine Verbindung zum Ursprung herzustellen

• https— verwendet CloudFront immer HTTPS, um eine Verbindung zum Ursprung herzustellen

sslProtocols (erforderlich)

Eine Liste, die das SSL-/TLS-Protokoll angibt, das mindestens CloudFront verwendet wird, wenn Sie über HTTPS eine Verbindung zu Ihrem Ursprung herstellen. Gültige Werte sind: SSLv3, TLSv1, TLSv1.1 und TLSv1.2. Weitere Informationen finden Sie unter Mindest-SSL-Protokoll für Ursprung.

Beispiel — Aktualisierung auf den Ursprung der Amazon S3 S3-Anfrage

Das folgende Beispiel ändert den Ursprung der Viewer-Anfrage in einen S3-Bucket, aktiviert OAC und setzt benutzerdefinierte Header zurück, die an den Ursprung gesendet wurden.

cf.updateRequestOrigin({
    "domainName" : "amzn-s3-demo-bucket-in-us-east-1.s3.us-east-1.amazonaws.com",
    "originAccessControlConfig": {
        "enabled": true,
        "signingBehavior": "always",
        "signingProtocol": "sigv4",
        "originType": "s3"
    },
    // Empty object resets any header configured on the assigned origin
    "customHeaders": {}
});

Beispiel — Aktualisierung der Herkunft der Application Load Balancer Balancer-Anforderung

Das folgende Beispiel ändert den Ursprung der Viewer-Anfrage in einen Application Load Balancer Balancer-Ursprung und legt einen benutzerdefinierten Header und Timeouts fest.

cf.updateRequestOrigin({
    "domainName" : "example-1234567890.us-east-1.elb.amazonaws.com",
    "timeouts": {
        "readTimeout": 30,
        "connectionTimeout": 5
    },
    "customHeaders": {
        "x-stage": "production",
        "x-region": "us-east-1"
    }
});

Beispiel — Update auf Origin mit aktiviertem Origin Shield

Im folgenden Beispiel ist Origin Shield für den Ursprung in der Distribution aktiviert. Der Funktionscode aktualisiert nur den Domainnamen, der für den Ursprung verwendet wurde, und lässt alle anderen optionalen Parameter weg. In diesem Fall wird Origin Shield weiterhin mit dem geänderten Ursprungs-Domainnamen verwendet, da die Origin Shield-Parameter nicht aktualisiert wurden.

cf.updateRequestOrigin({
    "domainName" : "www.example.com"
});

selectRequestOriginById() Methode

Verwenden Sie diese OptionselectRequestOriginById(), um einen vorhandenen Ursprung zu aktualisieren, indem Sie einen anderen Ursprung auswählen, der bereits in Ihrer Distribution konfiguriert ist. Diese Methode verwendet dieselben Einstellungen, die durch den aktualisierten Ursprung definiert sind.

Diese Methode akzeptiert nur Ursprünge, die bereits in derselben Distribution definiert sind, die beim Ausführen der Funktion verwendet wurde. Ursprünge werden durch die Quell-ID referenziert. Dabei handelt es sich um den Ursprungsnamen, den Sie bei der Einrichtung des Ursprungs definiert haben.

Wenn Sie in Ihrer Distribution einen VPC-Ursprung konfiguriert haben, können Sie mit dieser Methode Ihren Ursprung auf Ihren VPC-Ursprung aktualisieren. Weitere Informationen finden Sie unter Beschränken Sie den Zugriff mit VPC-Ursprüngen.

Anforderung

selectRequestOriginById(origin_id)

Im vorherigen Beispiel origin_id handelt es sich um eine Zeichenfolge, die auf den Ursprungsnamen eines Ursprungs in der Distribution verweist, auf der die Funktion ausgeführt wird.

Beispiel — Wählen Sie den Ursprung der Amazon S3 S3-Anfrage

Im folgenden Beispiel wird der angegebene Ursprung amzn-s3-demo-bucket-in-us-east-1 aus der Liste der Ursprünge ausgewählt, die mit der Verteilung verknüpft sind, und die Konfigurationseinstellungen des amzn-s3-demo-bucket-in-us-east-1 Ursprungs werden auf die Anfrage angewendet.

cf.selectRequestOriginById("amzn-s3-demo-bucket-in-us-east-1");

Beispiel — Wählen Sie den Ursprung der Application Load Balancer Balancer-Anforderung

Im folgenden Beispiel wird ein Application Load Balancer Balancer-Ursprung ausgewählt, der myALB-prod aus der Liste der mit der Verteilung verknüpften Ursprünge benannt ist, und wendet die Konfigurationseinstellungen von myALB-prod auf die Anforderung an.

cf.selectRequestOriginById("myALB-prod");

createRequestOriginMethode Group ()

Wird verwendetcreateRequestOriginGroup(), um zwei Ursprünge zu definieren, die als Ursprungsgruppe für Failover in Szenarien verwendet werden sollen, die eine hohe Verfügbarkeit erfordern.

Eine Ursprungsgruppe umfasst zwei Ursprünge (einen primären und einen sekundären) und ein von Ihnen festgelegtes Failover-Kriterium. Sie erstellen eine Ursprungsgruppe, um das Origin-Failover in zu unterstützen. CloudFront Wenn Sie mit dieser Methode eine Ursprungsgruppe erstellen oder aktualisieren, können Sie die Ursprungsgruppe anstelle eines einzelnen Ursprungs angeben. CloudFront führt unter Verwendung der Failover-Kriterien ein Failover vom primären Ursprung zum sekundären Ursprung durch.

Wenn Sie in Ihrer Distribution einen VPC-Ursprung konfiguriert haben, können Sie diese Methode verwenden, um eine Ursprungsgruppe mithilfe eines VPC-Ursprungs zu erstellen. Weitere Informationen finden Sie unter Beschränken Sie den Zugriff mit VPC-Ursprüngen.

Anforderung

createRequestOriginGroup({origin_group_properties})

Im vorherigen Beispiel origin_group_properties kann sie Folgendes enthalten:

OriginIDs (erforderlich)

Array vonorigin_ids, wobei das eine Zeichenfolge origin_id ist, die auf den Ursprungsnamen eines Ursprungs in der Distribution verweist, auf der die Funktion ausgeführt wird. Sie müssen zwei Ursprünge als Teil des Arrays angeben. Der erste Ursprung in der Liste ist der primäre Ursprung und der zweite Ursprung dient als zweiter Ursprung für Failover-Zwecke.

Auswahlkriterien (optional)

Wählen Sie aus, ob Sie die ursprünglichen default Failover-Kriterien oder die media-quality-score basierte Failoverlogik verwenden möchten. Gültige Werte sind:

• defaultverwendet die Failover-Kriterien, basierend auf den Statuscodes, die in der angegeben sind. failoverCriteria Wenn Sie die Funktion selectionCriteria nicht angeben, default wird verwendet.

• media-quality-scorewird verwendet, wenn die medienbewusste Routing-Funktion verwendet wird.

Failover-Kriterien (erforderlich)

Eine Reihe von Statuscodes, die, wenn sie vom primären Ursprung zurückgegeben werden, einen Failover CloudFront zum sekundären Ursprung auslösen. Wenn Sie eine bestehende Ursprungsgruppe überschreiben, überschreibt dieses Array alle Failover-Statuscodes, die in der ursprünglichen Konfiguration der Ursprungsgruppe festgelegt sind.

Wenn Sie diese Option verwenden media-quality-scoreselectionCriteria, CloudFront wird versucht, Anfragen auf der Grundlage der Medienqualitätsbewertung weiterzuleiten. Wenn der ausgewählte Ursprung einen in diesem Array festgelegten Fehlercode zurückgibt, CloudFront erfolgt ein Failover zum anderen Ursprung.

Beispiel — Gruppe mit Ursprung der Anfrage erstellen

Das folgende Beispiel erstellt eine Ursprungsgruppe für eine Anfrage, die den Ursprung verwendet IDs. Diese Ursprünge IDs stammen aus der Konfiguration der Ursprungsgruppe für die Distribution, die zur Ausführung dieser Funktion verwendet wurde.

cf.createRequestOriginGroup({
    originIds: ["us-east-1-s3-origin", "us-west-2-s3-origin"],
    failoverCriteria: {
        statusCodes: [500, 502, 503, 504] 
    }
});