Configurer des routes de service

Media CDN fournit des fonctionnalités de routage HTTP avancées qui vous permettent de mapper avec précision le trafic vers des configurations et origines de périphérie spécifiques.

Configurer une règle de routage

Configurez une règle de routage pour un service Media CDN.

Console

  1. Dans la console Google Cloud, accédez à la page Media CDN.

    Accéder à Media CDN

  2. Pour ouvrir la page Détails du service pour lequel vous souhaitez configurer une règle de routage, cliquez sur le nom du service.

  3. Pour passer en mode Édition, cliquez sur le bouton Modifier.

  4. Pour accéder à la section Routing (Routage), cliquez sur Next (Suivant).

  5. Spécifiez au moins une règle d'hôte. Cliquez sur Ajouter une règle d'hôte. Ensuite, procédez comme suit:

    1. Dans Hôtes, spécifiez au moins un hôte à faire correspondre.

    2. Dans Description, fournissez une brève description de la règle d'hôte.

    Pour modifier une règle d'hôte, cliquez sur la flèche pour la développer.

  6. Spécifiez au moins une règle de routage. Cliquez sur Ajouter une règle de routage.

    Pour modifier une règle de routage, cliquez sur Modifier sur la ligne correspondante.

  7. Dans le volet Modifier la règle de routage, pour Priorité, définissez une valeur pour la priorité de routage.

  8. Dans Description, fournissez une brève description qui peut aider à identifier la règle dans une liste de règles.

  9. Dans la section Correspondance, spécifiez au moins une condition de correspondance. Cliquez sur Ajouter une condition de correspondance. Ensuite, procédez comme suit :

    1. Pour Type de correspondance, sélectionnez une option de correspondance de chemin.
    2. Pour Correspondance de chemin d'accès, spécifiez les noms, les chemins d'accès ou les modèles. Envisagez d'utiliser la correspondance de modèle avec des caractères génériques.

      Si nécessaire, sélectionnez également Activer la sensibilité à la casse pour la valeur du chemin.

    3. Facultatif: sélectionnez Les en-têtes correspondent et Les paramètres de requête correspondent. Cliquez ensuite sur les boutons appropriés pour ajouter des en-têtes et des paramètres de requête. Pour chacun d'eux, spécifiez le nom, le type de correspondance et la valeur.

      Pour en savoir plus, consultez la section Correspondance sur les en-têtes et les paramètres de requête.

    4. Pour enregistrer la condition de correspondance, cliquez sur OK.

  10. Pour Action principale, sélectionnez l'une des options suivantes:

    • Extraire d'une origine: pour diriger les requêtes vers une origine spécifique, sélectionnez cette option, puis une origine.

    • URL de redirection: sélectionnez cette option pour rediriger les requêtes. Spécifiez ensuite le type de redirection, le chemin d'accès et le code d'état.

      Vous pouvez également sélectionner les options pour rediriger toutes les réponses vers HTTPS ou pour supprimer la requête.

  11. Cliquez sur Configurations avancées.

    1. Dans la section Action d'en-tête, cliquez sur Ajouter un élément.

      Sélectionnez un type d'action, puis spécifiez un en-tête sous la forme d'une paire nom-valeur. Cliquez ensuite sur OK.

    2. Dans la section Action de routage, cliquez sur Ajouter un élément.

      Spécifiez un type d'action et les options associées. Cliquez ensuite sur OK.

  12. Pour Filtrage selon la méthode HTTP, sélectionnez Personnaliser le filtrage selon la méthode HTTP.

    Sélectionnez ensuite les méthodes HTTP que vous souhaitez mettre en proxy vers votre origine.

  13. Pour enregistrer la règle de routage, cliquez sur Enregistrer.

  14. Pour enregistrer vos modifications apportées au service, cliquez sur Mettre à jour le service.

gcloud et YAML

  1. Exportez votre configuration du CDN multimédia dans un fichier YAML. Exécutez la commande gcloud edge-cache services export.

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

    Remplacez les éléments suivants :

    • SERVICE_NAME : nom de votre service.
    • FILENAME : nom de votre fichier YAML
  2. Mettez à jour le fichier YAML avec la configuration requise, comme décrit dans les sections de cette page.

  3. Pour mettre à jour le service, importez votre configuration Media CDN à partir du fichier YAML. Exécutez la commande gcloud edge-cache services import.

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

Mise en correspondance des requêtes

