Définir des en-têtes personnalisés

Media CDN vous permet de spécifier des en-têtes de requête et de réponse personnalisés. Les en-têtes de requête personnalisés sont compatibles avec les valeurs statiques, tandis que les en-têtes de réponse personnalisés acceptent les valeurs statiques et dynamiques.

Les en-têtes personnalisés vous permettent d'effectuer les opérations suivantes :

Renvoyer les données géographiques du client, telles que le pays, la région ou la ville, que vous pouvez utiliser pour afficher du contenu localisé.
Déterminer si une réponse a été diffusée à partir du cache (entièrement ou en partie) et connaître l'emplacement à partir duquel elle a été diffusée.
Supprimer ou remplacer les en-têtes de requête et de réponse.

Vous pouvez également utiliser des en-têtes pour acheminer les requêtes vers différentes origines, comme décrit dans la documentation sur le routage avancé. Si vous devez configurer les en-têtes CORS (Cross-Origin Resource Sharing), configurez une règle CORS pour chaque route.

Appliquer des en-têtes personnalisés

Les en-têtes sont définis sur chaque route, ce qui vous permet d'ajouter et de supprimer des en-têtes pour différents contenus, tels que des fichiers manifestes ou des séquences vidéo.

Par défaut, les valeurs d'en-tête sont ajoutées aux en-têtes de réponse ou de requête avec les mêmes noms de champs. Les valeurs ajoutées sont séparées par des virgules.

Pour écraser les valeurs existantes, définissez replace sur true.

L'exemple .routing.pathMatchers[].routeRules[].headerAction suivant illustre l'ajout et la suppression d'en-têtes dans un EdgeCacheService :

gcloud edge-cache services describe prod-media-service

routeRules:
- priority: 1
  description: "video routes"
  matchRules:
  - prefixMatch: "/video/"
  headerAction:
    responseHeadersToAdd:
      # Return the IATA (airport) code(s) nearest the cache node(s) that served
      # the response
      - headerName: "cache-id"
        headerValue: "{cdn_cache_id}"
        replace: true
      # Return how the response was served - for example, "MISS, HIT"
      - headerName: "x-cache-status"
        headerValue: "{cdn_cache_status}"
    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"

Cet exemple :

Ajoute un en-tête Cache-ID personnalisé à la réponse (en utilisant la variable {cdn_cache_id}) pour afficher l'ID de cache (ou les ID, en cas de remplissage à plusieurs niveaux) utilisé pour répondre à la requête.
Ajoute un en-tête x-downstream-cdn personnalisé à la requête à l'aide d'une chaîne statique.
Supprime deux en-têtes internes.

Variables d'en-tête dynamiques

Les en-têtes de réponse acceptent les variables personnalisées, identiques à celles compatibles avec Cloud CDN et l'équilibrage de charge HTTP(S).

La liste des variables acceptées est définie comme suit :

