Questa pagina è stata tradotta dall'API Cloud Translation.

Definire intestazioni personalizzate

Media CDN ti consente di specificare intestazioni di richiesta e risposta personalizzate.

Le intestazioni personalizzate ti consentono di:

Restituisce i dati geografici del cliente, ad esempio paese, regione o città, che puoi utilizzare per mostrare contenuti localizzati.
Determina se una risposta è stata generata dalla cache (in toto o in parte) e da quale posizione della cache.
Rimuovi, sostituisci o accoda le intestazioni di richiesta e risposta.

Puoi anche utilizzare le intestazioni per instradare le richieste a diverse origini. Se devi configurare le intestazioni CORS (Cross-Origin Resource Sharing), configura un regolamento CORS per ogni percorso.

Impostare intestazioni personalizzate

Le intestazioni vengono impostate su ogni route, il che ti consente di aggiungerle e rimuoverle per contenuti diversi, ad esempio manifest o segmenti video.

Imposta le intestazioni delle richieste personalizzate per route all'inizio del percorso di elaborazione della CDN, prima delle decisioni relative alla memorizzazione nella cache. Ad esempio, se imposti un'intestazione cache-control come intestazione personalizzata per percorso, influisce sul comportamento della memorizzazione nella CDN.

Per impostazione predefinita, i valori delle intestazioni aggiunti sono separati da virgole e aggiunti alle intestazioni di risposta o di richiesta con gli stessi nomi di campo.

Per sovrascrivere i valori esistenti, imposta replace su true.

L'esempio seguente di .routing.pathMatchers[].routeRules[].headerAction mostra le intestazioni aggiunte e rimosse in una risorsa EdgeCacheService:

gcloud edge-cache services describe prod-media-service

routeRules:
  - priority: 1
    description: "video routes"
    matchRules:
      - prefixMatch: "/video/"
    headerAction:
      responseHeadersToAdd:
        # Return the country (or region) associated with the client's IP address.
        - headerName: "client-geo"
          headerValue: "{client_region}"
          replace: true
      requestHeadersToAdd:
        # Inform the upstream origin server the request is from Media CDN
        - headerName: "x-downstream-cdn"
          headerValue: "Media CDN"
      responseHeadersToRemove:
        - headerName: "X-User-ID"
        - headerName: "X-Other-Internal-Header"

Questo esempio esegue le seguenti operazioni:

Aggiunge un'intestazione client-geo personalizzata alla risposta utilizzando la variabile {client_region}, che restituisce il paese (o la regione) associato all'indirizzo IP del client.
Aggiunge un'intestazione x-downstream-cdn personalizzata alla richiesta utilizzando una stringa statica.
Rimuove due intestazioni interne.

Per configurare intestazioni personalizzate specifiche per l'origine, consulta Configurare le riscritture dell'host o le modifiche dell'intestazione specifiche per l'origine.

Variabili di intestazione dinamiche

Le intestazioni personalizzate possono contenere una o più variabili dinamiche.

Le intestazioni delle richieste che fanno parte del criterio della chiave della cache (cacheKeyPolicy.includedHeaderNames) possono contenere una o più variabili personalizzate. Le intestazioni di richiesta che contengono altre variabili dinamiche non possono far parte della chiave della cache.

