CloudFront Functions のテスト機能で HTTP ヘッダー名の大文字・小文字を確認してみた

はじめに

テクニカルサポートの 片方 です。

CloudFront Functions は、CloudFront のエッジロケーションで JavaScript を実行できる機能です。リダイレクト、URL の書き換え、リクエストやレスポンスの HTTP ヘッダー操作など、軽量な処理に利用できます。
CloudFront Functions のイベントオブジェクトでは、HTTP ヘッダー名は小文字で扱われます。関数コードからヘッダーを追加・変更する場合も、小文字で指定する必要があります。

https://docs.aws.amazon.com/ja_jp/AmazonCloudFront/latest/DeveloperGuide/functions-event-structure.html?utm_source=openai

一方で、CloudFront Functions がイベントオブジェクトを HTTP レスポンスへ変換する際、ヘッダー名はハイフン（-）区切りの各単語の先頭が大文字に変換されます。例えば、関数コード内で x-custom-header を追加すると、HTTP レスポンスでは X-Custom-Header として返されます。
今回は、CloudFront Functions のテスト機能を使用して、HTTP ヘッダー名の大文字・小文字の扱いを確認しました。

https://docs.aws.amazon.com/ja_jp/AmazonCloudFront/latest/DeveloperGuide/test-function.html?utm_source=openai

CloudFront Functions のテスト機能を使用すると、CloudFront ディストリビューションへ関連付ける前に関数の動作を確認できます。本ブログでは、既存の CloudFront ディストリビューションや公開中のサイトに影響を与えず、CloudFront コンソール上のテスト機能のみで検証しました。

本ブログで確認すること

• テストイベント内の HTTP ヘッダー名を小文字で指定できるか
• 関数コードで小文字の x-cm-test-header をレスポンスヘッダーへ追加できるか
• テスト結果のイベントオブジェクトで、x-cm-test-header が小文字で出力されるか

先に結論から

CloudFront Functions のテスト機能を使用して、HTTP ヘッダー名の扱いを確認しました。

• テストイベントの HTTP ヘッダー名は小文字で指定できました。
• 関数コードで x-cm-test-header を小文字で追加できました。
• テスト結果のイベントオブジェクトでも、x-cm-test-header は小文字で出力されました。

CloudFront Functions のテスト画面ではイベントオブジェクトが表示されるため、
HTTP レスポンスへ変換された後の X-Cm-Test-Header は確認していません。

検証環境について

CloudFront Functions のテスト機能を使用して検証します。
CloudFront ディストリビューションには関連付けず、CloudFront コンソール上で関数コードとテストイベントを作成・実行します。そのため、既存の CloudFront ディストリビューションや公開中のサイトには影響しません。

検証では、関数コードで小文字の x-cm-test-header をレスポンスヘッダーへ追加します。テスト結果のイベントオブジェクトで、x-cm-test-header が小文字のまま追加されるかを確認します。

CloudFront Functions のテスト機能
  ├─ 関数コード
  │   └─ x-cm-test-header を追加
  └─ テストイベント
       └─ viewer response を模擬

実装してみた

今回は、viewer response イベントでレスポンスヘッダーを追加する CloudFront Functions の関数を作成します。
CloudFront Functions のイベントオブジェクトでは、HTTP ヘッダー名を小文字で扱います。関数コードでヘッダーを追加する場合も、小文字で指定する必要があります。

CloudFront Function を作成する

CloudFront コンソールで 関数 を開き、関数を作成 を選択します。

以下の値を設定しました。

関数コードを記述する

関数コードには、以下を入力します。

function handler(event) {
    var response = event.response;

    response.headers['x-cm-test-header'] = {
        value: 'cloudfront-functions'
    };

    return response;
}

response.headers に対して、x-cm-test-header を追加しています。
ポイントは、関数コード上のヘッダー名を x-cm-test-header のように小文字で指定していることです。
コードを入力後、［変更を保存］を選択します。

テストイベントを作成する

続いて、［テスト］タブを開き、イベントタイプに［Viewer response］を選択します。
テストイベントはフォームから入力できます。今回は、イベントオブジェクト内のヘッダー名を明示的に確認するため、［JSON を編集］を使用しました。
［JSON を編集］で、以下のイベントオブジェクトを入力して保存します。

