Champ Version Objet Contexte Objet Utilisateur Objet Requête Objet Réponse Code de statut et corps Structure d'une chaîne de requête, d'un en-tête ou d'un cookie Exemple d'objet de réponse Exemple d'objet d'événement

Structure d'évènements CloudFront Functions

CloudFront Functions envoie un objet event à votre code de fonction en tant qu'entrée lorsque le service exécute la fonction. Lorsque vous testez une fonction, vous créez l'objet event et le transférez à votre fonction. Lorsque vous créez un objet event pour tester une fonction, vous pouvez omettre les champs distributionDomainName, distributionId et requestId de l'objet context. Assurez-vous que les noms des en-têtes sont en minuscule, ce qui est toujours le cas dans l'objet event que les fonctions CloudFront envoient à votre fonction en production.

La section suivante présente une vue d'ensemble de la structure de cet objet d'évènement.


{
    "version": "1.0",
    "context": {
        <context object>
    },
    "viewer": {
        <viewer object>
    },
    "request": {
        <request object>
    },
    "response": {
        <response object>
    }
}

Pour plus d’informations, consultez les rubriques suivantes :

Rubriques

Champ Version
Objet Contexte
Objet Utilisateur
Objet Requête
Objet Réponse
Code de statut et corps
Structure d'une chaîne de requête, d'un en-tête ou d'un cookie
Exemple d'objet de réponse
Exemple d'objet d'événement

Champ Version

Le champ version contient une chaîne qui spécifie la version de l'objet d'évènement CloudFront Functions. La version actuelle est 1.0.

Objet Contexte

L'objet context contient des informations contextuelles sur l'évènement. Il inclut les champs suivants :

distributionDomainName

Le nom de domaine CloudFront (par exemple d111111abcdef8.cloudfront.net) de la distribution standard associée à l’événement.

Le champ distributionDomainName n’apparaît que lorsque votre fonction est invoquée pour les distributions standard.

endpoint

Le Nom de domaine CloudFront (par exemple d111111abcdef8.cloudfront.net) du groupe de connexions associé à l’événement.

Le champ endpoint n’apparaît que lorsque votre fonction est invoquée pour les distributions multi-locataires.

distributionId

ID de la distribution (par exemple EDFDVBD6EXAMPLE) associée à l’événement.

eventType

Le type d'évènement, viewer-request ou viewer-response.

requestId

Une chaîne qui identifie de manière unique une requête CloudFront (et sa réponse associée).

Objet Utilisateur

L'objet viewer comporte un champ ip dont la valeur est l'adresse IP de l'utilisateur (client) qui a envoyé la requête. Si la requête utilisateur a été envoyée via un proxy HTTP ou un équilibreur de charge, la valeur correspond à l'adresse IP du proxy ou de l'équilibreur de charge.

Objet Requête

L'objet request contient une représentation d'une requête HTTP envoyée par l'utilisateur à CloudFront. Dans l'objet event transféré à votre fonction, l'objet request représente la demande réelle que CloudFront a reçue de l'utilisateur.

Si votre code de fonction renvoie un objet request à CloudFront, il doit utiliser cette même structure.

L'objet request comporte les champs suivants :

method

Méthode HTTP de la demande. Si votre code de fonction renvoie une request, il ne peut pas modifier ce champ. Il s'agit du seul champ en lecture seule de l'objet request.

uri

Chemin d’accès relatif de l’objet demandé.

Note

Si votre fonction modifie la valeur uri, les règles suivantes s’appliquent :

La nouvelle valeur uri doit commencer par une barre oblique (/).
Lorsqu'une fonction modifie la valeur uri, elle change l'objet que l'utilisateur demande.
Quand une fonction modifie la valeur uri, elle ne modifie pas le comportement de cache pour la demande ni l'origine vers laquelle la demande d'origine est envoyée.

querystring

Objet qui représente la chaîne de requête dans la requête. Si la demande n'inclut pas de chaîne de requête, l'objet request inclut néanmoins un objet querystring vide.

L'objet querystring comporte un champ pour chaque paramètre de chaîne de requête dans la requête.

headers

Objet qui représente les en-têtes HTTP dans la requête. Si la requête contient des en-têtes Cookie, ces derniers ne font pas partie de l'objet headers. Les cookies sont représentés séparément dans l'objet cookies.

