Configurer les commandes de diffusion pour la recherche

Les commandes de diffusion (également appelées commandes) modifient le comportement par défaut d'une requête.

Par exemple, les commandes peuvent mettre en avant et masquer des résultats, filtrer les entrées des résultats renvoyés, associer des requêtes en tant que synonymes ou rediriger des requêtes vers des URI spécifiés.

Cette page décrit les commandes de diffusion pour les applications de recherche. Pour en savoir plus sur l'utilisation des commandes de diffusion avec les recommandations multimédias, consultez Créer et gérer des configurations de diffusion.

À 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 à une application. Une commande n'affecte que les requêtes traitées par une application à laquelle elle est associée. Si un contrôle n'est pas associé à une application, il n'a aucun effet.

Certaines commandes, comme les commandes de boost, dépendent des magasins de données. Si un data store est supprimé d'une application, toutes les commandes dépendant de cet data store sont également supprimées de cette application et deviennent inactives, mais ne sont pas supprimées.

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

  • queryTerms. Le contrôle est appliqué lorsque des requêtes spécifiques sont recherchées.
  • activeTimeRange : le contrôle est appliqué lorsqu'une requête se produit dans une période spécifiée.

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

Prenons l'exemple suivant, dans lequel deux termes de requête sont spécifiés:

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

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

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

Pour en savoir plus, consultez la documentation de référence de l'API servingConfigs.search.

Types de commandes de diffusion

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

Contrôle Description Disponible pour
Contrôle du boost Modifie l'ordre des résultats renvoyés Applications de recherche avec des data stores compatibles avec un schéma, tels que des data stores contenant des données structurées, des sites Web avec des données structurées, des données non structurées avec des métadonnées ou des données multimédias
Commande de filtrage Supprime les entrées des résultats renvoyés. Applications de recherche avec des data stores compatibles avec un schéma, tels que des data stores contenant des données structurées, des sites Web avec des données structurées, des données non structurées avec des métadonnées ou des données multimédias
Contrôle des synonymes Associe les requêtes les unes aux autres Applications de recherche avec des data stores de site Web, de données structurées, non structurées ou multimédias
Contrôle des redirections Redirection vers un URI spécifié Toutes les applications de recherche

À propos des commandes de diffusion optimisée

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

La syntaxe d'un boostAction est la suivante:

{
    "boost": "BOOST",
    "filter": "FILTER",
    "dataStore": "DATA_STORE_RESOURCE_PATH"
}
  • BOOST: nombre à virgule flottante compris entre -1 et 1. Lorsque la valeur est négative, les résultats sont rétrogradés et apparaissent plus loin dans les résultats de recherche. Lorsque la valeur est positive, les résultats sont promus pour apparaître plus tôt dans les résultats de recherche.
  • 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, aucune modification n'est apportée. Si ce champ est vide, l'amélioration est appliquée à tous les documents du magasin de données. Pour connaître la syntaxe de filtrage, consultez la section Syntaxe des expressions de filtre.
  • DATA_STORE_RESOURCE_PATH: chemin d'accès complet de la ressource du data store dont les documents doivent être optimisés par ce contrôle. Le format du chemin d'accès complet de la ressource est projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Ce data store doit être associé au moteur spécifié dans la requête.

À propos des commandes de diffusion des filtres

Un contrôle de diffusion de filtre est défini comme un contrôle avec un filterAction.

La syntaxe d'un filterAction est la suivante:

{
    "filter": "FILTER"
}
  • FILTER: chaîne spécifiant les exigences que le document doit respecter. Si le document répond à toutes les exigences, le résultat est inclus dans la liste des résultats. Sinon, le résultat est supprimé de la liste des résultats. Pour connaître la syntaxe de filtrage, consultez la section Syntaxe des expressions de filtre.

À propos des commandes de diffusion des synonymes

Un contrôle de diffusion de synonymes est défini comme un contrôle avec un synonymsAction.

