クライアント側の評価を使用する - AWS AppConfig を使用

プロジェクトでクライアント側の評価 - AWS AppConfig を使用 (クライアント側の評価) を使用すると、アプリケーションが EvaluateFeature オペレーションを呼び出してバリエーションを割り当てるのではなく、ローカルでバリエーションをユーザーセッションに割り当てることができます。これにより、API コールに伴うレイテンシーと可用性のリスクが軽減されます。

クライアント側の評価を使用するには、AWS AppConfig Lambda の拡張機能を Lambda 関数のレイヤーとしてアタッチし、環境変数を設定します。クライアント側の評価は、ローカルホストのサイドプロセスとして実行されます。次に、localhost に対して [EvaluationFeature] および [PutProjectEvent] オペレーションを呼び出すことができます。クライアント側の評価プロセスでは、バリエーションの割り当て、キャッシュ、およびデータ同期の処理が行われます。AWS AppConfig の詳細については、「AWS AppConfig の仕組み」を参照してください。

AWS AppConfig と統合する場合、Evidently に対して AWS AppConfig アプリケーション ID と AWS AppConfig 環境 ID を指定します。Evidenly のプロジェクト間では、同じアプリケーション ID と環境 ID を使用できます。

クライアント側の評価を有効にしたプロジェクトを作成すると、Evidently はそのプロジェクトの AWS AppConfig 設定プロファイルを作成します。各プロジェクトの設定プロファイルは異なります。

クライアント側の評価のアクセスコントロール

Evidently のクライアント側の評価では、他の Evidently とは異なるアクセスコントロールメカニズムを使用しています。このことを理解していただき、適切なセキュリティ対策を実施することを強くお勧めします。

Evidently では、ユーザーが個々のリソースで実行できるアクションを制限する IAM ポリシーを作成できます。例えば、[EvaluateFeature] アクションを持つことを禁止するユーザーロールを作成することができます。IAM ポリシーで制御できる Evidently アクションの詳細については、「Actions defined by Amazon CloudWatch Evidently」(Amazon CloudWatch Evidentlyで定義されるアクション) を参照してください。

クライアント側の評価モデルでは、プロジェクトのメタデータを使用する Evidently 機能をローカルで評価できます。クライアント側の評価が有効になっているプロジェクトのユーザーは、ローカルホストのエンドポイントに対して [EvaluateFeature] API を呼び出すことができますが、このAPI コールは Evidently に到達せず、Evidenly サービスの IAMポリシーによって認証されません。この呼び出しは、ユーザーが [EvaluateFeature] アクションを使用する IAM アクセス許可を持っていない場合でも成功します。ただし、エージェントが評価イベントやカスタムイベントをバッファリングし、Evidently に非同期的にデータをオフロードするためには、ユーザーにはアクセス許可 [PutProjectEvents] が必要です。

また、ユーザーは、クライアント側の評価を使用するプロジェクトを作成するためのアクセス許可 evidently:ExportProjectAsConfiguration を持っている必要があります。これにより、クライアント側の評価中に呼び出される [EvaluateFeature] アクションへのアクセスを制御しやすくなります。

クライアント側の評価のセキュリティモデルが、他の Evidently に設定したポリシーを覆す可能性があるため、アクセスコントロールは慎重に行ってください。アクセス許可 evidently:ExportProjectAsConfiguration を持つユーザーは、IAM ポリシーで [EvaluateFeature] アクションが明示的に拒否されている場合でも、クライアント側の評価を有効にしたプロジェクトを作成し、[EvaluateFeature] アクションを使用してそのプロジェクトでクライアント側の評価を行うことができます。

Lambda の使用を開始する

Evidently では現在、AWS Lambda 環境を使用するクライアント側の評価がサポートされています。開始するには、まず、どの AWS AppConfig アプリケーションと環境を使用するかを決めます。既存のアプリケーションと環境を選択するか、または新しいアプリケーションと環境を作成するかを選択します。

次のサンプル AWS AppConfig AWS CLI コマンドはアプリケーションと環境を作成します。


aws appconfig create-application --name YOUR_APP_NAME


aws appconfig create-environment --application-id YOUR_APP_ID --name YOUR_ENVIRONMENT_NAME

次に、これらの AWS AppConfig リソースを使用して Evidently プロジェクトを作成します。詳細については、「の新規プロジェクトの作成」を参照してください。

クライアント側の評価は、Lambda レイヤーを使用することで Lambda でサポートされます。これは AWS-AppConfig-Extension の一部であるパブリックレイヤーで、AWS AppConfig サービスによって作成されたパブリック AWS AppConfig 拡張機能です。Lambda レイヤーの詳細については、「レイヤー」を参照してください。

クライアント側の評価を使用するには、このレイヤーを Lambda 関数に追加し、アクセス許可と環境変数を設定する必要があります。

Evidently クライアント側の評価 Lambda レイヤーを Lambda 関数に追加して設定するには

Lambda 関数を作成します (まだ作成していない場合)。
クライアント側の評価レイヤーを関数に追加します。その ARN を指定するか、まだ選択していない場合は AWS レイヤーのリストから選択することができます。詳細については、「関数を設定してレイヤーを使用する」と「AWS AppConfig Lambda 拡張機能の使用可能なバージョン」を参照してください。

[EvidentlyAppConfigCachingAgentPolicy] という名前の IAM ポリシーを以下の内容で作成し、関数の実行ロールにアタッチします。詳細については、「Lambda 実行ロール」を参照してください。


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "appconfig:GetLatestConfiguration",
                "appconfig:StartConfigurationSession",
                "evidently:PutProjectEvents"
            ],
            "Resource": "*"
        }
    ]
}

