Configurer les commandes de diffusion

Les commandes de diffusion (également appelées commandes) modifient le comportement par défaut de la diffusion d'une requête lorsque des résultats sont renvoyés. Les commandes de diffusion agissent au niveau du datastore.

Par exemple, les commandes peuvent booster et rétrograder des résultats, filtrer les entrées des résultats renvoyés, associer des chaînes entre elles en tant que synonymes ou rediriger les résultats vers des URI spécifiés.

À propos des commandes de diffusion

Pour modifier les résultats d'une requête, commencez par créer un contrôle de diffusion. Ensuite, associez cette commande à la configuration de diffusion d'une application. Une configuration de diffusion configure les métadonnées utilisées pour générer les résultats au moment de la diffusion, tels que les résultats de recherche ou les réponses. Une commande de diffusion n'affecte les requêtes diffusées par l'application que si elle est associée à la configuration de diffusion de l'application.

Certaines commandes, telles que les commandes de boost, dépendent des datastores. Si un data store est supprimé d'une application, toutes les commandes qui en dépendent sont également supprimées de cette application et deviennent inactives, mais ne sont pas supprimées.

Types de commandes de mise en service

Les types de contrôles de diffusion suivants sont disponibles :

Contrôle Description Disponible pour
Contrôle accru Modifie l'ordre des résultats renvoyés. Applications de recherche avec des datastores compatibles avec un schéma, tels que les datastores contenant des données structurées ou des données non structurées avec des métadonnées
Commande de filtrage Supprime des entrées des résultats renvoyés. Applications de recherche avec des datastores compatibles avec un schéma, tels que les datastores contenant des données structurées ou des données non structurées avec des métadonnées
Commande de synonymes Associe les requêtes entre elles. Applications de recherche avec des datastores de données structurées ou non structurées
Commande de redirection Redirige vers un URI spécifié Toutes les applications de recherche
Commande de promotion Met en avant un lien spécifié pour une requête Applications de recherche avec des datastores de données structurées ou non structurées

À propos des conditions

Lorsque vous créez un contrôle, vous pouvez éventuellement définir une condition qui détermine quand il est appliqué. Les conditions sont définies à l'aide de champs de condition. Les champs de condition suivants sont disponibles :

  • queryTerms : commande facultative appliquée lorsque des requêtes spécifiques sont recherchées. Lorsque la condition queryTerms est utilisée, le contrôle est appliqué lorsque la valeur de queryTerms correspond à un terme de SearchRequest.query. Les termes de requête ne peuvent être utilisés que lorsque Control.searchUseCase est défini sur SOLUTION_TYPE_SEARCH. Vous pouvez spécifier jusqu'à 10 queryTerms différents sur un même Control.condition. Si aucun terme de requête n'est spécifié, le champ queryTerms est ignoré.

    Pour créer un contrôle de promotion, vous devez spécifier le champ queryTerms avec fullMatch défini sur true ou false.

  • activeTimeRange : contrôle facultatif appliqué lorsqu'une requête se produit dans un intervalle de temps spécifié. Elle vérifie que l'heure de réception d'une requête est comprise entre activeTimeRange.startTime et activeTimeRange.endTime. Vous pouvez spécifier jusqu'à 10 plages activeTimeRange sur un seul Control.condition. Si le champ activeTimeRange n'est pas spécifié, il est ignoré.

Si plusieurs conditions sont spécifiées pour une commande, celle-ci est appliquée à la requête de recherche lorsque les deux types de conditions sont remplis. Si plusieurs valeurs sont spécifiées pour la même condition, une seule d'entre elles doit correspondre pour que la condition soit remplie.

Par exemple, considérons la condition suivante avec deux termes de requête spécifiés :

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

La condition sera remplie pour une requête avec SearchRequest.query="gShoe" ou une requête avec SearchRequest.query="gBoot", mais pas pour SearchRequest.query="gSandal" ou toute autre chaîne.

Si aucune condition n'est spécifiée, le contrôle est toujours appliqué.

Pour en savoir plus, consultez le champ Condition dans la documentation de référence de l'API.

Créer et associer des commandes de diffusion de boost

Une commande de diffusion de boosting réorganise les résultats en les promouvant ou en les rétrogradant en fonction des conditions appliquées. L'amélioration consiste à appliquer un facteur de multiplication au classement d'un document qui remplit les conditions d'amélioration.

Suivez les instructions ci-dessous pour créer une commande de diffusion de boost.

Console

