Estructura de eventos de Lambda@Edge - Amazon CloudFront
Selección dinámica del origenEventos de solicitudEventos de respuesta

Estructura de eventos de Lambda@Edge

En los temas siguientes se describen los objetos de evento de solicitud y respuesta que CloudFront pasa a una función de Lambda@Edge cuando se activa.

Selección dinámica del origen

Puede utilizar el patrón de ruta de un comportamiento de la caché para enviar las solicitudes a un origen, en función de la ruta y el nombre del objeto solicitado, como images/*.jpg. Lambda@Edge también le permite direccionar las solicitudes a un origen en función de otras características, como los valores de los encabezados de solicitudes.

Esta selección dinámica del origen puede resultar útil en varios casos. Por ejemplo, puede distribuir solicitudes entre orígenes de diferentes zonas geográficas para facilitar el balanceo de carga global. También puede direccionar solicitudes selectivamente a varios orígenes, cada uno de ellos con un propósito distinto: control de bots, optimización SEO, autenticación, etc. Para obtener ejemplos de código que muestran cómo utilizar esta característica, consulte Selección de origen dinámico basada en contenido: ejemplos.

En el evento de solicitud de origen de CloudFront, el objeto origin de la estructura de eventos contiene información sobre el origen al que se enviaría la solicitud, en función del patrón de ruta. Puede actualizar los valores del objeto origin para enviar una solicitud a otro origen. Al actualizar el objeto de origin, no es necesario definir el origen en la distribución. También puede reemplazar un objeto de origen de Amazon S3 por un objeto de origen personalizado y viceversa. Sin embargo, solo se puede especificar un único origen por solicitud, ya sea un origen personalizado o un origen de Amazon S3, pero no ambos.

Eventos de solicitud

En los temas siguientes se muestra la estructura del objeto que CloudFront pasa a una función de Lambda para los eventos de solicitud de lector y de origen. Estos ejemplos muestran una solicitud GET sin cuerpo. Después de los ejemplos, se muestra una lista de todos los campos posibles en eventos de solicitud de lector y de origen.

Ejemplo de solicitud de lector

En el ejemplo siguiente se muestra un objeto de evento de solicitud de lector.

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "viewer-request",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "host": [
              {
                "key": "Host",
                "value": "d111111abcdef8.cloudfront.net"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "curl/7.66.0"
              }
            ],
            "accept": [
              {
                "key": "accept",
                "value": "*/*"
              }
            ]
          },
          "method": "GET",
          "querystring": "",
          "uri": "/"
        }
      }
    }
  ]
}

Ejemplo de solicitud de origen

En el ejemplo siguiente se muestra un objeto de evento de solicitud de origen.

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "origin-request",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "x-forwarded-for": [
              {
                "key": "X-Forwarded-For",
                "value": "203.0.113.178"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "Amazon CloudFront"
              }
            ],
            "via": [
              {
                "key": "Via",
                "value": "2.0 2afae0d44e2540f472c0635ab62c232b.cloudfront.net (CloudFront)"
              }
            ],
            "host": [
              {
                "key": "Host",
                "value": "example.org"
              }
            ],
            "cache-control": [
              {
                "key": "Cache-Control",
                "value": "no-cache"
              }
            ]
          },
          "method": "GET",
          "origin": {
            "custom": {
              "customHeaders": {},
              "domainName": "example.org",
              "keepaliveTimeout": 5,
              "path": "",
              "port": 443,
              "protocol": "https",
              "readTimeout": 30,
              "sslProtocols": [
                "TLSv1",
                "TLSv1.1",
                "TLSv1.2"
              ]
            }
          },
          "querystring": "",
          "uri": "/"
        }
      }
    }
  ]
}

Campos de eventos de solicitud

Los datos del objeto de evento de solicitud se incluyen en dos subobjetos: config (Records.cf.config) y request (Records.cf.request). En las listas siguientes se describen los campos de cada subobjeto.

Campos del objeto config

En la siguiente lista se describen los campos del objeto config (Records.cf.config).

distributionDomainName (solo lectura)

El nombre de dominio de la distribución asociada a la solicitud.

