오리진 수정용 헬퍼 메서드 - Amazon CloudFront
CloudFront Functions과 Lambda@Edge 중에서 선택updateRequestOrigin() 메서드selectRequestOriginById() 메서드createRequestOriginGroup() 메서드

오리진 수정용 헬퍼 메서드

이 섹션은 CloudFront Functions 코드 내에서 요청에 사용되는 오리진을 동적으로 업데이트하거나 변경하는 경우에 적용됩니다. 뷰어 요청 CloudFront Functions에서만 오리진을 업데이트할 수 있습니다. CloudFront Functions에는 오리진을 동적으로 업데이트하거나 변경하는 헬퍼 메서드를 제공하는 모듈이 있습니다.

이 모듈을 사용하려면 JavaScript 런타임 2.0을 사용하여 CloudFront Functions을 만들고 함수 코드의 첫 번째 줄에 다음 스테이트먼트를 포함합니다.

import cf from 'cloudfront';

자세한 내용은 CloudFront Functions를 위한 JavaScript 런타임 2.0 기능 섹션을 참조하세요.

참고

테스트 API 및 테스트 콘솔 페이지에서는 오리진 수정이 발생했는지 여부를 테스트하지 않습니다. 그러나 테스트는 함수 코드가 오류 없이 실행되도록 합니다.

CloudFront Functions과 Lambda@Edge 중에서 선택

CloudFront Functions 또는 Lambda@Edge를 사용하여 오리진을 업데이트할 수 있습니다.

CloudFront Functions을 사용하여 오리진을 업데이트할 때 뷰어 요청 이벤트 트리거를 사용합니다. 즉, 이 함수가 사용될 때 해당 로직이 모든 요청에서 실행됩니다. Lambda@Edge를 사용하는 경우 오리진 업데이트 기능은 오리진 요청 이벤트 트리거에 존재합니다. 즉, 이 로직은 캐시 누락에서만 실행됩니다.

주로 워크로드와 배포에서 CloudFront Functions 및 Lambda@Edge의 기존 사용량에 따라 선택이 달라집니다. 다음 고려 사항을 통해 CloudFront Functions 또는 Lambda@Edge를 사용하여 오리진을 업데이트할지 여부를 결정할 수 있습니다.

CloudFront Functions은 다음과 같은 상황에서 가장 유용합니다.

  • 요청이 동적(즉, 캐싱할 수 없음)이고 항상 오리진으로 이동하는 경우입니다. CloudFront Functions은 더 나은 성능과 더 낮은 전체 비용을 제공합니다.

  • 각 요청에서 실행되는 기존 뷰어 요청 CloudFront Functions이 이미 있는 경우 기존 함수에 오리진 업데이트 로직을 추가할 수 있습니다.

CloudFront Functions을 사용하여 오리진을 업데이트하려면 다음 주제의 헬퍼 메서드를 참조하시기 바랍니다.

Lambda@Edge는 다음과 같은 상황에서 가장 유용합니다.

  • 캐싱 가능성이 높은 콘텐츠가 있으면 Lambda@Edge는 캐시 누락 시에만 실행되고 CloudFront Functions은 모든 요청 시 실행되므로 더 비용 효율적일 수 있습니다.

  • 기존 오리진 요청 Lambda@Edge 함수가 이미 있는 경우 오리진 업데이트 로직을 기존 함수에 추가할 수 있습니다.

  • 오리진 업데이트 로직에서 Amazon DynamoDB 또는 Amazon S3와 같은 서드 파티 데이터 소스에서 데이터를 가져와야 하는 경우입니다.

Lambda@Edge에 대한 자세한 내용은 Lambda@Edge를 사용하여 엣지에서 사용자 지정 섹션을 참조하시기 바랍니다.

updateRequestOrigin() 메서드

updateRequestOrigin() 메서드를 사용하여 요청의 오리진 설정을 업데이트합니다. 이 메서드를 사용하여 배포에 이미 정의된 오리진의 기존 오리진 속성을 업데이트하거나 요청에 대한 새 오리진을 정의할 수 있습니다. 이렇게 하려면 변경하려는 속성을 지정합니다.

중요

updateRequestOrigin()에서 지정하지 않은 설정은 기존 오리진의 구성에서 동일한 설정을 상속합니다.

updateRequestOrigin() 메서드에 따라 설정된 오리진은 HTTP 엔드포인트일 수 있으며 CloudFront 배포 내의 기존 오리진일 필요는 없습니다.

