Metodi di assistente di gestione per la modifica dell’origine - Amazon CloudFront
Scelta tra Funzioni CloudFront e Lambda@EdgeMetodo updateRequestOrigin()Metodo selectRequestOriginById()Metodo createRequestOriginGroup()

Metodi di assistente di gestione per la modifica dell’origine

Questa sezione si applica se aggiorni o modifichi dinamicamente l’origine utilizzata nella richiesta all’interno del codice Funzioni CloudFront. Puoi aggiornare l’origine solo su Funzioni CloudFront della richiesta visualizzatore. Funzioni CloudFront dispone di un modulo che fornisce metodi di assistente di gestione per aggiornare o modificare dinamicamente l’origine.

Per utilizzare questo modulo, crea una funzione CloudFront utilizzando JavaScript runtime 2.0 e includi la seguente istruzione nella prima riga del codice della funzione:

import cf from 'cloudfront';

Per ulteriori informazioni, consulta Funzionalità di runtime JavaScript 2.0 per Funzioni CloudFront.

Nota

Le pagine della console Esegui test API ed Esegui test non controllano se si è verificata una modifica dell’origine. Tuttavia, il test garantisce che il codice della funzione venga eseguito senza errori.

Scelta tra Funzioni CloudFront e Lambda@Edge

Puoi aggiornare le origini utilizzando Funzioni CloudFront o Lambda@Edge.

Quando si utilizza Funzioni CloudFront per aggiornare le origini, si utilizza il trigger dell’evento di richiesta visualizzatore, il che significa che questa logica verrà eseguita su ogni richiesta quando viene utilizzata questa funzione. Quando si utilizza Lambda@Edge, le funzionalità di aggiornamento dell’origine si trovano nel trigger dell’evento di richiesta origine, il che significa che questa logica viene eseguita solo in caso di perdita della cache.

La scelta dipende in gran parte dal carico di lavoro e dall’eventuale utilizzo di Funzioni CloudFront e Lambda@Edge sulle distribuzioni. Le seguenti considerazioni possono aiutare a decidere se utilizzare Funzioni CloudFront o Lambda@Edge per aggiornare le origini.

Funzioni CloudFront è molto utile nelle seguenti situazioni:

  • Quando le richieste sono dinamiche (ovvero non possono essere memorizzate nella cache) e vengono sempre indirizzate all’origine. Funzioni CloudFront offre prestazioni migliori e costi complessivi inferiori.

  • Se disponi già di una funzione CloudFront di richiesta visualizzatore esistente che verrà eseguita ad ogni richiesta, puoi aggiungere la logica di aggiornamento dell’origine alla funzione esistente.

Per utilizzare Funzioni CloudFront per aggiornare le origini, consulta i metodi di assistente di gestione nei seguenti argomenti.

Lambda@Edge è particolarmente utile nelle seguenti situazioni:

  • Se disponi di contenuti altamente memorizzabili nella cache, Lambda@Edge può essere più conveniente dal punto di vista dei costi perché viene eseguita solo in caso di mancati riscontri nella cache, mentre Funzioni CloudFront viene eseguita ad ogni richiesta.

  • Se disponi già di una funzione Lambda@Edge per le richieste origine, puoi aggiungere la logica di aggiornamento dell’origine alla funzione esistente.

  • Quando la logica di aggiornamento dell’origine richiede il recupero di dati da origini dati di terze parti, come Amazon DynamoDB o Amazon S3.

Per ulteriori informazioni su Lambda@Edge, consulta Personalizzazione al livello di edge con Lambda@Edge.

Metodo updateRequestOrigin()

Utilizza il metodo updateRequestOrigin() per aggiornare le impostazioni di origine per una richiesta. Puoi utilizzare questo metodo per aggiornare le proprietà di origine esistenti per le origini già definite nella distribuzione o per definire una nuova origine per la richiesta. A tale scopo, specifica le proprietà che desideri modificare.

Importante

