Cette page a été traduite par l'API Cloud Translation.

Configurer des commandes de diffusion

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

Elles permettent, par exemple, d'améliorer et de redescendre les résultats, de filtrer les entrées des des résultats, associer des requêtes entre elles en tant que synonymes ou rediriger les requêtes vers ou les 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 à 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, telles que les commandes d'optimisation, dépendent des datastores. Si un data store est supprimé d'une application, tous les contrôles dépendant du data store sont également supprimés de cette application et deviennent inactifs, mais ils ne sont pas supprimés.

Lorsque vous créez une commande, vous pouvez éventuellement définir une condition qui détermine lorsque la commande est appliquée. Les conditions sont définies à l'aide de champs de condition. La 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 remplie pour une requête avec SearchRequest.query="gShoe" ou une requête avec SearchRequest.query="gBoot", mais ne sera pas satisfait de SearchRequest.query="gSandal" ni d'une autre .

Si aucune condition n'est spécifiée, la commande est toujours appliquée.

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

Types de commandes de diffusion

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

Contrôle	Description	Disponible pour
Contrôle de l'amplification	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	Rechercher des applications avec des data stores compatibles avec un schéma, tels que des data stores contenant des données structurées, des sites Web contenant 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 des requêtes entre elles	Applications de recherche avec des data stores de site Web, de données structurées, non structurées ou multimédias
Commande de redirection	Redirection vers un URI spécifié	Toutes les applications de recherche

À propos des commandes d'optimisation de diffusion

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

La syntaxe d'un élément 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 correspond à tous les les conditions requises, le boost est appliqué. Sinon, il n'y a aucun changement. 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 magasin de données 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 demande.

À 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 à respecter par le paramètre document. 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

Une commande de diffusion de synonymes est définie comme une commande avec un synonymsAction.

La syntaxe d'un élément synonymsAction est la suivante:

{
    "synonyms": "SYNONYMS"
}

SYNONYMS: chaînes qui seront associées les unes aux autres, ce qui il est plus probable que chacun affiche des résultats similaires. Vous devez spécifier au moins deux chaînes, et vous pouvez spécifier jusqu'à 100 chaînes. Les chaînes doivent être au format UTF-8. et en minuscules. Aucune chaîne en double n'est autorisée.

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 comportant 2 000 caractères au maximum.

Par exemple, si la valeur du terme de requête est "support", vous pouvez définir une redirection vers votre page d'assistance technique au lieu de revenir dans les 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 pour un même objet. Control.condition Si aucun terme de requête n'est spécifié, le champ est ignoré.

La syntaxe d'un seul élément 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: une valeur booléenne. Si elle est définie sur true, elle nécessite SearchRequest.query pour correspondre exactement à 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 sont ignorées.

La syntaxe d'un seul activeTimeRange est la suivante :

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]

START_TIMESTAMP_1: définit la date/heure la plus proche (incluse) à laquelle le contrôle sera appliqué. Codes temporels sont au format RFC 3339 UTC "Zoulou" avec une résolution à la nanoseconde près et jusqu'à neuf chiffres décimaux (par exemple, "2023-10-02T15:01:23Z"
END_TIMESTAMP_1: définit le date/heure la plus récente (incluse) d'application du contrôle. Cette heure doit être à l'avenir.

Instructions relatives à l'API: modifier le comportement des requêtes de recherche par défaut à l'aide de 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 commandes de diffusion, contactez votre et demander à être ajouté à la liste d'autorisation pour les contrôles de diffusion.

Créer une commande de diffusion

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

Pour plus d'informations sur les champs, consultez les Documentation de référence de l'API Controls et Documentation de référence de l'API Controls.create

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.

Choisissez le type de condition et les valeurs de champ pour votre commande.

Voici un exemple tronqué de 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"
    },
  ]
}

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

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",
    }'

Commande de filtrage: cliquez pour afficher la commande curl pour créer une commande 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. pour créer un contrôle de 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 projet projet Google Cloud.
DATA_STORE_ID: identifiant unique du data store.
CONTROL_ID: identifiant unique (dans un data store) pour le 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 d'utiliser ce nom comme indication du moment ou pourquoi utiliser ce contrôle. Doit être une chaîne UTF-8 d'une longueur de [1,128].
USE_CASE: doit être 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 le Documentation de référence de l'API boostAction
FILTER_ACTION: permet de définir une commande de filtrage. Consultez le Documentation de référence de l'API filterAction
SYNONYMS_ACTION: permet de définir un contrôle de synonymes. Consultez le Documentation de référence de l'API synonymsAction
REDIRECT_ACTION: utilisé pour spécifier un URI de redirection. Consultez le Documentation de référence de l'API redirectAction

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 pour permettre l'utilisation lors de la diffusion des requêtes:

    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 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 une commande de redirection à un pour permettre l'utilisation lors de la diffusion de requêtes:

    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 Évaluer la qualité de la recherche

Configurer des commandes de diffusion

À propos des commandes de diffusion

Types de commandes de diffusion

À propos des commandes d'optimisation de diffusion

À propos des commandes de diffusion des filtres

À propos des commandes de diffusion des synonymes

À propos des commandes de diffusion de redirection

À propos de la condition queryTerms

À propos de la condition activeTimeRange

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

Avant de commencer

Créer une commande de diffusion

Étape suivante

À propos de la condition `queryTerms`

À propos de la condition `activeTimeRange`