L'objet headers comporte un champ pour chaque en-tête de la requête. Les noms des en-têtes sont convertis en minuscules ASCII dans l’objet d’événement, et les noms des en-têtes doivent être en minuscules ASCII lorsqu’ils sont ajoutés par votre code de fonction. Lorsque les fonctions CloudFront reconvertissent l’objet d’événement en demande HTTP, la première lettre de chaque mot du nom d’en-tête est mise en majuscule, si c’est une lettre ASCII. Les fonctions CloudFront n’appliquent aucune modification aux symboles non ASCII présents dans les noms d’en-tête. Par exemple, TÈst-header deviendra tÈst-header à l’intérieur de la fonction. Le symbole non ASCII È est inchangé.

Les mots sont séparés par un trait d’union (-). 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 requête HTTP.

cookies

Objet qui représente les cookies dans la requête (en-têtes Cookie).

L'objet cookies comporte un champ pour chaque cookie dans la requête.

Pour plus d'informations sur la structure des chaînes de requêtes, des en-têtes et des cookies, consultez Structure d'une chaîne de requête, d'un en-tête ou d'un cookie.

Pour un exemple d'objet event, consultez Exemple d'objet d'événement.

Objet Réponse

L'objet response contient une représentation d'une réponse HTTP envoyée par CloudFront à l'utilisateur. Dans l'objet event transmis à votre fonction, l'objet response représente la réponse réelle de CloudFront à une demande de visionnage.

Si votre code de fonction renvoie un objet response, il doit utiliser cette même structure.

L'objet response comporte les champs suivants :

statusCode

Code de statut HTTP de la réponse. Cette valeur est un entier, pas une chaîne.

Votre fonction peut générer ou modifier le statusCode.

statusDescription

Description de l’état HTTP de la réponse. Si votre code de fonction génère une réponse, ce champ est facultatif.

headers

Objet qui représente les en-têtes HTTP dans la réponse. Si la réponse contient des en-têtes Set-Cookie, ces derniers ne font pas partie de l'objet headers. Les cookies sont représentés séparément dans l'objet cookies.

L'objet headers comporte un champ pour chaque en-tête de la réponse. Les noms des en-têtes sont convertis en minuscules dans l'objet d'événement, et les noms des en-têtes doivent être en minuscules lorsqu'ils sont ajoutés par votre code de fonction. Lorsque CloudFront Functions reconvertit l'objet d'événement en réponse HTTP, la première lettre de chaque mot dans les noms des en-têtes est mise en majuscules. Les mots sont séparés par un trait d'union (-). 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 réponse HTTP.

cookies

Objet qui représente les cookies dans la réponse (en-têtes Set-Cookie).

L'objet cookies comporte un champ pour chaque cookie dans la réponse.

body

L'ajout du champ body est facultatif et il ne sera pas présent dans l'objet response à moins que vous ne le spécifiiez dans votre fonction. Votre fonction n'a pas accès au corps d'origine renvoyé par le cache ou l'origine de CloudFront. Si vous n'indiquez pas le champ body dans votre fonction de réponse de visionnage, le corps d'origine renvoyé par le cache ou l'origine CloudFront est retourné à l'utilisateur.

Si vous souhaitez que CloudFront renvoie un corps personnalisé à l'utilisateur, spécifiez le contenu du corps dans le champ data et le codage du corps dans le champ encoding. Vous pouvez spécifier le codage sous forme de texte brut ("encoding": "text") ou de contenu codé en Base64 ("encoding": "base64").

Comme raccourci, vous pouvez également spécifier le contenu du corps directement dans le champ body ("body": "<specify the body content here>"). Dans ce cas, omettez les champs data et encoding. CloudFront traite le corps comme du texte brut dans ce cas.

encoding

Codage du contenu de body (champ data). Les seuls encodages valides sont text et base64.

Si vous spécifiez encoding en base64, mais que le corps n’est pas valide en base64, CloudFront renvoie une erreur.

data

Contenu de body.

Pour plus d'informations sur les codes de statut modifiés et le contenu du corps, consultez Code de statut et corps.

Pour plus d'informations sur la structure des en-têtes et des cookies, consultez Structure d'une chaîne de requête, d'un en-tête ou d'un cookie.

Pour un exemple d’objet response, consultez Exemple d'objet de réponse.

