# 関数をテストする
<a name="test-function"></a>

関数をライブステージ (本番環境) にデプロイする前に、テストして期待どおりに動作することを確認できます。関数をテストするには、CloudFront ディストリビューションが本番環境で受信する可能性がある HTTP リクエストやレスポンスを表すイベントオブジェクトを指定します。**

CloudFront Functions は以下の処理を行います。

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

1. 関数の結果 (変更されたイベントオブジェクト) を、関数ログまたはエラーメッセージ、および関数の*コンピューティング使用率*とともに返します。コンピューティング使用率の詳細については、「[コンピューティング使用率を理解する](#compute-utilization)」を参照してください。

**注記**  
関数をテストすると、CloudFront は関数実行エラーのみを検証します。CloudFront は、リクエストが一度発行されると、正常に流れるかどうかは検証しません。例えば、関数が必須ヘッダーを削除しても、コードには問題がないため、テストは成功します。ただし、関数を発行してディストリビューションに関連付けると、CloudFront を介してリクエストが行われたときに関数は失敗します。

**Contents**
+ [イベントオブジェクトをセットアップする](#test-function-create-event)
+ [関数をテストする](#test-function-step-test)
+ [コンピューティング使用率を理解する](#compute-utilization)

## イベントオブジェクトをセットアップする
<a name="test-function-create-event"></a>

関数をテストする前に、テストに使用するイベントオブジェクトをセットアップする必要があります。これには複数のオプションがあります。

**オプション 1: イベントオブジェクトを保存せずにセットアップする**  
CloudFront コンソールのビジュアルエディターでイベントオブジェクトをセットアップしても、保存はできません。  
このイベントオブジェクトを使用して、保存されていなくても CloudFront コンソールから関数をテストできます。

**オプション 2: ビジュアルエディターでイベントオブジェクトを作成する**  
CloudFront コンソールのビジュアルエディターでイベントオブジェクトをセットアップしても、保存はできません。関数ごとに 10 個のイベントオブジェクトを作成して、例えば、考えられるさまざまな入力をテストできます。  
この方法でイベントオブジェクトを作成すると、イベントオブジェクトを使用して CloudFront コンソールで関数をテストできます。AWS API や SDK を使用して関数をテストする場合には使用できません。

**オプション 3: テキストエディターを使用してイベントオブジェクトを作成する**  
テキストエディターを使用して、イベントオブジェクトを JSON 形式で作成できます。イベントオブジェクトの構造については、「[イベントの構造](functions-event-structure.md)」を参照してください。  
このイベントオブジェクトを使用して、CLI で関数をテストできます。ただし、これを使用して CloudFront コンソールで関数をテストすることはできません。

**イベントオブジェクトを作成するには (オプション 1 または 2)**

1. CloudFront コンソール ([https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)) にサインインし、**[関数]** ページを選択します。

   テストする関数を選択します。

1. 関数の詳細ページで、**[テスト]** タブを選択します。

1. **[イベントタイプ]** で、以下のいずれかのオプションを選択します。
   + 関数が HTTP リクエストを変更したり、リクエストに基づいてレスポンスを生成する場合は、**[ビューワーリクエスト]** を選択します。**[リクエスト]** セクションが表示されます。
   + **[ビューアーレスポンス]** を選択します。**[リクエスト]** セクションと **[レスポンス]** セクションが表示されます。

1. イベントに含めるフィールドに入力します。**[JSON を編集]** を選択すると、未加工の JSON を表示できます。

1. (オプション) イベントを保存するには、**[保存]** を選択し、**[テストイベントを保存]** に名前を入力して **[保存]** を選択します。

   **[JSON を編集]** を選択し、未加工の JSON をコピーして、CloudFront 外の独自のファイルに保存することもできます。

**イベントオブジェクトを作成するには (オプション 3)**

テキストエディタを使用してイベントオブジェクトを作成します。このファイルは、コンピューターが接続できるディレクトリに保存します。

以下のガイドラインに確実に従ってください。
+ `distributionDomainName`、`distributionId`、`requestId` の各フィールドは省略します。
+ ヘッダー、Cookie、クエリ文字列の名前は必ず小文字にします。

この方法でイベントオブジェクトを作成する方法の 1 つは、ビジュアルエディターを使用してサンプルを作成することです。サンプルが正しいフォーマットになっていることを確認できます。そして、未加工の JSON をコピーし、テキストエディターに貼り付け、ファイルを保存することができます。

イベントの構造の詳細については、「[イベントの構造](functions-event-structure.md)」を参照してください。

## 関数をテストする
<a name="test-function-step-test"></a>

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

------
#### [ Console ]

**関数をテストするには**

1. CloudFront コンソール ([https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)) にサインインし、**[関数]** ページを選択します。

1. テストする関数を選択します。

1. **[テスト]** タブを選択します。

1. 正しいイベントが表示されていることを確認します。現在表示されているイベントから切り替えるには、**[テストイベントを選択]** フィールドで別のイベントを選択します。

1. **[関数をテスト]** を選択します。コンソールに、関数ログとコンピューティング使用率を含む、関数の出力が表示されます。

------
#### [ CLI ]

**aws cloudfront test-function** コマンドを使用して関数をテストできます。

**関数をテストするには**

1. コマンドラインウィンドウを開きます。

1. 指定したファイルがある同じディレクトリから、次のコマンドを実行します。

   この例では、`fileb://` 表記を使用してイベントオブジェクトファイルを渡します。コマンドを読みやすくするために改行も含まれています。

   ```
   aws cloudfront test-function \
       --name MaxAge \
       --if-match ETVABCEXAMPLE \
       --event-object fileb://event-maxage-test01.json \
       --stage DEVELOPMENT
   ```
**注意事項**  
関数は名前と ETag (`if-match` パラメータ内) で参照します。イベントオブジェクトはファイルシステム内のロケーションによって参照します。
ステージは、`DEVELOPMENT` または `LIVE` の場合があります。

   コマンドが成功した場合は、以下のような出力が表示されます。

   ```
   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: MaxAge function
         Runtime: cloudfront-js-2.0
         KeyValueStoreAssociations= \
         {Quantity=1, \
         Items=[{KeyValueStoreARN='arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111'}]} \
       FunctionMetadata:
         CreatedTime: '2021-04-18T20:38:56.915000+00:00'
         FunctionARN: arn:aws:cloudfront::111122223333:function/MaxAge
         LastModifiedTime: '2023-17-20T10:38:57.057000+00:00'
         Stage: DEVELOPMENT
       Name: MaxAge
       Status: UNPUBLISHED
   ```

------

**注意事項**  
`FunctionExecutionLogs` には、関数が `console.log()` ステートメントに書き込んだ (該当する場合) ログ行のリストが含まれます。
`ComputeUtilization` には、関数の実行に関する情報が含まれています。「[コンピューティング使用率を理解する](#compute-utilization)」を参照してください。
`FunctionOutput` には、関数が返したイベントオブジェクトが含まれます。

## コンピューティング使用率を理解する
<a name="compute-utilization"></a>

**コンピューティング使用率**は、関数の実行にかかった時間 (最大許容時間に対するパーセンテージ) です。たとえば、値 35 は、関数が最大許容時間の 35% で完了したことを意味します。

関数が最大許容時間を継続的に超える場合、CloudFront で関数がスロットリングされます。次のリストは、コンピューティング使用率の値に基づいて関数がスロットリングされる可能性を説明しています。

**コンピューティング使用率値:**
+ ** 1～50** —関数は最大許容時間を十分に下回っており、スロットリングなしで実行する必要があります。
+ ** 51～70** —関数が最大許容時間に近づいています。関数コードの最適化を検討してください。
+ ** 71～100** —関数が最大許容時間に非常に近いか、それを超えています。ディストリビューションに関連付けると、CloudFront でこの関数が抑制される可能性があります。