Configura le route del servizio

Media CDN offre funzionalità avanzate di routing HTTP che consentono di mappare il traffico a origini e configurazioni perimetrali specifiche a un livello granulare.

Configurare una regola di route

Configura una regola di routing per un servizio Media CDN.

Console

1. Nella console Google Cloud, vai alla pagina Media CDN.

   Vai a Media CDN

2. Per aprire la pagina Dettagli del servizio per cui vuoi configurare una regola di routing, fai clic sul nome del servizio.

3. Per passare alla modalità di modifica, fai clic sul pulsante Modifica.

4. Per andare alla sezione Routing (Inoltro), fai clic su Avanti.

5. Specifica almeno una regola host. Fai clic su Aggiungi regola host. Poi, procedi nel seguente modo:

   1. Per Host, specifica almeno un host per la corrispondenza.

   2. In Descrizione, fornisci una breve descrizione della regola host.

   In alternativa, per modificare una regola host, fai clic sulla freccia per espanderla.

6. Specifica almeno una regola di route. Fai clic su Aggiungi regola di percorso.

   In alternativa, per modificare una regola di routing, fai clic su Modifica nella riga corrispondente.

7. Nel riquadro Modifica regola di route, per Priorità, imposta un valore per la priorità del route.

8. In Descrizione, fornisci una breve descrizione che possa aiutare a identificare la regola in un elenco di regole.

9. Nella sezione Corrispondenza, specifica almeno una condizione di corrispondenza. Fai clic su Aggiungi una condizione di corrispondenza. Poi:

   1. In Tipo di corrispondenza, seleziona un'opzione di corrispondenza del percorso.

   2. Per Corrispondenza percorso, specifica i nomi, i percorsi o i modelli. Valuta la possibilità di utilizzare la corrispondenza di pattern con caratteri jolly.

      Se necessario, seleziona anche Attiva la distinzione tra maiuscole e minuscole per il valore del percorso.

   3. (Facoltativo) Seleziona Corrispondenza intestazioni e Corrispondenza parametri di query. Poi, fai clic sui pulsanti pertinenti per aggiungere intestazioni e parametri di ricerca. Per ogni parametro, specifica il nome, il tipo di corrispondenza e il valore.

      Per ulteriori informazioni, consulta Corrispondenza su intestazioni e parametri di query.

   4. Per salvare la condizione di corrispondenza, fai clic su Fine.

10. Per Azione principale, seleziona una delle seguenti opzioni:

    • Recupero da un'origine: per indirizzare le richieste a un'origine specifica, seleziona questa opzione e poi un'origine.

    • Reindirizzamento URL: per reindirizzare le richieste, seleziona questa opzione. Poi specifica il tipo di reindirizzamento, il percorso e il codice di stato.

      Se vuoi, seleziona le opzioni per reindirizzare tutte le risposte a HTTPS o per rimuovere la query.

11. Fai clic su Configurazioni avanzate.

    1. Nella sezione Azione intestazione, fai clic su Aggiungi un elemento.

       Seleziona un tipo di azione e poi specifica un'intestazione come coppia di nome e valore. Poi fai clic su Fine.

    2. Nella sezione Azione del percorso, fai clic su Aggiungi un elemento.

       Specifica un tipo di azione e le relative opzioni. Poi fai clic su Fine.

12. Per Filtro del metodo HTTP, seleziona Personalizza filtro del metodo HTTP.

    Quindi, seleziona i metodi HTTP da eseguire tramite proxy per l'origine.

13. Per salvare la regola di routing, fai clic su Salva.

14. Per salvare le modifiche apportate al servizio, fai clic su Aggiorna servizio.

gcloud e YAML

1. Esporta la configurazione Media CDN in un file YAML. Utilizza il comando gcloud edge-cache services export.

   gcloud edge-cache services export SERVICE_NAME \
       --destination=FILENAME.yaml
   

   Sostituisci quanto segue:

   • SERVICE_NAME: il nome del servizio
   • FILENAME : il nome del file YAML

2. Aggiorna il file YAML con la configurazione richiesta come descritto nelle sezioni di questa pagina.

3. Per aggiornare il servizio, importa la configurazione di Media CDN dal file YAML. Utilizza il comando gcloud edge-cache services import.

   gcloud edge-cache services import SERVICE_NAME \
       --source=FILENAME.yaml
   

Corrispondenza delle richieste

Una configurazione Media CDN contiene un insieme di route definiti nella sezione Routing per una risorsa EdgeCacheService. Questi percorsi corrispondono alle richieste in base a (almeno) un host. Per ulteriori dettagli su come viene indirizzato il traffico a un'origine, consulta HostRule e PathMatcher. Ogni route è in grado di definire la propria configurazione CDN, le riscritture, i reindirizzamenti, i criteri CORS, le intestazioni HTTP personalizzate e la mappatura delle origini. Le route possono condividere le origini.

Ad esempio, puoi indirizzare le richieste dei manifest a un'origine specifica e definire un TTL della cache di breve durata e un criterio di memorizzazione nella cache negativa. Le richieste di segmenti possono essere suddivise in un'altra origine utilizzando intestazioni e parametri di query per suddividere utenti o tipi di manifest specifici.

