CloudFront Fonctions, structure de l'événement - Amazon CloudFront
Champ VersionObjet ContexteObjet UtilisateurObjet RequêteObjet RéponseCode de statut et corpsStructure d'une chaîne de requête, d'un en-tête ou d'un cookieExemple d'objet de réponseExemple d'objet d'événement

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

CloudFront Fonctions, structure de l'événement

CloudFront Functions transmet un event objet à votre code de fonction en entrée lors de l'exécution de 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 minuscules, ce qui est toujours le cas dans l'eventobjet que CloudFront Functions transmet à 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 :

Champ Version

Le version champ contient une chaîne qui indique 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 CloudFront de domaine (par exemple, d111111abcdef8.cloudfront.net) de la distribution associée à l'événement.

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

Chaîne qui identifie de manière unique une CloudFront demande (et la réponse qui lui est 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'requestobjet contient une représentation d'une requête HTTP entre un visualiseur et un utilisateur. CloudFront Dans l'eventobjet transmis à votre fonction, l'requestobjet représente la demande réelle CloudFront reçue du visualiseur.

Si le code de votre fonction renvoie un request objet à 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 unrequest, 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 uri valeur, 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 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 HTTP, la première lettre de chaque mot dans les noms d'en-tête est mise en majuscule. 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, il le CloudFront convertit en en-tête 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'responseobjet contient une représentation d'une réponse HTTP CloudFront à l'utilisateur. Dans l'eventobjet transmis à votre fonction, l'responseobjet représente la réponse réelle CloudFront de l'utilisateur à une demande de consultation.

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 des noms d'en-tête est mise en majuscule. 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, il le CloudFront 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 CloudFront cache ou l'origine. Si vous ne spécifiez pas le body champ dans votre fonction de réponse du spectateur, le corps d'origine renvoyé par le CloudFront cache ou l'origine est renvoyé au visualiseur.

Si vous CloudFront souhaitez renvoyer un corps personnalisé au visualiseur, spécifiez le contenu du corps dans le data champ et le codage du corps dans le encoding champ. 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>"). Lorsque vous effectuez cette opération, omettez les encoding champs data et. 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 as 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 CloudFront Functions, vous pouvez mettre à jour le code d'état de la réponse du lecteur, remplacer l'intégralité du corps de la réponse par un nouveau ou supprimer le corps de la réponse. Parmi les scénarios courants de mise à jour de la réponse du spectateur après avoir évalué certains aspects de la réponse provenant du CloudFront cache ou de l'origine, 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 CloudFront fonction ne sera pas exécutée. Pour plus d’informations, consultez Restrictions sur toutes les fonctions périphériques.

Lorsque vous travaillez avec la réponse HTTP, CloudFront Functions n'a 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 ne mettez pas à jour le champ body de votre fonction, le corps d'origine renvoyé par le CloudFront cache ou l'origine est renvoyé au visualiseur.

Astuce

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

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

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

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.

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

Pour modifier une chaîne de requête dans le code de votre fonction, utilisez le code 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 des noms d'en-tête est mise en majuscule. 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, il le CloudFront convertit Example-Header-Name dans la requête ou la réponse HTTP.

Exemple

Tenez compte de l'Hosten-tête suivant dans une requête 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

Prenons l'exemple d'une requête HTTP avec les Accept en-têtes suivants.

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

Ces en-têtes sont représentés comme suit dans l'requestobjet.

"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 à la fois dans les multiValue propriétés value et. 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 contenant un multiValue tableau, CloudFront Functions applique les règles suivantes pour appliquer les modifications :

  1. 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é.

  2. 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

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

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

Cet en-tête est représenté comme suit dans l'requestobjet.

"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

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.

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