Métodos auxiliares para la modificación del origen - Amazon CloudFront
Elección entre CloudFront Functions y Lambda@EdgeMétodo updateRequestOrigin()Método selectRequestOriginById()Método createRequestOriginGroup()

Métodos auxiliares para la modificación del origen

Esta sección se aplica si actualiza o cambia dinámicamente el origen utilizado en la solicitud dentro del código de CloudFront Functions. Solo puede actualizar el origen cuando el espectador solicite CloudFront Functions. CloudFront Functions tiene un módulo que proporciona métodos auxiliares para actualizar o cambiar el origen de forma dinámica.

Para usar este módulo, cree una función de CloudFront con tiempo de ejecución 2.0 de JavaScript e incluya la siguiente instrucción en la primera línea del código de la función:

import cf from 'cloudfront';

Para obtener más información, consulte Características del tiempo de ejecución 2.0 de JavaScript para CloudFront Functions.

nota

Las páginas de la API de pruebas y la consola de pruebas no comprueban si se ha producido una modificación del origen. Sin embargo, las pruebas garantizan que el código de la función se ejecute sin errores.

Elección entre CloudFront Functions y Lambda@Edge

Puede actualizar sus orígenes mediante CloudFront Functions o Lambda@Edge.

Cuando se utiliza CloudFront Functions para actualizar los orígenes, se utiliza el desencadenador de eventos de solicitud del espectador, lo que significa que esta lógica se ejecutará en todas las solicitudes cuando se utilice esta función. Cuando se utiliza Lambda@Edge, las funciones de actualización del origen se encuentran en el desencadenador de eventos de solicitud de origen, lo que significa que esta lógica solo se ejecuta cuando se pierde memoria caché.

La elección depende en gran medida de la carga de trabajo y del uso actual de CloudFront Functions y Lambda@Edge en sus distribuciones. Las siguientes consideraciones pueden ayudarlo a decidir si debe utilizar CloudFront Functions o Lambda@Edge para actualizar sus orígenes.

CloudFront Functions es más útil en las siguientes situaciones:

  • Cuando sus solicitudes son dinámicas (es decir, no se pueden almacenar en caché) y siempre van al origen. CloudFront Functions ofrece un mejor rendimiento y un coste total más bajo.

  • Si tiene una función de CloudFront de solicitud de espectador existente que se ejecutará en cada solicitud, puede añadir la lógica de actualización del origen a la función existente.

Para usar CloudFront Functions para actualizar los orígenes, consulte los métodos auxiliares en los temas siguientes.

Lambda@Edge es más útil en las siguientes situaciones:

  • Cuando tiene contenido que se puede almacenar en caché con gran frecuencia, Lambda@Edge puede ser más rentable, ya que solo se ejecuta cuando se pierde memoria caché, mientras que CloudFront Functions se ejecuta en todas las solicitudes.

  • Si tiene una función de Lambda@Edge de solicitud de origen existente, puede añadir la lógica de actualización del origen a la función existente.

  • Cuando la lógica de actualización de origen requiere obtener datos de orígenes de datos de terceros, como Amazon DynamoDB o Amazon S3.

Para obtener más información sobre Lambda@Edge, consulte Personalización en la periferia con Lambda@Edge.

Método updateRequestOrigin()

Use el método updateRequestOrigin() para actualizar la configuración de origen de una solicitud. Puede usar este método para actualizar las propiedades de origen existentes para los orígenes que ya están definidos en su distribución o para definir un nuevo origen para la solicitud. Para ello, especifique las propiedades que desea cambiar.

importante

Cualquier configuración que no especifique en updateRequestOrigin() heredará la misma configuración de la configuración del origen existente.

El origen establecido por el método updateRequestOrigin() puede ser cualquier punto de conexión HTTP y no es necesario que sea un origen existente en la distribución de CloudFront.

Notas

  • Si está actualizando un origen que forma parte de un grupo de origen, solo se actualiza el origen principal del grupo de origen. El origen secundario no cambia. Cualquier código de respuesta del origen modificado que coincida con los criterios de conmutación por error desencadenará una conmutación por error al origen secundario.

  • Si va a cambiar el tipo de origen y tiene habilitado el OAC, asegúrese de que el tipo de origen en originAccessControlConfig coincida con el nuevo tipo de origen.

  • No puede usar el método updateRequestOrigin() para actualizar los orígenes de la VPC. Se producirá un error en la solicitud.

Solicitud

updateRequestOrigin({origin properties})

Las origin properties pueden incluir lo siguiente:

domainName (opcional)

El nombre de dominio del origen. Si no se proporciona, se utiliza en su lugar el nombre de dominio del origen asignado.