Tutte le impostazioni non specificate in updateRequestOrigin() erediteranno le stesse impostazioni dalla configurazione dell’origine esistente.

L’origine impostata dal metodo updateRequestOrigin() può essere qualsiasi endpoint HTTP e non è necessario che sia un’origine esistente all’interno della distribuzione CloudFront.

Note

  • Se stai aggiornando un’origine che fa parte di un gruppo di origine, viene aggiornata solo l’origine principale del gruppo di origine. L’origine secondaria rimane invariata. Qualsiasi codice di risposta proveniente dall’origine modificata che soddisfi i criteri di failover attiverà un failover all’origine secondaria.

  • Se stai modificando il tipo di origine e hai abilitato l’OAC, assicurati che il tipo di origine in originAccessControlConfig corrisponda al nuovo tipo di origine.

  • Non puoi utilizzare il metodo updateRequestOrigin() per aggiornare VPC Origins. La richiesta non andrà a buon fine.

Richiesta

updateRequestOrigin({origin properties})

Le origin properties possono contenere i seguenti valori:

domainName (facoltativo)

Il nome di dominio dell'origine. Se non è fornito, viene utilizzato il nome di dominio dell’origine assegnata.

Per origini personalizzate

Specifica un nome di dominio DNS, ad esempio www.example.com. Il nome di dominio non può includere due punti (:) e non può essere un indirizzo IP. Il nome di dominio può contenere fino a 253 caratteri.

Per origini S3

Specifica il nome di dominio DNS del bucket Amazon S3, ad esempio amzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com. Il nome può contenere fino a 128 caratteri e deve essere tutto in minuscolo.

originPath (facoltativo)

Il percorso di directory sul server di origine in cui la richiesta deve trovare il contenuto. Il percorso può iniziare, ma non deve terminare, con una barra (/). Ad esempio, non deve terminare con example-path/. Se questo non è fornito, viene utilizzato il percorso di origine dall’origine assegnata.

Per origini personalizzate

Il percorso deve essere codificato URL e avere una lunghezza massima di 255 caratteri.

customHeaders (facoltativo)

Puoi includere intestazioni personalizzate con la richiesta specificando un nome di intestazione e una coppia di valori per ogni intestazione personalizzata. Il formato è diverso da quello delle intestazioni di richiesta e risposta nella struttura dell’evento. Utilizza la seguente sintassi della coppia chiave-valore:

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

Non è possibile aggiungere intestazioni non consentite e un’intestazione con lo stesso nome non può essere presente anche nelle headers della richiesta in entrata. Il nome dell’intestazione deve essere in minuscolo nel codice della funzione. Quando Funzioni CloudFront converte l’oggetto evento in una richiesta HTTP, la prima lettera di ogni parola nei nomi delle intestazioni è in maiuscolo e le parole sono separate da un trattino.

Ad esempio, se il codice funzione aggiunge un’intestazione denominata example-header-name, CloudFront lo converte in Example-Header-Name nella richiesta HTTP. Per ulteriori informazioni, consulta Intestazioni personalizzate che CloudFront non può aggiungere alle richieste di origine e Restrizioni sulle funzioni edge.

Se questo non viene fornito, vengono utilizzate le intestazioni personalizzate dell’origine assegnata.

connectionAttempts (facoltativo)

Numero di tentativi di connessione all'origine di CloudFront. Il valore minimo è 1 e il valore massimo è 3. Se questo non viene fornito, vengono utilizzati i tentativi di connessione dall’origine assegnata.

originShield (facoltativo)

Questo abilita o aggiorna CloudFront Origin Shield. L'utilizzo di Origin Shield può contribuire a ridurre il carico sulla tua origine. Per ulteriori informazioni, consulta Utilizzo di Origin Shield di Amazon CloudFront. Se questo non è fornito, vengono utilizzate le impostazioni Origin Shield dall’origine assegnata.

enabled (obbligatorio)