L'esempio seguente mostra come instradare le richieste che corrispondono a un'intestazione, un parametro di query e un prefisso del percorso specifici per l'host media.example.com:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 10
      origin: staging-live-origin
      matchRules:
      - prefixMatch: /vod/
        headerMatches:
        - headerName: "x-staging-client"
          presentMatch: true
        queryParameterMatches:
        - name: "live"
          exactMatch: "yes"
      routeAction:
        cdnPolicy:
          defaultTtl: 5s

Corrispondenza percorso

Media CDN supporta la corrispondenza completa (esatta), con prefisso e con caratteri jolly. La corrispondenza dei percorsi può essere combinata con la corrispondenza basata su host, intestazioni e parametri di query per creare regole di routing delle richieste granulari.

Di seguito sono riportati tre modi per eseguire la corrispondenza in base al percorso dell'URL.

Campo	Descrizione	Esempio
matchRules[].fullPathMatch	La condizione fullPathMatch corrisponde al percorso dell'URL completo, che non include la stringa di query. Devi specificare le barre diagonali finali, se pertinenti.	Un percorso con una regola di corrispondenza fullPathMatch: "/stream/" corrisponde a /stream/, ma non a /stream o /stream/us/hls/1234.ts. Un fullPathMatch è una corrispondenza esplicita (esatta).
matchRules[].prefixMatch	La condizione prefixMatch corrisponde al prefisso del percorso dell'URL; gli URL che iniziano con la stessa stringa corrispondono.	Un route con una regola di corrispondenza prefixMatch: "/videos/" corrisponde sia a /videos/hls/58481314/manifest.m3u8 sia a /videos/dash perché entrambi contengono il prefisso /videos/.
matchRules[].pathTemplateMatch	La condizione pathTemplateMatch supporta gli operatori di caratteri jolly, che ti consentono di associare pattern URL e segmenti di percorso complessi, nonché di acquisire variabili denominate per la riscrittura degli URL.	Un route con una regola di corrispondenza di pathTemplateMatch: "/**.m3u8" corrisponde a qualsiasi percorso dell'URL che termina con .m3u8. Sia /content/en-GB/13/51491/manifest_193193.m3u8 sia /p/abc/1234/manifest_1080p5000.m3u8 corrispondono a questo pattern. Per altri esempi, consulta la sezione sulla corrispondenza dei pattern.

Per ulteriori dettagli, consulta la specifica dell'API per MatchRule.

Attenzione: un percorso deve avere un matchRule con esattamente uno dei valori prefixMatch, fullPathMatch o pathTemplateMatch definito. Se non includi uno di questi campi, l'API restituisce un errore.

Ad esempio, per trovare una corrispondenza per tutte le richieste che iniziano con /stream/, crea una regola di routing simile alla seguente:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    - *.vod.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      matchRules:
      - prefixMatch: /stream/

Questo esempio include esplicitamente la barra finale nella regola di corrispondenza:

• Una richiesta a media.example.com/stream/id/1234/hls/manifest.m3u8 corrisponde a questo percorso.
• Una richiesta a media.example.com/stream-eu/id/4567/hls/manifest.m3u8 non corrisponde a questo percorso.

Nel secondo caso, Media CDN restituisce un errore HTTP 404, a meno che non sia stato configurato un altro percorso o un percorso generico.

Per indicazioni su come funziona la precedenza per le route con prefissi simili, consulta la sezione Ordinamento e priorità route.

Corrispondenza di pattern (caratteri jolly)

La corrispondenza dei pattern consente di abbinare più parti di un URL, compresi gli URL parziali e i suffissi (estensioni dei file), utilizzando una sintassi con caratteri jolly.

Puoi anche associare uno o più segmenti di percorso a variabili denominate in un pathTemplateMatch campo e poi fare riferimento a queste variabili quando riscrivi l'URL in un campo pathTemplateRewrite. In questo modo puoi riordinare e rimuovere i segmenti di URL prima che la richiesta venga inviata all'origine.

L'esempio seguente mostra come puoi trovare una corrispondenza su due diversi suffissi URL:

# EdgeCacheService.routing.pathMatchers[]
    routeRules:
    - priority: 1
      description: "Match video segments"
      matchRules:
      - pathTemplateMatch: "/**.ts"
      - pathTemplateMatch: "/**.m4s"
      origin: prod-video-storage

La sintassi supportata include quanto segue.