Para orígenes personalizados

Especifique un nombre de dominio DNS, como www.example.com. El nombre de dominio no puede incluir dos puntos (:) ni puede ser una dirección IP. El nombre de dominio puede tener una longitud de hasta 253 caracteres.

Para orígenes de S3

Especifique el nombre de dominio DNS del bucket de Amazon S3, como amzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com. El nombre puede tener una longitud de hasta 128 caracteres y debe escribirse en letras minúsculas.

originPath (opcional)

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/. Si no se proporciona, se utiliza la ruta de origen del origen asignado.

Para orígenes personalizados

La ruta debe estar codificada en URL y tener una longitud máxima de 255 caracteres.

customHeaders (opcional)

Si desea incluir encabezados personalizados con la solicitud, especifique un nombre de encabezado y un par de valores para cada uno de ellos. El formato es diferente al de los encabezados de solicitud y respuesta de la estructura de eventos. Use la siguiente sintaxis de pares clave-valor:

{"key1": "value1", "key2": "value2", ...}

No puede agregar encabezados que no estén permitidos y un encabezado con el mismo nombre tampoco puede estar presente en la solicitud entrante headers. El nombre del encabezado debe estar en minúsculas en el código de la función. Cuando CloudFront Functions convierte el objeto de evento de nuevo en una solicitud HTTP, la primera letra de cada palabra en los nombres de encabezados se escribe en mayúsculas, y las palabras se separan con guiones.

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 HTTP. Para obtener más información, consulte Encabezados personalizados que CloudFront no puede agregar a solicitudes de origen y Restricciones en funciones de borde.

Si no se proporciona, se utilizará cualquier encabezado personalizado del origen asignado.

connectionAttempts (opcional)

El número de veces que CloudFront intenta conectarse al origen. El valor mínimo es 1 y el máximo, 3. Si no se proporciona, se utilizarán los intentos de conexión del origen asignado.

originShield (opcional)

Esto habilita o actualiza Origin Shield de CloudFront. El uso de Origin Shield puede ayudar a reducir la carga en el origen. Para obtener más información, consulte Uso de Amazon CloudFront Origin Shield. Si no se proporciona, se utiliza la configuración de Origin Shield del origen asignado.

enabled (obligatorio)

Expresión booleana para activar o desactivar Origin Shield. Acepta un valor true o false.

region (obligatorio cuando está habilitado)

La Región de AWS para Origin Shield. Especifique la Región de AWS que tiene la latencia más baja en su origen. Use el código de la región, no el nombre de la región. Por ejemplo, use us-east-2 para especificar la región Este de EE. UU. (Ohio).

Cuando habilite Origin Shield de CloudFront, debe especificar la Región de AWS para Origin Shield. Para ver una lista de las Regiones de AWS disponibles y ayudarlo a elegir la mejor región para su origen, consulte Elegir la región de AWS para el escudo de origen.

originAccessControlConfig (opcional)

El identificador único de un control de acceso de origen (OAC) para este origen. Esto solo se usa cuando el origen admite un OAC de CloudFront, como Amazon S3, las URL de funciones de Lambda, MediaStore y MediaPackage V2. Si no se proporciona, se utiliza la configuración de OAC del origen asignado.

Esto no admite la identidad de acceso de origen (OAI) heredada. Para obtener más información, consulte Restricción del acceso a un origen de AWS.

enabled (obligatorio)

Expresión booleana para activar o desactivar OAC. Acepta un valor true o false.

signingBehavior (obligatorio cuando está habilitado)

Especifica qué solicitudes firma CloudFront (agrega información de autenticación). Especifique always para el caso de uso más común. Para obtener más información, consulte Configuración avanzada para el control de acceso de origen.

Este campo puede tener uno de los siguientes valores:

  • always: CloudFront firma todas las solicitudes de origen y sobrescribe el encabezado Authorization de la solicitud del lector, si existe.

  • never: CloudFront no firma ninguna solicitud de origen. Este valor desactiva el control de acceso de origen para el origen.

  • no-override: si la solicitud del espectador no contiene el encabezado Authorization, CloudFront firma la solicitud de origen. Si la solicitud del espectador contiene el encabezado Authorization, CloudFront no firma la solicitud de origen y, en cambio, pasa el encabezado Authorization de la solicitud del espectador.

    aviso

    Para pasar el encabezado Authorization de la solicitud del espectador, debe agregarlo a una política de solicitud de origen para todos los comportamientos de caché que utilizan los orígenes asociados a este control de acceso de origen. Para obtener más información, consulte Control de las solicitudes de origen con una política.

signingProtocol (obligatorio cuando está habilitado)

