Metodi di supporto per la modifica dell'origine - Amazon CloudFront
Scegli tra CloudFront Functions e Lambda @EdgeupdateRequestOriginmetodo ()selectRequestOriginByIdmetodo ()createRequestOriginMetodo Group ()

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Metodi di supporto per la modifica dell'origine

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

Per utilizzare questo modulo, create una CloudFront funzione utilizzando JavaScript runtime 2.0 e includete la seguente dichiarazione nella prima riga del codice della funzione:

import cf from 'cloudfront';

Per ulteriori informazioni, consulta JavaScript funzionalità di runtime 2.0 per CloudFront Functions.

Nota

Le pagine Test API e Test console non verificano se è avvenuta una modifica dell'origine. Tuttavia, il test garantisce che il codice della funzione venga eseguito senza errori.

Scegli tra CloudFront Functions e Lambda @Edge

Puoi aggiornare le tue origini utilizzando CloudFront Functions o Lambda @Edge.

Quando si utilizza CloudFront Functions per aggiornare le origini, si utilizza il trigger dell'evento Viewer Request, 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 di origine, il che significa che questa logica viene eseguita solo in caso di errori nella cache.

La scelta dipende in gran parte dal carico di lavoro e dall'eventuale utilizzo esistente di CloudFront Functions e Lambda @Edge nelle distribuzioni. Le seguenti considerazioni possono aiutarti a decidere se utilizzare CloudFront Functions o Lambda @Edge per aggiornare le tue origini.

CloudFront Functions è particolarmente utile nelle seguenti situazioni:

  • Quando le tue richieste sono dinamiche (il che significa che non possono essere memorizzate nella cache) e andranno sempre all'origine. CloudFront Functions offre prestazioni migliori e costi complessivi inferiori.

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

Per utilizzare CloudFront Functions per aggiornare le origini, consultate i metodi di supporto nei seguenti argomenti.

Lambda @Edge è particolarmente utile nelle seguenti situazioni:

  • Quando si dispone di contenuti altamente memorizzabili nella cache, Lambda @Edge può essere più efficiente in termini di costi perché viene eseguito solo in caso di errori di cache, mentre Functions viene eseguito su ogni richiesta. CloudFront

  • Se disponi già di una funzione Lambda @Edge della richiesta di 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 fonti di dati di terze parti, come Amazon DynamoDB o Amazon S3.

Per ulteriori informazioni su Lambda @Edge, consulta. Personalizzazione all'avanguardia con Lambda @Edge

updateRequestOriginmetodo ()

Utilizzate il updateRequestOrigin() metodo per aggiornare le impostazioni di origine per una richiesta. È possibile 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, specificate le proprietà che desiderate modificare.

Importante

Tutte le impostazioni che non specificate nella updateRequestOrigin() erediteranno le stesse impostazioni dalla configurazione dell'origine esistente.

L'origine impostata dal updateRequestOrigin() metodo 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 verso l'origine secondaria.

  • Se state modificando il tipo di origine e avete abilitato l'OAC, assicuratevi che il tipo di origine in originAccessControlConfig corrisponda al nuovo tipo di origine.

  • Non puoi utilizzare il updateRequestOrigin() metodo per aggiornare le origini del VPC. La richiesta avrà esito negativo.

Richiesta

updateRequestOrigin({origin properties})

La origin properties lattina può contenere quanto segue:

DomainName (opzionale)

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

Per origini personalizzate

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

Per le origini di S3

Specificare 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 (opzionale)

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

Per origini personalizzate

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

CustomHeaders (opzionale)

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. Utilizzate la seguente sintassi della coppia chiave-valore:

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

Non puoi aggiungere intestazioni non consentite e un'intestazione con lo stesso nome non può essere presente anche nella richiesta in arrivo. headers Il nome dell'intestazione deve essere minuscolo nel codice della funzione. Quando CloudFront Functions riconverte 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 di funzione aggiunge un'intestazione denominataexample-header-name, la CloudFront converte in nella richiesta HTTP. Example-Header-Name Per ulteriori informazioni, consultare Intestazioni personalizzate che non CloudFront possono essere aggiunte alle richieste di origine e Restrizioni sulle funzioni edge.

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