Notes

  • 오리진 그룹의 일부인 오리진을 업데이트하는 경우 오리진 그룹의 프라이머리 오리진만 업데이트됩니다. 보조 오리진은 변경되지 않습니다. 장애 조치 기준과 일치하는 수정된 오리진의 모든 응답 코드는 보조 오리진으로 장애 조치를 트리거합니다.

  • 오리진 유형을 변경하고 OAC를 사용 설정한 경우 originAccessControlConfig의 오리진 유형이 새 오리진 유형과 일치하는지 확인합니다.

  • updateRequestOrigin() 메서드를 사용하여 VPC 오리진을 업데이트할 수 없습니다. 요청이 완료되지 않습니다.

요청

updateRequestOrigin({origin properties})

origin properties에는 다음 사항이 포함될 수 있습니다.

domainName(선택 사항)

오리진의 도메인 이름입니다. 이를 제공하지 않으면 대신 할당된 오리진의 도메인 이름이 사용됩니다.

사용자 지정 오리진의 경우

DNS 도메인 이름(예: www.example.com)을 지정합니다. 도메인 이름에는 콜론(:)이 포함될 수 없으며 IP 주소가 될 수 없습니다. 도메인 이름은 최대 253자일 수 있습니다.

S3 오리진의 경우

Amazon S3 버킷의 DNS 도메인 이름(예: amzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com)을 지정합니다. 이름은 최대 128자여야 하며, 모두 소문자여야 합니다.

originPath(선택 사항)

요청이 콘텐츠를 찾아야 하는 오리진의 디렉터리 경로입니다. 경로는 슬래시(/)로 시작해야 하지만 슬래시 하나로 끝나지 않아야 합니다. 예를 들어 example-path/로 끝나지 않아야 합니다. 이를 제공하지 않으면 할당된 오리진의 오리진 경로가 사용됩니다.

사용자 지정 오리진의 경우

경로는 URL 인코딩되어야 하고 최대 255자여야 합니다.

customHeaders(선택 사항)

각 사용자 지정 헤더에 대한 헤더 이름 및 값 페어를 지정하여 요청을 포함한 사용자 지정 헤더를 포함할 수 있습니다. 형식은 이벤트 구조에서 요청 및 응답 헤더의 형식과 다릅니다. 다음의 키/값 쌍 구문을 사용합니다.

{"key1": "value1", "key2": "value2", ...}

허용되지 않는 헤더는 추가할 수 없으며 동일한 이름의 헤더가 수신되는 요청 headers에 존재할 수 없습니다. 헤더 이름은 함수 코드에서 소문자여야 합니다. CloudFront Functions이 이벤트 객체를 HTTP 요청으로 다시 변환하는 경우 헤더 이름에 있는 각 단어의 첫 글자가 대문자로 표시됩니다. 단어는 하이픈으로 구분됩니다.

예를 들어 함수 코드가 example-header-name이라는 이름의 헤더를 추가하는 경우, CloudFront는 이 헤더를 HTTP 요청에서 Example-Header-Name으로 변환합니다. 자세한 내용은 CloudFront에서 오리진 요청에 추가할 수 없는 사용자 지정 헤더 및 엣지 함수에 대한 제한 사항(을)를 참조하세요.

이를 제공하지 않으면 할당된 오리진의 사용자 지정 헤더가 사용됩니다.

connectionAttempts(선택 사항)

CloudFront가 오리진에 연결을 시도하는 횟수입니다. 최솟값은 1이고, 최댓값은 3입니다. 이를 제공하지 않으면 할당된 오리진을 통해 연결 시도가 사용됩니다.

originShield(선택 사항)

이렇게 하면 CloudFront Origin Shield가 사용 설정되거나 업데이트됩니다. Origin Shield를 사용하면 오리진의 부하를 줄일 수 있습니다. 자세한 내용은 Amazon CloudFront Origin Shield 사용 섹션을 참조하세요. 이를 제공하지 않으면 할당된 오리진을 통해 Origin Shield 설정이 사용됩니다.

enabled(필수)

Origin Shield를 사용 또는 사용 해제하는 부울 표현식입니다. true 또는 false 값을 허용합니다.

region(사용 설정된 경우 필수)

Origin Shield의 AWS 리전입니다. 오리진에 대한 지연 시간이 가장 낮은 AWS 리전을 지정합니다. 리전 이름이 아닌 리전 코드를 사용합니다. 예를 들어 us-east-2를 사용하여 미국 동부(오하이오) 리전을 지정합니다.

