커스텀 헤더 정의

Media CDN을 사용하면 커스텀 요청 및 응답 헤더를 지정할 수 있습니다.

커스텀 헤더를 사용하면 다음을 수행할 수 있습니다.

• 국가, 리전, 도시와 같이 지역화된 콘텐츠를 표시하는 데 사용할 수 있는 클라이언트에 대한 지리적 데이터를 반환합니다.
• 캐시에서 응답이 제공되었는지 여부(전체 또는 일부) 그리고 제공된 캐시 위치를 확인합니다.
• 요청 및 응답 헤더 모두를 삭제, 대체, 추가합니다.

또한 헤더를 사용해서 요청을 다른 원본으로 라우팅할 수 있습니다. 교차 출처 리소스 공유(CORS) 헤더를 구성해야 하면 각 경로에 대해 CORS 정책을 구성합니다.

커스텀 헤더 설정

헤더가 각 경로에 설정되어 매니페스트 또는 동영상 세그먼트와 같은 여러 콘텐츠에 대해 헤더를 추가 및 삭제할 수 있습니다.

기본적으로 추가한 헤더 값은 쉼표로 구분되고 동일한 필드 이름의 응답 또는 요청 헤더에 추가됩니다.

기존 값을 덮어쓰려면 replace를 true로 설정합니다.

다음 .routing.pathMatchers[].routeRules[].headerAction 예시는 EdgeCacheService 리소스에서 추가 및 삭제된 헤더를 보여줍니다.

gcloud edge-cache services describe prod-media-service

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

이 예시에서는 다음을 수행합니다.

• 클라이언트의 IP 주소와 연결된 국가(또는 리전)를 반환하는 {client_region} 변수를 사용하여 응답에 커스텀 client-geo 헤더를 추가합니다.
• 정적 문자열을 사용해서 요청에 커스텀 x-downstream-cdn 헤더를 추가합니다.
• 2개의 내부 헤더를 삭제합니다.

동적 헤더 변수

커스텀 헤더는 하나 이상의 동적 변수를 포함할 수 있습니다.

캐시 키 정책(cacheKeyPolicy.includedHeaderNames)의 일부인 요청 헤더는 하나 이상의 커스텀 변수를 포함할 수 있습니다. 다른 동적 변수를 포함하는 요청 헤더는 캐시 키의 일부일 수 없습니다.