Tentativi di connessione (opzionale)

Il numero di volte che CloudFront tenta di connettersi all'origine. Il minimo è 1 e il massimo è 3. Se ciò non viene fornito, vengono utilizzati i tentativi di connessione dall'origine assegnata.

OriginShield (opzionale)

Ciò 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 Amazon CloudFront Origin Shield. Se ciò non viene fornito, vengono utilizzate le impostazioni Origin Shield dell'origine assegnata.

abilitato (richiesto)

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

regione (richiesta se abilitata)

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

Quando abiliti CloudFront Origin Shield, devi specificare Regione AWS il nome. Per un elenco delle regioni disponibili Regioni AWS e assistenza nella scelta della regione migliore per la tua origine, consultaScelta della AWS regione per Origin Shield.

originAccessControlConfig (opzionale)

L'identificatore univoco di un controllo di accesso all'origine (OAC) per questa origine. Viene utilizzato solo quando l'origine supporta un CloudFront OAC, come Amazon S3, la URLs funzione MediaStore Lambda e V2. MediaPackage Se ciò non viene fornito, vengono utilizzate le impostazioni OAC dell'origine assegnata.

Ciò non supporta la legacy Origin Access Identity (OAI). Per ulteriori informazioni, consulta Limita l'accesso a un' AWS origine.

abilitato (richiesto)

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

SigningBehavior (obbligatorio se abilitato)