El protocolo de firma del OAC, que determina cómo CloudFront firma (autentica) las solicitudes. El único valor válido es sigv4.

originType (obligatorio cuando está habilitado)

El tipo de origen de este OAC. Los valores válidos son s3, mediapackagev2, mediastore y lambda.

timeouts (opcional)

Tiempos de espera en los que puede especificar durante cuánto tiempo CloudFront debe intentar esperar a que los orígenes respondan o envíen datos. Si no se proporciona, se utiliza la configuración de tiempo de espera del origen asignado.

readTimeout (opcional)

Los tiempos de espera solo se aplicarán a orígenes personalizados, no a orígenes de Amazon S3. (Las configuraciones de origen de S3 ignorarán estas configuraciones). readTimeout se aplicará a ambos de los siguientes valores:

  • Tiempo (en segundos) que CloudFront espera una respuesta después de enviar una solicitud al origen.

  • Tiempo (en segundos) que CloudFront espera después de recibir el paquete de una respuesta desde el origen y antes de recibir el paquete siguiente.

El tiempo de espera mínimo es 1 segundo; el máximo es 60 segundos. Para obtener más información, consulte Tiempo de espera de respuesta (solo orígenes personalizados y de VPC).

keepAliveTimeout (opcional)

Los tiempos de espera solo se aplicarán a orígenes personalizados, no a orígenes de Amazon S3. (Las configuraciones de origen de S3 ignorarán estas configuraciones). keepAliveTimeout especifica el tiempo que CloudFront debería intentar mantener la conexión con el origen después de recibir el último paquete de la respuesta. El tiempo de espera mínimo es 1 segundo; el máximo es 60 segundos. Para obtener más información, consulte Tiempo de espera de keep-alive (solo orígenes personalizados y de VPC).

connectionTimeout (opcional)

Número de segundos que espera CloudFront al intentar establecer una conexión con el origen. El tiempo de espera mínimo es 1 segundo; el máximo es 10 segundos. Para obtener más información, consulte Tiempo de espera de conexión.

customOriginConfig (opcional)

Se utiliza customOriginConfig para especificar la configuración de conexión para los orígenes que no son un bucket de Amazon S3. Hay una excepción: puede especificar esta configuración si el bucket de S3 está configurado con alojamiento de sitios web estáticos. (Otros tipos de configuraciones de bucket de S3 ignorarán esta configuración). Si no se proporciona customOriginConfig, se utiliza la configuración del origen asignado.

port (obligatorio)

El puerto HTTP que CloudFront utiliza para conectarse al origen. Especifique el puerto HTTP que escucha el origen.

protocol (obligatorio)

Especifica el protocolo (HTTP o HTTPS) que CloudFront utiliza para conectarse al origen. Los valores válidos son los siguientes:

  • http: CloudFront utiliza siempre HTTP para conectarse al origen

  • https: CloudFront utiliza siempre HTTPS para conectarse al origen

sslProtocols (obligatorio)

Una lista que especifica el protocolo SSL/TLS mínimo que CloudFront utiliza al conectarse a su origen a través de HTTPS. Los valores válidos son SSLv3, TLSv1, TLSv1.1 y TLSv1.2. Para obtener más información, consulte Protocolo SSL mínimo del origen.

ejemplo : actualización al origen de la solicitud de Amazon S3

El siguiente ejemplo cambia el origen de la solicitud del espectador a un bucket de S3, activa el OAC y restablece los encabezados personalizados enviados al origen.

cf.updateRequestOrigin({
    "domainName" : "amzn-s3-demo-bucket-in-us-east-1.s3.us-east-1.amazonaws.com",
    "originAccessControlConfig": {
        "enabled": true,
        "signingBehavior": "always",
        "signingProtocol": "sigv4",
        "originType": "s3"
    },
    // Empty object resets any header configured on the assigned origin
    "customHeaders": {}
});
ejemplo : actualización al origen de la solicitud del equilibrador de carga de aplicación

El siguiente ejemplo cambia el origen de la solicitud del espectador a un origen de equilibrador de carga de aplicación y establece un encabezado personalizado y tiempos de espera.

cf.updateRequestOrigin({
    "domainName" : "example-1234567890.us-east-1.elb.amazonaws.com",
    "timeouts": {
        "readTimeout": 30,
        "connectionTimeout": 5
    },
    "customHeaders": {
        "x-stage": "production",
        "x-region": "us-east-1"
    }
});
ejemplo : actualización al origen con Origin Shield activado

En el siguiente ejemplo, el origen de la distribución tiene Origin Shield activado. El código de función actualiza solo el nombre de dominio utilizado para el origen y omite todos los demás parámetros opcionales. En este caso, Origin Shield seguirá utilizándose con el nombre de dominio del origen modificado porque los parámetros de Origin Shield no se actualizaron.