{
  "version": "1.0",
  "context": {
    "eventType": "viewer-response"
  },
  "viewer": {
    "ip": "192.0.2.1"
  },
  "request": {
    "method": "GET",
    "uri": "/",
    "querystring": {},
    "headers": {
      "host": {
        "value": "example.com"
      }
    },
    "cookies": {}
  },
  "response": {
    "statusCode": 200,
    "statusDescription": "OK",
    "headers": {
      "content-type": {
        "value": "text/html"
      }
    },
    "cookies": {}
  }
}

テストイベントでは、host や content-type のように HTTP ヘッダー名を小文字で指定しています。
テスト用イベントでは、distributionDomainName、distributionId、requestId などの一部フィールドを省略できます。

関数をテストする

テストイベントを設定後、［関数をテスト］を選択します。
CloudFront コンソールでは、関数の実行後に出力、実行ログ、コンピューティング使用率を確認できます。
次の「検証してみた」では、テスト結果の出力を確認し、x-cm-test-header が小文字で追加されていることを確認します。

確認してみた

［関数をテスト］を選択して、開発ステージの CloudFront Functions を実行します。
実行結果は 200 OK でした。また、コンピューティング使用率は 6 でした。

出力では、関数コードで追加した x-cm-test-header を確認できました。

{
  "response": {
    "statusCode": 200,
    "statusDescription": "OK",
    "headers": {
      "x-cm-test-header": {
        "value": "cloudfront-functions"
      },
      "content-type": {
        "value": "text/html"
      }
    },
    "cookies": {}
  }
}

テストイベントの content-type と、関数コードで追加した x-cm-test-header は、どちらも小文字で指定しました。テスト結果でも、x-cm-test-header は小文字のまま出力されました。
CloudFront Functions のテスト画面には、実際の HTTP レスポンスではなく、関数実行後のイベントオブジェクトが表示されます。そのため、テスト画面上では X-Cm-Test-Header ではなく、x-cm-test-header と表示されます。

CloudFront Functions がイベントオブジェクトを HTTP レスポンスへ変換する際は、x-cm-test-header のようなヘッダー名を X-Cm-Test-Header の形式へ変換します。ただし、本記事では CloudFront ディストリビューションへ関数を関連付けていないため、実際の HTTP レスポンスでの変換結果は確認していません。
今回の検証結果をまとめます。

CloudFront Functions で HTTP ヘッダーを操作する場合は、イベントオブジェクトおよび関数コードでヘッダー名を小文字で扱う必要があることを確認できました。

まとめ

CloudFront Functions のテスト機能を使用して、HTTP ヘッダー名の大文字・小文字の扱いを確認しました。
今回の検証で確認できた内容は以下のとおりです。

• テストイベント内の HTTP ヘッダー名は、小文字で指定できました。
• 関数コードで、小文字の x-cm-test-header をレスポンスヘッダーへ追加できました。
• テスト結果のイベントオブジェクトでも、x-cm-test-header は小文字のまま出力されました。
• CloudFront Functions のテスト機能だけを使用したため、CloudFront ディストリビューションや公開中のサイトへ影響を与えずに確認できました。

CloudFront Functions のイベントオブジェクトでは、HTTP ヘッダー名を小文字で扱います。関数コードでヘッダーを参照・追加・変更する際も、小文字で指定する必要があります。
一方で、CloudFront がイベントオブジェクトを実際の HTTP レスポンスへ変換する際は、x-cm-test-header のようなヘッダー名は X-Cm-Test-Header の形式に変換されます。今回はテスト機能のみを利用したため、HTTP レスポンスでの変換結果は確認していません。

CloudFront Functions の開発時は、まずテスト機能でイベントオブジェクトを確認してから、必要に応じて CloudFront ディストリビューションへ関連付けることで、段階的に実装を進められます。
本ブログがどなたかの参考になれば幸いです。

参考資料

• CloudFront Functions のイベント構造 - Amazon CloudFront
• 関数をテストする - Amazon CloudFront

クラスメソッドオペレーションズ株式会社について

クラスメソッドグループのオペレーション企業です。
運用・保守開発・サポート・情シス・バックオフィスの専門チームが、IT・AIをフル活用した「しくみ」を通じて、お客様の業務代行から課題解決や高付加価値サービスまでを提供するエキスパート集団です。
当社は様々な職種でメンバーを募集しています。
「オペレーション・エクセレンス」と「らしく働く、らしく生きる」を共に実現するカルチャー・しくみ・働き方にご興味がある方は、クラスメソッドオペレーションズ株式会社 コーポレートサイト をぜひご覧ください。※2026年1月 アノテーション㈱から社名変更しました