Choisissez entre CloudFront Functions et Lambda @Edge updateRequestOrigin() méthode selectRequestOriginById() méthode createRequestOriginMéthode Group ()

Méthodes auxiliaires pour la modification de l'origine

Cette section s'applique si vous mettez à jour ou modifiez dynamiquement l'origine utilisée dans la demande dans votre code CloudFront Functions. Vous pouvez mettre à jour l'origine uniquement à la CloudFront demande du spectateur. CloudFront Functions possède un module qui fournit des méthodes d'assistance pour mettre à jour ou modifier dynamiquement l'origine.

Pour utiliser ce module, créez une CloudFront fonction à l'aide de JavaScript Runtime 2.0 et incluez l'instruction suivante dans la première ligne du code de fonction :


import cf from 'cloudfront';

Pour de plus amples informations, veuillez consulter JavaScript fonctionnalités d'exécution 2.0 pour CloudFront Functions.

Note

Les pages de l'API de test et de la console de test ne vérifient pas si une modification d'origine s'est produite. Cependant, les tests garantissent que le code de fonction s'exécute sans erreur.

Choisissez entre CloudFront Functions et Lambda @Edge

Vous pouvez mettre à jour vos origines en utilisant CloudFront Functions ou Lambda @Edge.

Lorsque vous utilisez CloudFront Functions pour mettre à jour les origines, vous utilisez le déclencheur d'événement de demande du visualiseur, ce qui signifie que cette logique s'exécutera à chaque demande lorsque cette fonction est utilisée. Lorsque vous utilisez Lambda @Edge, les fonctionnalités de mise à jour de l'origine se trouvent sur le déclencheur de l'événement de demande d'origine, ce qui signifie que cette logique ne s'exécute qu'en cas d'échec du cache.

Votre choix dépend largement de votre charge de travail et de toute utilisation existante de CloudFront Functions et Lambda @Edge dans vos distributions. Les considérations suivantes peuvent vous aider à décider d'utiliser CloudFront Functions ou Lambda @Edge pour mettre à jour vos origines.

CloudFront Les fonctions sont particulièrement utiles dans les situations suivantes :

Lorsque vos demandes sont dynamiques (c'est-à-dire qu'elles ne peuvent pas être mises en cache) et qu'elles vont toujours à l'origine. CloudFront Les fonctions offrent de meilleures performances et un coût global inférieur.
Lorsque vous disposez déjà d'une CloudFront fonction de demande d'affichage qui s'exécute sur chaque demande, vous pouvez ajouter la logique de mise à jour de l'origine à la fonction existante.

Pour utiliser CloudFront Functions pour mettre à jour les origines, consultez les méthodes d'assistance décrites dans les rubriques suivantes.

Lambda @Edge est particulièrement utile dans les situations suivantes :

Lorsque le contenu peut être facilement mis en cache, Lambda @Edge peut être plus rentable car il s'exécute uniquement en cas d'erreur de cache, CloudFront tandis que Functions s'exécute sur chaque requête.
Lorsque vous avez déjà une fonction Lambda @Edge de demande d'origine existante, vous pouvez ajouter la logique de mise à jour de l'origine dans la fonction existante.
Lorsque votre logique de mise à jour d'origine nécessite de récupérer des données à partir de sources de données tierces, telles qu'Amazon DynamoDB ou Amazon S3.

Pour plus d'informations sur Lambda @Edge, consultez. Personnalisez à la périphérie avec Lambda @Edge

updateRequestOrigin() méthode

Utilisez updateRequestOrigin() cette méthode pour mettre à jour les paramètres d'origine d'une demande. Vous pouvez utiliser cette méthode pour mettre à jour les propriétés d'origine existantes pour les origines déjà définies dans votre distribution, ou pour définir une nouvelle origine pour la demande. Pour ce faire, spécifiez les propriétés que vous souhaitez modifier.

Important