cf.updateRequestOrigin({
    "domainName" : "www.example.com"
});

Método selectRequestOriginById()

Utilice selectRequestOriginById() para actualizar un origen existente mediante la selección un origen diferente que ya esté configurado en la distribución. Este método utiliza toda la configuración definida por el origen actualizado.

Este método solo acepta orígenes que ya estén definidos en la misma distribución utilizada al ejecutar la función. Se hace referencia a los orígenes por el ID de origen, que es el nombre del origen que se ha definido al configurar el origen.

Si tiene un origen de VPC configurado en la distribución, puede utilizar este método para actualizar el origen al origen de VPC. Para obtener más información, consulte Restricción del acceso con orígenes de la VPC.

Solicitud

selectRequestOriginById(origin_id)

En el ejemplo anterior, origin_id es una cadena que apunta al nombre de un origen en la distribución que está ejecutando la función.

ejemplo : selección del origen de solicitud de Amazon S3

El siguiente ejemplo selecciona el origen denominado amzn-s3-demo-bucket-in-us-east-1 de la lista de orígenes asociados a la distribución y aplica los ajustes de configuración del origen amzn-s3-demo-bucket-in-us-east-1 a la solicitud.

cf.selectRequestOriginById("amzn-s3-demo-bucket-in-us-east-1");
ejemplo : selección del origen de la solicitud del equilibrador de carga de aplicación

El siguiente ejemplo selecciona un origen del equilibrador de carga de aplicación denominado myALB-prod de la lista de orígenes asociada a la distribución y aplica los ajustes de configuración de myALB-prod a la solicitud.

cf.selectRequestOriginById("myALB-prod");

Método createRequestOriginGroup()

Utilice createRequestOriginGroup() para definir dos orígenes que se utilizarán como grupo de orígenes para la conmutación por error en escenarios que requieren alta disponibilidad.

Un grupo de orígenes incluye dos orígenes (uno principal y otro secundario) y un criterio de conmutación por error especificado. Cree un grupo de origen para admitir la conmutación por error de origen en CloudFront. Cuando cree o actualice un grupo de orígenes mediante este método, puede especificar el grupo de orígenes en lugar de un único origen. CloudFront realizará la conmutación por error del origen principal al secundario, mediante los criterios de conmutación por error.

Si tiene un origen de VPC configurado en la distribución, puede utilizar este método para crear un grupo de orígenes utilizando un origen de VPC. Para obtener más información, consulte Restricción del acceso con orígenes de la VPC.

Solicitud

createRequestOriginGroup({origin_group_properties})

En el ejemplo anterior, el archivo origin_group_properties contiene lo siguiente:

originIds (obligatorio)

Matriz de origin_ids, donde origin_id es una cadena que apunta al nombre de un origen en la distribución que ejecuta la función. Debe proporcionar dos orígenes como parte de la matriz. El primer origen de la lista es el origen principal y el segundo sirve como segundo origen a efectos de conmutación por error.

selectionCriteria (opcional)

Seleccione si desea utilizar los criterios de conmutación por error del origen default o utilizar la lógica de conmutación por error basada en media-quality-score. Los valores válidos son los siguientes:

  • default utiliza los criterios de conmutación por error basados en los códigos de estado que se especifican en failoverCriteria. Si no configura selectionCriteria en la función, se utilizará default.

  • media-quality-score se utiliza cuando se emplea la capacidad de enrutamiento con reconocimiento multimedia.

failoverCriteria (obligatorio)

Una matriz de códigos de estado que, cuando se devuelven desde el origen principal, desencadenarán que CloudFront conmute por error al origen secundario. Si sobrescribe un grupo de orígenes existente, esta matriz sobrescribirá todos los códigos de estado de conmutación por error establecidos en la configuración original del grupo de orígenes.

Cuando utilice media-quality-score selectionCriteria, CloudFront intentará enrutar las solicitudes basándose en la puntuación de calidad de los medios. Si el origen seleccionado devuelve un código de error establecido en esta matriz, CloudFront realizará la conmutación por error al otro origen.

ejemplo : creación del grupo de orígenes de solicitudes

En el siguiente ejemplo se crea un grupo de orígenes para una solicitud mediante los ID de origen. Estos ID de origen proceden de la configuración del grupo de orígenes para la distribución utilizada para ejecutar esta función.

cf.createRequestOriginGroup({
    originIds: ["us-east-1-s3-origin", "us-west-2-s3-origin"],
    failoverCriteria: {
        statusCodes: [500, 502, 503, 504] 
    }
});