CloudFront Origin Shield를 사용하는 경우 이에 대한 AWS 리전을 지정해야 합니다. 사용 가능한 AWS 리전 목록과 오리진에 가장 적합한 리전을 선택하는 데 도움이 되는 목록은 Origin Shield의 AWS 리전 선택 섹션을 참조하시기 바랍니다.

originAccessControlConfig(선택 사항)

해당 오리진에 대한 원본 액세스 제어(OAC)의 고유한 식별자입니다. 이는 오리진이 Amazon S3, Lambda 함수 URL, MediaStore, MediaPackage V2 등 CloudFront OAC를 지원하는 경우에만 사용됩니다. 이를 제공하지 않으면 할당된 오리진의 OAC 설정이 사용됩니다.

이는 레거시 오리진 액세스 ID(OAI)를 지원하지 않습니다. 자세한 내용은 AWS 오리진에 대한 액세스 제한 섹션을 참조하세요.

enabled(필수)

OAC를 사용 또는 사용 해제하는 부울 표현식입니다. true 또는 false 값을 허용합니다.

signingBehavior(사용 설정된 경우 필수)

CloudFront가 서명(인증 정보 추가)하는 요청을 지정합니다. 대부분의 사용 사례에서 always를 지정합니다.. 자세한 내용은 오리진 액세스 제어를 위한 고급 설정 섹션을 참조하세요.

이 필드는 다음 값 중 하나를 가질 수 있습니다.

  • always - CloudFront가 모든 오리진 요청을 서명하고, 최종 사용자 요청으로부터 Authorization 헤더를 덮어씁니다(있는 경우).

  • never - CloudFront가 오리진 요청을 서명하지 않습니다. 이 값은 오리진에 대한 오리진 액세스 제어를 끕니다.

  • no-override - 뷰어 요청에 Authorization 헤더가 포함되지 않은 경우 CloudFront가 오리진 요청을 서명합니다. 뷰어 요청에 Authorization 헤더가 포함된 경우 CloudFront가 오리진 요청에 서명하지 않고 최종 사용자 요청의 Authorization 헤더와 함께 전달합니다.

    주의

    뷰어 요청에서 Authorization 헤더를 전달하려면 이 오리진 액세스 제어와 연결된 오리진을 사용하는 모든 캐시 동작에 대한 해당 헤더를 오리진 요청 정책에 추가해야 합니다. 자세한 내용은 정책을 통한 오리진 요청 제어 섹션을 참조하세요.

signingProtocol(사용 설정된 경우 필수)

CloudFront가 요청을 서명(인증)하는 방법을 결정하는 OAC의 서명 프로토콜입니다. 유일한 유효 값은 sigv4입니다.

originType(사용 설정된 경우 필수)

이 OAC의 오리진 유형입니다. 유효한 값에는 s3, mediapackagev2, mediastore 및 lambda 등이 있습니다.

timeouts(선택 사항)

CloudFront가 오리진이 응답하거나 데이터를 전송할 때까지 대기해야 하는 기간에 대해 지정할 수 있는 제한 시간입니다. 이를 제공하지 않으면 할당된 오리진의 제한 시간 설정이 사용됩니다.

readTimeout(선택 사항)

제한 시간은 Amazon S3 오리진이 아닌 사용자 지정 오리진에만 적용됩니다. (S3 오리진 구성은 이러한 설정을 무시합니다.) readTimeout은 다음 두 값 모두에 적용됩니다.

  • CloudFront가 오리진에 요청을 전달한 후 응답을 기다리는 시간(초).

  • CloudFront가 오리진으로부터 응답 패킷을 수신한 후 다음 패킷을 수신할 때까지 대기하는 시간(초).

최소 제한 시간은 1초이고, 최대 제한 시간은 120초입니다. 자세한 내용은 응답 제한 시간(사용자 지정 및 VPC 오리진만 해당) 섹션을 참조하세요.

keepAliveTimeout(선택 사항)

제한 시간은 Amazon S3 오리진이 아닌 사용자 지정 오리진에만 적용됩니다. (S3 오리진 구성은 이러한 설정을 무시합니다.) keepAliveTimeout은 응답의 마지막 패킷을 수신한 후 CloudFront가 오리진에 대한 연결을 유지하려고 시도하는 시간을 지정합니다. 최소 제한 시간은 1초이고, 최대 제한 시간은 120초입니다. 자세한 내용은 연결 유지 제한 시간(사용자 지정 및 VPC 오리진만 해당) 섹션을 참조하세요.