Variabile	Descrizione	Supportato per le intestazioni delle richieste	Supportato per le intestazioni delle richieste in una chiave cache	Supportato per le intestazioni di risposta
`cdn_cache_status`	Un elenco separato da virgole delle località (codice IATA dell'aeroporto più vicino) e degli stati di ciascun nodo della cache nel percorso richiesta/risposta, dove il valore più a destra rappresenta la cache più vicina all'utente.			✔
`client_city`	Il nome della città da cui ha avuto origine la richiesta, ad esempio `Mountain View` per Mountain View, California. Non esiste un elenco canonico di valori validi per questa variabile. I nomi delle città possono contenere lettere, numeri, spazi e i seguenti caratteri US-ASCII: !#$%&'*+-.^_`\|~.	✔		✔
`client_city_lat_long`	La latitudine e la longitudine della città da cui ha avuto origine la richiesta, ad esempio `37.386051,-122.083851` per una richiesta da Mountain View.	✔		✔
`client_region`	Il paese (o la regione) associato all'indirizzo IP del client. Si tratta di un codice regione CLDR Unicode, ad esempio `US` o `FR`. Per la maggior parte dei paesi, questi codici corrispondono direttamente ai codici ISO-3166-2.	✔	✔	✔
`client_region_subdivision`	La suddivisione, ad esempio la provincia o lo stato, del paese associato all'indirizzo IP del client. Si tratta di un ID suddivisione CLDR Unicode, ad esempio `USCA` o `CAON`. Questi codici Unicode derivano dalle suddivisioni definite dallo standard ISO-3166-2.	✔	✔	✔
`client_rtt_msec`	Il tempo di trasmissione di andata e ritorno stimato tra la CDN e il client HTTP(S), in millisecondi. Si tratta del parametro del tempo di round trip mediato (SRTT) misurato dallo stack TCP della CDN, come indicato nel RFC 2988.	✔		✔
`device_request_type`	Il tipo di dispositivo utilizzato dal cliente. Questi sono i valori validi: `DESKTOP`, `MOBILE`, `TABLET`, `SMART_TV`, `GAME_CONSOLE`, `WEARABLE` e `UNDETERMINED`.	✔	✔
`original_request_id`	L'identificatore univoco assegnato alla richiesta che ha generato inizialmente questa risposta. Deve essere compilato solo se è diverso da `request_id` per le risposte memorizzate nella cache.			✔
`origin_name`	La risorsa `EdgeCacheOrigin` da cui è stata eseguita la proxy della risposta.			✔
`origin_request_header`	Riflette il valore dell'intestazione Origin nella richiesta per i casi d'uso della condivisione delle risorse tra origini (CORS).			✔
`proxy_status`	Un elenco di proxy HTTP intermedi nel percorso di risposta. Il valore è definito dall'RFC 9209. Una risorsa `EdgeCacheService` è rappresentata da `Google-Edge-Cache`. Se la risposta è stata recuperata dall'origine, una risorsa `EdgeCacheOrigin` è rappresentata da `Google-Edge-Cache-Origin`.			✔
`tls_sni_hostname`	L'indicazione del nome del server (come definito nel RFC 6066), se fornito dal client durante il handshake TLS o QUIC. Il nome host viene convertito in minuscolo e i punti finali vengono rimossi.	✔		✔
`tls_version`	La versione TLS negoziata tra il client e il bilanciatore del carico durante l'handshake SSL. I valori possibili includono `TLSv1`, `TLSv1.1`, `TLSv1.2` e `TLSv1.3`. Se il client si connette utilizzando QUIC anziché TLS, il valore è QUIC.	✔		✔
`tls_cipher_suite`	La suite di crittografia negoziata durante l'handshake TLS. Il valore è definito dal registro delle suite di crittografia TLS dell'IANA, ad esempio `TLS_RSA_WITH_AES_128_GCM_SHA256`. Questo valore è vuoto per le connessioni client QUIC e non criptate.	✔		✔
`user_agent_family`	La famiglia di browser utilizzata dal cliente. Questi sono i valori validi: `APPLE`, `APPLEWEBKIT`, `BLACKBERRY`, `DOCOMO`, `GECKO`, `GOOGLE`, `KHTML`, `KOREAN`, `MICROSOFT`, `MSIE`, `NOKIA`, `NETFRONT`, `OBIGO`, `OPENWAVE`, `OPERA`, `OTHER`, `POLARIS`, `TELECA`, `SEMC`, `SMIT` e `USER_DEFINED`.	✔	✔

Le seguenti considerazioni si applicano alle variabili personalizzate:

Le intestazioni di richiesta e risposta esistenti vengono conservate, ad eccezione di quelle elencate di seguito, che vengono rimosse:
- X-User-IP
- Eventuali intestazioni con X-Google o X-GFE
Le chiavi e i valori delle intestazioni devono essere conformi al documento RFC 7230 e le forme obsolete non sono consentite.
Tutte le chiavi dell'intestazione sono in minuscolo (secondo HTTP/2).
Alcune intestazioni sono unite. Quando sono presenti più istanze della stessa chiave di intestazione (ad es. Via), il bilanciatore del carico combina i relativi valori in un unico elenco separato da virgole per una singola chiave di intestazione. Vengono unite solo le intestazioni cuyos valori possono essere rappresentati come elenco separato da virgole. Altre intestazioni, come Set-Cookie, non vengono mai unite.
Alcune intestazioni vengono aggiunte o vengono aggiunti valori. Media CDN aggiunge o modifica sempre determinate intestazioni, ad esempioVia e X-Forwarded-For.
Media CDN espande qualsiasi intestazione di risposta con una variabile supportata, anche se impostata dal client o dall'origine. In questo modo, oltre a configurare le intestazioni personalizzate, puoi impostare intestazioni dinamiche dal client (ad esempio un video player) o dall'infrastruttura di origine. Media CDN non espande le variabili nel percorso della richiesta.
Ad esempio, in base alle regole descritte in precedenza, le intestazioni X-Goog- e X-Amz- vengono conservate e scritte in minuscolo.

Valori dello stato della cache

La variabile di intestazione {cdn_cache_status} può restituire più valori corrispondente al livello della cache che ha fornito la risposta. Tieni conto delle seguenti linee guida per l'interpretazione della variabile di intestazione {cdn_cache_status}:

Se l'intestazione contiene hit, i contenuti richiesti sono stati recuperati dalla cache.
Se l'intestazione contiene miss, significa che i contenuti richiesti non sono stati trovati in un nodo della cache e hanno dovuto essere recuperati da un nodo a monte.
Se l'intestazione contiene fetch, i contenuti richiesti sono stati recuperati dall'origine.
Se l'intestazione contiene uncacheable, i contenuti richiesti sono stati considerati non memorizzabili nella cache da alcuni o tutti i componenti dell'infrastruttura di memorizzazione nella cache.
- Se l'intestazione contiene anche hit o miss, i contenuti richiesti sono stati considerati non memorizzabili nella cache da alcuni componenti della memorizzazione nella cache e memorizzabili nella cache da altri.
- Se l'intestazione non contiene anche hit o miss, i contenuti richiesti sono stati considerati non memorizzabili nella cache da tutti i componenti di memorizzazione nella cache e tutte le richieste di questi contenuti vengono recuperate dall'origine. Per assicurarti che i contenuti vengano memorizzati nella cache in modo appropriato, consulta i requisiti per le origini di Media CDN.

Intestazioni predefinite

Media CDN aggiunge le seguenti intestazioni di richiesta e risposta alle richieste di origine e alle risposte del client, rispettivamente.

Intestazione	Descrizione	Richiesta	Risposta
`x-request-id`	Un identificatore univoco per la richiesta specificata. Questo valore viene aggiunto anche al log delle richieste come `jsonPayload.requestId`, il che consente di correlare una richiesta/risposta del client a una voce di log.		✔
`age`	Restituisce l'età dell'oggetto memorizzato nella cache (numero di secondi trascorsi dalla memorizzazione nella cache). In genere, l'età viene calcolata in base al momento in cui l'oggetto è stato inizialmente memorizzato nella cache in una posizione della cache long-tail (shield). Le risposte senza un'intestazione `age` non vengono pubblicate dalla cache.		✔
`via`	Identifica Google come proxy intermedio. Questo valore è impostato su `1.1 google` e non può essere modificato.	✔	✔
`server`	È impostato su `Google-Edge-Cache`.		✔
`cdn-loop`	Identifica i loop, ad esempio quando l'host di origine è uguale all'host di elaborazione (edge) rivolto agli utenti. Un token `google` viene aggiunto all'intestazione come da RFC 8586. Il token non può essere modificato.	✔
`forwarded`	La versione strutturata dell'intestazione `x-forwarded-for`. L'intestazione `forwarded` è definita nel documento RFC 7239. Queste intestazioni ti consentono di identificare l'indirizzo IP del client in connessione quando nel percorso è presente un proxy (o più proxy). Ad esempio, se un client con indirizzo IP `192.0.2.60` si connette a Media CDN tramite HTTPS, l'intestazione `forwarded` viene compilata come segue: `forwarded: [for=192.0.2.60;proto=https]` In caso di più proxy lato client, il client che si è connesso alla Media CDN è l'ultimo indirizzo aggiunto nel valore dell'intestazione.	✔
`x-forwarded-for`	La versione non strutturata e standard di fatto dell'intestazione`forwarded`. In genere i valori sono separati da virgole. Entrambe le intestazioni vengono inviate in una richiesta per supportare le origini precedenti che potrebbero non essere a conoscenza dell'intestazione `forwarded`.	✔

Le chiavi delle intestazioni sono in minuscolo sia per le intestazioni di richiesta sia per quelle di risposta perché le chiavi delle intestazioni non fanno distinzione tra maiuscole e minuscole.

È possibile aggiungere altri intestazioni, tra cui la posizione del punto di presenza (PoP) di confine e lo stato della cache (ad es. hit e miss), utilizzando le variabili di intestazione dinamica.