Method: projects.locations.collections.engines.servingConfigs.recommend

コンテキスト ユーザー イベントを必要とするレコメンデーションを作成します。

HTTP リクエスト

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:recommend

この URL では gRPC Transcoding 構文を使用します。

パスパラメータ

パラメータ
servingConfig

string

必須。ServingConfig の完全なリソース名: projects/*/locations/global/collections/*/engines/*/servingConfigs/* または projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

デフォルトのサービス構成は、レコメンデーション エンジンの作成と同時に作成されます。エンジン ID は、デフォルトのサービス提供構成の ID として使用されます。たとえば、Engine projects/*/locations/global/collections/*/engines/my-engine の場合、RecommendationService.Recommend リクエストに projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine を使用できます。

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

JSON 表現 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
フィールド
userEvent

object (UserEvent)

必須。ユーザーに関するコンテキスト、ユーザーが何を見ているか、servingConfigs.recommend リクエストをトリガーするためにユーザーがどのようなアクションを行ったか。このユーザー イベントの詳細は userEvent ログに取り込まれません。そのため、イベントのロギングには個別の userEvent 書き込みリクエストが必要です。

UserEvent.user_pseudo_id または UserEvent.user_info.user_id を異なるユーザーに対して同じ固定 ID に設定しないでください。パーソナライズされていないおすすめコンテンツを受け取ろうとしている場合（おすすめしません。モデルのパフォーマンスに悪影響を及ぼす可能性があります）、代わりに UserEvent.user_pseudo_id をランダムな一意の ID に設定し、UserEvent.user_info.user_id を未設定のままにします。
pageSize

integer

ページあたりの結果数の上限です。このプロパティを必要なレコメンデーション結果の数に設定します。ゼロの場合、サービスは適切なデフォルトを選択します。最大値は 100 です。100 を超える値は 100 に設定されます。
filter

string

レコメンデーションの結果を制限するフィルタ。長さの上限は 5,000 文字です。現在、filterTags 属性のフィルタ式のみがサポートされています。

例:

  • (filterTags: ANY("Red", "Blue") OR filterTags: ANY("Hot", "Cold"))
  • (filterTags: ANY("Red", "Blue")) AND NOT (filterTags: ANY("Green"))

params フィールドで attributeFilteringSyntax が true に設定されている場合、上記で説明したタグベースの構文ではなく、属性ベースの式が想定されます。例:

  • (language: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
  • (available: true) AND (language: ANY("en", "es")) OR (categories: ANY("Movie"))

フィルタによってすべての結果がブロックされると、API は一般的な（フィルタされていない）人気の高いドキュメントを返します。フィルタに厳密に一致する結果のみが必要な場合は、RecommendRequest.params で strictFiltering を true に設定して、代わりに空の結果を受け取ります。

フィルタの選択に関係なく、API は storageStatus が EXPIRED または DELETED の Document を返すことはありません。
validateOnly

boolean

この推奨事項クエリには、検証専用モードを使用します。true に設定すると、任意のドキュメント ID を返すフェイクモデルが使用されます。検証専用モードは、API のテストまたはモデルの準備が整っていない場合にのみ使用してください。
params

map (key: string, value: value (Value format))

推奨事項のドメイン固有の追加パラメータ。

使用できる値:

  • returnDocument: ブール値true に設定すると、関連付けられた Document オブジェクトが RecommendResponse.RecommendationResult.document で返されます。
  • returnScore: ブール値true に設定すると、返された各ドキュメントに対応する推奨スコアが RecommendResponse.RecommendationResult.metadata に設定されます。指定されたスコアは、ユーザーのコンテキストと履歴に基づいてドキュメントが変換される確率を示します。
  • strictFiltering: ブール値デフォルトでは True です。false に設定されている場合、フィルタによってすべてのレコメンデーション結果がブロックされると、サービスは空ではなく一般的な（フィルタされていない）人気のドキュメントを返します。
  • diversityLevel: 文字列。デフォルトは空です。空でない値に設定する場合は、次のいずれかにする必要があります。
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity: リクエスト レベルで制御し、ドキュメントのカテゴリに基づいてレコメンデーションの結果を調整します。
  • attributeFilteringSyntax: ブール値デフォルトは False です。true に設定すると、filter フィールドは新しい属性ベースの構文に従って解釈されます。
userLabels

map (key: string, value: string)

リソースに適用するユーザーラベルは、次の要件を満たす必要があります。

  • 1 つのリソースには、最大 64 個のラベルを適用できます。
  • ラベルは、Key-Value ペアでなければなりません。
  • キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
  • キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。
  • ラベルのキー部分は一意でなければなりません。ただし、複数のリソースで同じキーを使用できます。
  • キーは、小文字または国際文字で始める必要があります。

詳しくは、ラベルの要件をご覧ください。

レスポンスの本文

成功した場合、レスポンスの本文には RecommendResponse のインスタンスが含まれます。

認可スコープ

次の OAuth スコープのいずれかが必要です。

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite

詳細については、Authentication Overview をご覧ください。

IAM 権限

servingConfig リソースに対する次の IAM 権限が必要です。

  • discoveryengine.servingConfigs.recommend

詳細については、IAM のドキュメントをご覧ください。