Specifica a quali richieste CloudFront firma (aggiunge le 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'Authorizationintestazione della richiesta del visualizzatore, se ne esiste una.

  • never— CloudFront non firma alcuna richiesta di origine. Questo valore disattiva il controllo dell'accesso all'origine per l'origine.

  • no-override— Se la richiesta del visualizzatore non contiene l'Authorizationintestazione, CloudFront firma la richiesta di origine. Se la richiesta del visualizzatore contiene l'Authorizationintestazione, CloudFront non firma la richiesta di origine e trasmette invece l'Authorizationintestazione della richiesta del visualizzatore.

    avvertimento

    Per trasmettere l'Authorizationintestazione della richiesta del visualizzatore, devi aggiungerla a una policy di richiesta di origine per tutti i comportamenti della cache che utilizzano le origini associate a questo controllo di accesso di origine. Per ulteriori informazioni, consulta Controlla le 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 (opzionale)

I timeout che puoi specificare per quanto tempo CloudFront devono cercare di attendere che le origini rispondano o inviino dati. Se questo non viene fornito, vengono utilizzate le impostazioni di timeout dell'origine assegnata.

ReadTimeout (opzionale)

I timeout si applicano solo alle origini personalizzate, non alle origini Amazon S3. (Le configurazioni di origine S3 ignoreranno queste impostazioni.) readTimeoutsi applica a entrambi i seguenti valori:

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

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

Il timeout minimo è di 1 secondo e il massimo è di 60 secondi. Per ulteriori informazioni, consulta Timeout di risposta (solo origini personalizzate e VPC).

keepAliveTimeout (facoltativo)

I timeout si applicano solo alle origini personalizzate, non alle origini Amazon S3. (Le configurazioni di origine S3 ignoreranno queste impostazioni.) keepAliveTimeoutspecifica per quanto tempo CloudFront deve cercare di mantenere la connessione all'origine dopo aver ricevuto l'ultimo pacchetto della risposta. Il timeout minimo è di 1 secondo e il massimo è di 60 secondi. Per ulteriori informazioni, consulta Timeout Keep-alive (solo origini personalizzate e VPC).

ConnectionTimeout (opzionale)

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

customOriginConfig (facoltativo)

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

porta (richiesta)

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

protocollo (richiesto)

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

  • http— utilizza CloudFront sempre HTTP per connettersi all'origine

  • https— utilizza CloudFront sempre HTTPS per connettersi all'origine

SSLProtocols (richiesto)

Un elenco che specifica il protocollo SSL/TLS minimo CloudFront utilizzato 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.

Esempio — Aggiornamento all'origine della richiesta Amazon S3

L'esempio seguente modifica l'origine della richiesta del visualizzatore in un bucket S3, abilita OAC e reimposta 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 all'origine della richiesta di Application Load Balancer

L'esempio seguente modifica l'origine della richiesta del visualizzatore in un'origine Application Load Balancer e imposta un'intestazione e dei 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 all'origine con Origin Shield abilitato

Nell'esempio seguente, l'origine della distribuzione ha Origin Shield abilitato. Il codice della funzione aggiorna solo il nome di dominio utilizzato per l'origine e omette tutti gli altri parametri opzionali. In questo caso, Origin Shield verrà comunque utilizzato con il nome di dominio di origine modificato perché i parametri Origin Shield non sono stati aggiornati.

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

selectRequestOriginByIdmetodo ()

selectRequestOriginById()Utilizzatelo 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 referenziate dall'ID di origine, che è il nome di origine definito durante la configurazione dell'origine.

Se hai un'origine VPC configurata nella tua distribuzione, puoi utilizzare questo metodo per aggiornare l'origine all'origine VPC. Per ulteriori informazioni, consulta Limita l'accesso con origini VPC.

Richiesta

selectRequestOriginById(origin_id)

Nell'esempio precedente, origin_id è una stringa che punta al nome di origine di un'origine nella distribuzione che esegue la funzione.

Esempio — Seleziona l'origine della richiesta Amazon S3

L'esempio seguente seleziona l'origine denominata amzn-s3-demo-bucket-in-us-east-1 dall'elenco di origini associate alla distribuzione e applica le impostazioni di configurazione dell'amzn-s3-demo-bucket-in-us-east-1origine alla richiesta.

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

L'esempio seguente seleziona un'origine Application Load Balancer myALB-prod denominata dall'elenco di origini associate alla distribuzione e applica le impostazioni myALB-prod di configurazione di alla richiesta.

cf.selectRequestOriginById("myALB-prod");

createRequestOriginMetodo Group ()

Viene utilizzato 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 principale e una secondaria) e un criterio di failover specificato dall'utente. Si crea un gruppo di origine per supportare il failover di origine in. CloudFront Quando si crea o si aggiorna un gruppo di origine utilizzando questo metodo, è possibile specificare il gruppo di origine anziché una singola origine. CloudFront eseguirà il failover dall'origine primaria all'origine secondaria, utilizzando i criteri di failover.

Se hai un'origine VPC configurata nella tua distribuzione, puoi utilizzare questo metodo per creare un gruppo di origine utilizzando un'origine VPC. Per ulteriori informazioni, consulta Limita l'accesso con origini VPC.

Richiesta

createRequestOriginGroup({origin_group_properties})

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

OriginIDs (obbligatorio)

Matrice diorigin_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 principale e la seconda funge da seconda origine ai fini del failover.

Criteri di selezione (opzionale)

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

  • defaultutilizza i criteri di failover, in base ai codici di stato specificati in. failoverCriteria Se non è selectionCriteria impostata la funzione, default verrà utilizzata.

  • media-quality-scoreviene utilizzato quando viene utilizzata la funzionalità di routing compatibile con i supporti multimediali.

FailoverCriteria (obbligatorio)

Una serie di codici di stato che, se restituiti dall'origine principale, CloudFront attivano il failover sull'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 si utilizza media-quality-scoreselectionCriteria, CloudFront tenterà di indirizzare 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 — Crea il gruppo di origine della richiesta

L'esempio seguente crea un gruppo di origine per una richiesta utilizzando l'origine IDs. Queste origini IDs 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] 
    }
});