Lambda 関数に必要な環境変数 AWS_APPCONFIG_EXTENSION_EVIDENTLY_CONFIGURATIONS を追加します。この環境変数は、Evidently プロジェクトと AWS AppConfig リソース間のマッピングを指定します。

1 つの Evidently プロジェクトでこの関数を使用している場合は、環境変数の値を次のように設定します: applications/APP_ID/environments/ENVIRONMENT_ID/configurations/PROJECT_NAME

この関数を複数の Evidently プロジェクトで使用する場合は、次の例のようにコンマを使用して値を区切ります: applications/APP_ID_1/environments/ENVIRONMENT_ID_1/configurations/PROJECT_NAME_1, applications/APP_ID_2/environments/ENVIRONMENT_ID_2/configurations/PROJECT_NAME_2
(オプション) 他の環境変数を設定します。詳細については、「設定: AWS AppConfig AppConfigLambda の拡張」を参照してください。

アプリケーションで、EvaluateFeature を localhost に送信して Evidently の評価をローカルに入手します。

Python の例


import boto3
from botocore.config import Config
        
def lambda_handler(event, context):
    local_client = boto3.client(
        'evidently',
        endpoint_url="http://localhost:2772",
        config=Config(inject_host_prefix=False)
    )
    response = local_client.evaluate_feature(
        project=event['project'],
        feature=event['feature'],
        entityId=event['entityId']
    )
    print(response)

Node.js の例:


const AWS = require('aws-sdk');
const evidently = new AWS.Evidently({
    region: "us-west-2",
    endpoint: "http://localhost:2772",
    hostPrefixEnabled: false
});

exports.handler = async (event) => {
    
    const evaluation = await evidently.evaluateFeature({
        project: 'John_ETCProject_Aug2022',
        feature: 'Feature_IceCreamFlavors',
        entityId: 'John'
    }).promise()
    
    console.log(evaluation)
    const response = {
        statusCode: 200,
        body: evaluation,
    };
    return response;
};

Kotlin の例:


String localhostEndpoint = "http://localhost:2772/"
public AmazonCloudWatchEvidentlyClient getEvidentlyLocalClient() {
    return AmazonCloudWatchEvidentlyClientBuilder.standard()
        .withEndpointConfiguration(AwsClientBuilder.EndpointConfiguration(localhostEndpoint, region))
        .withClientConfiguration(ClientConfiguration().withDisableHostPrefixInjection(true))
        .withCredentials(credentialsProvider)
        .build();
}

AmazonCloudWatchEvidentlyClient evidently = getEvidentlyLocalClient();

// EvaluateFeature via local client.
EvaluateFeatureRequest evaluateFeatureRequest = new EvaluateFeatureRequest().builder()
   .withProject(${YOUR_PROJECT}) //Required.
   .withFeature(${YOUR_FEATURE}) //Required.
   .withEntityId(${YOUR_ENTITY_ID}) //Required.
   .withEvaluationContext(${YOUR_EVAL_CONTEXT}) //Optional: a JSON object of attributes that you can optionally pass in as part of the evaluation event sent to Evidently.
   .build();
   
EvaluateFeatureResponse evaluateFeatureResponse = evidently.evaluateFeature(evaluateFeatureRequest);

// PutProjectEvents via local client. 
PutProjectEventsRequest putProjectEventsRequest = new PutProjectEventsRequest().builder()
    .withData(${YOUR_DATA})
    .withTimeStamp(${YOUR_TIMESTAMP})
    .withType(${YOUR_TYPE})
    .build();
    
PutProjectEvents putProjectEventsResponse = evidently.putProjectEvents(putProjectEventsRequest);

クライアントが Evidently にデータを送信する頻度を設定する

クライアント側の評価が Evidently にデータを送信する頻度を指定するには、オプションで 2 つの環境変数を設定できます。

AWS_APPCONFIG_EXTENSION_EVIDENTLY_EVENT_BATCH_SIZE は Evidently に送信する前にバッチ処理するプロジェクトごとのイベント数を指定します。有効な範囲は 1～50 の整数で、デフォルトは 40 です。
AWS_APPCONFIG_EXTENSION_EVIDENTLY_BATCH_COLLECTION_DURATION は Evidently に送信する前にイベントを待機する時間を秒単位で指定します。デフォルトは 30 です。

トラブルシューティング

以下の情報を参考にして、CloudWatch Evidently のクライアント側の評価 (AWS AppConfig を使用) を実行する際のトラブルシューティングを行います。

EvaluateFeature オペレーションの呼び出し中にエラー (BadRequestException) が発生しました: 提供されたパスでは HTTP メソッドがサポートされていません。

環境変数が正しく設定されていない可能性があります。例えば、環境変数名として、AWS_APPCONFIG_EXTENSION_EVIDENTLY_CONFIGURATIONS ではなく EVIDENTLY_CONFIGURATIONS を使用した可能性があります。

ResourceNotFoundException: デプロイが見つかりません

プロジェクトメタデータの更新が AWS AppConfig にデプロイされていません。クライアント側の評価に使用した AWS AppConfig 環境で、アクティブなデプロイがあるかどうかを確認します。

ValidationException: プロジェクトで Evidently が設定されていません

AWS_APPCONFIG_EXTENSION_EVIDENTLY_CONFIGURATIONS 環境変数に間違ったプロジェクト名が設定されている可能性があります。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

の新規プロジェクトの作成

プロジェクトに機能を追加する