Pour créer et associer une commande de boost à l'aide de la console Google Cloud , procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

    Gemini Enterprise

  2. Sélectionnez l'application pour laquelle vous souhaitez créer le contrôle de boost.

  3. Cliquez sur Configurations, puis sur l'onglet Contrôle.

  4. Cliquez sur Créer une commande.

  5. Pour Que souhaitez-vous faire ?, spécifiez le nom et le type de la commande :

    1. Dans le champ Nom de la commande, saisissez un nom pour votre commande de boosting/rétrogradation.

    2. Pour Type de commande, sélectionnez Boosting/Rétrogradation.

    3. Cliquez sur Continuer.

  6. Dans Définir le champ d'application et l'impact de la règle, définissez les actions que vous souhaitez déclencher avec cette commande :

    1. Sélectionnez un data store dans la liste. Si vous souhaitez que l'action soit appliquée à plusieurs datastores, créez un contrôle pour chaque data store.

    2. Pour Filtre, ajoutez un filtre.

      Chaîne spécifiant les exigences que le document doit respecter. La condition de boost n'est appliquée que si le document remplit toutes les conditions. Sinon, aucun changement n'est apporté. Si vous ne spécifiez pas de filtre, le boost est appliqué à tous les documents du data store.

      Pour en savoir plus sur la syntaxe de filtrage, consultez Syntaxe des expressions de filtre.

    3. Pour Valeur de boosting/rétrogradation, sélectionnez une valeur de boosting/rétrogradation comprise entre -1 et 1 à l'aide du curseur. Le curseur se déplace par incréments de 0,01.

    4. Cliquez sur Continuer.

  7. Pour Facultatif : circonstances d'activation de cette règle, définissez les conditions suivantes qui déclenchent le contrôle. Si aucune condition n'est configurée, la commande est toujours opérationnelle :

    1. Ajoutez des termes de requête à correspondance partielle. La commande prend effet lorsque ces termes de requête correspondent partiellement.

    2. Ajoutez des termes de requête à correspondance exacte. La commande prend effet lorsque ces termes de requête correspondent exactement.

    3. Pour ajouter une plage horaire active, cliquez sur Ajouter une plage horaire, puis définissez Heure de début 1 et Heure de fin 1. Cela définit la période pendant laquelle la condition est active. Vous pouvez ajouter jusqu'à 10 périodes.

    4. Cliquez sur Continuer.

  8. Dans Paramètres supplémentaires, indiquez si vous souhaitez activer la règle :

    1. Si vous ne souhaitez pas activer ce contrôle dès sa création, désactivez l'option Publier ce contrôle immédiatement.

    2. Cliquez sur Continuer.

  9. Cliquez sur Envoyer.

REST

Une commande de diffusion de boost est définie comme une commande avec un boostAction.

Suivez les instructions ci-dessous pour créer une commande de diffusion de boost.

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous disposez déjà de l'ID de votre application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": [
  "USE_CASE"
],
"conditions": {
 "queryTerms": [
   {
     "value": "VALUE",
     "fullMatch": FULL_MATCH
   }
 ],
 "activeTimeRange": [
   {
     "startTime": "START_TIMESTAMP",
     "endTime": "END_TIMESTAMP"
   }
 ]
},
"boostAction": {
  "boost": BOOST_VALUE,
  "filter": "FILTER",
  "dataStore": "DATA_STORE_RESOURCE_PATH"
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir de 1 à 63 caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
    • DISPLAY_NAME : nom lisible par l'humain du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Il doit s'agir d'une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
    • USE_CASE : doit avoir la valeur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit quand le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à mettre en correspondance. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut comporter au maximum trois termes séparés par des espaces.
      • FULL_MATCH : valeur booléenne indiquant si la requête de recherche doit correspondre exactement au terme de la requête. Lorsqu'il est défini sur true, il nécessite que SearchRequest.query corresponde complètement à queryTerm.value. Lorsqu'il est défini sur false, il nécessite que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
      • START_TIMESTAMP : horodatage au format RFC 3339 UTC "Zulu" pour indiquer le début d'une période.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer la fin d'une période.
    • BOOST_VALUE : nombre à virgule flottante compris entre -1 et 1. Lorsque la valeur est négative, les résultats sont rétrogradés (ils apparaissent plus bas dans les résultats). Lorsque la valeur est positive, les résultats sont promus (ils apparaissent plus haut dans les résultats). Pour en savoir plus, consultez la page sur la méthode boostAction.
    • FILTER : chaîne spécifiant les exigences que le document doit respecter. Si le document répond à toutes les exigences, le boost est appliqué. Sinon, aucun changement n'est apporté. Si ce champ est vide, le boost est appliqué à tous les documents du data store. Pour connaître la syntaxe de filtrage, consultez Syntaxe des expressions de filtre. Remarque : Le champ de document title ne peut pas être filtré.
    • DATA_STORE_RESOURCE_PATH : chemin d'accès complet à la ressource du data store dont les documents doivent être boostés par cette commande. Le format du chemin d'accès complet à la ressource est projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Ce data store doit être associé au moteur spécifié dans la requête.

  3. Associez la commande à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
-d '{
 "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
}'

    Remplacez BOOST_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