distributionID (solo lectura)

El ID de la distribución asociada a la solicitud.

eventType (solo lectura)

El tipo de desencadenador asociado a la solicitud: viewer-request u origin-request.

requestId (solo lectura)

Una cadena cifrada que identifica de forma inequívoca una solicitud de lector a CloudFront. El valor requestId también aparece en los registros de acceso de CloudFront como x-edge-request-id. Para obtener más información, consulte Configuración y uso de registros estándar (registros de acceso) y Campos de archivo de registro estándar.

Campos del objeto de solicitud

En la siguiente lista se describen los campos del objeto request (Records.cf.request).

clientIp (solo lectura)

La dirección IP del espectador que ha realizado la solicitud. Si el espectador utiliza un proxy HTTP o un equilibrador de carga para enviar la solicitud, el valor es la dirección IP del proxy o del equilibrador de carga.

headers (lectura y escritura)

Los encabezados de la solicitud. Tenga en cuenta lo siguiente:

  • Las claves del objeto headers son nombres de encabezado HTTP estándar en minúsculas. El uso de claves en minúsculas le proporciona acceso a los valores del encabezado sin diferenciar mayúsculas de minúsculas.

  • Cada objeto header (por ejemplo, headers["accept"] o headers["host"]) es una matriz de pares de clave-valor. Para un encabezado determinado, la matriz contiene un par de clave-valor para cada valor de la solicitud.

  • key contiene el nombre con distinción de mayúsculas y minúsculas del encabezado tal como aparecía en la solicitud HTTP; por ejemplo Host, User-Agent, X-Forwarded-For, etc.

  • value contiene el valor del encabezado tal como aparecía en la solicitud HTTP.

  • Cuando la función Lambda agrega o modifica encabezados de solicitud y no incluye el campo key del encabezado, Lambda@Edge inserta automáticamente un encabezado key usando el nombre de encabezado que proporcione. Independientemente de cómo haya formateado el nombre del encabezado, la clave de encabezado que se inserta automáticamente se formatea con mayúscula inicial para cada parte, separada por guiones (-).

    Por ejemplo, puede agregar un encabezado como el siguiente, sin la clave de encabezado key:

    "user-agent": [
  {
    "value": "ExampleCustomUserAgent/1.X.0"
  }
]

    En este ejemplo, Lambda @Edge inserta automáticamente "key": "User-Agent".

Para obtener más información acerca de restricciones de uso de encabezados, consulte Restricciones en funciones de borde.

method (solo lectura)

El método HTTP de la solicitud.

querystring (lectura y escritura)

La cadena de consulta, si hay alguna, de la solicitud. Si la solicitud no incluye una cadena de consulta, el objeto del evento incluye igualmente querystring con un valor vacío. Para obtener más información acerca de cadenas de consulta, consulte Almacenamiento en caché de contenido en función de parámetros de cadenas de consulta.

uri (lectura y escritura)

La ruta relativa del objeto solicitado. Si su función de Lambda modifica el valor uri, tenga en cuenta lo siguiente:

  • El nuevo valor uri debe comenzar con una barra diagonal (/).

  • Si una función cambia el valor de uri, se cambia el objeto que el lector solicita.

  • Si una función cambia el valor de uri, no cambia el comportamiento de la caché de la solicitud ni del origen al que se envía la solicitud.

body (lectura y escritura)

El cuerpo de la solicitud HTTP. La estructura body puede contener los siguientes campos:

inputTruncated (solo lectura)

Un indicador booleano que indica si Lambda@Edge truncó el cuerpo. Para obtener más información, consulte Restricciones para el cuerpo de la solicitud con la opción Incluir cuerpo.

action (lectura y escritura)

La acción que va a realizar con el cuerpo. Las opciones de action son las siguientes:

  • read-only: Esta es la opción predeterminada. Cuando se devuelve la respuesta de la función de Lambda, si action es solo lectura, Lambda@Edge omite los cambios realizados en encoding o data.

  • replace: Especifique este valor cuando desee reemplazar el cuerpo enviado al origen.

encoding (lectura y escritura)