Tous les paramètres que vous ne spécifiez pas dans le updateRequestOrigin() hériteront des mêmes paramètres de la configuration d'origine existante.

L'origine définie par la updateRequestOrigin() méthode peut être n'importe quel point de terminaison HTTP et il n'est pas nécessaire qu'il s'agisse d'une origine existante au sein de votre CloudFront distribution.

Remarques

Si vous mettez à jour une origine qui fait partie d'un groupe d'origine, seule l'origine principale du groupe d'origine est mise à jour. L'origine secondaire reste inchangée. Tout code de réponse provenant de l'origine modifiée qui correspond aux critères de basculement déclenchera un basculement vers l'origine secondaire.
Si vous modifiez le type d'origine et que l'OAC est activé, assurez-vous que le type d'origine originAccessControlConfig correspond au nouveau type d'origine.
Vous ne pouvez pas utiliser updateRequestOrigin() cette méthode pour mettre à jour les origines des VPC. La demande échouera.

Demande


updateRequestOrigin({origin properties})

Ils origin properties peuvent contenir les éléments suivants :

DomainName (facultatif)

Nom de domaine de l'origine. Si ce n'est pas le cas, le nom de domaine de l'origine attribuée est utilisé à la place.

Pour des origines personnalisées: Spécifiez un nom de domaine DNS, tel quewww.example.com. Le nom de domaine ne peut pas inclure de deux-points (:) et ne peut pas être une adresse IP. Le nom du domaine peut contenir jusqu'à 253 caractères.
Pour S3 Origins: Spécifiez le nom de domaine DNS du compartiment Amazon S3, tel queamzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com. Il peut comporter jusqu'à 128 caractères, qui doivent tous être en minuscules.

OriginPath (facultatif)

Chemin de répertoire à l'origine où la demande doit localiser le contenu. Le chemin doit commencer par une barre oblique (/) mais ne doit pas se terminer par une barre oblique. Par exemple, cela ne devrait pas se terminer parexample-path/. Si ce n'est pas le cas, le chemin d'origine à partir de l'origine attribuée est utilisé.

Pour des origines personnalisées: Le chemin doit être codé en URL et avoir une longueur maximale de 255 caractères.

CustomHeaders (facultatif)

Vous pouvez inclure des en-têtes personnalisés dans la requête en spécifiant un nom et une valeur d'en-tête pour chacun d'eux. Le format est différent de celui des en-têtes de demande et de réponse dans la structure de l'événement. Utilisez la syntaxe de paire clé-valeur suivante :


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

Vous ne pouvez pas ajouter d'en-têtes interdits, et un en-tête portant le même nom ne peut pas également être présent dans la demande entrante. headers Le nom de l'en-tête doit être en minuscules dans le code de votre fonction. Lorsque CloudFront Functions reconvertit l'objet d'événement en requête HTTP, la première lettre de chaque mot dans les noms d'en-tête est mise en majuscule et les mots sont séparés par un trait d'union.

Par exemple, si le code de votre fonction ajoute un en-tête nomméexample-header-name, le CloudFront convertit en en-tête Example-Header-Name dans la requête HTTP. Pour plus d’informations, consultez En-têtes personnalisés qui ne CloudFront peuvent pas être ajoutés aux demandes d'origine et Restrictions sur les fonctions périphériques.

Si ce n'est pas le cas, tous les en-têtes personnalisés de l'origine assignée sont utilisés.

Tentatives de connexion (facultatif)

Nombre de CloudFront tentatives de connexion à l'origine. Le minimum est 1 et le maximum est 3. Si ce n'est pas le cas, les tentatives de connexion depuis l'origine assignée sont utilisées.

OriginShield (facultatif)

Cela active ou met à jour CloudFront Origin Shield. L'utilisation d'Origin Shield permet de réduire la charge sur votre origine. Pour de plus amples informations, veuillez consulter Utilisation d'Amazon CloudFront Origin Shield. Si ce n'est pas le cas, les paramètres Origin Shield de l'origine attribuée sont utilisés.