La syntaxe d'un synonymsAction est la suivante:

{
    "synonyms": "SYNONYMS"
}
  • SYNONYMS: chaînes qui seront associées les unes aux autres, ce qui est plus susceptible de générer des résultats similaires. Vous devez spécifier au moins deux chaînes et pouvez en spécifier jusqu'à 100. Les chaînes doivent être au format UTF-8 et en minuscules. Les chaînes en double ne sont pas autorisées.

Exemple :

{
    "synonyms": ["pixel", "android phone", "google phone"]
}

À propos 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.

Syntaxe pour redirectAction:

{
    "redirect_uri": "REDIRECT_URI"
}
  • REDIRECT_URI: URI d'au plus 2 000 caractères.

Par exemple, si la valeur du terme de requête est "assistance", vous pouvez définir une redirection vers votre page d'assistance technique au lieu de renvoyer (ou de ne pas renvoyer) des résultats de recherche pour "assistance".

{
    "redirect_uri": ["https://www.example.com/support"]
}

À propos de la condition queryTerms

queryTerms est facultatif. Utilisez-le si vous souhaitez qu'un contrôle de diffusion soit utilisé 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 dans 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 est ignoré.

La syntaxe d'un seul queryTerm est la suivante:

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}
  • VALUE_1: chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est true, il ne peut contenir au maximum que trois termes séparés par des espaces.
  • FULL_MATCH_1: valeur booléenne. Lorsque la valeur est true, SearchRequest.query doit correspondre complètement à queryTerm.value. Lorsque ce paramètre est défini sur false, SearchRequest.query doit contenir queryTerm.value en tant que sous-chaîne.

À propos de la condition activeTimeRange

activeTimeRange est facultatif. Il 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 aucune plage activeTimeRange n'est spécifiée, le champ est ignoré.

La syntaxe d'un seul activeTimeRange est la suivante:

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]
  • START_TIMESTAMP_1: définit la première heure (inclusive) à laquelle le contrôle sera appliqué. Les horodatages sont au format RFC 3339 UTC "Zulu", avec une résolution de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux (par exemple, "2023-10-02T15:01:23Z").
  • END_TIMESTAMP_1: définit l'heure limite (inclusive) à laquelle le contrôle sera appliqué. Cette heure doit être située dans le futur.

Instructions relatives à l'API: modifier le comportement par défaut des requêtes de recherche à l'aide des commandes de diffusion

Pour modifier le comportement par défaut des requêtes de recherche, créez un contrôle de diffusion et associez-le à la configuration de diffusion par défaut.

Avant de commencer

Si vous souhaitez créer des contrôles de diffusion, contactez votre équipe de compte Google et demandez à être ajouté à la liste d'autorisation pour les contrôles de diffusion.