Créer et associer des commandes de diffusion de filtres

Une règle de diffusion de filtre est définie comme une règle avec un filterAction.

Suivez les instructions ci-dessous pour créer un contrôle de diffusion de filtre.

Console

Pour créer et associer une commande de filtre à l'aide de la console Google Cloud , procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

    Gemini Enterprise

  2. Sélectionnez l'application pour laquelle vous souhaitez créer la commande de filtrage.

  3. Cliquez sur Configurations, puis sur l'onglet Contrôle.

  4. Cliquez sur Créer une commande.

  5. Pour Que souhaitez-vous faire ?, spécifiez le nom et le type de la commande :

    1. Dans le champ Nom de la commande, saisissez un nom pour votre commande de filtre.

    2. Pour Type de commande, sélectionnez Filtre.

    3. Cliquez sur Continuer.

  6. Dans Définir le champ d'application et l'impact de la règle, définissez les actions que vous souhaitez déclencher avec cette commande :

    1. Sélectionnez un data store dans la liste. Si vous souhaitez que l'action soit appliquée à plusieurs datastores, créez un contrôle pour chaque datastore.

    2. Pour Filtre, indiquez à la règle les éléments spécifiques à rechercher. Vous pouvez combiner des termes de recherche à l'aide de AND, OR NOT et regrouper des termes avec (). Pour les expressions exactes, utilisez des guillemets (""). Par exemple : category: "electronics" AND price < 500, status: "open" AND priority:"P1".

      Pour en savoir plus sur la syntaxe de filtrage, consultez Syntaxe des expressions de filtre.

    3. Cliquez sur Continuer.

  7. Pour Facultatif : circonstances d'activation de cette règle, définissez les conditions suivantes qui déclenchent le contrôle. Si aucune condition n'est configurée, la commande est toujours opérationnelle :

    1. Ajoutez des termes de requête à correspondance partielle. La commande prend effet lorsque ces termes de requête correspondent partiellement.

    2. Ajoutez des termes de requête à correspondance exacte. La commande prend effet lorsque ces termes de requête correspondent exactement.

    3. Pour ajouter une plage horaire active, cliquez sur Ajouter une plage horaire, puis définissez Heure de début 1 et Heure de fin 1. Cela définit la période pendant laquelle la condition est active. Vous pouvez ajouter jusqu'à 10 périodes.

    4. Cliquez sur Continuer.

  8. Dans Paramètres supplémentaires, indiquez si vous souhaitez activer la règle :

    1. Si vous ne souhaitez pas activer ce contrôle dès sa création, désactivez l'option Publier ce contrôle immédiatement.

    2. Cliquez sur Continuer.

  9. Cliquez sur Envoyer.

REST

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous disposez déjà de l'ID de votre application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"filterAction": {
  "filter": "FILTER"
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir de 1 à 63 caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
    • DISPLAY_NAME : nom lisible par l'humain du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Il doit s'agir d'une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
    • USE_CASE : doit avoir la valeur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit quand le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à mettre en correspondance. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut comporter au maximum trois termes séparés par des espaces.
      • FULL_MATCH : valeur booléenne indiquant si la requête de recherche doit correspondre exactement au terme de la requête. Lorsqu'il est défini sur true, il nécessite que SearchRequest.query corresponde complètement à queryTerm.value. Lorsqu'il est défini sur false, il nécessite que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
      • START_TIMESTAMP : horodatage au format RFC 3339 UTC "Zulu" pour indiquer le début d'une période.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer la fin d'une période.
    • FILTER : chaîne spécifiant les exigences que le document doit respecter. Si le document répond à toutes les exigences, il est renvoyé dans les résultats. Sinon, le document n'est pas inclus dans les résultats. Pour en savoir plus sur la syntaxe de filtrage, consultez Syntaxe des expressions de filtre. Pour en savoir plus, consultez filterAction. Remarque : Le champ de document title ne peut pas être filtré.

  3. Associez la commande à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
-d '{
  "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
}'

    Remplacez FILTER_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

Créer et associer des contrôles de diffusion de synonymes

