GetRecommendations - Amazon Personalize

GetRecommendations

推奨アイテムのリストを返します。キャンペーンについて、キャンペーンの Amazon リソースネーム (ARN) は必須であり、必要なユーザーとアイテムの入力は、キャンペーンをサポートするソリューションの作成に使用されたレシピタイプによって次のように異なります。

  • USER_PERSONALIZATION - userId 必須、itemId 未使用

  • RELATED_ITEMS - itemId 必須、userId 未使用

注記

タイプ PERSONALIZED_RANKING のレシピを使用して作成されたソリューションにサポートされたキャンペーンは、GetPersonalizedRanking API を使用します。

レコメンダーの場合、レコメンダーの ARN が必要であり、必要なアイテムとユーザー入力は、レコメンダーをサポートするユースケース (ドメインベースのレシピ) によって異なります。ユースケースにおける要件の詳細については、「レコメンダーのユースケースの選択」を参照してください。

リクエストの構文

POST /recommendations HTTP/1.1 Content-type: application/json { "campaignArn": "string", "context": { "string" : "string" }, "filterArn": "string", "filterValues": { "string" : "string" }, "itemId": "string", "metadataColumns": { "string" : [ "string" ] }, "numResults": number, "promotions": [ { "filterArn": "string", "filterValues": { "string" : "string" }, "name": "string", "percentPromotedItems": number } ], "recommenderArn": "string", "userId": "string" }

URI リクエストパラメータ

リクエストでは URI パラメータを使用しません。

リクエストボディ

リクエストは以下の JSON 形式のデータを受け入れます。

campaignArn

レコメンデーションの取得に使用するキャンペーンの Amazon リソースネーム (ARN)。

型: 文字列

長さの制限:最大長は 256 です。

パターン: arn:([a-z\d-]+):personalize:.*:.*:.+

必須: いいえ

context

レコメンデーションを取得するときに使用するコンテキストメタデータ。コンテキストメタデータには、ユーザーの現在の場所やデバイスタイプなど、ユーザーのレコメンデーションを取得するときに関連する可能性のあるインタラクション情報が含まれます。

タイプ: 文字列から文字列へのマップ

マップエントリ: アイテムの最大数は 150 です。

キーの長さの制限: 最大長は 150 です。

キーパターン: [A-Za-z\d_]+

値の長さの制限: 最大長は 1000 です。

必須: いいえ

filterArn

返されたレコメンデーションに適用するフィルターの ARN。詳細については、「レコメンデーションのフィルタリング」を参照してください。

このパラメータを使用するときは、フィルターのリソースが ACTIVE であることを確認してください。

型: 文字列

長さの制限:最大長は 256 です。

パターン: arn:([a-z\d-]+):personalize:.*:.*:.+

必須: いいえ

filterValues

レコメンデーションをフィルタリングするときに使用する値。フィルター式の各プレースホルダーパラメータについて、(大文字と小文字が一致した状態で) パラメータ名をキーとして指定し、フィルター値を対応する値として指定します。1 つのパラメータの複数の値をコンマで区切ります。

INCLUDE 要素を使用してアイテムを含めるフィルター式について、式で定義されているすべてのパラメータの値を指定する必要があります。EXCLUDE 要素を使用してアイテムを除外する式を含むフィルターについては、filter-values を省略できます。この場合、Amazon Personalize は、レコメンデーションをフィルタリングするために式のその部分を使用しません。

詳細については、「レコメンデーションとユーザーセグメントのフィルタリング」を参照してください。

型: 文字列間のマッピング

マップエントリ: アイテムの最大数は 25 です。

キーの長さの制限: 最大長は 50 です。

キーパターン: [A-Za-z0-9_]+

値の長さの制限: 最大長は 1000 です。

必須: いいえ

itemId

レコメンデーションを提供するアイテム ID。

RELATED_ITEMS レシピタイプに必要です。

型: 文字列

長さの制限:最大長は 256 です。

必須: いいえ

metadataColumns

キャンペーンまたはレコメンダーを作成または更新したときにレコメンデーションのメタデータを有効にした場合は、アイテムデータセットのメタデータ列をアイテムレコメンデーションに含めるように指定します。マップキーは ITEMS で、値はアイテムデータセットの列名のリストです。指定できる列の最大数は 10 です。

キャンペーンのメタデータを有効にする方法については、「Enabling metadata in recommendations for a campaign」を参照してください。レコメンダーのメタデータを有効にする方法については、「Enabling metadata in recommendations for a recommender」を参照してください。

タイプ: 文字列マップの配列への文字列

マップエントリ: アイテムの最大数は 1 です。

キーの長さの制限: 最大長は 256 です。

配列メンバー: 最大数は 99 アイテムです。

長さの制限: 最大長は 1,024 です。

必須: いいえ

numResults

返される結果の数。デフォルトは 25 です。レコメンデーションにメタデータを含める場合、最大数は 50 です。それ以外の場合、最大数は 500 です。

型: 整数

値の範囲: 最小値 は 0 です。

必須: いいえ

promotions

レコメンデーションリクエストに適用するプロモーション。プロモーションは、設定可能なおすすめアイテムのサブセットに適用される追加のビジネスルールを定義します。

型: Promotion オブジェクトの配列

配列メンバー: 最大数は 1 項目です。

必須: いいえ

recommenderArn

レコメンデーションを取得するために使用するレコメンダーの Amazon リソースネーム (ARN)。ドメインユースケース向けのレコメンダーを含むドメインデータセットグループを作成した場合は、レコメンダー ARN を提供します。

型: 文字列

長さの制限:最大長は 256 です。

パターン: arn:([a-z\d-]+):personalize:.*:.*:.+

必須: いいえ

userId

レコメンデーションを提供するユーザー ID。

USER_PERSONALIZATION レシピタイプに必要です。

型: 文字列

長さの制限:最大長は 256 です。

必須: いいえ

レスポンスの構文

HTTP/1.1 200 Content-type: application/json { "itemList": [ { "itemId": "string", "metadata": { "string" : "string" }, "promotionName": "string", "score": number } ], "recommendationId": "string" }

レスポンス要素

アクションが成功すると、サービスは HTTP 200 レスポンスを返します。

サービスから以下のデータが JSON 形式で返されます。

itemList

予測スコアでソートされたレコメンデーションのリスト (降順)。リストには最大 500 個のアイテムを含めることができます。

型: PredictedItem オブジェクトの配列

recommendationId

レコメンデーションの ID。

型: 文字列

エラー

InvalidInputException

フィールドまたはパラメータに有効な値を指定します。

HTTP ステータスコード:400

ResourceNotFoundException

指定されたリソースは存在しません。

HTTP ステータスコード: 404

以下の資料も参照してください。

言語固有の AWS SDK のいずれかでこの API を使用する方法の詳細については、以下を参照してください。