Code de statut et corps

Avec fonctions CloudFront, vous pouvez mettre à jour le code de statut de réponse d'utilisateur et remplacer ou supprimer le corps entier de la réponse. Parmi les scénarios courants de mise à jour de la réponse d'utilisateur après avoir évalué certains aspects de la réponse depuis le cache ou l'origine CloudFront, citons les suivants :

Modification du statut pour définir un code de statut HTTP 200 et création d'un contenu de corps statique à renvoyer à l'utilisateur.
Modification du statut pour définir un code de statut HTTP 301 ou 302 afin de rediriger l'utilisateur vers un autre site Web.
Décider de diffuser ou de supprimer le corps de la réponse d'utilisateur.

Note

Si l'origine renvoie une erreur HTTP supérieure ou égale à 400, la fonction CloudFront ne s'exécutera pas. Pour plus d’informations, consultez Restrictions sur toutes les fonctions périphériques.

Lorsque vous utilisez la réponse HTTP, les fonctions CloudFront n'ont pas accès au corps de la réponse. Vous pouvez remplacer le contenu du corps en lui attribuant la valeur souhaitée, ou supprimer le corps en définissant une valeur vide. Si vous n'actualisez pas le champ du corps dans votre fonction, le corps d'origine renvoyé par le cache ou l'origine CloudFront est retourné à l'utilisateur.

Astuce

Lorsque vous utilisez les fonctions CloudFront pour remplacer un corps, veillez à aligner les en-têtes correspondants, tels que content-encoding, content-type ou content-length, sur le nouveau contenu du corps.

Par exemple, si l'origine ou le cache CloudFront renvoie content-encoding: gzip mais que la fonction de réponse d'utilisateur définit un corps en texte brut, la fonction doit également modifier les en-têtes content-encoding et content-type en conséquence.

Si votre fonction CloudFront est configurée pour renvoyer une erreur HTTP égale ou supérieure à 400, votre utilisateur ne verra pas la page d'erreur personnalisée que vous avez spécifiée pour le même code de statut.

Les chaînes de requête, les en-têtes et les cookies partagent la même structure. Les chaînes de requête peuvent apparaître dans les demandes. Les en-têtes apparaissent dans les demandes et les réponses. Les cookies apparaissent dans les demandes et les réponses.

Chaque chaîne de requête, en-tête ou cookie est un champ unique au sein de l'objet parent querystring, headers ou cookies. Le nom du champ est le nom de la chaîne de requête, de l'en-tête ou du cookie. Chaque champ comporte une propriété value avec la valeur de la chaîne de requête, de l'en-tête ou du cookie.

Table des matières

Valeurs de chaînes de requête ou objets de chaîne de requête

Une fonction peut renvoyer une valeur de chaîne de requête en plus d'un objet de chaîne de requête. La valeur de chaîne de requête peut être utilisée pour organiser les paramètres de chaîne de requête dans n'importe quel ordre personnalisé.

Exemple exemple

Pour modifier une chaîne de requête dans le code d’une fonction, utilisez un code analogue au suivant.


var request = event.request; 
request.querystring = 'ID=42&Exp=1619740800&TTL=1440&NoValue=&querymv=val1&querymv=val2,val3';

Considérations spéciales pour les en-têtes

Pour les en-têtes uniquement, les noms des en-têtes sont convertis en minuscules dans l'objet d'événement, et les noms des en-têtes doivent être en minuscules lorsqu'ils sont ajoutés par votre code de fonction. Lorsque CloudFront Functions reconvertit l'objet d'événement en requête ou réponse HTTP, la première lettre de chaque mot dans les noms des en-têtes est mise en majuscules. Les mots sont séparés par un trait d'union (-). 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 requête ou la réponse HTTP.

Exemple exemple

Examinez l’en-tête Host suivant dans une demande HTTP.


Host: video.example.com

Cet en-tête est représenté comme suit dans l'objet request :


"headers": {
    "host": {
        "value": "video.example.com"
    }
}

Pour accéder à l'en-tête Host dans votre code de fonction, utilisez le code comme suit :


var request = event.request;
var host = request.headers.host.value;

Pour ajouter ou modifier un en-tête dans votre code de fonction, utilisez le code suivant (ce code ajoute un en-tête nommé X-Custom-Header avec la valeur example value) :