Espressione booleana per abilitare o disabilitare Origin Shield. Accetta un valore true o false.

region (obbligatorio se abilitato)

La Regione AWS per Origin Shield. Specifica la Regione AWS con la latenza più bassa all'origine. Utilizza il codice della regione, non il nome della regione. Ad esempio, utilizza us-east-2 per specificare la regione Stati Uniti orientali (Ohio).

Quando abiliti Origin Shield di CloudFront, devi specificare la Regione AWS per lo stesso. Per un elenco delle Regioni AWS disponibili e informazioni sulla scelta della regione migliore per l’origine, consulta Scegli la Regione AWS per Origin Shield..

originAccessControlConfig (facoltativo)

L’identificativo univoco di un controllo di accesso origine (OAC) per tale origine. Viene utilizzato solo quando l’origine supporta un OAC CloudFront, come Amazon S3, URL della funzione Lambda, MediaStore e MediaPackage V2. Se questo non viene fornito, vengono utilizzate le impostazioni OAC dell’origine assegnata.

Questo non supporta l’identità di accesso origine (OAI) legacy. Per ulteriori informazioni, consulta Limitazione dell’accesso a un’origine AWS.

enabled (obbligatorio)

Espressione booleana per abilitare o disabilitare OAC. Accetta un valore true o false.

signingBehavior (obbligatorio se abilitato)

Specifica le richieste che CloudFront firma (alle quali aggiunge informazioni di autenticazione). Specifica always per il caso d'uso più comune. Per ulteriori informazioni, consulta Impostazioni avanzate per il controllo dell'accesso all'origine.

Questo campo può avere uno dei seguenti valori:

  • always: CloudFront firma tutte le richieste di origine, sovrascrivendo l'intestazione Authorization dalla richiesta del visualizzatore, se esistente.

  • never: CloudFront non firma alcuna richiesta di origine. Questo valore disattiva il controllo di accesso origine per l’origine.

  • no-override: se la richiesta visualizzatore non contiene l’intestazione Authorization, CloudFront firma la richiesta origine. Se la richiesta visualizzatore contiene l’intestazione Authorization, CloudFront non firma la richiesta origine e invece trasmette l’intestazione Authorization dalla richiesta visualizzatore.

    avvertimento

    Per trasmettere l’intestazione Authorization dalla richiesta visualizzatore, è necessario aggiungerla a una policy di richiesta origine per tutti i comportamenti cache che utilizzano origini associate a questo controllo di accesso origine. Per ulteriori informazioni, consulta Controllo delle richieste di origine con una policy.

signingProtocol (richiesto se abilitato)

Il protocollo di firma dell’OAC, che determina il modo in cui CloudFront firma (autentica) le richieste. L'unico valore valido è sigv4.

originType (richiesto se abilitato)

Il tipo di origine per questo OAC. I valori validi includono s3, mediapackagev2, mediastore e lambda.

timeout (facoltativo)

Timeout che è possibile specificare per indicare per quanto tempo CloudFront deve attendere la risposta delle origini o l’invio dei dati. Se questo non viene fornito, vengono utilizzate le impostazioni di timeout dell’origine assegnata.

Nota

Se non diversamente specificato, questi timeout supportano sia origini personalizzate che origini Amazon S3.

readTimeout (facoltativo)

readTimeout si applica a entrambi i seguenti valori:

  • Quanto tempo (in secondi) CloudFront attende la risposta dopo l'inoltro di una richiesta all'origine.

  • Quanto tempo (in secondi) CloudFront attende dopo aver ricevuto un pacchetto di una risposta dall'origine e prima di ricevere il pacchetto successivo.

Il timeout minimo è di 1 secondo e quello massimo è di 120 secondi. Per ulteriori informazioni, consulta Timeout di risposta.

responseCompletionTimeout (facoltativo)

Il tempo (in secondi) durante il quale una richiesta da CloudFront all’origine può rimanere aperta in attesa di una risposta. Se entro questo tempo non viene ricevuta una risposta completa dall’origine, CloudFront interrompe la connessione.

