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 et structure des événements
<a name="functions-event-structure"></a>

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](test-function.md), 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'`event`objet 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 :

**Topics**
+ [Champ Version](#functions-event-structure-version)
+ [Objet Contexte](#functions-event-structure-context)
+ [Structure des événements de connexion](#functions-event-structure-connection)
+ [Objet Utilisateur](#functions-event-structure-viewer)
+ [Objet Requête](#functions-event-structure-request)
+ [Objet Réponse](#functions-event-structure-response)
+ [Code de statut et corps](#functions-event-structure-status-body)
+ [Structure d'une chaîne de requête, d'un en-tête ou d'un cookie](#functions-event-structure-query-header-cookie)
+ [Exemple d'objet de réponse](#functions-response-structure-example)
+ [Exemple d'objet d'événement](#functions-event-structure-example)

## Champ Version
<a name="functions-event-structure-version"></a>

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
<a name="functions-event-structure-context"></a>

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 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 CloudFront de domaine (par exemple, d111111abcdef8.cloudfront.net) du groupe de connexion associé à l'événement.  
Le champ `endpoint` n’apparaît que lorsque votre fonction est invoquée pour les distributions multi-locataires.

**`distributionId`**  
L'ID de la distribution (par EDFDVBD6 exemple, EXAMPLE) 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 associée).

## Structure des événements de connexion
<a name="functions-event-structure-connection"></a>

Les fonctions de connexion reçoivent une structure d'événements différente de celle des fonctions de visualisation. Pour des informations détaillées sur la structure des événements de connexion et le format de réponse, consultez[Associer une fonction CloudFront de connexion](connection-functions.md).

## Objet Utilisateur
<a name="functions-event-structure-viewer"></a>

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
<a name="functions-event-structure-request"></a>

L'`request`objet contient une représentation d'une requête viewer-to-CloudFront HTTP. Dans l'`event`objet transmis à votre fonction, l'`request`objet représente la demande réelle CloudFront reçue du visualiseur.

Si votre code de 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 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é.   
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 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 en majuscule, s'il s'agit d'une lettre ASCII. CloudFront Functions n'applique aucune modification aux symboles non ASCII 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`, 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](#functions-event-structure-query-header-cookie).

Pour un exemple d’objet `event`, consultez [Exemple d'objet d'événement](#functions-event-structure-example).

## Objet Réponse
<a name="functions-event-structure-response"></a>

L'`response`objet contient une représentation d'une réponse CloudFront-to-viewer HTTP. Dans l'`event`objet transmis à votre fonction, l'`response`objet 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>"`). Dans ce cas, 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](#functions-event-structure-status-body).

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](#functions-event-structure-query-header-cookie).

Pour un exemple d’objet `response`, consultez [Exemple d'objet de réponse](#functions-response-structure-example).

## Code de statut et corps
<a name="functions-event-structure-status-body"></a>

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 de plus amples informations, veuillez consulter [Restrictions sur toutes les fonctions périphériques](edge-function-restrictions-all.md).

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 que`content-encoding`, ou `content-type``content-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](creating-custom-error-pages.md) 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
<a name="functions-event-structure-query-header-cookie"></a>

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.

**Contents**
+ [Valeurs de chaînes de requête ou objets de chaîne de requête](#functions-event-structure-query)
+ [Considérations spéciales pour les en-têtes](#functions-event-structure-headers)
+ [Dupliquer les chaînes de requêtes, les en-têtes et les cookies (tableau `multiValue`)](#functions-event-structure-multivalue)
+ [Attributs de cookies](#functions-event-structure-cookie-attributes)

### Valeurs de chaînes de requête ou objets de chaîne de requête
<a name="functions-event-structure-query"></a>

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

**Example 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
<a name="functions-event-structure-headers"></a>

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.

**Example 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`)
<a name="functions-event-structure-multivalue"></a>

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.

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

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

**Example 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"
    }
}
```

### Attributs de cookies
<a name="functions-event-structure-cookie-attributes"></a>

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. 

**Example 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
<a name="functions-response-structure-example"></a>

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
<a name="functions-event-structure-example"></a>

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 `endpoint` champ est utilisé à la place de `distributionDomainName` La valeur de `endpoint` est le nom de CloudFront domaine (par exemple, d111111abcdef8.cloudfront.net) du groupe de connexion 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"
                    }
                ]
            }
        }
    }
}
```