activé (obligatoire)

Expression booléenne pour activer ou désactiver Origin Shield. Accepte une false valeur true or.

région (obligatoire lorsqu'elle est activée)

Le Région AWS pour Origin Shield. Spécifiez l' Région AWS dont la latence est la plus faible par rapport à votre origine. Utilisez le code de région, pas le nom de la région. Par exemple, utilisez us-east-2 pour spécifier la région USA Est (Ohio).

Lorsque vous activez CloudFront Origin Shield, vous devez Région AWS le spécifier. Pour obtenir la liste des régions disponibles Régions AWS et vous aider à choisir la meilleure région pour votre origine, consultezChoisir la AWS région pour Origin Shield.

originAccessControlConfig (facultatif)

Identifiant unique d'un contrôle d'accès à l'origine (OAC) pour cette origine. Ceci n'est utilisé que lorsque l'origine prend en charge un CloudFront OAC, tel qu'Amazon S3, la URLs fonction Lambda et la MediaStore V2. MediaPackage Si ce n'est pas le cas, les paramètres OAC de l'origine attribuée sont utilisés.

Cela ne prend pas en charge l'ancienne identité d'accès à l'origine (OAI). Pour de plus amples informations, veuillez consulter Restreindre l'accès à une AWS origine.

activé (obligatoire)

Expression booléenne pour activer ou désactiver OAC. Accepte une false valeur true or.

SigningBehavior (obligatoire lorsqu'il est activé)

Spécifie les demandes CloudFront signées (ajoute des informations d'authentification à). Spécifiez always pour le cas d'utilisation le plus courant. Pour de plus amples informations, veuillez consulter Paramètres avancés pour le contrôle d'accès à l'origine.

Ce champ peut avoir l'une des valeurs suivantes :

always— CloudFront signe toutes les demandes d'origine, en remplaçant l'Authorizationen-tête de la demande du lecteur s'il en existe une.
never— CloudFront ne signe aucune demande d'origine. Cette valeur désactive le contrôle d'accès à l'origine pour l'origine.
no-override— Si la demande du lecteur ne contient pas l'Authorizationen-tête, CloudFront signe la demande d'origine. Si la demande du visualiseur contient l'Authorizationen-tête, CloudFront elle ne signe pas la demande d'origine et transmet à la place l'Authorizationen-tête de la demande du visualiseur.

Avertissement
Pour transmettre l'Authorizationen-tête de la demande du lecteur, vous devez l'ajouter à une politique de demande d'origine pour tous les comportements de cache qui utilisent les origines associées à ce contrôle d'accès à l'origine. Pour de plus amples informations, veuillez consulter Contrôlez les demandes d'origine à l'aide d'une politique.

Protocole de signature (obligatoire lorsqu'il est activé)

Protocole de signature de l'OAC, qui détermine la manière dont les demandes sont CloudFront signées (authentifiées). La seule valeur valide est sigv4.

OriginType (obligatoire lorsqu'il est activé)

Type d'origine de cet OAC. Les valeurs valides sont les suivantes : s3, mediapackagev2, mediastore et lambda.

délais d'attente (facultatif)

Les délais d'expiration que vous pouvez spécifier CloudFront doivent tenter d'attendre que les origines répondent ou envoient des données. Si ce n'est pas le cas, les paramètres de délai d'expiration de l'origine attribuée sont utilisés.

ReadTimeout (facultatif)

Les délais d'expiration ne s'appliquent qu'aux origines personnalisées, et non aux origines Amazon S3. (Les configurations d'origine S3 ignoreront ces paramètres.) readTimeouts'applique aux deux valeurs suivantes :

Durée (en secondes) d' CloudFront attente d'une réponse après avoir transmis une demande à l'origine.
Durée (en secondes) d' CloudFront attente après réception d'un paquet de réponse de l'origine et avant de recevoir le paquet suivant.

Le délai minimum est de 1 seconde et le maximum de 60 secondes. Pour de plus amples informations, veuillez consulter Délai de réponse (origines personnalisées et VPC uniquement).

keepAliveTimeout (facultatif)

Les délais d'expiration ne s'appliquent qu'aux origines personnalisées, et non aux origines Amazon S3. (Les configurations d'origine S3 ignoreront ces paramètres.) keepAliveTimeoutindique combien de temps CloudFront il faut essayer de maintenir la connexion à l'origine après avoir reçu le dernier paquet de la réponse. Le délai minimum est de 1 seconde et le maximum de 60 secondes. Pour de plus amples informations, veuillez consulter Délai de conservation (origines personnalisées et VPC uniquement).

ConnectionTimeout (facultatif)

Le nombre de secondes d' CloudFront attente lorsque vous essayez d'établir une connexion avec l'origine. Le délai minimum est de 1 seconde et le maximum de 10 secondes. Pour de plus amples informations, veuillez consulter Délai de connexion.

customOriginConfig (facultatif)

customOriginConfigÀ utiliser pour spécifier les paramètres de connexion pour les origines qui ne sont pas un compartiment Amazon S3. Il existe une exception : vous pouvez spécifier ces paramètres si le compartiment S3 est configuré avec un hébergement de site Web statique. (Les autres types de configurations de compartiment S3 ignoreront ces paramètres.) Si customOriginConfig ce n'est pas le cas, les paramètres de l'origine attribuée sont utilisés.

port (obligatoire)

Port HTTP CloudFront utilisé pour se connecter à l'origine. Spécifiez le port HTTP sur lequel l'origine personnalisée écoute.

protocole (obligatoire)

Spécifie le protocole (HTTP ou HTTPS) CloudFront utilisé pour se connecter à l'origine. Les valeurs valides sont les suivantes :

http— utilise CloudFront toujours le protocole HTTP pour se connecter à l'origine
https— utilise CloudFront toujours HTTPS pour se connecter à l'origine

Protocoles SSLProtocoles (obligatoire)

Une liste qui indique le protocole SSL/TLS minimal à CloudFront utiliser lors de la connexion à votre point d'origine via HTTPS. Les valeurs valides sont les suivantes : SSLv3, TLSv1, TLSv1.1 et TLSv1.2. Pour de plus amples informations, veuillez consulter Minimum de protocole SSL d’origine.

Exemple — Mise à jour de l'origine de la demande Amazon S3

L'exemple suivant remplace l'origine de la demande du lecteur par un compartiment S3, active l'OAC et réinitialise les en-têtes personnalisés envoyés à l'origine.


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": {}
});

Exemple — Mise à jour de l'origine de la demande Application Load Balancer

L'exemple suivant change l'origine de la demande du visualiseur en une origine Application Load Balancer et définit un en-tête et des délais personnalisés.


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"
    }
});

