Méthodes d’assistance pour la modification de l’origine - Amazon CloudFront
Choix entre les fonctions CloudFront et Lambda@EdgeMéthode updateRequestOrigin()Méthode selectRequestOriginById()méthode createRequestOriginGroup()

Méthodes d’assistance pour la modification de l’origine

Cette section s’applique si vous mettez à jour ou modifiez dynamiquement l’origine utilisée pour la demande dans votre code des fonctions CloudFront. Vous ne pouvez mettre à jour l’origine que dans les fonctions CloudFront de type demande de l’utilisateur. Les fonctions CloudFront possèdent un module qui fournit des méthodes d’assistance pour mettre à jour ou modifier l’origine de manière dynamique.

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

import cf from 'cloudfront';

Pour plus d’informations, consultez Fonctionnalités d’exécution JavaScript 2.0 pour les fonctions CloudFront.

Note

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

Choix entre les fonctions CloudFront et Lambda@Edge

Vous pouvez mettre à jour vos origines à l’aide des fonctions CloudFront ou de Lambda@Edge.

Lorsque vous utilisez les fonctions CloudFront pour mettre à jour les origines, vous utilisez le déclencheur d’événement demande de l’utilisateur, 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 d’événement demande de l’origine, ce qui signifie que cette logique ne s’exécute qu’en cas d’échec du cache.

Votre choix dépend en grande partie de votre charge de travail et de l’utilisation existante des fonctions CloudFront et Lambda@Edge sur vos distributions. Les points ci-dessous peuvent vous aider à déterminer si vous devez utiliser les fonctions CloudFront ou Lambda@Edge pour mettre à jour vos origines.

Les fonctions CloudFront sont particulièrement utiles dans les cas suivants :

  • Lorsque vos demandes sont dynamiques (c’est-à-dire qu’elles ne peuvent pas être mises en cache) et vont systématiquement vers l’origine. Les fonctions CloudFront améliorent les performances et réduisent le coût global.

  • Lorsque vous disposez déjà d’une fonction CloudFront de type demande de l’utilisateur qui s’exécute à chaque demande, vous pouvez y ajouter la logique de mise à jour de l’origine.

Pour utiliser les fonctions CloudFront 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 cas suivants :

  • Lorsque votre contenu est fortement cacheable, Lambda@Edge peut être plus rentable, car il ne s’exécute qu’en cas d’échec de cache, tandis que les fonctions CloudFront s’exécutent à chaque demande.

  • Lorsque vous disposez déjà d’une fonction Lambda@Edge de type demande de l’origine, vous pouvez y ajouter la logique de mise à jour de l’origine.

  • 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 Personnalisation en périphérie avec Lambda@Edge.

Méthode updateRequestOrigin()

Utilisez la méthode updateRequestOrigin() 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 updateRequestOrigin() hériteront des paramètres définis dans la configuration de l’origine existante.

L’origine définie par la méthode updateRequestOrigin() peut être n’importe quel point de terminaison HTTP et n’a pas besoin d’être une origine déjà présente dans votre distribution CloudFront.

Remarques

  • Si vous mettez à jour une origine qui fait partie d’un groupe d’origines, seule l’origine principale du groupe d’origines 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é, veillez à ce que le type d’origine dans originAccessControlConfig corresponde au nouveau type d’origine.

  • Vous ne pouvez pas utiliser la méthode updateRequestOrigin() pour mettre à jour les origines VPC. La demande échouera.

Demande

updateRequestOrigin({origin properties})

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

domainName (facultatif)

Nom de domaine de l’origine. Si cette valeur n’est pas fournie, le nom de domaine de l’origine associée est utilisé à la place.

Pour les origines personnalisées

Spécifiez un nom de domaine DNS, tel que www.example.com. Le nom de domaine ne peut pas inclure un signe deux-points (:) et ne peut pas être une adresse IP. Le nom du domaine peut contenir jusqu’à 253 caractères.

Pour les origines S3

Spécifiez le nom de domaine DNS du compartiment Amazon S3, tel que amzn-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. Ce chemin doit commencer par une barre oblique (/) mais ne doit pas se terminer par une barre oblique. Par exemple, il ne doit pas se terminer par example-path/. Si cette valeur n’est pas fournie, le chemin d’origine de l’origine associée est utilisé.

Pour les origines personnalisées

Le chemin d’accès doit être codé en URL et ne pas dépasser 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 non autorisés, et un en-tête portant le même nom ne peut pas déjà ê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 les fonctions CloudFront reconvertissent l’objet d’événement en demande HTTP, la première lettre de chaque mot dans les noms d’en-têtes est mise en majuscule et les mots sont séparés par un tiret.

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

