Benutzerdefinierte Header definieren

Mit Media CDN können Sie benutzerdefinierte Anfrage- und Antwortheader angeben. Benutzerdefinierte Anfrageheader unterstützen statische Werte, während benutzerdefinierte Antwortheader sowohl statische als auch dynamische Werte unterstützen.

Mit benutzerdefinierten Headern können Sie:

  • Geografische Daten zum Client zurückgeben, z. B. Land, Region oder Stadt, mit denen Sie lokalisierte Inhalte anzeigen können.
  • Ermitteln, ob eine Antwort vollständig oder teilweise aus dem Cache bereitgestellt wurde und von welchem Cache-Speicherort sie bereitgestellt wurde.
  • Sowohl Anfrage- als auch Antwortheader entfernen oder ersetzen.

Sie können auch Header verwenden, um Anfragen an verschiedene Ursprünge weiterzuleiten, wie in der Dokumentation zum erweiterten Routing beschrieben. Wenn Sie CORS-Header (Cross-Origin Resource Sharing) konfigurieren müssen, konfigurieren Sie für jede Route eine CORS-Richtlinie.

Benutzerdefinierte Header festlegen

Für jede Route werden Header festgelegt, sodass Sie Header für verschiedene Inhalte wie Manifeste oder Videosegmente hinzufügen und entfernen können.

Standardmäßig werden hinzugefügte Headerwerte an die Antwort- oder Anfrageheader mit denselben Feldnamen angehängt. Die hinzugefügten Werte werden durch Kommas getrennt.

Wenn Sie vorhandene Werte überschreiben möchten, setzen Sie replace auf true.

Das folgende Beispiel für .routing.pathMatchers[].routeRules[].headerAction zeigt Header, die in einem EdgeCacheService hinzugefügt und entfernt wurden:

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"

Dieses Beispiel:

  • Fügt der Antwort einen benutzerdefinierten Cache-ID-Header unter Verwendung der {cdn_cache_id}-Variablen hinzu, der die Cache-ID (oder IDs bei einer abgestuften Füllung) anzeigt, die zur Erfüllung der Anfrage verwendet wurde.
  • Fügt der Anfrage mithilfe eines statischen Strings einen benutzerdefinierten x-downstream-cdn-Header hinzu.
  • Entfernt zwei interne Header.

Dynamische Header-Variablen

Antwortheader unterstützen benutzerdefinierte Variablen, die mit denen übereinstimmen, die von Cloud CDN und dem HTTP(S)-Load-Balancing unterstützt werden.

Die Liste der unterstützten Variablen wird so definiert:

