Method: projects.locations.dataStores.servingConfigs.recommend

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

Requête HTTP

POST https://discoveryengine.googleapis.com/v1alpha/{servingConfig=projects/*/locations/*/dataStores/*/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 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 recommandation. 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 détails sur l'événement utilisateur ne seront pas ingérés 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 ni 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 100. Les valeurs supérieures à 100 sont définies sur 100.
filter

string

Filtre permettant de limiter les résultats de recommandation,avec une limite de 5 000 caractères. Actuellement, 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 attributeFilteringSyntax est défini sur "true" dans le champ params, des expressions basées sur des attributs sont attendues à la place de la syntaxe basée sur des tags 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 des documents populaires génériques (non filtrés). Si vous ne souhaitez que des résultats correspondant strictement 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 défini sur EXPIRED ou DELETED, quels que soient les choix de filtre.
validateOnly

boolean

Utilisez le mode de validation uniquement pour cette requête de recommandation. Si la valeur est définie sur true, un faux modèle est utilisé et renvoie des ID de document arbitraires. Notez que le mode de validation 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 : valeur booléenne. Si la valeur est définie sur true, l'objet Document associé est renvoyé dans RecommendResponse.RecommendationResult.document.
  • returnScore : valeur booléenne. 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 donné indique la probabilité de conversion d'un document en fonction du contexte et de l'historique de l'utilisateur.
  • strictFiltering : valeur booléenne. Valeur par défaut : "true". 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. Valeur par défaut : vide. Si la valeur n'est pas vide, elle doit être l'une des suivantes :
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity : permet de contrôler au niveau de la requête et d'ajuster les résultats de recommandation en fonction de la catégorie de document.
  • attributeFilteringSyntax : valeur booléenne. Valeur par défaut : "false". Si la valeur est définie sur "true", le champ filter est interprété selon la nouvelle syntaxe basée sur des 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 libellé doit correspondre à une paire clé/valeur.
  • Les clés doivent comporter au moins 1 caractère et au maximum 63 caractères, et ne peuvent pas être vides. Les valeurs peuvent être vides et comporter au maximum 63 caractères.
  • Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des caractères numériques, 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. Toutefois, 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 concernant les 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 niveaux d'accès OAuth suivants :

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

Pour plus d'informations, consultez la page 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.