Operatore	Corrisponde a	Esempio
*	Corrisponde a un singolo segmento di percorso, fino al separatore di percorso successivo: /	/videos/*/*/*.m4s corrispondenze /videos/123414/hls/1080p5000_00001.m4s.
**	Corrisponde a zero o più segmenti di percorso. Se presente, deve essere l'ultimo operatore.	/**.mpd corrispondenze /content/123/india/dash/55/manifest.mpd.
{name} or {name=*}	Una variabile denominata corrispondente a un segmento di percorso. Corrisponde a un singolo segmento di percorso, fino al separatore di percorso successivo: /.	/content/{format}/{lang}/{id}/{file}.vtt corrisponde a /content/hls/en-us/12345/en_193913.vtt e acquisisce format="hls", lang="en-us", id="12345" e file="en_193913" come variabili.
{name=videos/*}	Una variabile denominata che corrisponde a più di un segmento di percorso. Il segmento del percorso corrispondente a videos/* viene acquisito come variabile denominata.	/videos/{language=lang/*}/* corrisponde /videos/lang/en/video.m4s e compila la variabile di percorso language con il valore lang/en.
{name=**}	Una variabile denominata che corrisponde a zero o più segmenti di percorso. Se presente, deve essere l'ultimo operatore.	/**.m3u8 o /{path=**}.m3u8 corrisponde a tutti i segmenti del percorso fino all'estensione. /videos/{file=**} corrisponde /videos/en-GB/def566/manifest.m3u8, inclusa l'estensione, e acquisisce la variabile percorso file="en-GB/def566/manifest.m3u8.

Note:

• Se non stai riscrivendo un URL, utilizza gli operatori * e ** più semplici.
• Quando utilizzi le variabili per acquisire i segmenti di percorso, non è possibile fare riferimento alle parti dell'URL che non vengono acquisite da una variabile in un pathTemplateRewrite successivo. Per un esempio, consulta la sezione relativa alla acquisizione delle variabili di percorso.
• Non puoi fare riferimento a variabili in un pathTemplateRewrite successivo che non esistono nel pathTemplateMatch nello stesso percorso.
• Le variabili sono sensibili alle maiuscole, con {FORMAT}, {forMAT} e {format} che rappresentano variabili e valori diversi.
• Puoi specificare fino a 10 operatori (sostituzioni o variabili) in una corrispondenza. I campi pathTemplateMatch e pathTemplateRewrite non devono superare i 255 caratteri.

Esempio: corrispondenza per estensione del file

L'esempio seguente mostra un caso d'uso comune per gli operatori di caratteri jolly: corrispondenza di tutti i segmenti del percorso fino a un suffisso.

In questo caso, svolgi le seguenti operazioni:

• Recupera i manifest video (playlist) che terminano con .m3u8 e .mpd dall'origine del manifest, applicando un TTL breve (5 secondi) a queste risposte perché cambiano regolarmente.
• Recupera i segmenti video che terminano con .ts e .m4s dall'origine del segmento e applica un TTL più lungo (1 giorno) a queste risposte.

Questo approccio viene spesso utilizzato quando si utilizzano servizi SSAI (Server-Side Ad Injection) o DAI (Dynamic Ad Insertion) e per i video dal vivo in cui il manifest viene aggiornato ogni pochi secondi.

La seguente configurazione mostra come configurare il routing Media CDN per supportare questa operazione:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    # the first route only matches video manifests
    - priority: 1
      matchRules:
      - pathTemplateMatch: "/**.m3u8" # "**" matches all path segments
      - pathTemplateMatch: "/**.mpd"
      origin: manifest-origin
      routeAction:
        cdnPolicy:
          cacheMode: FORCE_CACHE_ALL
          defaultTtl: 5s
    # the second route matches video segments, fetches them
    # from a separate origin server, caching them for a longer
    # duration (1 day).
    - priority: 2
      matchRules:
      - pathTemplateMatch: "/**.ts"
      - pathTemplateMatch: "/**.m4s"
      origin: segment-origin
      routeAction:
        cdnPolicy:
          cacheMode: FORCE_CACHE_ALL
          defaultTtl: 86400s

Esempio: acquisire le variabili di percorso

L'esempio seguente mostra come utilizzare le variabili con nome per descrivere uno o più segmenti di percorso.

Queste variabili possono essere utilizzate in un pathTemplateRewrite per riscrivire il percorso prima che la richiesta venga inviata all'origine o per creare un pathTemplateMatch complesso autodescrittivo.

routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      matchRules:
      # Matches a request of "/us/en/hls/123139139/segments/00001.ts"
      - pathTemplateMatch: "/{country}/{lang}/{format}/{id}/{file=**}"
      origin: my-origin
      routeAction:
        urlRewrite:
          # Rewrites to "/123139139/hls/segments/00001.ts"
          pathTemplateRewrite: "/{id}/{format}/{file}"

In particolare:

• Ogni variabile {name} acquisisce un singolo segmento di percorso. Un segmento di percorso è costituito da tutti i caratteri tra una coppia di / ("barre") in un percorso dell'URL.
• Una variabile {name=**} acquisisce tutti i segmenti di percorso rimanenti. In questo caso, corrisponde sia a segments/00001.ts che a master.m3u8.
• In pathTemplateRewrite sulla stessa strada, fai riferimento a alcune delle variabili acquisite in pathTemplateMatch. Ometti esplicitamente le variabili {country} e {lang} perché non corrispondono alla struttura della directory nell'origine.

In questo esempio si verifica quanto segue:

• Un URL di richiesta in arrivo di /us/en/hls/123139139/segment_00001.ts corrisponde pathTemplateMatch e viene riscritto in /123139139/hls/segment_00001.ts prima di essere inviato all'origine.
• Un URL di richiesta in entrata /us/123139139/master.m3u8 non corrisponde a pathTemplateMatch e riceve una risposta HTTP 404 (Not Found).
• Un URL di richiesta in arrivo di /br/es/dash/c966cbbe6ae3/subtitle_00001.vtt corrisponde anche a pathTemplateMatch e viene riscritto in /c966cbbe6ae3/dash/subtitle_00001.vtt prima di essere inviato all'origine.

Per scoprire di più su come la corrispondenza con caratteri jolly interagisce con la riscrittura dell'URL, consulta la sezione Riscrivi.

Corrispondenza host

Ogni servizio può corrispondere a più nomi host, con ogni insieme di nomi host contenente il proprio gruppo di route (noti come corrispondimenti di percorso). Nella maggior parte dei casi, tutti i nomi host di un servizio vengono mappati a un unico insieme di route con un unico elenco di host e un unico matcher di percorso.

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    - *.vod.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    # list of routes for the configured hosts
    - priority: 999
      matchRules:
      - prefixMatch: /
      origin: DEFAULT_ORIGIN

Agli host che non corrispondono viene mostrata una pagina 404 HTTP predefinita. Per accettare qualsiasi host, puoi includere il carattere jolly * come voce hostRules[].hosts[].

Puoi anche definire gruppi di percorsi (ad esempio raggruppandoli per paese o per contenuti dal vivo/su richiesta). Poiché ogni servizio ha un unico criterio di sicurezza, in genere consigliamo di avere un servizio per ogni mercato (geografia) o carico di lavoro.

Note:

• Le intestazioni host (o :authority HTTP/2) che contengono una porta vengono associate implicitamente a un host configurato. Non è necessario specificare esplicitamente le porte.
• Se la richiesta avviene tramite HTTP, una voce hostRules[].hosts[] di *.vod.example.com corrisponde a us.vod.example.com e us.vod.example.com:80.
• Se la richiesta avviene tramite HTTPS (TLS), una voce hostRules[].hosts[] di *.vod.example.com corrisponde a us.vod.example.com:443.

Per ulteriori dettagli, consulta la specifica dell'API per HostRule.

Corrispondenza per intestazioni e parametri di ricerca

Puoi configurare i percorsi in modo che corrispondano a nomi di intestazioni e parametri di query specifici, nonché alla presenza di un valore dell'intestazione (prefisso, suffisso o corrispondenza esatta).

La corrispondenza dei parametri di query e delle intestazioni è un "AND" logico: la richiesta deve corrispondere a tutti i parametri di ricerca e alle chiavi (e ai valori, se specificati) delle intestazioni per corrispondere al percorso specificato.

Ad esempio, se vuoi inoltrare le richieste con un nome e un valore di campo dell'intestazione specifici a un'origine denominata alternate-origin, configura le condizioni di corrispondenza in routeRules[].matchRules[].headerMatches[]:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: alternate-origin
      matchRules:
      - prefixMatch: "/videos/"
        headerMatches:
        - headerName: "x-device-name"
          exactMatch: "roku"

In questo esempio, le richieste con /videos/ all'inizio dell'URL e l'intestazione x-device-name: roku corrispondono a questo percorso. Le richieste che non contengono questo nome di intestazione o che hanno un valore diverso non corrispondono a questo percorso.

Nota: se hai route che corrispondono allo stesso percorso della richiesta con un valore priority superiore rispetto ai route che specificano condizioni di corrispondenza di intestazioni e parametri di query aggiuntive, i route con priority inferiore non corrispondono. Assicurati che i percorsi con condizioni di corrispondenza più specifiche abbiano un valore priority più alto (numero più piccolo).

Per ulteriori dettagli, consulta la specifica dell'API per HeaderMatch.

Analogamente, per la corrispondenza con parametri di ricerca, specifica uno o più queryParameterMatches come segue:

name: prod-service
routing:
  hostRules:
  - hosts:
    - media.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: eu-live-origin-prod
      matchRules:
      - prefixMatch: "/videos/"
        queryParameterMatches:
        - name: "playback_type"
          exactMatch: "live"
        - name: "geo"
          exactMatch: "eu"

In questo esempio, una richiesta del client di https://cdn.example.com/videos/1234/abcd/xyz.m3u8?playback_type=live&geo=eu corrisponde a questo percorso.

Per ulteriori dettagli, consulta la specifica dell'API per QueryParameterMatcher.

Definire un percorso catch-all (predefinito)

Per impostazione predefinita, Media CDN restituisce un errore HTTP 404 (Not Found) se una richiesta non corrisponde a nessuna route configurata.

Per configurare una route generica per un determinato pathMatcher (raccolta di route), procedi nel seguente modo:

• Crea un routeRule con la priorità più bassa (numero più alto), ad esempio 999, che è la priorità del route più bassa possibile.
• Configura un matchRule con una corrispondenza del prefisso / (corrisponde a tutti i percorsi delle richieste).
• Configura (uno di) un origin o un urlRedirect sul percorso.

Ad esempio, per configurare una route catch-all che indirizzi tutte le richieste non corrispondenti a un'origine predefinita denominata my-origin, crea una nuova route con priority: 999 e un matchRules[].prefixMatch di / come segue:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 999
      origin: my-origin
      matchRules:
      - prefixMatch: /

Se vuoi, puoi riscrivere l'URL prima del recupero dell'origine o reindirizzare a una pagina predefinita (ad esempio la pagina di destinazione) anziché inviare la richiesta "così com'è" all'origine.

Ordinamento e priorità route

Ogni percorso in un array di routeRules[] deve avere un priority associato.

Le route più specifiche devono essere impostate su una priorità più alta (numero inferiore). Una route che corrisponde a un prefisso /stream/ con una priorità 1 impedisce altrimenti a una route più specifica di /stream/live/eu/ con una priorità 5 di corrispondere a qualsiasi richiesta.

• La route con la priorità più alta è "1" e quella con la priorità più bassa è "999".
• Non puoi configurare due o più routeRules con la stessa priorità. La priorità per ogni regola deve essere impostata su un numero compreso tra 1 e 999 inclusi.
• La definizione di un percorso catch-all ti consente di inviare tutte le richieste non corrispondenti a un'origine predefinita o di reindirizzarle a una pagina di destinazione o a un endpoint.

Nell'esempio seguente, puoi vedere che la route /live/us/ non verrà mai associata perché la route /live/ ha una priorità più alta:

routeRules:
- priority: 1
  description: "Live routes"
  matchRules:
  - prefixMatch: /live/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 2
  description: "U.S based live streams"
  matchRules:
  # This would never be matched, as the /live/ prefixMatch at priority 1
  # would always take precedence.
  - prefixMatch: /live/us/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 999
  description: "Catch-all route"
  matchRules:
  - prefixMatch: /

Per risolvere il problema, assegna una priorità più alta al percorso più specifico (più lungo):

routeRules:
- priority: 1
  description: "U.S based live streams"
  matchRules:
  # The more specific (longer) match is at a higher priority, and now
  # matches requests as expected.
  - prefixMatch: /live/us/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 2
  description: "Live routes"
  matchRules:
  - prefixMatch: /live/
  routeAction:
    cdnPolicy:
      defaultTtl: 5s
- priority: 999
  description: "Catch-all route"
  matchRules:
  - prefixMatch: /

In questo modo, il percorso più specifico può corrispondere correttamente alle richieste. Una richiesta con prefisso /live/eu/ passerebbe comunque al percorso /live/ con priorità 2.

Filtro dei metodi

Per impostazione predefinita, Media CDN esegue il proxy solo dei metodi GET, HEAD e OPTIONS per l'origine e filtra i metodi che possono modificarla.

Puoi ignorare questo comportamento predefinito per una regola di routing specifica specificando i metodi di cui vuoi eseguire il proxy per l'origine. Oltre a GET, HEAD e OPTIONS, Media CDN supporta PUT, POST, DELETE e PATCH.

Per configurare il supporto di un insieme di metodi per una regola di percorso, specifica una sezione routeMethods con un valore allowed_methods per ogni metodo.

routeRules:
- priority: 5
  description: "Video uploads"
  routeMethods:
    allowedMethods: ["PUT", "POST", "OPTIONS"]
  matchRules:
  - pathTemplateMatch: "/uploads/**.ts"
  origin: prod-video-storage
- priority: 10
  description: "Video serving"
  routeMethods:
    allowedMethods: ["GET", "HEAD"]
  matchRules:
  - pathTemplateMatch: "/videos/**.ts"
  origin: prod-video-storage

Normalizzazione del percorso

La normalizzazione del percorso descrive in che modo Media CDN combina più rappresentazioni di un URL in un'unica rappresentazione canonica in scenari specifici.

La normalizzazione dei percorsi può migliorare direttamente le percentuali di successo della cache riducendo il numero di URL di richiesta che rappresentano gli stessi contenuti e mitigando gli errori di origine per le origini che si aspettano percorsi normalizzati.

Le richieste in arrivo vengono normalizzate come segue:

• Più barre consecutive vengono unite in un'unica barra. Ad esempio, un percorso URL di /videos///12345/manifest.mpd viene normalizzato in /videos/12345/manifest.mpd.
• I segmenti del percorso vengono normalizzati in base alla sezione 6.2.2.3 di RFC 3986. Ad esempio, il percorso /a/b/c/./../../g viene normalizzato in /a/g in base all'algoritmo "rimuovi segmenti con puntini" definito in RFC 3986. Questa normalizzazione avviene prima del controllo della cache o dell'inoltro della richiesta all'origine.
• Le richieste non sono normalizzate con la codifica percentuale. Ad esempio, un URL con un carattere barra codificato in percentuale (%2F) non viene decodificato nella forma non codificata.

Gli URL rimangono sensibili alle maiuscole e non vengono normalizzati alle maiuscole. Molti URL contengono codifica Base64 sensibile alle maiuscole, inclusi gli URL con token di richiesta firmata.

Riscritture e reindirizzamenti

Le sezioni seguenti forniscono esempi su come riscrivere le richieste e configurare i reindirizzamenti.

Riscrivere gli URL delle richieste

Media CDN supporta le riscritture di host e percorso. Le riscritture modificano l'URL inviato all'origine e ti consentono di modificare gli host e i percorsi in base alle tue esigenze. Le riscritture dell'host e del percorso si trovano a livello di route e ti consentono di definire quali richieste specifiche devono essere riscritte in base a qualsiasi comparatore, tra cui percorso, parametro di query e intestazione della richiesta.

Per ulteriori dettagli, consulta la specifica dell'API per RouteAction.UrlRewrite.

Di seguito sono riportati tre modi per riscrivere una richiesta:

Campo	Descrizione
urlRewrite.pathPrefixRewrite	Riscrivi il percorso rimuovendo il prefisso specificato in prefixMatch che corrispondeva alla richiesta. In una singola regola del percorso è possibile specificare solo uno tra pathPrefixRewrite o pathTemplateRewrite.
urlRewrite.pathTemplateRewrite	pathTemplateRewrite può essere utilizzato solo con una regola di corrispondenza pathTemplateMatch corrispondente nella stessa route. In una singola regola del percorso è possibile specificare solo uno tra pathPrefixRewrite o pathTemplateRewrite.
urlRewrite.hostRewrite	Riscrivi l'host prima che la richiesta venga inviata al server di origine.

Note:

• Gli URL riscritti non modificano la chiave della cache. La chiave della cache si basa sull'URL della richiesta inviato dal client.
• La riscrittura avviene dopo la corrispondenza della route e la convalida della richiesta firmata. I percorsi non vengono riassociati a un'altra regola di corrispondenza.

Esempio: rimuovere un prefisso di percorso

Ad esempio, per riscrivere un URL di richiesta del client da /vod/videos/hls/1234/abc.ts a /videos/hls/1234/abc.ts (rimuovendo /vod dal percorso), puoi utilizzare la funzionalità pathPrefixRewrite:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: my-origin
      matchRules:
      - prefixMatch: "/vod/videos/"
      routeAction:
        urlRewrite:
          pathPrefixRewrite: "/videos/"

Un pathPrefixRewrite funziona sostituendo l'intero prefisso del percorso corrispondente in matchRules[].prefixMatch con il valore di pathPrefixRewrite.

Per riscrivere un nome host (ad esempio cdn.example.com in my-bucket.s3.us-west-2.amazonaws.com), puoi configurare quanto segue:

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 1
      origin: my-origin
      matchRules:
      - prefixMatch: "/videos/"
      routeAction:
        urlRewrite:
          hostRewrite: "my-bucket.s3.us-west-2.amazonaws.com"

In questo caso, l'URL della richiesta di origine passerà da cdn.example.com/videos/* a my-bucket.s3.us-west-2.amazonaws.com/videos/*. Puoi anche combinare le riscritture dell'host e del percorso all'interno di un unico percorso.

Esempio: utilizzare le variabili per riscrivere gli URL

Per utilizzare pathTemplateMatch e pathTemplateRewrite per riscrivere parti di un URL della richiesta in entrata, consulta la sezione sulle variabili di acquisizione.

Richieste di reindirizzamento

Media CDN supporta tre tipi di reindirizzamenti:

• Reindirizzamenti dell'host, che reindirizzano solo l'host (dominio), mantenendo invariati il percorso e parametri di ricerca.
• Reindirizzamenti dei percorsi, che sostituiscono il percorso per intero.
• I reindirizzamenti dei prefissi dei percorsi, che sostituiscono solo il prefisso corrispondente.

Il valore predefinito dei reindirizzamenti è HTTP 301 (Moved Permanently), ma può essere configurato per restituire codici di stato di reindirizzamento diversi in base al percorso.

La seguente configurazione è un esempio di reindirizzamento basato su prefisso, in cui reindirizzi gli utenti che visitano https://cdn.example.com/on-demand/* a https://cdn.example.com/streaming/*.

name: prod-service
routing:
  hostRules:
  - hosts:
    - cdn.example.com
    pathMatcher: example_routes
  pathMatchers:
  - name: example_routes
    routeRules:
    - priority: 10
      matchRules:
      - prefixMatch: "/on-demand/"
      urlRedirect:
        # The prefix matched in matchRules.prefixMatch is replaced
        # by this value
        prefixRedirect: "/streaming/"
        redirectResponseCode: TEMPORARY_REDIRECT # corresponds to a HTTP 307

Questo esempio modifica anche il reindirizzamento in un reindirizzamento temporaneo, che impedisce ai client (ad esempio i browser) di memorizzarlo nella cache. Questa opzione può essere utile se prevedi di modificarla nel prossimo futuro.

I valori redirectResponseCode supportati sono riportati nella tabella seguente.

Codice di risposta reindirizzamento	Codice di stato HTTP
MOVED_PERMANENTLY_DEFAULT	HTTP 301 (Spostato definitivamente)
FOUND	HTTP 302 (Trovato)
SEE_OTHER	HTTP 303 (Vedi altro)
TEMPORARY_REDIRECT	HTTP 307 (Reindirizzamento temporaneo)
PERMANENT_REDIRECT	HTTP 308 (Reindirizzamento permanente)

Note:

• Un percorso può indirizzare il traffico a un'origine o restituire un reindirizzamento al client. Non puoi impostare contemporaneamente i campi origin e urlRedirect.
• I percorsi che reindirizzano a HTTPS richiedono che al servizio sia associato almeno un certificato SSL.

Per ulteriori dettagli, consulta la specifica dell'API per RouteRule.UrlRedirect.

Reindirizza tutte le richieste a HTTPS

Per reindirizzare tutte le richieste a HTTPS (anziché a HTTP), puoi configurare ciascuno dei tuoi servizi in modo che reindirizzi automaticamente tutte le richieste dei client a HTTPS. Ai client che si connettono tramite HTTP viene inviata una risposta 301 (Permanent Redirect) HTTP con l'intestazione Location impostata sullo stesso URL utilizzando "https://" anziché "http://".

gcloud

gcloud edge-cache services update MY_SERVICE \
    --require-tls

Request issued for: [MY_SERVICE]
Updated service [MY_SERVICE].

Il comando restituisce una descrizione del servizio, con requireTls impostato su true.

  name: MY_SERVICE
  requireTls: true

Nota: questa impostazione sostituisce le impostazionipathMatcher[].routeRules[].routeAction.urlRedirect.httpsRedirect per ogni percorso. Tutto il traffico viene reindirizzato a HTTP/HTTPS con un 301 (Permanent Redirect) codice di stato HTTP

.

Puoi anche scegliere di impostare l'intestazione Strict-Transport-Security come intestazione di risposta per indurre i client a connettersi sempre direttamente tramite HTTPS.

Utilizzare backend di archiviazione di terze parti

Media CDN supporta la connessione a endpoint HTTP accessibili pubblicamente esterni a Google Cloud, inclusi i bucket di archiviazione AWS S3, Azure Blob Storage e altri provider di archiviazione. Questa operazione può essere utile se hai un'architettura multicloud o se non hai ancora eseguito la migrazione dei dati in Cloud Storage utilizzando Storage Transfer Service.

Una configurazione dell'origine minima che configura un bucket ospitato virtuale in AWS S3:

name: MY_S3_ORIGIN
originAddress: BUCKET-NAME.s3.REGION.amazonaws.com

Se non utilizzi un nome del bucket che corrisponda ai nomi host configurati per le tue risorse EdgeCacheService, devi anche configurare una riscrittura dell'host per le route associate a questa o a queste origini. In caso contrario, l'intestazione Host impostata dalla richiesta del client viene utilizzata durante il recupero dall'origine.

Ad esempio, per mappare tutte le richieste con un prefisso del percorso /legacy/ al tuo bucket esterno, puoi configurare sia un hostRewrite sia un pathPrefixRewrite per rimuovere questo prefisso dalla richiesta di origine:

routeRules:
  - description: legacy backend
    matchRules:
    - prefixMatch: "/legacy/"
    routeAction:
      urlRewrite:
        hostRewrite: BUCKET-NAME.s3.REGION.amazonaws.com
        pathPrefixRewrite: /
      cdnPolicy:
        cacheMode: CACHE_ALL_STATIC
        defaultTtl: 3600s

Per ulteriori informazioni su come viene impostata l'intestazione host nelle richieste di origine, consulta la documentazione relativa alle intestazioni delle richieste di origine.

Condivisione delle risorse tra origini (CORS)

La condivisione delle risorse tra origini (CORS) è un approccio incentrato sul browser per effettuare in sicurezza richieste cross-origin. I criteri CORS ti consentono di impostare automaticamente le intestazioni CORS, ad esempioAccess-Control-Allow-Origins, in base a un criterio per route.

Configurare CORS

Media CDN ti consente di definire un criterio CORS su una route per un EdgeCacheService.

Un criterio CORS definisce queste regole con un insieme comune di intestazioni HTTP. Puoi impostare intestazioni CORS comuni nelle risposte, ad esempio Access-Control-Allow-Origin, Access-Control-Max-Age e Access-Control-Allow-Headers. Queste intestazioni ti consentono di effettuare chiamate cross-origin ai tuoi servizi Media CDN che potrebbero essere ospitati su un dominio (origine) diverso dal frontend del tuo sito web e potrebbero impedire le richieste cross-origin che non consenti esplicitamente.

Ad esempio, player.example.com e api.example.com sono origini diverse (nel senso del browser) e potresti volere che la tua applicazione frontend effettui richieste a api.example.com per recuperare la playlist successiva o aggiornare una elencazione di contenuti correlati. Analogamente, player.example.com potrebbe dover contattare cdn.example.com per recuperare le playlist e i segmenti video:cdn.example.com deve indicare che è tutto a posto e cheplayer.example.com è un allowed origin, nonché eventuali altre regole (intestazioni consentite, possibilità di includere i cookie).

Per fare un altro esempio, se vuoi consentire stream.example.com come origine e un'intestazione X-Client-ID nelle richieste CORS, puoi configurare un corsPolicy su un percorso, come segue:

corsPolicy: maxAge: 600 allowOrigins: ["stream.example.com"] allowHeaders:
["X-Client-ID"]

Un corsPolicy è configurato in routing.pathMatchers[].routeRules[].routeAction.corsPolicy all'interno di un EdgeCacheService. Ogni routeRule può definire un corsPolicy diverso in base alle esigenze o non definirne nessuno.

Importante: le richieste HTTP OPTIONS che corrispondono a un route con un criterio CORS configurato vengono pubblicate direttamente da Media CDN e non devono essere inviate all'origine. In questo modo si riduce il numero di richieste inviate all'origine e migliora il tasso di off-load.

Se definisci un valore corsPolicy e imposti anche un'intestazione di risposta personalizzata utilizzando i campi responseHeadersToAdd in un percorso con lo stesso nome, l'intestazione di risposta personalizzata ha la precedenza sul valore corsPolicy e viene utilizzata al suo posto.

Se la risposta dell'origine imposta intestazioni HTTP e hai impostato un valore corsPolicy, vengono utilizzati i valori corsPolicy. I valori non vengono compressi o combinati per evitare di inviare valori di intestazione non validi a un client o di impostare involontariamente un criterio più permissivo del previsto.

Il valore speciale {origin_request_header} viene compilato con l'intestazione HTTP Origin nella richiesta del client. Questo valore può essere impostato come valore dell'intestazione della risposta personalizzata su un percorso per l'intestazione Access-Control-Allow-Origin.

Per ulteriori dettagli, consulta la specifica dell'API per RouteAction.CORSPolicy.

Campi dei criteri CORS

La tabella seguente descrive i campi contenuti da una norma CORS.

Campo	Descrizione	Esempio
allowOrigins	Imposta l'intestazione della risposta Access-Control-Allow-Origins, che specifica quali origini possono effettuare richieste cross-origin in un ambiente browser. Ad esempio, se i tuoi contenuti video vengono pubblicati da https://video.example.com, ma il tuo portale rivolto agli utenti viene visualizzato da https://stream.example.com, dovrai aggiungere https://stream.example.com come origine consentita.	Access-Control-Allow-Origins: https://stream.example.com
maxAge	Imposta l'intestazione di risposta Access-Control-Max-Age, che specifica per quanto tempo, in secondi, un client del browser deve memorizzare nella cache la risposta a una richiesta di preflight CORS. Alcuni browser limitano questo valore a 2 ore o meno, anche se viene specificato il valore massimo (86400 secondi).	Access-Control-Max-Age: 7200
allowMethods	Imposta l'intestazione di risposta Access-Control-Allow-Methods, che specifica quali metodi HTTP sono autorizzati ad accedere alla risorsa. Per impostazione predefinita, Media CDN supporta solo i metodi GET, HEAD e OPTIONS. Per configurare il supporto di altri metodi, consulta Metodi di routing.	Access-Control-Allow-Methods: GET, OPTIONS, HEAD
allowHeaders	Imposta l'intestazione Access-Control-Allow-Headers, che determina quali intestazioni possono essere inviate in una richiesta CORS. Questo è spesso richiesto dai video player, che devono accedere ad alcune righe di intestazione di risposta per i contenuti video quando li richiedono in cross-origin.	Access-Control-Allow-Headers: Content-Type, If-Modified-Since, Range, User-Agent
exposeHeaders	Imposta l'intestazione della risposta Access-Control-Expose-Headers, che determina a quali intestazioni può accedere JavaScript lato client. Questo è spesso richiesto dai video player, che potrebbero dover accedere a intestazioni di risposta specifiche per i contenuti video quando richiedono contenuti cross-origin.	Access-Control-Expose-Headers: Date, Cache-Status, Content-Type, Content-Length
allowCredentials	Imposta l'intestazione della risposta Access-Control-Allow-Credentials, che consente a JavaScript lato client di ispezionare la risposta per le richieste con le credenziali incluse. Questa intestazione viene omessa se impostata su false.	Access-Control-Allow-Credentials: true
disabled	Disattiva corsPolicy senza rimuoverlo. Le richieste pre-volo OPTIONS vengono proxy all'origine.	N/D

Esempio di corsPolicy

L'esempio di configurazione seguente mostra una configurazione corsPolicy di base:

routeRules:
- priority: 1
  matchRules:
  - prefixMatch: /stream/
  routeAction:
    cdnPolicy:
      defaultTtl: 3600s
    corsPolicy:
      allowOrigins:
      - "https://stream.example.com"
      - "https://stream-staging.example.com"
      maxAge: 86400s # some browsers might only honor up to 7200s or less
      allowMethods:
      - "GET"
      - "HEAD"
      - "OPTIONS"
      allowHeaders:
      - "Content-Type"
      - "If-Modified-Since"
      - "Range"
      - "User-Agent"
      exposeHeaders:
      - "Content-Type"
      - "Content-Length"
      - "Date"

Risolvere i problemi di routing

Se alcune richieste non recuperano risultati corrispondenti o restituiscono errori, controlla quanto segue:

• Un percorso deve avere un matchRule con esattamente uno dei valori prefixMatch, fullPathMatch o pathTemplateMatch definito. L'API restituisce un errore se non includi uno di questi campi.
• Assicurati che il valore priority di ogni route sia impostato correttamente: alle route più specifiche (più lunghe) deve essere assegnata una priorità più alta rispetto alle corrispondenze di route più brevi e più ampie.
• Per impostazione predefinita, sono supportate solo le richieste GET, HEAD e OPTIONS. Per configurare il supporto di altri metodi, consulta Metodi di routing. I metodi non abilitati per un determinato route vengono rifiutati con un errore HTTP 405 (Method Not Allowed).
• Le richieste HTTP GET con un corpo o qualsiasi richiesta con trailer vengono rifiutate con un errore HTTP 400, perché i corpi delle richieste non sono consentiti nelle richieste GET.
• La corrispondenza del parametro di query e dell'intestazione è un "AND" logico: la richiesta deve corrispondere a tutte le chiavi (e ai valori, se specificati) del parametro di query o dell'intestazione per corrispondere al percorso specificato.

Passaggi successivi

• Consulta la documentazione sulla configurazione della memorizzazione nella cache.
• Scopri come collegarti a origini diverse.
• Configura i certificati TLS (SSL) per il tuo servizio.
• Configura le richieste firmate per autenticare l'accesso ai contenuti.