변수	설명	요청 헤더에 지원됨	캐시 키의 요청 헤더에 지원됨	응답 헤더에 지원됨
cdn_cache_status	요청/응답 경로에서 각 캐시 노드의 위치(가장 가까운 공항의 IATA 코드) 및 상태가 쉼표로 구분된 목록입니다. 여기에서 가장 오른쪽 값은 사용자에게 가장 가까운 캐시를 나타냅니다.			✔
client_city	요청이 시작된 도시의 이름입니다(예: 캘리포니아주 마운틴뷰의 경우 Mountain View). 이 변수에 유효한 값의 표준 목록은 없습니다. 도시 이름에는 US-ASCII 문자, 숫자, 공백, !#$%&'*+-.^_`|~ 문자가 포함될 수 있습니다.	✔		✔
client_city_lat_long	요청이 시작된 도시의 위도와 경도입니다(예: 마운틴뷰에서 요청한 경우 37.386051,-122.083851).	✔		✔
client_region	클라이언트의 IP 주소와 연관된 국가(또는 리전)입니다. US 또는 FR과 같은 유니코드 CLDR 리전 코드입니다. 대부분의 국가에서 이 코드는 ISO-3166-2 코드와 바로 대응합니다.	✔	✔	✔
client_region_subdivision	클라이언트의 IP 주소와 관련된 국가의 구획입니다(예: 주 또는 시/도). 유니코드 CLDR 하위 영역 ID입니다(예: USCA 또는 CAON). 이러한 유니코드 코드는 ISO-3166-2 표준에 정의된 구획에서 파생된 것입니다.	✔	✔	✔
client_rtt_msec	CDN과 HTTP(S) 클라이언트 사이의 예상 왕복 전송 시간(밀리초)입니다. 이는 RFC 2988에 따라 CDN의 TCP 스택으로 측정된 평활 왕복 시간(Smoothed Round Trip Time, SRTT) 매개변수입니다.	✔		✔
device_request_type	클라이언트가 사용 중인 기기 유형입니다. 유효한 값은 DESKTOP, MOBILE, TABLET, SMART_TV, GAME_CONSOLE, WEARABLE, UNDETERMINED입니다.	✔	✔
original_request_id	원래 이 응답을 생성한 요청에 할당된 고유 식별자입니다. 캐시된 응답의 경우 request_id와 다른 경우에만 채워집니다.			✔
origin_name	응답이 프록시된 EdgeCacheOrigin 리소스입니다.			✔
origin_request_header	교차 출처 리소스 공유(CORS) 사용 사례에 대해 요청의 원본 헤더 값을 반영합니다.			✔
proxy_status	응답 경로에 있는 중간 HTTP 프록시의 목록입니다. 이 값은 RFC 9209로 정의됩니다. EdgeCacheService 리소스는 Google-Edge-Cache로 표시됩니다. 원본에서 응답을 가져온 경우 EdgeCacheOrigin 리소스가 Google-Edge-Cache-Origin을 표시됩니다.			✔
tls_sni_hostname	TLS 또는 QUIC 핸드셰이크 중에 클라이언트가 제공한 경우 서버 이름 표시(RFC 6066에 정의된 대로)입니다. 호스트 이름이 소문자로 변환되고 모든 후행 점이 삭제됩니다.	✔		✔
tls_version	SSL 핸드셰이크 중 클라이언트와 부하 분산기 사이에 협상된 TLS 버전입니다. 가능한 값에는 TLSv1, TLSv1.1, TLSv1.2, TLSv1.3이 포함됩니다. 클라이언트가 TLS 대신 QUIC를 사용하여 연결하는 경우에는 값이 QUIC입니다.	✔		✔
tls_cipher_suite	TLS 핸드셰이크 중에 협상된 암호 모음입니다. 값은 IANA TLS 암호화 스위트 레지스트리에서 정의됩니다(예: TLS_RSA_WITH_AES_128_GCM_SHA256). QUIC 및 암호화되지 않은 클라이언트 연결의 경우 이 값은 비어 있습니다.	✔		✔
user_agent_family	클라이언트가 사용 중인 브라우저 제품군입니다. 유효한 값은 APPLE, APPLEWEBKIT, BLACKBERRY, DOCOMO, GECKO, GOOGLE, KHTML, KOREAN, MICROSOFT, MSIE, NOKIA, NETFRONT, OBIGO, OPENWAVE, OPERA, OTHER, POLARIS, TELECA, SEMC, SMIT, USER_DEFINED입니다.	✔	✔

커스텀 변수에는 다음 고려사항이 적용됩니다.

• 삭제되는 다음 항목을 제외하고 기존 요청 및 응답 헤더는 보존됩니다.

  • X-User-IP
  • X-Google 또는 X-GFE가 있는 모든 헤더

• 오래된 양식은 허용되지 않으며 헤더 키와 값은 RFC 7230과 호환되어야 합니다.

• 모든 헤더 키는 소문자로 표시됩니다(HTTP/2 기준).

• 일부 헤더는 병합됩니다. 동일한 헤더 키의 인스턴스가 여러 개인 경우(예: Via) 부하 분산기는 단일 헤더 키의 단일 쉼표로 구분된 목록에 해당 값을 결합합니다. 값이 쉼표로 구분된 목록으로 표시될 수 있는 헤더만 병합됩니다. 다른 헤더(예: Set-Cookie)는 병합되지 않습니다.

• 일부 헤더가 추가되거나 헤더에 값이 추가됩니다. Media CDN은 항상 Via 및 X-Forwarded-For와 같은 특정 헤더를 추가 또는 수정합니다.

• Media CDN은 클라이언트 또는 원본에서 설정되었더라도 지원되는 변수가 있는 모든 응답 헤더를 확장합니다. 이렇게 하면 커스텀 헤더 구성 외에도 클라이언트(예: 동영상 플레이어) 또는 원본 인프라에서 동적 헤더를 설정할 수 있습니다. Media CDN은 요청 경로의 변수를 확장하지 않습니다.