Exemple — Mise à jour vers Origin avec Origin Shield activé

Dans l'exemple suivant, Origin Shield est activé sur l'origine de la distribution. Le code de fonction met à jour uniquement le nom de domaine utilisé pour l'origine et omet tous les autres paramètres facultatifs. Dans ce cas, Origin Shield sera toujours utilisé avec le nom de domaine d'origine modifié car les paramètres d'Origin Shield n'ont pas été mis à jour.


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

selectRequestOriginById() méthode

Permet selectRequestOriginById() de mettre à jour une origine existante en sélectionnant une autre origine déjà configurée dans votre distribution. Cette méthode utilise les mêmes paramètres que ceux définis par l'origine mise à jour.

Cette méthode accepte uniquement les origines déjà définies dans la même distribution que celle utilisée lors de l'exécution de la fonction. Les origines sont référencées par l'ID d'origine, qui est le nom d'origine que vous avez défini lors de la configuration de l'origine.

Si une origine VPC est configurée dans votre distribution, vous pouvez utiliser cette méthode pour mettre à jour votre origine vers votre origine VPC. Pour de plus amples informations, veuillez consulter Restreindre l'accès avec les origines des VPC.

Demande


selectRequestOriginById(origin_id)

Dans l'exemple précédent, origin_id il s'agit d'une chaîne qui pointe vers le nom d'origine d'une origine dans la distribution qui exécute la fonction.