Créer un contrôle de diffusion

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

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

  1. Recherchez l'ID de votre data store. Si vous disposez déjà de l'ID de votre data store, passez à l'étape suivante.

    1. Dans la console Google Cloud, accédez à la page Agent Builder et cliquez sur Data Stores dans le menu de navigation.

      Accéder à la page "Datastores"

    2. Cliquez sur le nom de votre data store.

    3. Sur la page Données de votre data store, obtenez l'ID du data store.

  2. Choisissez le type de condition et les valeurs des champs pour votre sélecteur.

    Voici un exemple tronqué d'une condition:

    {
  "queryTerms": [
      {
        "value": "VALUE_1",
        "fullMatch": FULL_MATCH_1
      },
      {
        "value": "VALUE_2",
        "fullMatch": FULL_MATCH_2
      },
    ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP_1",
      "endTime": "END_TIMESTAMP_1"
    },
    {
      "startTime": "START_TIMESTAMP_2",
      "endTime": "END_TIMESTAMP_2"
    },
  ]
}

  3. Exécutez les commandes curl suivantes pour créer vos commandes.

    Contrôle de boost: cliquez pour afficher la commande curl permettant de créer un contrôle de boost.

    Exécutez la commande curl suivante:

        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/dataStores/DATA_STORE_ID/controls?CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "boostAction": "BOOST_ACTION",
    }'

    Contrôle de filtrage: cliquez pour afficher la commande curl permettant de créer un contrôle de filtrage.

    Exécutez la commande curl suivante:

        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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "filterAction": "FILTER_ACTION",
    }'

    Contrôle des synonymes: cliquez pour afficher la commande curl permettant de créer un contrôle des synonymes.

    Exécutez la commande curl suivante:

        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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "synonymsAction": "SYNONYMS_ACTION",
    }'

    Contrôle de redirection: cliquez pour afficher la commande curl permettant de créer un contrôle de redirection.

    Exécutez la commande curl suivante:

        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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "redirectAction": "REDIRECT_ACTION",
    }'
    • PROJECT_ID: numéro ou ID de votre projet Google Cloud.
    • DATA_STORE_ID: ID unique du data store.
    • CONTROL_ID: identifiant unique (dans un data store) du contrôle. L'ID peut contenir des lettres minuscules, des chiffres, des traits d'union et des traits de soulignement.
    • DISPLAY_NAME: nom lisible du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne UTF-8 de longueur [1,128].
    • 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 (facultatif) : définit le moment où le contrôle doit être appliqué.
    • BOOST_ACTION: permet de définir un contrôle de boost. Consultez la documentation de référence de l'API boostAction.
    • FILTER_ACTION: permet de définir un contrôle de filtre. Consultez la documentation de référence de l'API filterAction.
    • SYNONYMS_ACTION: permet de définir un contrôle de synonymes. Consultez la documentation de référence de l'API synonymsAction.
    • REDIRECT_ACTION: permet de spécifier un URI de redirection. Consultez la documentation de référence de l'API redirectAction.

  4. Associez le contrôle à l'application.

    Contrôle de boost: cliquez pour obtenir la commande curl pour un contrôle de boost.

    Exécutez la commande curl suivante pour associer un contrôle de boost à une configuration de diffusion afin d'autoriser son utilisation dans les requêtes de diffusion:

        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/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
    -d '{
      "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2" … ]
    }'

    BOOST_ID_1 et BOOST_ID_2: représentent les ID de contrôle que vous avez créés à l'étape précédente.

    Commande de filtrage: cliquez sur la commande curl pour une commande de filtrage.

    Exécutez la commande curl suivante pour associer un contrôleur de filtre à une configuration de diffusion afin de l'utiliser pour les requêtes de diffusion:

        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/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
    -d '{
      "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2" … ]
    }'

    FILTER_ID_1 et FILTER_ID_2: représentent les ID de contrôle que vous avez créés à l'étape précédente.

    Contrôle des synonymes: cliquez pour obtenir la commande curl pour un contrôle des synonymes.

    Exécutez la commande curl suivante pour associer un contrôle de synonymes à une application afin de l'utiliser pour les requêtes de diffusion:

        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/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
    -d '{
     "synonymsControlIds": ["SYNONYM_ID_1", "SYNONYM_ID_2" … ]
    }'

    SYNONYM_ID_1 et SYNONYM_ID_2: représentent les ID de contrôle que vous avez créés à l'étape précédente.

    Contrôle de redirection: cliquez pour obtenir la commande curl pour un contrôle de redirection.

    Exécutez la commande curl suivante pour associer un contrôle de redirection à une application afin de l'utiliser pour les requêtes de diffusion:

        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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
    -d '{
      "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2" … ]
    }'

    REDIRECT_ID_1 et REDIRECT_ID_2: représentent les ID de contrôle que vous avez créés à l'étape précédente.

Étape suivante

  • Pour comprendre l'impact d'un contrôle de diffusion sur la qualité de recherche d'une application de recherche générique, évaluez la qualité de recherche. Pour en savoir plus, consultez la section Évaluer la qualité de la recherche.