Une configuration Media CDN contient un ensemble de routes définies dans la section Routing (Routage) pour une ressource EdgeCacheService. Ces routes sont mises en correspondance avec des requêtes en fonction (au minimum) d'un hôte. Pour en savoir plus sur la façon dont le trafic est dirigé vers une origine, consultez HostRule et PathMatcher. Chaque route peut définir sa propre configuration CDN, ses réécritures, ses redirections, sa règle CORS, ses en-têtes HTTP personnalisés et son mappage d'origine. Les routes peuvent partager des origines.

Par exemple, vous pouvez acheminer les requêtes pour les fichiers manifestes vers une origine spécifique et définir une valeur TTL de cache de courte durée ainsi qu'une règle de cache négatif. Les requêtes portant sur des segments peuvent être réparties vers une autre origine en utilisant des en-têtes et des paramètres de requête pour répartir des types de fichier manifeste ou des utilisateurs spécifiques.

L'exemple suivant montre comment acheminer les requêtes correspondant à un en-tête, à un paramètre de requête et à un préfixe de chemin d'accès spécifiques pour l'hôte 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

Mise en correspondance des chemins d'accès

Media CDN est compatible avec la mise en correspondance complète (exacte), de préfixe et de chemin d'accès générique. La correspondance de chemin d'accès peut être combinée avec la correspondance basée sur l'hôte, l'en-tête et les paramètres de requête afin de créer des règles de routage de requêtes précises.

Voici trois méthodes pour mettre en correspondance un chemin d'URL.

Champ Description Exemple
matchRules[].fullPathMatch La condition fullPathMatch est mise en correspondance avec le chemin d'URL complet, qui n'inclut pas la chaîne de requête. Vous devez spécifier les barres obliques finales, le cas échéant.

Une route avec une règle de correspondance de fullPathMatch: "/stream/" est mise en correspondance avec /stream/, mais pas avec /stream ni avec /stream/us/hls/1234.ts.

Une fullPathMatch est une correspondance explicite (exacte).

matchRules[].prefixMatch La condition prefixMatch est mise en correspondance avec le préfixe de chemin d'URL. Les URL commençant par la même chaîne sont mises en correspondance.

Une route avec une règle de correspondance de prefixMatch: "/videos/" est mise en correspondance à la fois avec /videos/hls/58481314/manifest.m3u8 et avec /videos/dash, car ces valeurs contiennent toutes les deux le préfixe /videos/.

matchRules[].pathTemplateMatch La condition pathTemplateMatch accepte les opérateurs génériques qui vous permettent de mettre en correspondance des formats d'URL complexes et des segments de chemin d'accès, mais aussi de capturer des variables nommées pour réécrire des URL.

Une route avec une règle de correspondance de pathTemplateMatch: "/**.m3u8" est mise en correspondance avec tout chemin d'URL se terminant par .m3u8.

/content/en-GB/13/51491/manifest_193193.m3u8 et /p/abc/1234/manifest_1080p5000.m3u8 correspondent tous deux à ce schéma.

Pour plus d'exemples, consultez la section Mise en correspondance de schémas.

Pour en savoir plus, consultez la spécification de l'API pour MatchRule.

Par exemple, pour mettre en correspondance toutes les requêtes commençant par /stream/, créez une règle de routage semblable à celle-ci :

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/

Cet exemple inclut explicitement la barre oblique finale dans la règle de correspondance :

  • Une requête envoyée à media.example.com/stream/id/1234/hls/manifest.m3u8 est mise en correspondance avec cette route.
  • Une requête adressée à media.example.com/stream-eu/id/4567/hls/manifest.m3u8 n'est pas mise en correspondance avec cette route.

Dans le deuxième cas, Media CDN renvoie une erreur HTTP 404, à moins qu'une autre route ou une route collecteur ne soit configurée.

Pour plus d'informations sur le fonctionnement de la priorité pour les routes avec des préfixes similaires, consultez la section Priorité et ordre des routes.

Correspondance de schémas (caractère générique)

La mise en correspondance de schémas vous permet de mettre en correspondance plusieurs parties d'une URL, y compris des URL partielles et des suffixes (extensions de fichiers), en utilisant une syntaxe de caractère générique.

Vous pouvez également associer un ou plusieurs segments de chemin d'accès à des variables nommées dans un champ pathTemplateMatch, puis faire référence à ces variables lors de la réécriture de l'URL dans un champ pathTemplateRewrite. Cela vous permet de réorganiser et de supprimer les segments d'URL avant que la requête ne soit envoyée à votre origine.

L'exemple suivant montre comment mettre en correspondance deux suffixes d'URL différents :

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

La syntaxe acceptée inclut les éléments suivants.