Exemple — Sélectionnez l'origine de la demande Amazon S3

L'exemple suivant sélectionne l'origine nommée amzn-s3-demo-bucket-in-us-east-1 dans la liste des origines associées à la distribution et applique les paramètres de configuration de l'amzn-s3-demo-bucket-in-us-east-1origine à la demande.


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

Exemple — Sélectionnez l'origine de la demande Application Load Balancer

L'exemple suivant sélectionne une origine Application Load Balancer nommée myALB-prod dans la liste des origines associées à la distribution et applique les paramètres de configuration de myALB-prod à la demande.


cf.selectRequestOriginById("myALB-prod");

createRequestOriginMéthode Group ()

Permet createRequestOriginGroup() de définir deux origines à utiliser comme groupe d'origine pour le basculement dans les scénarios nécessitant une haute disponibilité.

Un groupe d'origine comprend deux origines (une principale et une secondaire) ainsi que des critères de basculement que vous spécifiez. Vous créez un groupe d'origine pour prendre en charge le basculement d'origine. CloudFront Lorsque vous créez ou mettez à jour un groupe d'origine à l'aide de cette méthode, vous pouvez spécifier le groupe d'origine au lieu d'une origine unique. CloudFront basculera de l'origine principale vers l'origine secondaire, en utilisant les critères de basculement.

Si une origine VPC est configurée dans votre distribution, vous pouvez utiliser cette méthode pour créer un groupe d'origine à l'aide d'une origine VPC. Pour de plus amples informations, veuillez consulter Restreindre l'accès avec les origines des VPC.

Demande


createRequestOriginGroup({origin_group_properties})

Dans l'exemple précédent, ils origin_group_properties peuvent contenir les éléments suivants :

Identifiants d'origine (obligatoire)

Tableau deorigin_ids, où il origin_id s'agit d'une chaîne qui pointe vers le nom d'origine d'une origine dans la distribution exécutant la fonction. Vous devez fournir deux origines dans le tableau. La première origine de la liste est l'origine principale et la seconde sert de seconde origine à des fins de basculement.

Critères de sélection (facultatif)

Choisissez d'utiliser les critères de basculement default d'origine ou d'utiliser la logique de basculement media-quality-score basée. Les valeurs valides sont les suivantes :

defaultutilise les critères de basculement, en fonction des codes d'état spécifiés dans lefailoverCriteria. Si vous ne définissez pas selectionCriteria la fonction, elle default sera utilisée.
media-quality-scoreest utilisé lorsque la fonctionnalité de routage compatible avec les médias est utilisée.

Critères de basculement (obligatoire)

Ensemble de codes d'état qui, lorsqu'ils sont renvoyés par l'origine principale, CloudFront déclenchent le basculement vers l'origine secondaire. Si vous remplacez un groupe d'origine existant, cette matrice remplacera tous les codes d'état de basculement définis dans la configuration d'origine du groupe d'origine.

Lorsque vous utilisez media-quality-scoreselectionCriteria, CloudFront tentera d'acheminer les demandes en fonction du niveau de qualité du média. Si l'origine sélectionnée renvoie un code d'erreur défini dans ce tableau, elle CloudFront basculera vers l'autre origine.

Exemple — Crée le groupe d'origine de la demande

L'exemple suivant crée un groupe d'origine pour une demande à l'aide de l'origine IDs. Ces origines IDs proviennent de la configuration du groupe d'origine de la distribution utilisée pour exécuter cette fonction.


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

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Méthodes d’aide pour les magasins de clés-valeurs

Méthodes d'assistance pour les propriétés de CloudFront SaaS Manager