Il valore per responseCompletionTimeout deve essere maggiore o uguale al valore per readTimeout. Per ulteriori informazioni, consulta Timeout completamento risposta.

keepAliveTimeout (facoltativo)

Questo timeout si applica solo alle origini personalizzate, non alle origini Amazon S3. Le configurazioni di origine S3 ignoreranno queste impostazioni.

keepAliveTimeout specifica per quanto tempo CloudFront deve tentare di mantenere la connessione all’origine dopo aver ricevuto l’ultimo pacchetto della risposta. Il timeout minimo è di 1 secondo e quello massimo è di 120 secondi. Per ulteriori informazioni, consulta Timeout keep-alive (solo origini personalizzate e VPC).

connectionTimeout (facoltativo)

Numero di secondi di attesa di CloudFront quando si tenta di stabilire una connessione all'origine. Il timeout minimo è di 1 secondo e quello massimo è di 10 secondi. Per ulteriori informazioni, consulta Timeout di connessione.

customOriginConfig (facoltativo)

Utilizza customOriginConfig per specificare le impostazioni di connessione per origini che non sono un bucket Amazon S3. C’è un’eccezione: puoi specificare queste impostazioni se il bucket S3 è configurato con hosting di siti web statici. Altri tipi di configurazioni di bucket S3 ignoreranno queste impostazioni. Se customOriginConfig non viene fornito, vengono utilizzate le impostazioni dell’origine assegnata.

port (obbligatorio)

La porta HTTP utilizzata da CloudFront per connettersi all'origine. La porta HTTP sulla quale l'origine è in ascolto.

protocol (obbligatorio)

Specifica il protocollo (HTTP o HTTPS) utilizzato da CloudFront per connettersi all'origine. I valori validi sono:

  • http: CloudFront utilizza sempre HTTP per connettersi all’origine.

  • https: CloudFront utilizza sempre HTTPS per connettersi all’origine.

sslProtocols (obbligatorio)

Un elenco che specifica il protocollo SSL/TLS minimo utilizzato da CloudFront per la connessione all’origine tramite HTTPS. I valori validi includono SSLv3, TLSv1, TLSv1.1 e TLSv1.2. Per ulteriori informazioni, consulta Protocollo SSL di origine minimo.

ipAddressType (facoltativo)

Specifica il tipo di indirizzo IP utilizzato da CloudFront per connettersi all’origine. I valori validi includono ipv4, ipv6 e dualstack. La modifica di ipAddressType è supportata solo quando viene modificata anche la proprietà domainName.

Esempio — Aggiornamento dell’origine richiesta Amazon S3

Nell’esempio seguente viene modificata l’origine della richiesta visualizzatore in un bucket S3, abilitato OAC e ripristinate le intestazioni personalizzate inviate all’origine.

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": {}
});
Esempio — Aggiornamento dell’origine richiesta di Application Load Balancer

Nell’esempio seguente viene modificata l’origine della richiesta visualizzatore in un’origine Application Load Balancer e impostata un’intestazione e timeout personalizzati.

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"
    }
});
Esempio — Aggiornamento dell’origine con Origin Shield abilitato

Nell’esempio seguente, Origin Shield è abilitato nell’origine della distribuzione. Il codice funzione aggiorna solo il nome di dominio utilizzato per l’origine e omette tutti gli altri parametri opzionali. In questo caso, Origin Shield continuerà a essere utilizzato con il nome di dominio di origine modificato poiché i parametri di Origin Shield non sono stati aggiornati.

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

Metodo selectRequestOriginById()

Utilizza selectRequestOriginById() per aggiornare un’origine esistente selezionando un’origine diversa già configurata nella distribuzione. Questo metodo utilizza tutte le stesse impostazioni definite dall’origine aggiornata.