var request = event.request;
request.headers['x-custom-header'] = {value: 'example value'};

Dupliquer les chaînes de requêtes, les en-têtes et les cookies (tableau `multiValue`)

Une requête ou une réponse HTTP peut contenir plusieurs chaînes de requêtes, en-têtes ou cookies portant le même nom. Dans ce cas, les chaînes de requêtes, les en-têtes ou les cookies en double sont regroupés dans un champ de l'objet request ou response, mais ce champ comporte une propriété supplémentaire nommée multiValue. La propriété multiValue contient un tableau avec les valeurs de chacun des en-têtes, cookies ou chaînes de requêtes dupliqués.

Exemple exemple

Imaginons une requête HTTP qui inclut les en-têtes Accept suivants.


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

Ces en-têtes sont représentés comme suit dans l’objet request.


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

Note

La première valeur d’en-tête (dans ce cas, application/json) est répétée dans les propriétés value et multiValue. Cela vous permet d'accéder à toutes les valeurs en faisant une boucle dans le tableau multiValue.

Si le code de votre fonction modifie une chaîne de requête, un en-tête ou un cookie qui comporte un tableau multiValue, Fonctions CloudFront utilise les règles suivantes pour appliquer les modifications :

Si le tableau multiValue existe et comporte des modifications, ces dernières sont appliquées. Le premier élément de la propriété value est ignoré.
Sinon, toute modification apportée à la propriété value est appliquée, et les valeurs suivantes (si elles existent) restent inchangées.

La propriété multiValue est utilisée uniquement lorsque la requête ou la réponse HTTP contient des chaînes de requêtes, des en-têtes ou des cookies en double portant le même nom, comme indiqué dans l'exemple précédent. Toutefois, s'il existe plusieurs valeurs dans un seul en-tête, cookie ou chaîne de requête, la propriété multiValue n'est pas utilisée.

Exemple exemple

Prenons l’exemple d’une demande avec un en-tête Accept contenant trois valeurs.


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

Cet en-tête est représenté comme suit dans l’objet request.


"headers": {
    "accept": {
        "value": "application/json, application/xml, text/html"
    }
}

Dans un en-tête Set-Cookie d'une réponse HTTP, l'en-tête contient la paire nom-valeur du cookie et éventuellement un ensemble d'attributs séparés par des points-virgules.

Exemple exemple



Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT

Dans l'objet response, ces attributs sont représentés dans la propriété attributes du champ cookie. Par exemple, l'en-tête Set-Cookie précédent est représenté comme suit :


"cookie1": {
    "value": "val1",
    "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
}

Exemple d'objet de réponse

L'exemple suivant montre un objet response (la sortie d'une fonction de réponse d'utilisateur) dans lequel le corps a été remplacé par une fonction de réponse d'utilisateur.


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

Exemple d'objet d'événement

L'exemple suivant illustre un objet event complet. Il s’agit d’un exemple d’invocation pour une distribution standard, et non pour une distribution multi-locataires. Pour les distributions multi-locataires, le champ endpoint est utilisé à la place de distributionDomainName. La valeur de endpoint correspond au nom de domaine CloudFront (par exemple, d111111abcdef8.cloudfront.net) du groupe de connexions associé à l’événement.

Note

L'objet event représente l'entrée de votre fonction. Votre fonction renvoie uniquement l'objet request ou response, et non l'objet event complet.


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

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

Détermination de l’objectif de la fonction

Fonctionnalités d’exécution JavaScript

Structure d'évènements CloudFront Functions

Rubriques

Champ Version

Objet Contexte

Objet Utilisateur

Objet Requête

Note

Objet Réponse

Code de statut et corps

Note

Astuce

Structure d'une chaîne de requête, d'un en-tête ou d'un cookie

Table des matières

Valeurs de chaînes de requête ou objets de chaîne de requête

Exemple exemple

Considérations spéciales pour les en-têtes

Exemple exemple

Dupliquer les chaînes de requêtes, les en-têtes et les cookies (tableau multiValue)

Exemple exemple

Note

Exemple exemple

Attributs de cookies

Exemple exemple

Exemple d'objet de réponse

Exemple d'objet d'événement

Note

Dupliquer les chaînes de requêtes, les en-têtes et les cookies (tableau `multiValue`)