Variable	Description
cdn_cache_id	Code d'emplacement et ID de l'instance de cache utilisée pour diffuser la requête. Il s'agit de la même valeur que celle indiquée dans le champ `jsonPayload.cacheId` des journaux de requêtes Cloud CDN dans Logging.
cdn_cache_status	État actuel du cache. Les valeurs reflètent l'état de la réponse mise en cache et le niveau de cache à partir duquel elle a été diffusée (le cas échéant).
origin_request_header	Correspond à la valeur de l'en-tête d'origine dans la requête pour les cas d'utilisation CORS (Cross-Origin Resource Sharing).
client_rtt_msec	Temps de transmission aller-retour estimé entre l'équilibreur de charge et le client HTTP(S), en millisecondes. Il s'agit du paramètre de temps d'aller-retour lissé (SRTT, Smoothed Round-Trip Time) mesuré par la pile TCP de l'équilibreur de charge, conformément à la RFC 2988.
client_region	Pays (ou région) associé à l'adresse IP du client. Il s'agit d'un code de région CLDR au format Unicode, tel que `US` ou `FR`. Pour la plupart des pays, ces codes correspondent directement aux codes ISO-3166-2.
client_region_subdivision	Subdivision (une province ou un État, par exemple) du pays associée à l'adresse IP du client. Il s'agit d'un ID de subdivision CLDR au format Unicode, tel que `USCA` ou `CAON`. (Ces codes Unicode sont dérivés des subdivisions définies par la norme ISO-3166-2.)
client_city	Nom de la ville d'origine de la requête, par exemple `Mountain View` pour Mountain View en Californie. Il n'existe pas de liste canonique de valeurs valides pour cette variable. Les noms de villes peuvent contenir des lettres, des chiffres et des espaces au format US-ASCII, ainsi que les caractères suivants : !#$%&'*+-.^_`\|~.
client_city_lat_long	Latitude et longitude de la ville d'origine de la requête, par exemple `37.386051,-122.083851` pour une requête provenant de Mountain View.
tls_sni_hostname	Indication du nom du serveur (telle que définie dans la RFC 6066), si ce nom est fourni par le client lors du handshake TLS ou QUIC. Le nom d'hôte est converti en minuscules et tous les points se trouvant à la fin du nom sont supprimés.
tls_version	Version de TLS négociée entre le client et l'équilibreur de charge lors du handshake SSL. Les valeurs possibles sont `TLSv1`, `TLSv1.1`, `TLSv1.2` et `TLSv1.3`. Si le client se connecte à l'aide de QUIC au lieu de TLS, la valeur est QUIC.
tls_cipher_suite	Suite de chiffrement négociée lors du handshake TLS. La valeur se compose de quatre chiffres hexadécimaux définis par le Registre des suites de chiffrement TLS de l'IANA. Par exemple, `009C` correspond à TLS_RSA_WITH_AES_128_GCM_SHA256. Cette valeur est vide pour QUIC et pour les connexions clientes non chiffrées.

Les en-têtes de requêtes et de réponses existants sont conservés, à l'exception des suivants, qui sont supprimés :

X-User-IP
Tous les en-têtes avec X-Google ou X-GFE

Autres caractéristiques :

