オリジン変更のヘルパーメソッド - Amazon CloudFront
CloudFront Functions と Lambda@Edge のどちらかを選択するupdateRequestOrigin() メソッドselectRequestOriginById() メソッドcreateRequestOriginGroup() メソッド

オリジン変更のヘルパーメソッド

このセクションは、CloudFront Functions コード内のリクエストで使用されているオリジンを動的に更新または変更する場合に適用されます。オリジンは、ビューワーリクエスト CloudFront Functions でのみ更新できます。CloudFront Functions には、オリジンを動的に更新または変更するためのヘルパーメソッドを提供するモジュールがあります。

このモジュールを使用するには、JavaScript ランタイム 2.0 を使用して CloudFront 関数を作成し、関数コードの最初の行に次のステートメントを含めます。

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 関数が既にある場合。オリジン更新ロジックを既存の関数内に追加できます。

CloudFront Functions を使用してオリジンを更新するには、以下のトピックでヘルパーメソッドを参照してください。

Lambda@Edge は、以下の場合に最も役立ちます。

  • 高度にキャッシュ可能なコンテンツがある場合。CloudFront Functions はすべてのリクエストで実行されるのに対して、Lambda@Edge はキャッシュミス時にのみ実行されるため、コスト効率が向上します。

  • 既存のオリジンリクエスト Lambda@Edge 関数が既にある場合。オリジン更新ロジックを既存の関数内に追加できます。

  • オリジン更新ロジックで、Amazon DynamoDB や Amazon S3 など、サードパーティのデータソースからデータを取得する必要がある場合。

Lambda@Edge の詳細については、「Lambda@Edge を使用してエッジでカスタマイズする」を参照してください。

updateRequestOrigin() メソッド

updateRequestOrigin() メソッドは、リクエストのオリジン設定を更新するために使用します。このメソッドを使用して、ディストリビューションで既に定義されているオリジンの既存のオリジンプロパティを更新したり、リクエストの新しいオリジンを定義したりできます。これを行うには、変更するプロパティを指定します。

重要

updateRequestOrigin() で指定しない設定は、既存のオリジンの設定から同じ設定を継承します。

updateRequestOrigin() メソッドで設定するオリジンは、任意の HTTP エンドポイントが可能であり、CloudFront ディストリビューション内の既存のオリジンである必要はありません。

メモ

  • オリジングループの一部であるオリジンを更新する場合、オリジングループのプライマリオリジンのみが更新されます。セカンダリオリジンは変更されません。フェイルオーバー条件に一致する変更されたオリジンからのレスポンスコードは、セカンダリオリジンへのフェイルオーバーをトリガーします。

  • オリジンタイプを変更し、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 設定が使用されます。

レガシーオリジンアクセスアイデンティティ (OAI) はサポートされていません。詳細については、「AWS オリジンへのアクセスを制限する」を参照してください。

enabled (必須）

OAC を有効または無効にするブール式。値として true または false を使用します。

signingBehavior (有効にする場合は必須）

CloudFront が署名する (認証情報を追加する) リクエストを指定します。最も一般的なユースケースには always を指定します。詳細については、「オリジンアクセスコントロールの詳細設定」を参照してください。

このフィールドには以下の値のいずれかがあります。

  • always - CloudFront はすべてのオリジンリクエストに署名し、ビューワーリクエストの Authorization ヘッダーが存在する場合は上書きします。

  • never - CloudFront はオリジンリクエストに署名しません。この値は、オリジンのオリジンアクセスコントロールをオフにします。

  • no-override - ビューワーリクエストに Authorization ヘッダーが含まれていない場合、CloudFront はオリジンリクエストに署名します。ビューワーリクエストに Authorization ヘッダーが含まれている場合、CloudFront はオリジンリクエストに署名せず、代わりにビューワーリクエストから Authorization ヘッダーを渡します。

    警告

    ビューワーリクエストから Authorization ヘッダーを渡すには、このオリジンアクセスコントロールに関連付けられているオリジンを使用するすべてのキャッシュ動作で、このヘッダーをオリジンリクエストポリシーに追加する必要があります。詳細については、「ポリシーを使用してオリジンリクエストを制御する」を参照してください。

signingProtocol (有効にする場合は必須）

OAC の署名プロトコル。CloudFront でリクエストを署名 (認証) する方法を決定します。唯一の有効な値は sigv4 です。

originType (有効にする場合は必須）

この OAC のオリジンのタイプ。有効な値は、s3、mediapackagev2、mediastore、および lambda です。

timeouts (オプション)

CloudFront がオリジンからの応答やデータ送信を待機する時間を指定できるタイムアウト。これを指定しない場合、割り当てられたオリジンのタイムアウト設定が使用されます。

readTimeout (オプション）

タイムアウトはカスタムオリジンにのみ適用され、Amazon S3 オリジンには適用されません (S3 オリジン設定では、これらの設定は無視されます)。readTimeout は、次の両方の値に適用されます。

  • CloudFront がリクエストをオリジンに転送してからレスポンスを受け取るまでの待機時間 (秒)

  • CloudFront がオリジンからレスポンスのパケットを受け取ってから次のパケットを受け取るまでの待機時間 (秒)

最小のタイムアウトは 1 秒、最大は 60 秒です。詳細については、「レスポンスタイムアウト (カスタムオリジンおよび VPC オリジンのみ)」を参照してください。

keepAliveTimeout (オプション）

タイムアウトはカスタムオリジンにのみ適用され、Amazon S3 オリジンには適用されません (S3 オリジン設定では、これらの設定は無視されます)。keepAliveTimeout は、レスポンスの最後のパケットを受信した後、CloudFront がオリジンへの接続を維持しようとする時間を指定します。最小のタイムアウトは 1 秒、最大は 60 秒です。詳細については、「キープアライブタイムアウト (カスタムオリジンおよび VPC オリジンのみ)」を参照してください。

connectionTimeout (オプション）

オリジンへの接続を確立しようとするときに CloudFront が待機する秒数。最小のタイムアウトは 1 秒、最大は 10 秒です。詳細については、「接続タイムアウト」を参照してください。

customOriginConfig (オプション）

customOriginConfig を使用して、Amazon S3 バケットではないオリジンの接続設定を指定します。1 つの例外があります。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() を使用して、高可用性を必要とするシナリオでフェイルオーバー用のオリジングループとして使用する 2 つのオリジンを定義します。

オリジングループには、2 つのオリジン (プライマリとセカンダリ) と指定したフェイルオーバー基準が含まれます。CloudFront でオリジンフェイルオーバーをサポートするオリジングループを作成します。このメソッドを使用してオリジングループを作成または更新する際に、単一のオリジンではなくオリジングループを指定できます。CloudFront は、フェイルオーバー基準を使用して、プライマリオリジンからセカンダリオリジンにフェイルオーバーします。

ディストリビューションに VPC オリジンが設定されている場合は、このメソッドを使用して、VPC オリジンを使用したオリジングループを作成できます。詳細については、「VPC オリジンを使用したアクセス制限」を参照してください。

リクエスト

createRequestOriginGroup({origin_group_properties})

上記の例で、origin_group_properties には以下を含めることができます。

originIds (必須）

origin_ids の配列。origin_id は、関数を実行するディストリビューション内のオリジンのオリジン名を指す文字列です。配列の一部として 2 つのオリジンを指定する必要があります。リストの最初のオリジンはプライマリオリジンで、2 番目のオリジンはフェイルオーバー用のセカンダリオリジンとして機能します。

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] 
    }
});