Si cette valeur n’est pas fournie, les en-têtes personnalisés de l’origine associée sont utilisés.

connectionAttempts (facultatif)

Nombre de tentatives de connexion à l’origine réalisé par CloudFront. La valeur minimale est 1 et la valeur maximale est 3. Si cette valeur n’est pas fournie, les tentatives de connexion provenant de l’origine attribuée sont utilisées.

originShield (facultatif)

Cette option active ou met à jour CloudFront Origin Shield. L'utilisation d'Origin Shield permet de réduire la charge sur votre origine. Pour plus d’informations, consultez Utilisation d’Amazon CloudFront Origin Shield. Si cette valeur n’est pas fournie, les paramètres Origin Shield de l’origine attribuée sont utilisés.

enabled (obligatoire)

Expression booléenne permettant d’activer ou de désactiver Origin Shield. Accepte la valeur true ou false.

region (obligatoire lorsqu’elle est activée)

L'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 et non 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 spécifier la Région AWS dans laquelle il sera déployé. Pour obtenir la liste des Régions AWS disponibles et choisir la région la plus appropriée pour votre origine, consultez Choix de la région AWS pour Origin Shield.

originAccessControlConfig (facultatif)

L’identifiant unique d’un contrôle d’accès d’origine (OAC) pour cette origine. Cette option n’est utilisée que lorsque l’origine prend en charge un OAC CloudFront, comme Amazon S3, les URL de fonction Lambda, MediaStore ou MediaPackage V2. Si cette valeur n’est pas fournie, les paramètres OAC de l’origine attribuée sont utilisés.

L’identité d’accès d’origine (OAI) héritée n’est pas prise en charge. Pour plus d’informations, consultez Restriction de l’accès à une origine AWS.

enabled (obligatoire)

Expression booléenne permettant d’activer ou de désactiver l’OAC. Accepte la valeur true ou false.

signingBehavior (obligatoire si activé)