Variable Beschreibung
cdn_cache_id Standortcode und ID der Cache-Instanz, die zur Verarbeitung der Anfrage verwendet wurde. Dies ist der gleiche Wert, der im Feld jsonPayload.cacheId der Cloud CDN-Anfragelogs in Logging steht.
cdn_cache_status Aktueller Cache-Status. Die Werte geben den Status der im Cache gespeicherten Antwort zurück und welche Cache-Ebene sie bereitgestellt hat (falls vorhanden).
origin_request_header Zeigt den Wert des Ursprungsheaders in der Anfrage für Anwendungsfälle mit CORS (Cross-Origin Resource Sharing) an.
client_rtt_msec Die geschätzte Übertragungszeit zwischen dem Load-Balancer und dem HTTP(S)-Client in Millisekunden. Dies ist der Parameter der ausgeglichenen Umlaufzeit (Smoothed Round-Trip Time, SRTT), der vom TCP-Stack des Load Balancers gemäß RFC 2988 ermittelt wird.
client_region Das Land oder die Region, das bzw. die der IP-Adresse des Clients zugeordnet ist. Dies ist ein Unicode-CLDR-Regionscode wie US oder FR. Für die meisten Länder entsprechen diese Codes den ISO-3166-2-Codes.
client_region_subdivision Eine Unterteilung des Landes, z. B. eine Region oder ein Bundesstaat, die bzw. der der IP-Adresse des Clients zugeordnet ist. Dies ist eine Unicode-CLDR-Unterteilungs-ID, z. B. USCA oder CAON. Diese Unicode-Codes werden von den durch den ISO-Standard 3166-2 definierten Unterteilungen abgeleitet.
client_city Der Name der Stadt, aus der die Anfrage stammt, z. B. Mountain View für Mountain View, Kalifornien. Für diese Variable gibt es keine offizielle Liste gültiger Werte. Die Namen der Orte können US-ASCII-Buchstaben, Zahlen, Leerzeichen und die folgenden Zeichen enthalten: !#$%&'*+-.^_`|~
client_city_lat_long Der Breiten- und Längengrad des Orts, aus dem die Anfrage stammt, z. B. 37.386051,-122.083851 für eine Anfrage aus Mountain View.
tls_sni_hostname Der Servername (gemäß RFC 6066) für die Bereitstellung vom Client während des TLS- oder QUIC-Handshakes. Der Hostname wird in Kleinbuchstaben konvertiert und alle nachgestellten Punkte werden entfernt.
tls_version Die TLS-Version, die während des SSL-Handshakes zwischen Client und Load-Balancer ausgehandelt wird. Mögliche-Werte sind TLSv1, TLSv1.1, TLSv1.2 und TLSv1.3 Stellt der Client eine Verbindung mit QUIC statt TLS her, so lautet der Wert QUIC.
tls_cipher_suite Die Chiffresammlung, die während des TLS-Handshakes ausgehandelt wird. Der Wert besteht aus vier Hexadezimalziffern, die von der IANA TLS Cipher Suite Registry definiert werden, z. B. 009C für TLS_RSA_WITH_AES_128_GCM_SHA256. Bei QUIC und unverschlüsselten Clientverbindungen ist dieser Wert leer.

Vorhandene Anfrage- und Antwortheader bleiben erhalten, mit Ausnahme der folgenden, die entfernt werden:

  • X-User-IP
  • Alle Header mit X-Google oder X-GFE

Außerdem gilt:

  • Headerschlüssel und -werte müssen RFC 7230 entsprechen. Ältere Formate sind nicht zulässig.
  • Alle Headerschlüssel werden in Kleinbuchstaben geschrieben (pro HTTP/2).
  • Einige Header werden zusammengeführt. Wenn mehrere Instanzen mit demselben Headerschlüssel vorhanden sind, z. B. Via, kombiniert der Load-Balancer deren Werte in einer durch Kommas getrennten Liste zu einem einzelnen Headerschlüssel. Es werden nur Header zusammengeführt, deren Werte als durch Kommas getrennte Liste dargestellt werden können. Andere Header wie Set-Cookie werden nie zusammengeführt.
  • Einige Header werden hinzugefügt oder Werte werden an sie angehängt. Die externen HTTP(S)-Load-Balancer fügen bestimmte Header immer hinzu oder ändern sie, z. B. Via und X-Forwarded-For.
  • Media CDN erweitert jeden Antwortheader mit einer unterstützten Variablen, auch wenn sie vom Client oder vom Ursprung festgelegt wurde. Sie können nicht nur benutzerdefinierte Header, sondern auch von Ihrem Client (z. B. ein Videoplayer) oder Ihrer Ursprungsinfrastruktur festlegen. Media CDN erweitert die Variablen für den Anfragepfad nicht.

Cache-Statuswerte

Die Header-Variable {cdn_cache_status} kann mehrere Werte zurückgeben, die der Cache-Stufe entsprechen, die die Antwort bereitgestellt hat.

Value Beschreibung
HIT Die im Cache gespeicherte Antwort wurde vollständig aus dem Cache bereitgestellt.
MISS Die Antwort befindet sich nicht im Cache.
PARTIAL Die Antwort wurde teilweise aus dem Cache bereitgestellt.

Bei großen Objekten (2 MB oder mehr) bedeutet dies, dass nur ein Teil der Byte im Cache verfügbar war und dass eine HTTP-Bereichsanfrage gestellt wurde, um die übrige angeforderte Antwort zu füllen.