Opérateur Correspondance établie Exemple
* Correspond à un seul segment de chemin d'accès, jusqu'au séparateur de chemin suivant: / /videos/*/*/*.m4s correspond à /videos/123414/hls/1080p5000_00001.m4s.
** Correspond à zéro segments de chemin ou plus. S'il est présent, il doit s'agir du dernier opérateur. /**.mpd correspond à /content/123/india/dash/55/manifest.mpd.
{name} or {name=*}

Une variable nommée correspondant à un segment de chemin d'accès.

Correspond à un seul segment de chemin, jusqu'au séparateur de chemin suivant : /.

/content/{format}/{lang}/{id}/{file}.vtt correspond à /content/hls/en-us/12345/en_193913.vtt et capture format="hls", lang="en-us", id="12345" et file="en_193913" en tant que variables.
{name=videos/*} Une variable nommée correspondant à plusieurs segments de chemin. Le segment de chemin d'accès correspondant à videos/* est capturé en tant que variable nommée. /videos/{language=lang/*}/* correspond à /videos/lang/en/video.m4s et renseigne la variable de chemin d'accès language avec la valeur lang/en.
{name=**}

Une variable nommée correspondant à zéro segments de chemin ou plus.

S'il est présent, il doit s'agir du dernier opérateur.

/**.m3u8 ou /{path=**}.m3u8 correspondent à tous les segments de chemin d'accès jusqu'à l'extension.

/videos/{file=**} correspond à /videos/en-GB/def566/manifest.m3u8, en incluant l'extension, et capture la variable de chemin d'accès file="en-GB/def566/manifest.m3u8.

Remarques :

  • Si vous ne réécrivez pas une URL, utilisez les opérateurs plus simples * et **.
  • Lorsque vous utilisez des variables pour capturer des segments de chemin d'accès, les parties de l'URL qui ne sont pas capturées par une variable ne peuvent pas être référencées dans un pathTemplateRewrite ultérieur. Pour obtenir un exemple, consultez la section Capturer des variables de chemin d'accès.
  • Vous ne pouvez pas faire référence, dans un pathTemplateRewrite ultérieur, à des variables qui n'existent pas dans la propriété pathTemplateMatch sur la même route.
  • Les variables sont sensibles à la casse. {FORMAT}, {forMAT} et {format} représentent différentes variables et valeurs.
  • Vous pouvez spécifier jusqu'à 10 opérateurs (caractères génériques ou variables) dans une correspondance. Les champs pathTemplateMatch et pathTemplateRewrite ne doivent pas dépasser 255 caractères.

Exemple : Correspondance avec une extension de fichier

L'exemple suivant montre un cas d'utilisation courant des opérateurs génériques, à savoir la mise en correspondance de tous les segments de chemin jusqu'à un suffixe.

Dans ce cas, vous effectuez les opérations suivantes :

  • Récupérer les fichiers manifestes de vidéo (listes de lecture) qui se terminent par .m3u8 et .mpd à partir de leur origine, en appliquant une valeur TTL courte (5 secondes) à ces réponses car elles changent régulièrement.
  • Extraire les séquences vidéo se terminant par .ts et .m4s à partir de l'origine du segment, puis appliquer une valeur TTL plus longue (1 jour) à ces réponses.

Cette approche est souvent utilisée lors de l'utilisation de services SSAI (injection d'annonce côté serveur) ou DAI (insertion dynamique d'annonce) ainsi que pour les flux vidéo en direct lorsque le fichier manifeste est mis à jour avec un intervalle de quelques secondes.

La configuration suivante montre comment configurer le routage Media CDN pour assurer cette compatibilité :

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

Exemple : Capturer des variales de chemin d'accès

L'exemple suivant montre comment utiliser des variables nommées pour décrire un ou plusieurs segments de chemin d'accès.

Ces variables peuvent être utilisées dans un pathTemplateRewrite pour réécrire le chemin d'accès avant l'envoi de la requête vers l'origine ou pour effectuer une autodescription pathTemplateMatch complexe.

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}"

À savoir :

  • Chaque variable {name} capture un seul segment de chemin d'accès. Un segment de chemin d'accès correspond à tous les caractères entre une paire de / (barre obliques) dans un chemin d'URL.
  • Une variable {name=**} capture tous les segments de chemin restants. Dans ce cas, elle est mise en correspondance à la fois avec segments/00001.ts et avec master.m3u8.
  • Dans la section pathTemplateRewrite sur la même route, vous faites référence à certaines des variables que vous avez capturées dans le pathTemplateMatch. Vous omettez explicitement les variables {country} et {lang}, car elles ne correspondent pas à la structure de répertoires de l'origine.

Dans cet exemple, les événements suivants se produisent :

  • Une URL de requête entrante de /us/en/hls/123139139/segment_00001.ts est mise en correspondance avec pathTemplateMatch et est réécrite en /123139139/hls/segment_00001.ts avant d'être envoyée à l'origine.
  • Une URL de requête entrante de /us/123139139/master.m3u8 n'est pas mise en correspondance avec pathTemplateMatch et reçoit une réponse HTTP 404 (Not Found).
  • Une URL de requête entrante de /br/es/dash/c966cbbe6ae3/subtitle_00001.vtt est également mise en correspondance avec pathTemplateMatch et est réécrite en /c966cbbe6ae3/dash/subtitle_00001.vtt avant d'être envoyée à l'origine.

Pour en savoir plus sur l'interaction de la mise en correspondance des caractères génériques avec la réécriture d'URL, consultez la section Réécritures.

Mise en correspondance des hôtes

Chaque service peut être mis en correspondance avec plusieurs noms d'hôte, chaque ensemble de noms d'hôte contenant son propre groupe de routes (que l'on appelle outils de mise en correspondance des chemins d'accès). Dans le cas le plus courant, tous les noms d'hôte d'un service sont mappés sur un même ensemble de routes partagées avec une seule liste d'hôtes et un seul outil de mise en correspondance des chemins d'accès.

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

Les hôtes qui ne sont pas mis en correspondance sont desservis avec une page HTTP 404 par défaut. Pour accepter n'importe quel hôte, vous pouvez inclure le caractère générique * en tant qu'entrée hostRules[].hosts[].

Vous pouvez également définir des groupes de routes (par exemple, pour un regroupement par pays ou pour regrouper les routes de diffusion en direct ou à la demande). Comme chaque service dispose d'une seule règle de sécurité, nous vous recommandons généralement d'avoir un service pour chaque marché (zone géographique) ou charge de travail.

Remarques :

  • Les en-têtes d'hôte (ou HTTP/2 :authority) contenant un port sont implicitement mis en correspondance avec un hôte configuré. Vous n'avez pas besoin de spécifier explicitement les ports.
  • Si la requête est effectuée via HTTP, une entrée hostRules[].hosts[] avec une valeur de *.vod.example.com est mise en correspondance avec us.vod.example.com et us.vod.example.com:80.
  • Si la requête est de type HTTPS (TLS), une entrée hostRules[].hosts[] avec une valeur de *.vod.example.com est mise en correspondance avec us.vod.example.com:443.

Pour en savoir plus, consultez la spécification de l'API pour HostRule.

Mise en correspondance des en-têtes et des paramètres de requête

Vous pouvez configurer des routes pour qu'elles soient mises en correspondance avec des noms d'en-tête et des paramètres de requête spécifiques, ainsi qu'avec la présence d'une valeur d'en-tête (préfixe, suffixe ou correspondance exacte).

La mise en correspondance des en-têtes et des paramètres de requête utilise un opérateur logique "AND". La requête doit correspondre à tous les paramètres de requête et à toutes les clés d'en-tête (et valeurs, le cas échéant) être mises en correspondance avec la route donnée.

Par exemple, si vous souhaitez acheminer les requêtes avec un nom de champ d'en-tête et une valeur d'en-tête spécifiques vers une origine nommée alternate-origin, configurez vos conditions de mise en correspondance dans 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"

Dans cet exemple, les requêtes contenant /videos/ au début de l'URL et l'en-tête x-device-name: roku seront mises en correspondance avec cette route. Les requêtes ne comportant pas ce nom d'en-tête ou une valeur différente ne seront pas mises en correspondance.

Pour en savoir plus, consultez la spécification de l'API pour HeaderMatch.

De même, pour la mise en correspondance avec des paramètres de requête, spécifiez une ou plusieurs valeurs queryParameterMatches comme suit :

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"

Dans cet exemple, une requête client https://cdn.example.com/videos/1234/abcd/xyz.m3u8?playback_type=live&geo=eu est mise en correspondance avec cette route.

Pour en savoir plus, consultez la spécification de l'API pour QueryParameterMatcher.

Définir une route collecteur (par défaut)

Par défaut, Media CDN renvoie une erreur HTTP 404 (Not Found) si une requête ne correspond à aucune route configurée.

Pour configurer une route collecteur pour un pathMatcher (collection de routes) donné, procédez comme suit :

  • Créez une routeRule avec la priorité la plus faible (nombre plus élevé), par exemple 999, qui est la priorité de route la plus faible possible.
  • Configurez une matchRule avec une correspondance de préfixe de / (correspondance avec tous les chemins de requête).
  • Configurez une origin ou une urlRedirect (un seul de ces éléments) sur la route.

Par exemple, pour configurer une route collecteur qui dirige toutes les requêtes sans correspondance vers une origine par défaut nommée my-origin, créez une route avec la valeur priority: 999 et avec une matchRules[].prefixMatch définie sur / comme suit :

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

Vous pouvez éventuellement réécrire l'URL avant la récupération de l'origine, ou rediriger vers une page par défaut (par exemple, votre page de destination) plutôt que d'envoyer la requête "en l'état" à l'origine.

Priorité et ordre des routes

Chaque route d'un tableau de routeRules[] doit être associée à une valeur de priority.

Les routes plus spécifiques doivent être définies avec une priorité plus élevée (nombre plus petit). Une route correspondant au préfixe /stream/ avec une priorité de 1 empêche une route plus spécifique correspondant au préfixe /stream/live/eu/ avec une priorité de 5 d'être mise en correspondance avec des requêtes.

  • La priorité de route la plus élevée est "1", et la plus faible est "999".
  • Vous ne pouvez pas configurer plusieurs routeRule avec la même priorité. La priorité de chaque règle doit être définie sur un nombre compris entre 1 et 999 (inclus).
  • La définition d'une route collecteur vous permet d'envoyer toutes les requêtes non correspondantes vers une origine par défaut ou de les rediriger vers une page de destination ou un point de terminaison.

Dans l'exemple suivant, vous pouvez constater que la route /live/us/ ne serait jamais mise en correspondance car la route /live/ a une priorité plus élevée :

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: /

Pour résoudre ce problème, définissez la route la plus spécifique (la plus longue) sur un niveau de priorité plus élevé :

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: /

Cela permet à la route plus spécifique d'être correctement mise en correspondance avec les requêtes. Une requête avec le préfixe /live/eu/ est toujours acheminée vers la route /live/ dont la priorité est de 2.

Filtrage par méthode

Par défaut, Media CDN ne met en proxy que les méthodes GET, HEAD et OPTIONS vers votre origine et filtre les méthodes pouvant modifier votre origine.

Vous pouvez remplacer ce comportement par défaut pour une règle de routage spécifique en spécifiant les méthodes que vous souhaitez mettre en proxy vers votre origine. Outre GET, HEAD et OPTIONS, Media CDN est compatible avec PUT, POST, DELETE et PATCH.

Pour configurer la prise en charge d'un ensemble de méthodes pour une règle d'itinéraire, spécifiez une section routeMethods avec une valeur allowed_methods pour chaque méthode.

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

Normalisation des chemins d'accès

La normalisation des chemins d'accès décrit comment Media CDN combine plusieurs représentations d'une URL en une seule représentation canonique dans des scénarios spécifiques.

La normalisation des chemins d'accès peut améliorer directement les taux de succès de mise en cache en réduisant le nombre d'URL de requête représentant le même contenu, et en limitant les erreurs d'origine pour les origines qui attendent des chemins normalisés.

Les requêtes entrantes sont normalisées comme suit :

  • Plusieurs barres obliques consécutives sont fusionnées en une seule. Par exemple, un chemin d'URL de /videos///12345/manifest.mpd est normalisé en /videos/12345/manifest.mpd.
  • Les segments de chemin d'accès sont normalisés conformément à la section 6.2.2.3 du document RFC 3986. Par exemple, le chemin d'accès /a/b/c/./../../g est normalisé en /a/g sur la base de l'algorithme Supprimer les segments à point défini dans la RFC 3986. Cette normalisation se produit avant de vérifier le cache ou de transférer la requête à l'origine.
  • Les requêtes ne sont pas normalisées en encodage-pourcent. Par exemple, une URL avec une barre oblique en encodage-pourcent (%2F) n'est pas décodée dans sa forme non encodée.

Les URL restent sensibles à la casse et ne sont pas normalisées en termes de casse. De nombreuses URL contiennent des encodages en base64 sensibles à la casse, y compris les URL avec des jetons de requête signée.

Réécritures et redirections

Les sections suivantes fournissent des exemples sur la réécriture des requêtes et la configuration des redirections.

Réécrire les URL de requête

Media CDN est compatible avec les réécritures d'hôtes et de chemins d'accès. Les réécritures modifient l'URL envoyée à l'origine et vous permettent de modifier les hôtes et les chemins d'accès selon vos besoins. Les réécritures d'hôtes et de chemins d'accès sont effectuées au niveau de la route, ce qui vous permet de définir les requêtes spécifiques qui sont réécrites en fonction de n'importe quelle mise en correspondance, y compris celles basées sur le chemin d'accès, les paramètres de requête et l'en-tête de requête.

Pour en savoir plus, consultez la spécification de l'API pour RouteAction.UrlRewrite.

Voici trois façons de réécrire une requête :

Champ Description
urlRewrite.pathPrefixRewrite

Réécrit le chemin d'accès, en supprimant le préfixe spécifié dans l'élément prefixMatch correspondant à la requête.

Une seule règle pathPrefixRewrite ou pathTemplateRewrite peut être spécifiée dans une même règle de routage.

urlRewrite.pathTemplateRewrite

pathTemplateRewrite ne peut être utilisé qu'avec une règle pathTemplateMatch correspondante sur la même route.

Une seule règle pathPrefixRewrite ou pathTemplateRewrite peut être spécifiée dans une même règle de routage.

urlRewrite.hostRewrite Réécrit l'hôte avant que la requête ne soit envoyée au serveur d'origine.

Remarques :

  • Les URL réécrites ne modifient pas la clé de cache. La clé de cache est basée sur l'URL de requête envoyée par le client.
  • La réécriture se produit après la mise en correspondance avec la route et la validation des requêtes signées. Les routes ne sont pas remises en correspondance avec une autre règle de correspondance.

Exemple : Supprimer un préfixe de chemin d'accès

Par exemple, pour réécrire une URL de requête client /vod/videos/hls/1234/abc.ts en /videos/hls/1234/abc.ts (en supprimant /vod du chemin d'accès), vous pouvez utiliser la fonctionnalité 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 fonctionne en remplaçant l'intégralité du préfixe de chemin d'accès mis en correspondance dans matchRules[].prefixMatch par la valeur de pathPrefixRewrite.

Pour réécrire un nom d'hôte (par exemple, réécrire cdn.example.com en my-bucket.s3.us-west-2.amazonaws.com), vous pouvez configurer les éléments suivants :

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"

Dans ce cas, l'URL de la requête d'origine passe de cdn.example.com/videos/* à my-bucket.s3.us-west-2.amazonaws.com/videos/*. Vous pouvez également combiner les réécritures d'hôte et de chemin d'accès dans une même route.

Exemple : Utiliser des variables pour réécrire des URL

Pour utiliser pathTemplateMatch et pathTemplateRewrite pour réécrire des parties d'une URL de requête entrante, consultez la section Capturer des variables.

Rediriger des requêtes

Media CDN accepte trois types de redirections :

  • Les redirections d'hôte, qui ne redirigent que l'hôte (domaine), sans modifier le chemin d'accès et les paramètres de requête.
  • Les redirections de chemin d'accès, qui remplacent complètement le chemin d'accès.
  • Les redirections de préfixe de chemin d'accès, qui ne remplacent que le préfixe correspondant.

Les redirections sont définies par défaut sur HTTP 301 (Moved Permanently), mais peuvent être configurées pour renvoyer différents codes d'état de redirection par route.

La configuration suivante est un exemple de redirection basée sur un préfixe, dans lequel vous redirigez les utilisateurs accédant à https://cdn.example.com/on-demand/* vers 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

Cet exemple modifie également la redirection en redirection temporaire, ce qui empêche les clients (tels que les navigateurs) de la mettre en cache. Cela peut être utile si vous prévoyez de modifier prochainement la redirection.

Les valeurs redirectResponseCode acceptées sont indiquées dans le tableau suivant.

Code de réponse de redirection Code d'état HTTP
MOVED_PERMANENTLY_DEFAULT HTTP 301 (déplacé définitivement)
FOUND HTTP 302 (trouvé)
SEE_OTHER HTTP 303 (voir ailleurs)
TEMPORARY_REDIRECT HTTP 307 (redirection temporaire)
PERMANENT_REDIRECT HTTP 308 (redirection permanente)

Remarques :

  • Une route peut diriger le trafic vers une origine ou renvoyer une redirection au client. Vous ne pouvez pas définir simultanément les champs origin et urlRedirect.
  • Les routes qui redirigent vers HTTPS nécessitent qu'au moins un certificat SSL soit associé au service.

Pour en savoir plus, consultez la spécification de l'API pour RouteRule.UrlRedirect.

Rediriger toutes les requêtes vers HTTPS

Pour rediriger toutes les requêtes vers HTTPS (au lieu de HTTP), vous pouvez configurer chacun de vos services pour rediriger automatiquement toutes les requêtes client vers HTTPS. Les clients se connectant via HTTP reçoivent une réponse HTTP 301 (Permanent Redirect) avec l'en-tête Location défini sur la même URL utilisant "https://" au lieu de "http://".

gcloud

gcloud edge-cache services update MY_SERVICE \
    --require-tls
Request issued for: [MY_SERVICE]
Updated service [MY_SERVICE].

La commande renvoie une description de votre service, avec requireTls maintenant défini sur true.

  name: MY_SERVICE
  requireTls: true

Vous pouvez également choisir de définir l'en-tête Strict-Transport-Security comme en-tête de réponse pour permettre aux clients de toujours se connecter directement via HTTPS.

Utiliser des backends de stockage tiers

Media CDN est compatible avec la connexion aux points de terminaison HTTP accessibles au public en dehors de Google Cloud, y compris aux buckets de stockage AWS S3, à Azure Blob Storage et à d'autres fournisseurs de stockage. Cela peut être utile si vous disposez d'une architecture multicloud ou si vous devez encore migrer des données vers Cloud Storage avec le service de transfert de stockage.

Voici une configuration d'origine minimale qui configure un bucket hébergé virtuellement dans AWS S3 :

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

Si vous n'utilisez pas un nom de bucket correspondant aux noms d'hôte configurés pour vos ressources EdgeCacheService, vous devez également configurer une réécriture d'hôte pour les routes associées à cette origine (ou à ces origines). Sans cela, l'en-tête "Host" défini par la requête client est utilisé lors de la récupération à partir de l'origine.

Par exemple, pour mapper toutes les requêtes dont le préfixe de chemin est /legacy/ vers votre bucket externe, vous pouvez configurer à la fois un hostRewrite et un pathPrefixRewrite pour supprimer ce préfixe de la requête d'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

Pour en savoir plus sur la manière dont l'en-tête d'hôte est défini sur les requêtes d'origine, consultez la documentation sur les en-têtes de requête d'origine.

Partage des ressources entre origines multiples (CORS)

Le partage des ressources entre origines multiples (CORS, Cross-Origin Resource Sharing) est une approche centrée sur le navigateur pour effectuer des requêtes entre origines de manière sécurisée. Les règles CORS vous permettent de définir automatiquement des en-têtes CORS (par exemple, Access-Control-Allow-Origins) avec une règle spécifique par route.

Configurer le CORS

Le CDN multimédia vous permet de définir une règle CORS sur une route pour un EdgeCacheService.

Une règle CORS définit ces règles avec un ensemble commun d'en-têtes HTTP. Vous pouvez définir des en-têtes CORS courants dans les réponses, tels que Access-Control-Allow-Origin, Access-Control-Max-Age et Access-Control-Allow-Headers. Ces en-têtes vous permettent d'effectuer des appels multi-origines vers vos services Media CDN, qui peuvent être hébergés sur un domaine (origine) différent de celui de l'interface de votre site Web, et peuvent empêcher les requêtes multi-origines que vous n'autorisez pas explicitement.

Par exemple, player.example.com et api.example.com sont des origines différentes (au sens du navigateur), et vous pouvez demander à votre application frontale d'envoyer des requêtes à api.example.com pour récupérer la playlist suivante ou actualiser une liste de contenus associés. De même, player.example.com peut avoir besoin de contacter cdn.example.com pour récupérer des playlists et des segments vidéo : cdn.example.com doit indiquer que cela est acceptable et que player.example.com est un allowed origin, ainsi que toute autre règle (en-têtes autorisés, possibilité d'inclure des cookies, etc.).

Prenons un autre exemple. Si vous souhaitez autoriser stream.example.com comme origine et un en-tête X-Client-ID dans les requêtes CORS, vous pouvez configurer un corsPolicy sur un parcours, comme suit:

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

Un corsPolicy est configuré à routing.pathMatchers[].routeRules[].routeAction.corsPolicy dans un EdgeCacheService. Chaque routeRule peut définir un corsPolicy différent si nécessaire, ou aucun.

Si vous définissez une valeur corsPolicy et un en-tête de réponse personnalisé à l'aide des champs responseHeadersToAdd sur une route portant le même nom, l'en-tête de réponse personnalisé prévaut sur la valeur corsPolicy et est utilisé à la place.

Si la réponse d'origine définit des en-têtes HTTP et que vous avez défini une valeur corsPolicy, les valeurs corsPolicy sont utilisées à la place. Les valeurs ne sont pas condensées ni combinées pour éviter d'envoyer des valeurs d'en-tête non valides à un client ou de définir par inadvertance une règle plus permissive que prévu.

L'{origin_request_header} spécial est renseigné avec l'en-tête HTTP Origin dans la requête client. Vous pouvez définir cette valeur en tant que valeur d'en-tête de réponse personnalisée sur un parcours, pour l'en-tête Access-Control-Allow-Origin.

Pour en savoir plus, consultez la spécification de l'API pour RouteAction.CORSPolicy.

Champs de la règle CORS

Le tableau suivant décrit les champs qu'une règle CORS contient.

Champ Description Exemple
allowOrigins

Définit l'en-tête de réponse Access-Control-Allow-Origins, qui spécifie les origines pouvant effectuer des requêtes multi-origines dans un environnement de navigateur.

Par exemple, si votre contenu vidéo est diffusé depuis https://video.example.com, mais que votre portail destiné aux utilisateurs est diffusé depuis https://stream.example.com, vous devez ajouter https://stream.example.com en tant qu'origine autorisée.

Access-Control-Allow-Origins: https://stream.example.com
maxAge

Définit l'en-tête de réponse Access-Control-Max-Age, qui spécifie la durée, en secondes, pendant laquelle un client de navigateur doit mettre en cache la réponse à une requête CORS préliminaire.

Certains navigateurs imposent une limite de 2 heures ou moins, même si la valeur maximale (86 400 secondes) est spécifiée.

Access-Control-Max-Age: 7200
allowMethods

Définit l'en-tête de réponse Access-Control-Allow-Methods, qui spécifie les méthodes HTTP autorisées à accéder à la ressource.

Par défaut, Media CDN n'est compatible qu'avec les méthodes GET, HEAD et OPTIONS. Pour configurer la prise en charge d'autres méthodes, consultez la section Méthodes de routage.

Access-Control-Allow-Methods: GET, OPTIONS, HEAD
allowHeaders

Définit l'en-tête Access-Control-Allow-Headers, qui détermine les en-têtes pouvant être envoyés dans une requête CORS.

Cela est souvent requis par les lecteurs vidéo, qui doivent accéder à certains en-têtes de réponse pour le contenu vidéo lorsqu'il est demandé avec une requête multi-origines.

Access-Control-Allow-Headers: Content-Type, If-Modified-Since, Range, User-Agent
exposeHeaders

Définit l'en-tête de réponse Access-Control-Expose-Headers, qui détermine les en-têtes accessibles par le code JavaScript côté client.

Cela est souvent requis par les lecteurs vidéo, qui peuvent avoir besoin d'accéder à des en-têtes de réponse spécifiques pour le contenu vidéo lorsqu'il est demandé avec une requête multi-origines.

Access-Control-Expose-Headers: Date, Cache-Status, Content-Type, Content-Length
allowCredentials

Définit l'en-tête de réponse Access-Control-Allow-Credentials, qui permet au code JavaScript côté client d'inspecter la réponse pour les requêtes incluant des identifiants.

Cet en-tête est omis lorsqu'il est défini sur "false".

Access-Control-Allow-Credentials: true
disabled Désactive le corsPolicy sans le supprimer. Les requêtes OPTIONS préliminaires sont envoyées par proxy à l'origine. Non disponible

Exemple de corsPolicy

L'exemple de configuration suivant illustre une configuration corsPolicy de 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"

Résoudre les problèmes de routage

Si certaines requêtes ne récupèrent pas de résultats correspondants ou renvoient des erreurs, vérifiez les points suivants:

  • Une route doit avoir une matchRule avec un seul élément défini parmi prefixMatch, fullPathMatch ou pathTemplateMatch. L'API renvoie une erreur si vous n'incluez pas l'un de ces champs.
  • Assurez-vous que la valeur priority de chaque route est définie correctement : les routes plus spécifiques (plus longues) doivent avoir une priorité plus élevée que les routes plus courtes et moins spécifiques.
  • Par défaut, seules les requêtes GET, HEAD et OPTIONS sont acceptées. Pour configurer la prise en charge d'autres méthodes, consultez la section Méthodes de routage. Les méthodes qui ne sont pas activées pour un parcours particulier sont rejetées avec une erreur HTTP 405 (Method Not Allowed).
  • Les requêtes HTTP GET avec un corps ou les requêtes avec des trailers sont rejetées avec une erreur HTTP 400, car les corps de requête ne sont pas autorisés dans les requêtes GET.
  • La mise en correspondance de paramètres de requête et d'en-têtes utilise un opérateur logique "AND". La requête doit donc correspondre à toutes les clés de paramètre de requête ou d'en-tête (et aux valeurs, le cas échéant) pour être mise en correspondance avec la route donnée.

Étape suivante