connectionTimeout(선택 사항)

오리진에 대한 연결을 설정하려고 할 때 CloudFront가 대기하는 시간(초)입니다. 최소 제한 시간은 1초이고, 최대 제한 시간은 10초입니다. 자세한 내용은 연결 제한 시간 섹션을 참조하세요.

customOriginConfig(선택 사항)

customOriginConfig를 사용하여 Amazon S3 버킷이 아닌 오리진에 대한 연결 설정을 지정합니다. 한 가지 예외는 다음과 같습니다. S3 버킷이 고정 웹 사이트 호스팅으로 구성된 경우 이러한 설정을 지정할 수 있습니다. (다른 유형의 S3 버킷 구성은 이러한 설정을 무시합니다.) customOriginConfig가 제공되지 않으면 할당된 오리진의 설정이 사용됩니다.

port(필수)

CloudFront가 오리진에 연결하는 데 사용하는 HTTP 포트입니다. 오리진에서 수신 대기하는 HTTP 포트를 지정하십시오.

protocol(필수)

CloudFront가 오리진에 연결하는 데 사용하는 프로토콜(HTTP 또는 HTTPS)을 지정합니다. 유효한 값은 다음과 같습니다.

  • http - CloudFront는 항상 HTTP를 사용하여 오리진에 연결합니다.

  • https - CloudFront는 항상 HTTPS를 사용하여 오리진에 연결합니다.

sslProtocols(필수)

HTTPS를 통해 오리진에 연결할 때 CloudFront에서 사용하는 최소 SSL/TLS 프로토콜을 지정하는 목록입니다. 유효한 값에는 SSLv3, TLSv1, TLSv1.1 및 TLSv1.2 등이 있습니다. 자세한 내용은 최소 오리진 SSL 프로토콜 섹션을 참조하세요.

예 - Amazon S3 요청 오리진 업데이트

다음 예제에서는 뷰어 요청의 오리진을 S3 버킷으로 변경하고 OAC를 사용 설정하며 오리진으로 전송된 사용자 지정 헤더를 재설정합니다.

cf.updateRequestOrigin({
    "domainName" : "amzn-s3-demo-bucket-in-us-east-1.s3.us-east-1.amazonaws.com",
    "originAccessControlConfig": {
        "enabled": true,
        "signingBehavior": "always",
        "signingProtocol": "sigv4",
        "originType": "s3"
    },
    // Empty object resets any header configured on the assigned origin
    "customHeaders": {}
});
예 - Application Load Balancer 요청 오리진 업데이트

다음 예제에서는 뷰어 요청의 오리진을 Application Load Balancer 오리진으로 변경하고 사용자 지정 헤더와 제한 시간을 설정합니다.

cf.updateRequestOrigin({
    "domainName" : "example-1234567890.us-east-1.elb.amazonaws.com",
    "timeouts": {
        "readTimeout": 30,
        "connectionTimeout": 5
    },
    "customHeaders": {
        "x-stage": "production",
        "x-region": "us-east-1"
    }
});
예 - Origin Shield가 사용 설정된 오리진으로 업데이트

다음 예제에서는 배포의 오리진에 Origin Shield가 사용 설정되어 있습니다. 함수 코드는 오리진에 사용되는 도메인 이름만 업데이트하고 다른 모든 선택 사항 파라미터를 생략합니다. 이 경우 Origin Shield 파라미터가 업데이트되지 않았으므로 Origin Shield는 수정된 오리진 도메인 이름과 함께 계속 사용됩니다.

cf.updateRequestOrigin({
    "domainName" : "www.example.com"
});

selectRequestOriginById() 메서드

selectRequestOriginById()를 사용해 배포에 이미 구성된 다른 오리진을 선택하여 기존 오리진을 업데이트합니다. 이 메서드는 업데이트된 오리진에서 정의한 것과 동일한 설정을 모두 사용합니다.

이 메서드는 함수를 실행할 때 사용된 것과 동일한 배포에 이미 정의된 오리진만 허용합니다. 오리진은 오리진을 설정할 때 정의한 오리진 이름인 오리진 ID로 참조됩니다.

