関数のテスト - Amazon CloudFront

関数のテスト

関数をテストするには、CloudFront ディストリビューションが運用環境で受信できる HTTP リクエストまたはレスポンスを表すイベントオブジェクトを指定します。CloudFront Functions は以下の処理を行います。

  1. 指定されたイベントオブジェクトを関数への入力として使用して、関数を実行します。

  2. 関数の結果 (変更されたイベントオブジェクト) を、関数ログまたはエラーメッセージ、および関数のコンピューティング使用率とともに返します。コンピューティング使用率とは、関数の実行にかかった時間の長さを、最大許容時間に対するパーセンテージで示す 0 ~ 100 の数値です。たとえば、コンピューティング使用率が 35 の場合、関数は最大許容時間の 35% で完了したことを意味します。

関数をテストする前に、テストに使用するイベントオブジェクトを作成する必要があります。イベントオブジェクトを作成するには、次のオプションがあります。

  • CloudFront コンソールでビジュアルエディタを使用します。ビジュアルエディタは、グラフィカルインターフェイスでイベントオブジェクトを作成し、関数をテストするために使用できます。イベントオブジェクトを作成したら、イベントオブジェクトの JSON 表記をコピーして、AWS CLI や CloudFront API などの他のインターフェイスを使用した関数のテストに使用することもできます。詳細は、関数のテスト のコンソールタブを参照してください。

  • イベントオブジェクトを手作業で JSON 形式で記述します。イベントオブジェクトの構造の詳細については、「イベントの構造」を参照してください。

    注記

    関数をテストするためにイベントオブジェクトを作成する場合は、distributionDomainNamedistributionIdrequestId フィールドを省略できます。また、ヘッダー、Cookie、クエリ文字列の名前が小文字であることを確認してください。

関数は、CloudFront コンソールまたは AWS CLI を使用してテストできます。

Console

CloudFront コンソールは、グラフィカルインターフェイス(ビジュアルエディタ)でイベントオブジェクトを作成および保存し、関数をテストするために使用できます。また、イベントオブジェクトの JSON 表記をコピーして、他のインターフェイスで関数をテストするために使用することもできます。

イベントオブジェクトの作成と関数のテスト (コンソール)

  1. まだ作成していない場合は、手順に従って関数を作成します。

    関数をテストするには、https://console.aws.amazon.com/cloudfront/v3/home#/functions で CloudFront コンソールの [Functions] (関数) ページを開き、テストする関数を選択します。

  2. 関数ページで、[Test] タブを選択します。次に、以下の操作を実行します。

    1. イベントタイプを選択します。関数がリクエストを変更したり、リクエストに基づいてレスポンスを生成したりする場合は、[Viewer Request] を選択します。レスポンスを変更する場合は、[Viewer Response] を選択します。

    2. テスト、開発またはライブする関数のステージを選択します。

    
                                    CloudFront 関数の [Test] (テスト) タブ。
  3. 下にスクロールしてコンソールのビジュアルエディタを選択し、テストする HTTP リクエストまたは HTTP レスポンスを表すイベントオブジェクトを作成します。[Event type] で [Viewer Response] を選択すると、ビジュアルエディタがフィールドが追加し、レスポンスをテストできます。

    リクエストの場合は、リクエスト方法を選択し、URI パスとクライアント IP アドレスを入力できます。クエリ文字列またはリクエストヘッダーを追加するには、キーと値を入力し、[Add] を選択します。

    レスポンスでは、レスポンスヘッダーを追加し、レスポンスステータスコードとステータスの説明を入力できます。

    イベントオブジェクトの JSON 表記を表示するには、[JSON] タブを選択します。イベントオブジェクトの JSON 表記をコピーして、それを AWS CLI や CloudFront API などの他のインターフェイスを使用した関数のテストに使用することができます。

    次の画像は、同じテストイベントのビジュアルエディタと JSON ビューを示しています。

    
                                    ビジュアルエディタでの CloudFront 関数のテストイベントの例。
    
                                    JSON エディタでの CloudFront 関数のテストイベントの例。
  4. 作成したイベントオブジェクトを使用して関数をテストするには、[Test event] を選択します。コンソールには、関数ログ、クエリ文字列、リクエスト (および該当する場合レスポンス) のヘッダーと Cookie を含むテストの出力が表示されます。また、コンピューティング使用率も表示されます。これは、関数の実行にかかった時間の長さを、最大許容時間に対するパーセンテージで示す 0 ~ 100 までの数値です。たとえば、コンピューティング使用率が 35 の場合、関数は最大許容時間の 35% で完了したことを意味します。