Une règle de diffusion de synonymes est définie comme une règle avec un synonymsAction.

Suivez les instructions ci-dessous pour créer une commande de diffusion de synonymes.

Console

Pour créer et associer un contrôle de synonymes à l'aide de la console Google Cloud , procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

    Gemini Enterprise

  2. Sélectionnez l'application pour laquelle vous souhaitez créer le contrôle des synonymes.

  3. Cliquez sur Configurations, puis sur l'onglet Contrôle.

  4. Cliquez sur Créer une commande.

  5. Pour Que souhaitez-vous faire ?, spécifiez le nom et le type de la commande :

    1. Dans le champ Nommer votre commande, saisissez un nom pour votre commande de synonymes.

    2. Pour Type de commande, sélectionnez Synonymes.

    3. Cliquez sur Continuer.

  6. Dans Définir le champ d'application et l'impact de la règle, définissez les actions que vous souhaitez déclencher avec cette commande :

    1. Saisissez les synonymes que vous souhaitez prendre en compte dans le contrôle. Par exemple, saisissez chats, appuyez sur Entrée (pas de virgule), puis saisissez félins.

    2. Cliquez sur Continuer.

  7. Pour Facultatif : circonstances d'activation de cette règle, définissez les conditions suivantes qui déclenchent le contrôle. Si aucune condition n'est configurée, la commande est toujours opérationnelle :

    1. Pour ajouter une plage horaire active, cliquez sur Ajouter une plage horaire, puis définissez l'Heure de début 1 et l'Heure de fin 1. Cela définit la période pendant laquelle la condition est active. Vous pouvez ajouter jusqu'à 10 périodes.

    2. Cliquez sur Continuer.

  8. Dans Paramètres supplémentaires, indiquez si vous souhaitez activer la règle :

    1. Si vous ne souhaitez pas activer ce contrôle dès sa création, désactivez l'option Publier ce contrôle immédiatement.

    2. Cliquez sur Continuer.

  9. Cliquez sur Envoyer.

REST

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous disposez déjà de l'ID de votre application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"synonymsAction": {
  "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir de 1 à 63 caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
    • DISPLAY_NAME : nom lisible par l'humain du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Il doit s'agir d'une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
    • USE_CASE : doit avoir la valeur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit quand le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à mettre en correspondance. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut comporter au maximum trois termes séparés par des espaces.
      • FULL_MATCH : valeur booléenne indiquant si la requête de recherche doit correspondre exactement au terme de la requête. Lorsqu'il est défini sur true, il nécessite que SearchRequest.query corresponde complètement à queryTerm.value. Lorsqu'il est défini sur false, il nécessite que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
      • START_TIMESTAMP : horodatage au format RFC 3339 UTC "Zulu" pour indiquer le début d'une période.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer la fin d'une période.
    • SYNONYMS_N : liste de chaînes associées les unes aux autres, ce qui augmente la probabilité que chacune d'elles affiche des résultats similaires. Bien qu'il soit plus probable que vous obteniez des résultats similaires, lorsque vous recherchez chacune des entrées de synonymes, vous ne recevrez peut-être pas tous les résultats pertinents pour tous les synonymes associés. Vous devez spécifier au moins deux synonymes et vous pouvez en spécifier jusqu'à 100. Chaque synonyme doit être encodé au format UTF-8 et en minuscules. Les chaînes en double ne sont pas autorisées. Par exemple, vous pouvez ajouter "pixel", "téléphone android" et "téléphone google" comme synonymes. Pour en savoir plus, consultez synonymsAction.

  3. Associez la commande à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
-d '{
  "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
}'

    Remplacez SYNONYMS_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

Créer et associer des commandes de diffusion de redirection

Une commande de diffusion de redirection permet de rediriger les utilisateurs vers un URI fourni. Les commandes de redirection sont définies comme une commande avec un redirectAction.

Suivez les instructions ci-dessous pour créer un contrôle de diffusion de redirection.

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous disposez déjà de l'ID de votre application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"redirectAction": {
  "redirectURI": "REDIRECT_URI"
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir de 1 à 63 caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
    • DISPLAY_NAME : nom lisible par l'humain du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Il doit s'agir d'une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
    • USE_CASE : doit avoir la valeur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit quand le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à mettre en correspondance. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut comporter au maximum trois termes séparés par des espaces.
      • FULL_MATCH : valeur booléenne indiquant si la requête de recherche doit correspondre exactement au terme de la requête. Lorsqu'il est défini sur true, il nécessite que SearchRequest.query corresponde complètement à queryTerm.value. Lorsqu'il est défini sur false, il nécessite que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
      • START_TIMESTAMP : horodatage au format RFC 3339 UTC "Zulu" pour indiquer le début d'une période.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer la fin d'une période.
    • REDIRECT_URI_N : URI vers lequel vous êtes redirigé. La longueur maximale est de 2 000 caractères. Par exemple, si la valeur du terme de recherche est "assistance", vous pouvez définir une redirection vers votre page d'assistance technique au lieu de renvoyer (ou de ne pas renvoyer) les résultats de recherche pour "assistance". Dans cet exemple, l'URI de redirection devient "https://www.example.com/support". Pour en savoir plus, consultez redirectAction.

  3. Associez la commande à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