La codificación del cuerpo. Cuando Lambda@Edge expone el cuerpo a la función de Lambda, primero lo convierte a base64-encoding. Si elige replace en action para reemplazar el cuerpo, puede elegir usar la codificación base64 o text (el valor predeterminado). Si especifica encoding como base64 pero el cuerpo no tiene una codificación base64 válida, CloudFront devuelve un error.

data (lectura y escritura)

El contenido del cuerpo de la solicitud.

origin (lectura y escritura) (solo eventos de origen)

El origen al que se envía la solicitud. La estructura origin debe contener exactamente un origen, que puede ser un origen personalizado o un origen de Amazon S3. La estructura de origen puede contener los siguientes campos:

customHeaders (lectura/escritura) (orígenes personalizados y de Amazon S3)

Si desea incluir encabezados personalizados con la solicitud, especifique un nombre de encabezado y un par de valores para cada uno de ellos. No puede agregar encabezados que no estén permitidos y un encabezado con el mismo nombre no puede estar presente en Records.cf.request.headers. Las notas sobre encabezados de solicitud también se aplican a los encabezados personalizados. Para obtener más información, consulte Encabezados personalizados que CloudFront no puede agregar a solicitudes de origen y Restricciones en funciones de borde.

domainName (lectura/escritura) (orígenes personalizados y de Amazon S3)

El nombre de dominio del origen. El nombre de dominio no puede estar vacío.

  • Para orígenes personalizados: especifique un nombre de dominio DNS, como www.example.com. El nombre de dominio no puede incluir dos puntos (:) y no puede ser una dirección IP. El nombre de dominio puede tener una longitud de hasta 253 caracteres.

  • Para orígenes de Amazon S3: especifique el nombre de dominio DNS del bucket de Amazon S3, como awsexamplebucket.s3.eu-west-1.amazonaws.com. El nombre puede tener una longitud de hasta 128 caracteres y debe escribirse en letras minúsculas.

path (lectura/escritura) (orígenes personalizados y de Amazon S3)

La ruta de directorio del servidor donde la solicitud debería encontrar el contenido. La ruta debe comenzar con una barra diagonal (/), pero no debe terminar con una (por ejemplo, no debería terminar con example-path/). Solo para los orígenes personalizados: la ruta debe estar codificada como una URL y tener una longitud máxima de 255 caracteres.

keepaliveTimeout (lectura y escritura) (solo orígenes personalizados)

El periodo de tiempo, en segundos, que CloudFront debería intentar mantener la conexión con el origen después de recibir el último paquete de la respuesta. El valor debe ser un número comprendido entre 1 y 60, ambos inclusive.

port (lectura y escritura) (solo orígenes personalizados)

El puerto al que CloudFront debe conectarse en el origen personalizado. Este valor debe ser 80, 443 o un número comprendido entre 1024 y 65535, ambos inclusive.

protocol (lectura y escritura) (solo orígenes personalizados)

El protocolo de conexión que CloudFront debe usar al conectarse a su origen. El valor puede ser http o https.

readTimeout (lectura y escritura) (solo orígenes personalizados)

El tiempo, en segundos, que CloudFront debe esperar una respuesta después de enviar una solicitud a su origen. También especifica cuánto tiempo debe esperar CloudFront después de recibir un paquete de una respuesta antes de recibir el siguiente paquete. El valor debe ser un número comprendido entre 4 y 60, ambos inclusive.

Si su caso de uso requiere más de 60 segundos, puede solicitar una cuota superior para Response timeout per origin. Para obtener más información, consulte Cuotas generales de distribuciones.

sslProtocols (lectura y escritura) (solo orígenes personalizados)

El protocolo SSL/TLS mínimo que CloudFront puede utilizar al establecer una conexión HTTPS con su origen. Los valores pueden ser alguno de los siguientes: TLSv1.2, TLSv1.1, TLSv1 o SSLv3.

authMethod (lectura/escritura) (solo orígenes de Amazon S3)