CLI

イベントオブジェクトを作成したら、次の例にあるように、そのオブジェクトを AWS CLI での aws cloudfront test-function コマンドを使用した関数のテストに使用できます。この例では、入力ファイル (event-object.json) を使用して、コマンドにイベントオブジェクトを提供します。以下の event-object.json ファイルで、テスト用の簡単なイベントオブジェクトの例を示しています。

{ "version": "1.0", "context": { "eventType": "viewer-request" }, "viewer": { "ip": "198.51.100.11" }, "request": { "method": "GET", "uri": "/example.png", "headers": { "host": {"value": "example.org"} } } }

次のコマンドの例を使用するには、次の操作を行います。

  • ExampleFunction をテストする関数の名前に置き換えます。

  • ETVABCEXAMPLE をテストするコードの関数の ETag 値に置き換えます。この値を取得するには、aws cloudfront describe-function コマンドを使用します。

  • event-object.json 関数をテストするイベントオブジェクトを含むファイルの名前に置き換えます。このファイルが含まれているのと同じディレクトリからコマンドを実行します。

  • 次のコマンドは、ステージ DEVELOPMENT の関数をテストします。代わりにステージ LIVE で関数をテストする場合は、DEVELOPMENTLIVE に置き換えます。

  • コマンドを 1 行で実行します。この例では、例を読みやすくするために改行されています。

aws cloudfront test-function \ --name ExampleFunction \ --if-match ETVABCEXAMPLE \ --event-object fileb://event-object.json --stage DEVELOPMENT

コマンドが正常に完了すると、関数のテスト結果を示す次のような出力が表示されます。

注記

次の出力は YAML 文字列としてフォーマットされています。この機能は、AWS CLI のバージョン 2 のみで使用できます。詳細については、AWS Command Line Interface ユーザーガイドの「AWS CLI 出力形式の設定」を参照してください。

出力について、以下の点に注意してください。

  • FunctionSummary に、テストされた関数を示します。

  • FunctionExecutionLogs には、関数が console.log() ステートメントに書き込んだ (該当する場合) ログ行のリストが含まれます。

  • ComputeUtilization には、関数の実行にかかった時間の長さを、最大許容時間に対するパーセンテージで示す 0 ~ 100 までの数が含まれます。たとえば、コンピューティング使用率が 35 の場合、関数は最大許容時間の 35% で完了したことを意味します。

  • 関数が正常に完了しなかった場合、FunctionErrorMessage にはエラーメッセージが含まれます。

  • FunctionOutput には、関数が返したイベントオブジェクトが含まれます。次の出力は、この関数が HTTP ステータスコード 302 (Found)Location ヘッダー (値 https://aws.amazon.com/cloudfront/)、および Cloudfront-Functions ヘッダー (値 generated-by-CloudFront-Functions) を含むレスポンスを返したことを示しています。

TestResult: ComputeUtilization: '21' FunctionErrorMessage: '' FunctionExecutionLogs: [] FunctionOutput: '{"response":{"headers":{"cloudfront-functions":{"value":"generated-by-CloudFront-Functions"},"location":{"value":"https://aws.amazon.com/cloudfront/"}},"statusDescription":"Found","cookies":{},"statusCode":302}}' FunctionSummary: FunctionConfig: Comment: Example function Runtime: cloudfront-js-1.0 FunctionMetadata: CreatedTime: '2021-04-18T20:38:56.915000+00:00' FunctionARN: arn:aws:cloudfront::111122223333:function/ExampleFunction LastModifiedTime: '2021-04-18T20:38:57.057000+00:00' Stage: DEVELOPMENT Name: ExampleFunction Status: UNPUBLISHED