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 :

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 :

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 :

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 :

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.

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.

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

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

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.

Host: video.example.com

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

var request = event.request;
var host = request.headers.host.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.

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

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

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 :

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.

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

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

Attributs de cookies

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.

Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; 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"
}

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.

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