Si utiliza una identidad de acceso de origen (OAI), establezca este campo a origin-access-identity. Si no usa una OAI, establézcala a none. Si establece authMethod en origin-access-identity, se aplican varios requisitos:

  • Debe especificar el elemento region (consulte el siguiente campo).

  • Debe utilizar la misma OAI cuando cambie la solicitud de un origen de Amazon S3 a otro.

  • No se puede utilizar una OAI cuando se cambia la solicitud de un origen personalizado a un origen de Amazon S3.

nota

Este campo no admite el control de acceso de origen (OAC).

region (lectura/escritura) (solo orígenes de Amazon S3)

La región de AWS de su bucket de Amazon S3. Esto solo es necesario cuando se establece authMethod en origin-access-identity.

Eventos de respuesta

En los temas siguientes se muestra la estructura del objeto que CloudFront pasa a una función Lambda para los eventos de respuesta de lector y de origen. Después de los ejemplos, se muestra una lista de todos los campos posibles en eventos de respuesta de lector y de origen.

Respuesta de origen de ejemplo

En el ejemplo siguiente se muestra un objeto de evento de respuesta de origen.

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "origin-response",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "x-forwarded-for": [
              {
                "key": "X-Forwarded-For",
                "value": "203.0.113.178"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "Amazon CloudFront"
              }
            ],
            "via": [
              {
                "key": "Via",
                "value": "2.0 8f22423015641505b8c857a37450d6c0.cloudfront.net (CloudFront)"
              }
            ],
            "host": [
              {
                "key": "Host",
                "value": "example.org"
              }
            ],
            "cache-control": [
              {
                "key": "Cache-Control",
                "value": "no-cache"
              }
            ]
          },
          "method": "GET",
          "origin": {
            "custom": {
              "customHeaders": {},
              "domainName": "example.org",
              "keepaliveTimeout": 5,
              "path": "",
              "port": 443,
              "protocol": "https",
              "readTimeout": 30,
              "sslProtocols": [
                "TLSv1",
                "TLSv1.1",
                "TLSv1.2"
              ]
            }
          },
          "querystring": "",
          "uri": "/"
        },
        "response": {
          "headers": {
            "access-control-allow-credentials": [
              {
                "key": "Access-Control-Allow-Credentials",
                "value": "true"
              }
            ],
            "access-control-allow-origin": [
              {
                "key": "Access-Control-Allow-Origin",
                "value": "*"
              }
            ],
            "date": [
              {
                "key": "Date",
                "value": "Mon, 13 Jan 2020 20:12:38 GMT"
              }
            ],
            "referrer-policy": [
              {
                "key": "Referrer-Policy",
                "value": "no-referrer-when-downgrade"
              }
            ],
            "server": [
              {
                "key": "Server",
                "value": "ExampleCustomOriginServer"
              }
            ],
            "x-content-type-options": [
              {
                "key": "X-Content-Type-Options",
                "value": "nosniff"
              }
            ],
            "x-frame-options": [
              {
                "key": "X-Frame-Options",
                "value": "DENY"
              }
            ],
            "x-xss-protection": [
              {
                "key": "X-XSS-Protection",
                "value": "1; mode=block"
              }
            ],
            "content-type": [
              {
                "key": "Content-Type",
                "value": "text/html; charset=utf-8"
              }
            ],
            "content-length": [
              {
                "key": "Content-Length",
                "value": "9593"
              }
            ]
          },
          "status": "200",
          "statusDescription": "OK"
        }
      }
    }
  ]
}

Respuesta de lector de ejemplo