Spécifie les requêtes que CloudFront signe (ajoute des informations d'authentification). Spécifiez always pour le cas d'utilisation le plus courant. Pour plus d’informations, consultez 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 écrasant l'en-tête Authorization de la demande de l'utilisateur s'il y en a.

  • never : CloudFront ne signe aucune demande d’origine. Cette valeur désactive le contrôle d’accès d’origine pour l’origine.

  • no-override : si la demande de l’utilisateur ne contient pas l’en-tête Authorization, CloudFront signe la demande d’origine. Si la demande de l’utilisateur contient l’en-tête Authorization, CloudFront ne signe pas la demande d’origine et transmet l’en-tête Authorization de la demande de l’utilisateur.

    Avertissement

    Pour transmettre l’en-tête Authorization de la demande de l’utilisateur, 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 d’origine. Pour plus d’informations, consultez Contrôle des demandes d’origine à l’aide d’une stratégie.

signingProtocol (obligatoire si activé)

Le protocole de signature de l’OAC, qui détermine la manière dont CloudFront signe (authentifie) les demandes. La seule valeur valide est sigv4.

originType (obligatoire si activé)

Le type d’origine de cet OAC. Les valeurs valides sont les suivantes : s3, mediapackagev2, mediastore et lambda.

timeouts (facultatif)

Des délais d’attente que vous pouvez définir pour indiquer combien de temps CloudFront doit attendre que les origines répondent ou envoient des données. Si cette valeur n’est pas fournie, les paramètres de délai d’attente de l’origine attribuée sont utilisés.

Note

Sauf indication contraire, ces délais prennent en charge les origines personnalisées et Amazon S3.

readTimeout (facultatif)

readTimeout s’applique aux deux valeurs suivantes :

  • Durée, en secondes, pendant laquelle CloudFront attend une réponse après avoir transféré une demande à l’origine.

  • Durée, en secondes, pendant laquelle CloudFront attend après avoir reçu un paquet d’une réponse provenant de l’origine et avant de recevoir le paquet suivant.

Le délai minimum est de 1 seconde et le délai maximum est de 120 secondes. Pour plus d’informations, consultez Délai de réponse.

responseCompletionTimeout (facultatif)

La durée (en secondes) durant laquelle une demande CloudFront adressée à l’origine peut rester ouverte en attendant une réponse. Si la réponse complète n’est pas reçue de l’origine à ce moment-là, CloudFront met fin à la connexion.

La valeur de responseCompletionTimeout doit être supérieure ou égale à la valeur de readTimeout. Pour plus d’informations, consultez Délai d’exécution de la réponse.

keepAliveTimeout (facultatif)

Ce délai s’applique uniquement aux origines personnalisées, et non aux origines Amazon S3. (Les configurations d’origine S3 ignoreront ces paramètres.)

Le keepAliveTimeout spécifie la durée pendant laquelle CloudFront doit tenter de maintenir la connexion avec l’origine après avoir reçu le dernier paquet de la réponse. Le délai minimum est de 1 seconde et le délai maximum est de 120 secondes. Pour plus d’informations, consultez Délai d’attente des connexions actives (origines personnalisées et VPC uniquement).

connectionTimeout (facultatif)

Nombre de secondes pendant lesquelles CloudFront attend lors d’une tentative d’établissement de connexion à l’origine. Le délai minimum est de 1 seconde et le délai maximum est de 10 secondes. Pour plus d’informations, consultez Délai de connexion.

customOriginConfig (facultatif)

Utilisez customOriginConfig pour spécifier les paramètres de connexion des 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 n’est pas renseigné, les paramètres de l’origine attribuée sont utilisés.

port (obligatoire)

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

protocol (obligatoire)

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

  • http : CloudFront utilise toujours HTTP pour se connecter à l’origine

  • https : CloudFront utilise toujours HTTPS pour se connecter à l’origine

sslProtocols (obligatoire)

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

ipAddressType (facultatif)

Spécifie le type d’adresse IP que CloudFront utilise pour se connecter à l’origine. Les valeurs valides sont ipv4, ipv6 et dualstack. La modification de ipAddressType n’est prise en charge que lorsque la propriété domainName est également modifiée.

Exemple – mise à jour de l’origine de la demande Amazon S3

L’exemple suivant modifie l’origine de la demande de l’utilisateur pour la remplacer 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 demande Application Load Balancer

L’exemple suivant modifie l’origine de la demande de l’utilisateur pour la remplacer par une origine Application Load Balancer et définit un en-tête personnalisé ainsi que des délais d’attente.

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 une origine 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 continuera d’être utilisé avec le nom de domaine d’origine modifié, puisque les paramètres Origin Shield n’ont pas été mis à jour.

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

Méthode selectRequestOriginById()

Utilisez selectRequestOriginById() pour 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 plus d’informations, consultez Restriction de l’accès avec les origines de VPC.

Demande

selectRequestOriginById(origin_id)

Dans l’exemple précédent, origin_id est une chaîne qui fait référence au nom de l’origine dans la distribution où la fonction s’exécute.

Exemple – sélection de l’origine de 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’origine amzn-s3-demo-bucket-in-us-east-1 à la demande.

cf.selectRequestOriginById("amzn-s3-demo-bucket-in-us-east-1");
Exemple – sélection de l’origine de 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 l’origine myALB-prod à la demande.

cf.selectRequestOriginById("myALB-prod");

méthode createRequestOriginGroup()

Utilisez createRequestOriginGroup() pour définir deux origines à utiliser comme groupe d’origines pour le basculement, dans les scénarios nécessitant une haute disponibilité.

Un groupe d’origine comprend deux origines (une origine principale et une origine secondaire), ainsi qu’un critère de basculement que vous spécifiez. Vous créez un groupe d'origine pour prendre en charge le basculement d'origine dans CloudFront. Lorsque vous créez ou mettez à jour un groupe d’origines à l’aide de cette méthode, vous pouvez spécifier le groupe d’origines 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’origines à l’aide de votre origine VPC. Pour plus d’informations, consultez Restriction de l’accès avec les origines de VPC.

Demande

createRequestOriginGroup({origin_group_properties})

Dans les exemples précédents, origin_group_properties peut contenir les éléments suivants :

originIds (obligatoire)

Tableau de origin_ids, où chaque origin_id est une chaîne qui pointe vers le nom de l’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 d’origine secondaire à des fins de basculement.

selectionCriteria (facultatif)

Sélectionnez si vous souhaitez utiliser les critères de basculement d’origine default ou appliquer la logique de basculement basée sur le media-quality-score. Les valeurs valides sont les suivantes :

  • default utilise les critères de basculement, en fonction des codes d’état spécifiés dans failoverCriteria. Si vous ne définissez pas selectionCriteria dans la fonction, default sera utilisé.

  • media-quality-score est utilisé lorsque la fonctionnalité de routage tenant compte de la qualité média est utilisée.

failoverCriteria (obligatoire)

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

Lorsque vous utilisez media-quality-score comme selectionCriteria, CloudFront tentera d’acheminer les demandes en fonction du score de qualité média. Si l’origine sélectionnée renvoie un code d’erreur défini dans ce tableau, CloudFront bascule vers l’autre origine.

Exemple – création du groupe d’origines de la demande

L’exemple suivant crée un groupe d’origines pour une demande à l’aide des identifiants d’origine. Ces identifiants d’origine proviennent de la configuration du groupe d’origines 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] 
    }
});