Les clés et les valeurs d'en-tête doivent être conformes à la RFC 7230, les formats obsolètes n'étant pas acceptés.
Toutes les clés d'en-tête sont en minuscules (conformément à la norme HTTP/2).
Certains en-têtes sont fusionnés. Lorsqu'il existe plusieurs instances de la même clé d'en-tête (par exemple, Via), l'équilibreur de charge combine leurs valeurs dans une même liste d'éléments séparés par des virgules correspondant à une clé d'en-tête unique. Seuls les en-têtes dont les valeurs peuvent être représentées sous la forme d'une liste d'éléments séparés par des virgules sont fusionnés. Les autres en-têtes, tels que Set-Cookie, ne sont jamais fusionnés.
Certains en-têtes sont ajoutés ou des valeurs leur sont ajoutées. Les équilibreurs de charge HTTP(S) externes ajoutent ou modifient toujours certains en-têtes, tels que Via et X-Forwarded-For.
Media CDN développe tout en-tête de réponse contenant une variable compatible, même s'il est défini par le client ou l'origine. Cela vous permet de définir des en-têtes dynamiques provenant de votre client (tel qu'un lecteur vidéo) ou de votre infrastructure d'origine, en plus de configurer des en-têtes personnalisés. Media CDN ne développe pas les variables sur le chemin d'accès de la requête.

Valeurs d'état de cache

La variable d'en-tête {cdn_cache_status} peut renvoyer plusieurs valeurs correspondant au niveau de cache qui a diffusé la réponse.

Valeur	Description
HIT	La réponse mise en cache a été entièrement diffusée à partir du cache.
MISS	La réponse n'était pas dans le cache.
PARTIAL	La réponse a été partiellement diffusée à partir du cache. Dans le cas d'objets volumineux (2 Mo ou plus), cela signifie que seuls des octets partiels étaient disponibles dans le cache et qu'une requête de plage HTTP a été effectuée pour remplir le reste de la réponse demandée.
REVALIDATED	La réponse était présente dans le cache, mais une revalidation était nécessaire avec l'origine avant la diffusion.
BYPASSED	Le cache a été ignoré. Cela se produit lorsque le paramètre `cdnPolicy.cacheMode` d'une route donnée est défini sur `BYPASS_CACHE`, par exemple lors du débogage.
UNCACHEABLE	La réponse n'a pas pu être diffusée à partir du cache et a été récupérée directement à partir de l'origine. Cela peut se produire si la réponse n'inclut pas d'instructions de cache valides, est trop grande pour la mise en cache ou n'est pas un type de contenu pouvant être mis en cache, selon la configuration `cdnPolicy.cacheMode`. Le champ `cache_details` du journal de requête correspondant contient la raison.

Chaque niveau de cache du chemin de réponse (le cas échéant) est ajouté à la valeur d'en-tête.

Exemples :

Si une réponse de cache n'était pas disponible dans le cache le plus proche de l'utilisateur, mais qu'elle était disponible dans le niveau suivant, cdn_cache_status est défini sur HIT, MISS.
Si la réponse de cache n'était pas disponible dans les deux premiers niveaux de cache et qu'un fragment partiel de la réponse était disponible dans le cache, le cdn_cache_status est PARTIAL, MISS, MISS.

Pour les requêtes et les réponses pour lesquelles BYPASSED et UNCACHEABLE s'appliquent, vous ne voyez qu'une seule valeur dans le champ cdn_cache_status, car ces valeurs s'appliquent à tous les niveaux de cache.

En-têtes par défaut

Media CDN ajoute respectivement les en-têtes de requête et de réponse suivants aux requêtes d'origine et aux réponses du client, respectivement :

En-tête	Détails	Requête	Réponse
x-request-id	Un identifiant unique de la requête en question. Cette valeur est également ajoutée au journal de requêtes en tant que `jsonPayload.requestId`, ce qui vous permet de mettre en corrélation une requête/réponse client avec une entrée de journal.		✔
age	Renvoie l'âge de l'objet mis en cache (nombre de secondes de présence dans le cache). L'âge est généralement calculé en fonction du moment où l'objet a été initialement mis en cache dans un emplacement de cache en longue traîne (protection d'origine). Les réponses sans en-tête "Age" ne sont pas diffusées à partir du cache.		✔
via	Identifie Google comme proxy intermédiaire. Défini sur `1.1 google` et non modifiable.	✔	✔
server	Cette valeur est définie sur `Google-Edge-Cache`.		✔
cdn-loop	Identifie les boucles ou "loops", par exemple lorsque l'hôte d'origine est identique à l'hôte visible par l'utilisateur (périphérie). Un jeton de `google` est ajouté à l'en-tête conformément à la RFC 8586. Le jeton ne peut pas être modifié.	✔
forwarded	La version structurée de l'en-tête `x-forwarded-for`. L'en-tête `forwarded` est défini dans la RFC 7239. Ces en-têtes vous permettent d'identifier l'adresse IP du client qui se connecte lorsqu'un ou plusieurs proxys sont présents dans le chemin. Par exemple, si un client avec l'adresse IP `192.0.2.60` se connecte à Media CDN via HTTPS, l'en-tête `forwarded` est renseigné comme suit : `forwarded: [for=192.0.2.60;proto=https]` Dans le cas de proxys multiples côté client, le client qui s'est connecté à Media CDN est la dernière adresse ajoutée dans la valeur d'en-tête.	✔
x-forwarded-for	La version standard de facto et non structurée de l'en-tête `forwarded`. Les valeurs sont généralement séparées par des virgules. Les deux en-têtes sont envoyés dans une requête pour assurer la compatibilité avec les anciennes origines qui peuvent ne pas reconnaître l'en-tête `forwarded`.	✔

Les clés d'en-tête sont en minuscules pour les en-têtes de requête et de réponse, car elles ne sont pas sensibles à la casse.

D'autres en-têtes, notamment l'emplacement du POP de périphérie et l'état du cache (HIT ou MISS, par exemple), peuvent être ajoutés via des variables d'en-tête dynamiques.