En el ejemplo siguiente se muestra un objeto de evento de respuesta de lector.

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "viewer-response",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "host": [
              {
                "key": "Host",
                "value": "d111111abcdef8.cloudfront.net"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "curl/7.66.0"
              }
            ],
            "accept": [
              {
                "key": "accept",
                "value": "*/*"
              }
            ]
          },
          "method": "GET",
          "querystring": "",
          "uri": "/"
        },
        "response": {
          "headers": {
            "access-control-allow-credentials": [
              {
                "key": "Access-Control-Allow-Credentials",
                "value": "true"
              }
            ],
            "access-control-allow-origin": [
              {
                "key": "Access-Control-Allow-Origin",
                "value": "*"
              }
            ],
            "date": [
              {
                "key": "Date",
                "value": "Mon, 13 Jan 2020 20:14:56 GMT"
              }
            ],
            "referrer-policy": [
              {
                "key": "Referrer-Policy",
                "value": "no-referrer-when-downgrade"
              }
            ],
            "server": [
              {
                "key": "Server",
                "value": "ExampleCustomOriginServer"
              }
            ],
            "x-content-type-options": [
              {
                "key": "X-Content-Type-Options",
                "value": "nosniff"
              }
            ],
            "x-frame-options": [
              {
                "key": "X-Frame-Options",
                "value": "DENY"
              }
            ],
            "x-xss-protection": [
              {
                "key": "X-XSS-Protection",
                "value": "1; mode=block"
              }
            ],
            "age": [
              {
                "key": "Age",
                "value": "2402"
              }
            ],
            "content-type": [
              {
                "key": "Content-Type",
                "value": "text/html; charset=utf-8"
              }
            ],
            "content-length": [
              {
                "key": "Content-Length",
                "value": "9593"
              }
            ]
          },
          "status": "200",
          "statusDescription": "OK"
        }
      }
    }
  ]
}

Campos del evento de respuesta

Los datos del objeto de evento de respuesta se incluyen en tres subobjetos: config (Records.cf.config), request (Records.cf.request) y response (Records.cf.response). Para obtener más información acerca de los campos del objeto de solicitud, consulte Campos del objeto de solicitud. En las listas siguientes se describen los campos de los subobjetos response y config.

Campos del objeto config

En la siguiente lista se describen los campos del objeto config (Records.cf.config).

distributionDomainName (solo lectura)

El nombre de dominio de la distribución asociada a la respuesta.

distributionID (solo lectura)

El ID de la distribución asociada a la respuesta.

eventType (solo lectura)

El tipo de desencadenador asociado a la respuesta: origin-response o viewer-response.

requestId (solo lectura)

Una cadena cifrada que identifica de forma inequívoca la solicitud del lector a CloudFront a la que está asociada esta respuesta. El valor requestId también aparece en los registros de acceso de CloudFront como x-edge-request-id. Para obtener más información, consulte Configuración y uso de registros estándar (registros de acceso) y Campos de archivo de registro estándar.

Campos del objeto de respuesta

En la siguiente lista se describen los campos del objeto response (Records.cf.response). Para obtener información sobre el uso de una función de Lambda @Edge para generar una respuesta HTTP, consulte Generación de respuestas HTTP en los desencadenadores de solicitud.

headers (lectura y escritura)

Los encabezados de la respuesta. Tenga en cuenta lo siguiente:

  • Las claves del objeto headers son nombres de encabezado HTTP estándar en minúsculas. El uso de claves en minúsculas le proporciona acceso a los valores del encabezado sin diferenciar mayúsculas de minúsculas.

  • Cada objeto header (por ejemplo, headers["content-type"] o headers["content-length"]) es una matriz de pares de clave-valor. Para un encabezado determinado, la matriz contiene un par de clave-valor para cada valor de la respuesta.

  • key contiene el nombre con distinción de mayúsculas y minúsculas del encabezado tal como aparece en la respuesta HTTP; por ejemplo Content-Type, Content-Length, Cookie, etc.

  • value contiene el valor del encabezado tal como aparece en la respuesta HTTP.

  • Cuando la función Lambda agrega o modifica encabezados de respuesta y no incluye el campo key del encabezado, Lambda@Edge inserta automáticamente un encabezado key usando el nombre de encabezado que proporcione. Independientemente de cómo haya formateado el nombre del encabezado, la clave de encabezado que se inserta automáticamente se formatea con mayúscula inicial para cada parte, separada por guiones (-).

    Por ejemplo, puede agregar un encabezado como el siguiente, sin la clave de encabezado key:

    "content-type": [
  {
    "value": "text/html;charset=UTF-8"
  }
]

    En este ejemplo, Lambda @Edge inserta automáticamente "key": "Content-Type".

Para obtener más información acerca de restricciones de uso de encabezados, consulte Restricciones en funciones de borde.

status

Código de estado HTTP de la respuesta.

statusDescription

La descripción del estado HTTP de la respuesta.