Estructura de eventos de CloudFront Functions

CloudFront Functions pasa un objeto event al código de función como entrada cuando ejecuta la función. Cuando prueba una función, crea el objeto event y lo pasa a la función. Al crear un objeto event para probar una función, puede omitir los campos distributionDomainName,distributionId yrequestId en el objeto context. Asegúrese de que los nombres de encabezados estén en minúsculas, esto siempre sucede en el objeto de event que CloudFront Functions pasa a la función en producción.

A continuación, se muestra la información general de la estructura de este objeto de evento.

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

Para obtener más información, consulte los temas siguientes:

Campo Versión

El campo version contiene una cadena que especifica la versión del objeto de evento de CloudFront Functions. La versión actual es 1.0.

Objeto Context (Contexto)

El objeto context contiene información contextual sobre el evento. Contiene los campos siguientes:

Objeto viewer (lector)

El objeto viewer contiene un campo ip cuyo valor es la dirección IP del lector (cliente) que envió la solicitud. Si el lector utiliza un proxy HTTP o un balanceador de carga para enviar la solicitud, el valor es la dirección IP del proxy o del balanceador de carga.

Objeto Request (solicitud)

El objeto request contiene una representación de una solicitud HTTP de lector-a-CloudFront. En el objeto event que se pasa a la función, el objeto request representa la solicitud real que CloudFront recibió del lector.

Si su código de función devuelve un objeto request a CloudFront, debe usar esta misma estructura.

El objeto request contiene los siguientes campos:

Para obtener más información sobre la estructura de cadenas de consulta, encabezados y cookies, consulte Estructura para una cadena de consulta, encabezado o cookie.

Para obtener un objeto de ejemplo event, consulte Objeto de evento de ejemplo.

Objeto de respuesta

El objeto response contiene una representación de una respuesta HTTP CloudFront-to-viewer. En el objeto event que se pasa a la función, el objeto response representa la respuesta real de CloudFront a una solicitud del lector.

Si su código de función devuelve un objeto response, debe usar esta misma estructura.

El objeto response contiene los siguientes campos:

Para obtener más información sobre los códigos de estado y el contenido del cuerpo modificados, consulte Código de estado y cuerpo.

Para obtener más información sobre la estructura de los encabezados y las cookies, consulte Estructura para una cadena de consulta, encabezado o cookie.

Para obtener un objeto de ejemplo response, consulte Objeto de respuesta de ejemplo.

Código de estado y cuerpo

Con CloudFront Functions, puede actualizar el código de estado de la respuesta del lector, sustituir todo el cuerpo de la respuesta por uno nuevo o eliminar el cuerpo de la respuesta. Algunos escenarios comunes para actualizar la respuesta del lector después de evaluar aspectos de la respuesta de la caché o el origen de CloudFront son los siguientes:

Cuando trabaja con la respuesta HTTP, CloudFront Functions no tiene acceso al cuerpo de la respuesta. Puede sustituir el contenido del cuerpo estableciéndolo en el valor deseado o puede eliminar el cuerpo estableciendo un valor vacío. Si no actualiza el campo cuerpo de la función, el cuerpo original devuelto por la caché o el origen de CloudFront se devuelve al lector.

Si CloudFront Function está configurada para devolver un error HTTP igual o superior a 400, el visor no verá una página de error personalizada que haya especificado para el mismo código de estado.

Estructura para una cadena de consulta, encabezado o cookie

Las cadenas de consulta, los encabezados y las cookies comparten la misma estructura. Las cadenas de consulta pueden aparecer en las solicitudes. Los encabezados aparecen en las solicitudes y las respuestas. Las cookies aparecen en las solicitudes y las respuestas.

Cada cadena de consulta, encabezado o cookie es un campo único dentro del objeto principal querystring,headers o cookies. El nombre del campo es el nombre de la cadena de consulta, el encabezado o la cookie. Cada campo contiene una propiedad value con el valor de la cadena de consulta, el encabezado o la cookie.

Valores de cadenas de consulta u objetos de cadenas de consulta

Una función puede devolver un valor de cadena de consulta además de un objeto de cadena de consulta. El valor de la cadena de consulta se puede utilizar para organizar los parámetros de la cadena de consulta en cualquier orden personalizado.

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

Consideraciones especiales sobre el uso de los encabezados

Solo en el caso de encabezados, los nombres de encabezados se convierten a minúsculas en el objeto de evento; deben estar en minúsculas cuando se agregan con el código de función. Cuando CloudFront Functions convierte el objeto de evento de nuevo en una solicitud o respuesta HTTP, la primera letra de cada palabra en los nombres de encabezados se escribe en mayúsculas. Las palabras están separadas por un guión (-). Por ejemplo, si el código de la función agrega un encabezado llamado example-header-name, CloudFront lo convierte en Example-Header-Name en la solicitud o respuesta 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'};

Cadenas de consulta, encabezados y cookies duplicados (matriz multiValue)

Una solicitud o respuesta HTTP puede contener más de una cadena de consulta, encabezado o cookie con el mismo nombre. En este caso, las cadenas de consulta duplicadas, encabezados o cookies se contraen en un campo del objeto request o response, pero este campo contiene una propiedad adicional denominada multiValue. La propiedad multiValue contiene una matriz con los valores de cada una de las cadenas de consulta duplicadas, encabezados o cookies.

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 el código de función modifica una cadena de consulta, encabezado o cookie que tiene una matriz multiValue, CloudFront Functions utiliza las siguientes reglas para aplicar los cambios:

La propiedad multiValue se utiliza solo cuando la solicitud o respuesta HTTP contiene cadenas de consulta, encabezados o cookies duplicados con el mismo nombre, como se muestra en el ejemplo anterior. Sin embargo, si hay varios valores en una sola cadena de consulta, encabezado o cookie, la propiedad multiValue no se utiliza.

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

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

Atributos de cookie

En un encabezado Set-Cookie de una respuesta HTTP, el encabezado contiene el par nombre-valor para la cookie y opcionalmente un conjunto de atributos separados por punto y coma.

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

Objeto de respuesta de ejemplo

En el siguiente ejemplo se muestra un objeto response (el resultado de una función de respuesta del lector) en el que el cuerpo se ha sustituido por una función de respuesta del lector.

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

Objeto de evento de ejemplo

En el siguiente ejemplo se muestra un objeto event completo.

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