커스텀 헤더 정의

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

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

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

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

커스텀 헤더 설정

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

캐싱 결정 전에 CDN 처리 경로 초기에 경로별 커스텀 요청 헤더를 설정합니다. 예를 들어 cache-control 헤더를 경로별 맞춤 헤더로 설정하면 CDN의 캐싱 동작에 영향을 미칩니다.

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

기존 값을 덮어쓰려면 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)를 포함하여 다른 헤더는 동적 헤더 변수를 사용하여 추가할 수 있습니다.