배포에 VPC 오리진이 구성된 경우 이 메서드를 사용하여 오리진을 VPC 오리진으로 업데이트할 수 있습니다. 자세한 내용은 VPC 오리진으로 액세스 제한 섹션을 참조하세요.

요청

selectRequestOriginById(origin_id)

앞의 예시에서 origin_id는 함수를 실행하는 배포에서 오리진의 오리진 이름을 가리키는 문자열입니다.

예 - Amazon S3 요청 오리진 선택

다음 예시에서는 배포와 연결된 오리진 목록에서 amzn-s3-demo-bucket-in-us-east-1라는 오리진을 선택하고 amzn-s3-demo-bucket-in-us-east-1 오리진의 구성 설정을 요청에 적용합니다.

cf.selectRequestOriginById("amzn-s3-demo-bucket-in-us-east-1");
예 - Application Load Balancer 요청 오리진 선택

다음 예시에서는 배포와 연결된 오리진 목록에서 myALB-prod라는 Application Load Balancer 오리진을 선택하고 myALB-prod의 구성 설정을 요청에 적용합니다.

cf.selectRequestOriginById("myALB-prod");

createRequestOriginGroup() 메서드

createRequestOriginGroup()를 사용하여 고가용성이 필요한 시나리오에서 장애 조치용 오리진 그룹으로 사용할 두 개의 오리진을 정의합니다.

오리진 그룹에는 두 개의 오리진(프라이머리 및 보조)과 사용자가 지정하는 장애 조치 기준이 포함됩니다. CloudFront에서 오리진 장애 조치를 지원할 오리진 그룹을 생성합니다. 이 메서드를 사용하여 오리진 그룹을 생성하거나 업데이트할 때 단일 오리진 대신 오리진 그룹을 지정할 수 있습니다. CloudFront는 장애 조치 기준을 사용하여 프라이머리 오리진에서 보조 오리진으로 장애 조치를 수행합니다.

배포에 VPC 오리진이 구성된 경우 이 메서드를 통해 VPC 오리진을 사용하여 오리진 그룹을 생성할 수 있습니다. 자세한 내용은 VPC 오리진으로 액세스 제한 섹션을 참조하세요.

요청

createRequestOriginGroup({origin_group_properties})

앞의 예시에서 origin_group_properties에는 다음이 포함될 수 있습니다.

originIds(필수)

origin_ids 배열이며, 여기서 origin_id는 함수를 실행하는 배포에서 오리진의 오리진 이름을 가리키는 문자열입니다. 배열의 일부로 두 개의 오리진을 제공해야 합니다. 목록의 첫 번째 오리진은 프라이머리 오리진이고 두 번째 오리진은 장애 조치를 위한 보조 오리진 역할을 합니다.

selectionCriteria(선택 사항)

default 오리진 장애 조치 기준을 사용할지 아니면 media-quality-score 기반 장애 조치 로직을 사용할지 선택합니다. 유효한 값은 다음과 같습니다.

  • default는 failoverCriteria에 지정된 상태 코드를 기반으로 장애 조치 기준을 사용합니다. 함수에서 selectionCriteria를 설정하지 않으면 default가 사용됩니다.

  • media-quality-score는 미디어 인식 라우팅 기능을 사용할 때 사용됩니다.

failoverCriteria(필수)

프라이머리 오리진에서 반환될 때 CloudFront가 보조 오리진으로 장애 조치하도록 트리거하는 상태 코드 배열입니다. 기존 오리진 그룹을 덮어쓰면 이 배열은 오리진 그룹의 원래 구성에 설정된 모든 장애 조치 상태 코드를 덮어씁니다.

media-quality-score selectionCriteria를 사용하는 경우 CloudFront는 미디어 품질 점수를 기반으로 요청을 라우팅하려고 시도합니다. 선택한 오리진이 이 배열에 설정된 오류 코드를 반환하면 CloudFront는 다른 오리진으로 장애 조치를 수행합니다.

예 - 요청 오리진 그룹 생성

다음 예시에서는 오리진 ID를 사용하여 요청에 대한 오리진 그룹을 생성합니다. 이러한 오리진 ID는 이 함수를 실행하는 데 사용되는 배포의 오리진 그룹 구성에서 가져옵니다.

cf.createRequestOriginGroup({
    originIds: ["us-east-1-s3-origin", "us-west-2-s3-origin"],
    failoverCriteria: {
        statusCodes: [500, 502, 503, 504] 
    }
});