Questo metodo accetta solo origini già definite nella stessa distribuzione utilizzata durante l’esecuzione della funzione. Le origini sono identificate dall’ID origine, ovvero il nome origine definito durante la configurazione dell’origine.

Se nella distribuzione è configurata un’origine VPC, puoi utilizzare questo metodo per aggiornare l’origine all’origine VPC. Per ulteriori informazioni, consulta Limitazione dell’accesso con VPC Origins.

Richiesta

selectRequestOriginById(origin_id)

Nell’esempio precedente, origin_id è una stringa che punta al nome dell’origine nella distribuzione che esegue la funzione.

Esempio — Selezione dell’origine della richiesta Amazon S3

Nell’esempio seguente viene selezionata l’origine denominata amzn-s3-demo-bucket-in-us-east-1 dall’elenco delle origini associate alla distribuzione e applicate le impostazioni di configurazione dell’origine amzn-s3-demo-bucket-in-us-east-1 alla richiesta.

cf.selectRequestOriginById("amzn-s3-demo-bucket-in-us-east-1");
Esempio — Selezione dell’origine della richiesta Application Load Balancer

Nell’esempio seguente viene selezionata un’origine Application Load Balancer denominata myALB-prod dall’elenco delle origini associate alla distribuzione e applicate le impostazioni di configurazione di myALB-prod alla richiesta.

cf.selectRequestOriginById("myALB-prod");

Metodo createRequestOriginGroup()

Utilizza createRequestOriginGroup() per definire due origini da utilizzare come gruppo di origine per il failover in scenari che richiedono un’elevata disponibilità.

Un gruppo di origine include due origini (una primaria e una secondaria) e un criterio di failover specificato. Un gruppo di origini viene creato per supportare il failover dell'origine in CloudFront. Quando si crea o si aggiorna un gruppo di origine utilizzando questo metodo, puoi il gruppo di origini invece di una singola origine. CloudFront eseguirà il failover dall’origine primaria all’origine secondaria, utilizzando i criteri di failover.

Se nella distribuzione è configurata un’origine VPC, puoi utilizzare questo metodo per creare un gruppo di origini utilizzando un’origine VPC. Per ulteriori informazioni, consulta Limitazione dell’accesso con VPC Origins.

Richiesta

createRequestOriginGroup({origin_group_properties})

Nell’esempio precedente, origin_group_properties può contenere quanto segue:

originIds (obbligatorio)

Array di origin_ids, dove origin_id è una stringa che punta al nome di origine di un’origine nella distribuzione che esegue la funzione. È necessario fornire due origini come parte dell’array. La prima origine nell’elenco è l’origine primaria, mentre la seconda funge da origine secondaria per il failover.

selectionCriteria (facoltativo)

Scegli se utilizzare i criteri di failover di origine default o la logica di failover basata su media-quality-score. I valori validi sono:

  • default utilizza i criteri di failover, in base ai codici di stato specificati in failoverCriteria. Se non si imposta selectionCriteria nella funzione, verrà utilizzato default.

  • media-quality-score viene utilizzato quando è attiva la funzionalità di instradamento sensibile ai contenuti multimediali.

failoverCriteria (obbligatorio)

Un array di codici di stato che, quando vengono restituiti dall’origine primaria, attivano il failover di CloudFront all’origine secondaria. Se si sovrascrive un gruppo di origine esistente, questo array sovrascriverà tutti i codici di stato di failover impostati nella configurazione originale del gruppo di origine.

Quando utilizzi media-quality-score selectionCriteria, CloudFront tenterà di instradare le richieste in base al punteggio di qualità multimediale. Se l’origine selezionata restituisce un codice di errore impostato in questo array, CloudFront eseguirà il failover sull’altra origine.

Esempio — Creazione del gruppo di origini della richiesta

Nell’esempio seguente viene creato un gruppo di origine per una richiesta utilizzando gli ID di origine. Questi ID di origine provengono dalla configurazione del gruppo di origine per la distribuzione utilizzata per eseguire questa funzione.

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