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

Effectue une recommandation, qui nécessite un événement utilisateur contextuel.

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
servingConfig

string

Obligatoire. Nom complet de la ressource d'un ServingConfig : projects/*/locations/global/collections/*/engines/*/servingConfigs/* ou projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

Une configuration de diffusion par défaut est créée en même temps que votre moteur de recommandations. L'ID du moteur est utilisé comme ID de la configuration de diffusion par défaut. Par exemple, pour le moteur projects/*/locations/global/collections/*/engines/my-engine, vous pouvez utiliser projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine pour vos requêtes RecommendationService.Recommend.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
Champs
userEvent

object (UserEvent)

Obligatoire. Contexte concernant l'utilisateur, ce qu'il regarde et l'action qu'il a effectuée pour déclencher la requête servingConfigs.recommend. Notez que ces informations détaillées sur l'événement utilisateur ne seront pas ingérées dans les journaux userEvent. Par conséquent, une requête d'écriture userEvent distincte est requise pour la journalisation des événements.

Ne définissez pas UserEvent.user_pseudo_id ou UserEvent.user_info.user_id sur le même ID fixe pour différents utilisateurs. Si vous essayez de recevoir des recommandations non personnalisées (non recommandé, car cela peut avoir un impact négatif sur les performances du modèle), définissez plutôt UserEvent.user_pseudo_id sur un ID unique aléatoire et laissez UserEvent.user_info.user_id non défini.
pageSize

integer

Nombre maximal de résultats sur une page. Définissez cette propriété sur le nombre de résultats de recommandation nécessaires. Si la valeur est zéro, le service choisit une valeur par défaut raisonnable. La valeur maximale autorisée est de 100. Les valeurs supérieures à 100 sont définies sur 100.
filter

string

Filtre permettant de limiter les résultats de recommandation (5 000 caractères maximum). Pour le moment, seules les expressions de filtre sur l'attribut filterTags sont acceptées.

Exemples :

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

Si la valeur de attributeFilteringSyntax est définie sur "true" dans le champ params, des expressions basées sur des attributs sont attendues à la place de la syntaxe basée sur des balises décrite ci-dessus. Exemples :

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

Si votre filtre bloque tous les résultats, l'API renvoie les documents populaires génériques (non filtrés). Si vous ne souhaitez obtenir que des résultats correspondant exactement aux filtres, définissez strictFiltering sur true dans RecommendRequest.params pour recevoir des résultats vides à la place.

Notez que l'API ne renvoie jamais de Document avec storageStatus comme EXPIRED ou DELETED, quels que soient les filtres choisis.
validateOnly

boolean

Utilisez le mode validation uniquement pour cette requête de recommandation. Si la valeur est définie sur true, un modèle factice est utilisé et renvoie des ID de document arbitraires. Notez que le mode "Valider uniquement" ne doit être utilisé que pour tester l'API ou si le modèle n'est pas prêt.
params

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

Paramètres supplémentaires spécifiques au domaine pour les recommandations.

Valeurs autorisées :

  • returnDocument : booléen. Si la valeur est définie sur true, l'objet Document associé est renvoyé dans RecommendResponse.RecommendationResult.document.
  • returnScore : booléen. Si la valeur est définie sur "true", le score de recommandation correspondant à chaque document renvoyé est défini dans RecommendResponse.RecommendationResult.metadata. Le score indiqué correspond à la probabilité de conversion d'un document en fonction du contexte et de l'historique de l'utilisateur.
  • strictFiltering : booléen. True par défaut. Si la valeur est définie sur false, le service renvoie des documents populaires génériques (non filtrés) au lieu de résultats vides si votre filtre bloque tous les résultats de recommandation.
  • diversityLevel : chaîne. La valeur par défaut est vide. S'il n'est pas vide, il doit correspondre à l'une des valeurs suivantes :
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity Cela permet de contrôler les requêtes et d'ajuster les résultats de recommandation en fonction de la catégorie de document.
  • attributeFilteringSyntax : booléen. Faux par défaut. Si la valeur est "true", le champ filter est interprété selon la nouvelle syntaxe basée sur les attributs.
userLabels

map (key: string, value: string)

Les libellés utilisateur appliqués à une ressource doivent répondre aux exigences suivantes :

  • Chaque ressource peut posséder plusieurs libellés, jusqu'à un maximum de 64.
  • Chaque étiquette doit correspondre à une paire clé/valeur.
  • Les clés doivent comporter un (1) caractère au minimum et 63 au maximum, et ne peuvent pas être vides. Les valeurs peuvent être vides et comporter 63 caractères au maximum.
  • Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets. Tous les caractères doivent être au format d'encodage UTF-8. Les caractères internationaux sont autorisés.
  • La partie clé d'un libellé doit être unique. Cependant, vous pouvez utiliser la même clé avec plusieurs ressources.
  • Les clés doivent commencer par une lettre minuscule ou un caractère international.

Pour en savoir plus, consultez Exigences relatives aux libellés.

Corps de la réponse

Si la requête aboutit, le corps de la réponse contient une instance de RecommendResponse.

Niveaux d'accès des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour plus d'informations, consultez la Authentication Overview.

Autorisations IAM

Nécessite l'autorisation IAM suivante sur la ressource servingConfig :

  • discoveryengine.servingConfigs.recommend

Pour en savoir plus, consultez la documentation IAM.