REVALIDATED Die Antwort war im Cache vorhanden, musste jedoch mit dem Ursprung neu validiert werden, bevor sie bereitgestellt wurde.
BYPASSED Der Cache wurde umgangen. Dies tritt auf, wenn der cdnPolicy.cacheMode für eine bestimmte Route auf BYPASS_CACHE gesetzt ist, z. B. beim Debugging.
UNCACHEABLE Die Antwort konnte nicht aus dem Cache bereitgestellt werden und wurde direkt vom Ursprung abgerufen. Dies kann auftreten, wenn die Antwort keine gültigen Cache-Anweisungen enthält, zu groß für den Cache war oder kein cachefähiger Inhaltstyp war, je nach konfiguriertem cdnPolicy.cacheMode.

Das Feld cache_details im entsprechenden Anfragelog enthält den Grund.

Jede Cache-Ebene im Antwortpfad (falls zutreffend) wird an den Headerwert angehängt.

Beispiele:

  • Wenn eine Cache-Antwort nicht in dem Cache verfügbar war, der dem Nutzer am nächsten ist, aber von der nächsten Stufe erfüllt wurde, ist cdn_cache_status HIT, MISS.
  • Wenn die Cache-Antwort in den ersten beiden Cache-Ebenen nicht verfügbar war und nur ein Teil der Antwort im Cache verfügbar war, ist cdn_cache_status PARTIAL, MISS, MISS.

Bei Anfragen und Antworten, bei denen BYPASSED und UNCACHEABLE gelten, wird im cdn_cache_status nur ein Wert angezeigt, da diese Werte für alle Cache-Ebenen gelten.

Standardheader

Media CDN fügt den Ursprungsanfragen bzw. Clientantworten die folgenden Anfrage- und Antwortheader hinzu:

Header Details Anfrage Antwort
x-request-id Eine eindeutige Kennung für die angegebene Anfrage. Dieser Wert wird dem Anfragelog auch als jsonPayload.requestId hinzugefügt, sodass Sie eine Clientanfrage/-antwort mit einem Logeintrag korrelieren können. ✔
age Gibt das Alter des im Cache gespeicherten Objekts zurück (Anzahl der Sekunden, die es sich im Cache befindet). Das Alter wird in der Regel anhand des Zeitpunkts berechnet, zu dem das Objekt ursprünglich in einem Longtail-Cache (Shielded)-Cache gespeichert wurde.

Antworten ohne Header „Age“ werden nicht aus dem Cache bereitgestellt.

✔
via Identifiziert Google als Zwischen-Proxy.

Wird als 1.1 google festgelegt und kann nicht geändert werden.

✔ ✔
server Dies ist auf Google-Edge-Cache festgelegt. ✔
cdn-loop Gibt „Loops“ an, z. B. wenn der Ursprungshost mit dem nutzerseitigen Edge-Host identisch ist.

Ein Token von google wird gemäß RFC 8586 an den Header angehängt. Das Token kann nicht geändert werden.

✔
forwarded Die strukturierte Version des Headers x-forwarded-for. Der Header forwarded ist in RFC 7239 definiert.

Mit diesen Headern können Sie die IP-Adresse des Verbindungsclients identifizieren, wenn sich ein Proxy (oder Proxys) im Pfad befinden. Wenn beispielsweise ein Client mit der IP-Adresse 192.0.2.60 über HTTPS eine Verbindung zu Media CDN herstellt, wird der Header forwarded so ausgefüllt:

forwarded: [for=192.0.2.60;proto=https]

Bei mehreren clientseitigen Proxys ist der Client, der mit Media CDN verbunden ist, die letzte Adresse im Headerwert. 		✔
x-forwarded-for Die unstrukturierte und die De-facto-Standardversion des Headers forwarded. Werte werden normalerweise durch Kommas getrennt.

Beide Header werden in einer Anfrage gesendet, um Legacy-Ursprünge zu unterstützen, die den Header forwarded möglicherweise nicht kennen.

✔

Header-Schlüssel werden sowohl für Anfrage- als auch für Antwort-Header in Kleinbuchstaben geschrieben, da bei Header-Schlüsseln die Groß-/Kleinschreibung nicht berücksichtigt wird.

Andere Header, einschließlich des Edge-POP-Speicherorts und des Cache-Status (z. B. HIT und MISS), können über dynamische Header-Variablen hinzugefügt werden.