-d '{
  "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
}'

    Remplacez REDIRECT_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

Créer et associer des contrôles de diffusion de promotion

Une commande de mise en service de promotion vous permet d'afficher un lien en tant que résultat mis en avant. Cette commande est disponible pour les applications de recherche avec des datastores de données structurées ou non structurées et les applications de recherche mixte.

Pour que la commande de promotion prenne effet, vous devez l'associer à la configuration de diffusion de l'application.

Les commandes de promotion sont définies à l'aide d'un promoteAction.

Pour créer un contrôle de promotion, vous devez spécifier le champ queryTerms avec fullMatch défini sur true ou false.

Suivez les instructions ci-dessous pour créer une commande de diffusion de promotion.

Console

Pour créer une commande de diffusion de promotion, suivez les instructions de l'onglet "REST".

REST

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous disposez déjà de l'ID de votre application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "URI_DESCRIPTION"
  }
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir de 1 à 63 caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
    • DISPLAY_NAME : nom lisible par l'humain du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Il doit s'agir d'une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
    • USE_CASE : doit avoir la valeur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit quand le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à mettre en correspondance. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000].
      • FULL_MATCH : valeur booléenne indiquant si le terme de la requête doit correspondre entièrement.
      • START_TIMESTAMP : horodatage au format RFC 3339 UTC "Zulu" pour indiquer le début d'une période.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer la fin d'une période.
    • DATA_STORE_RESOURCE_PATH : chemin d'accès complet de la ressource du data store dont les résultats de recherche contiennent l'URL promue. Le format du chemin d'accès complet à la ressource est projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Ce data store doit être associé au moteur spécifié dans la requête.

    • DOCUMENT_RESOURCE_PATH : champ permettant de spécifier le chemin d'accès à la ressource du document à promouvoir. Vous devez fournir l'ID du document dans le champ DOCUMENT_RESOURCE_PATH, l'URI dans le champ URI, ou les deux.

      Le format du chemin d'accès complet à la ressource est le suivant : projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.

    • TITLE : champ obligatoire permettant de spécifier le titre du document ou de la page Web à promouvoir. Ce titre s'affiche dans le résultat de recherche.

    • URI : champ permettant de spécifier l'URI vers lequel le résultat de recherche redirige l'utilisateur. Vous devez fournir l'ID du document dans le champ DOCUMENT_RESOURCE_PATH, l'URI dans le champ URI, ou les deux.

    • URI_DESCRIPTION : champ facultatif permettant de décrire l'URI, qui s'affiche dans le résultat de recherche.

    La réponse contient les ID de contrôle de promotion dont vous avez besoin pour associer votre contrôle de promotion à votre application de recherche.

  3. Associez la commande à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch. L'ordre dans lequel vous associez les promoteControlIds dans la requête suivante correspond à l'ordre dans lequel les résultats promus sont renvoyés.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=promote_control_ids" \
-d '{
  "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]
}'

    Remplacez PROMOTE_ID_N par les ID de contrôle que vous avez reçus à l'étape précédente.

Modifier les commandes de diffusion

Pour modifier la configuration d'un contrôle, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

    Gemini Enterprise

  2. Sélectionnez l'application pour laquelle vous souhaitez modifier les commandes.

  3. Cliquez sur Configurations, puis sur l'onglet Contrôle.

  4. Dans la liste des commandes de l'application, cliquez sur pour une commande que vous souhaitez modifier, puis sur Modifier.

  5. Modifiez la commande dans le volet Modifier la commande :

    1. Pour activer ou désactiver un contrôle, dans la liste des contrôles de filtre de l'application, cliquez sur pour le contrôle que vous souhaitez activer ou désactiver, puis cliquez sur Activer ou Désactiver, respectivement.

    2. Pour supprimer un contrôle, dans la liste des contrôles de l'application, cliquez sur pour le contrôle que vous souhaitez supprimer, puis cliquez sur Supprimer.

Étapes suivantes