• 예를 들어 앞에서 설명한 규칙에 따라 X-Goog- 및 X-Amz- 헤더가 보존되고 소문자로 변환됩니다.

캐시 상태 값

{cdn_cache_status} 헤더 변수는 응답을 제공한 캐시 계층에 따라 여러 값을 반환할 수 있습니다. {cdn_cache_status} 헤더 변수를 해석하기 위한 다음 가이드라인을 고려하세요.

• 헤더에 hit가 포함된 경우 요청된 콘텐츠가 캐시에서 검색됩니다.
• 헤더에 miss가 포함된 경우 요청된 콘텐츠를 캐시 노드에서 찾을 수 없고 업스트림 노드에서 검색해야 합니다.
• 헤더에 fetch가 포함된 경우 요청된 콘텐츠가 원본에서 검색됩니다.

• 헤더에 uncacheable이 포함되었으면 요청된 콘텐츠가 캐싱 인프라의 일부 또는 모든 구성요소에서 캐시 불가능한 것으로 고려됩니다.

  • 또한 헤더에 hit 또는 miss가 포함되었으면 요청된 콘텐츠가 일부 캐싱 구성요소에서 캐시 불가능하고 다른 구성요소에서는 캐시 가능한 것으로 고려됩니다.
  • 또한 헤더에 hit 또는 miss가 포함되지 않았으면 요청된 콘텐츠가 모든 캐싱 구성요소에서 캐시 불가능한 것으로 고려되고 이 콘텐츠의 모든 요청을 원본에서 가져옵니다. 콘텐츠가 적절하게 캐시되었는지 확인하려면 Media CDN 원본 요구사항을 검토합니다.

기본 헤더

Media CDN은 다음 요청 및 응답 헤더를 각각 원본 요청과 클라이언트 응답에 추가합니다.

헤더	설명	요청	응답
x-request-id	지정된 요청의 고유 식별자입니다. 이 값은 또한 요청 로그에 jsonPayload.requestId로 추가됩니다. 이를 통해 로그 항목에 대해 클라이언트 요청/응답을 일치시킬 수 있습니다.		✔
age	캐시된 객체의 기간(캐시에 머무른 초 단위 시간)을 반환합니다. 일반적으로 기간은 롱테일(보호) 캐시 위치에서 객체가 처음 캐시되었을 때를 기준으로 계산됩니다. age 헤더가 없는 응답은 캐시에서 제공되지 않습니다.		✔
via	Google을 중간 프록시로 식별합니다. 1.1 google로 설정되며 변경할 수 없습니다.	✔	✔
server	Google-Edge-Cache로 설정됩니다.		✔
cdn-loop	루프를 식별합니다. 예를 들어 원본 호스트가 사용자 대상(에지) 호스트와 동일한 위치입니다. google 토큰은 RFC 8586에 따라 헤더에 추가됩니다. 토큰은 변경할 수 없습니다.	✔
forwarded	x-forwarded-for 헤더의 구조화된 버전입니다. forwarded 헤더는 RFC 7239에 정의됩니다. 이러한 헤더를 사용하면 프록시가 경로에 있을 때 연결 중인 클라이언트의 IP 주소를 식별할 수 있습니다. 예를 들어 IP 주소가 192.0.2.60인 클라이언트가 HTTPS를 통해 Media CDN에 연결할 경우 forwarded 헤더가 다음과 같이 채워집니다. forwarded: [for=192.0.2.60;proto=https] 클라이언트 측 프록시가 여러 개 있으면 Media CDN에 연결된 클라이언트가 헤더 값에 추가된 마지막 주소입니다.	✔
x-forwarded-for	forwarded 헤더의 구조화되지 않은 사실상의 표준 버전입니다. 값은 일반적으로 쉼표로 구분됩니다. 두 헤더 모두 forwarded 헤더를 인식하지 못할 수 있는 기존 원점을 지원하기 위해 요청에서 전송됩니다.	✔

헤더 키는 대소문자를 구분하지 않기 때문에 요청 및 응답 헤더 모두 소문자로 변환됩니다.

에지 접속 지점(PoP) 위치와 캐시 상태(예: hit 및 miss)를 포함하여 다른 헤더는 동적 헤더 변수를 사용하여 추가할 수 있습니다.