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

Configurer des commandes de diffusion

Les contrôles de diffusion (également appelés contrôles) modifient le comportement par défaut de la façon dont une requête est traitée lorsque des résultats sont renvoyés. Les contrôles de diffusion agissent au niveau du data store.

Par exemple, les contrôles peuvent booster et enterrer des résultats, filtrer des entrées à partir des résultats renvoyés, associer des chaînes entre elles en tant que synonymes ou rediriger des 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 ce contrôle à 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.

Certains contrôles, tels que les contrôles d'amplification, dépendent des magasins de données. Si un data store est supprimé d'une application, tous les contrôles qui en dépendent sont également supprimés de cette application et deviennent inactifs, mais ne sont pas supprimés.

Types de commandes de diffusion

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

Contrôle	Description	Disponible pour
Contrôle renforcé	Modifie l'ordre des résultats renvoyés	Applications de recherche avec des data stores compatibles avec un schéma, tels que les data stores contenant des données structurées ou des données non structurées avec des métadonnées
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 les data stores contenant des données structurées ou des données non structurées avec des métadonnées
Contrôle des synonymes	Associer des requêtes entre elles	Applications de recherche avec des data stores de données structurées ou non structurées
Contrôle des redirections	Redirige vers un URI spécifié	Toutes les applications de recherche
Commande de promotion	Promouvoir un lien spécifique pour une requête	Applications de recherche avec des data stores 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 le contrôle 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 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 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 une plage horaire spécifiée. Elle vérifie que l'heure à laquelle une requête a été reçue se situe entre activeTimeRange.startTime et activeTimeRange.endTime. Vous pouvez spécifier jusqu'à 10 plages activeTimeRange dans un même Control.condition. Si le champ activeTimeRange n'est pas spécifié, il est ignoré.

Si plusieurs conditions sont spécifiées pour un contrôle, celui-ci est appliqué à la demande 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 SearchRequest.query="gBoot", mais pas avec SearchRequest.query="gSandal" ni aucune 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 contrôles de diffusion de boost

Un contrôle de diffusion avec boost est défini comme un contrôle avec un boostAction.

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

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.

Trouvez l'ID de votre application. Si vous avez déjà votre ID d'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.
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 entre 1 et 63 caractères (lettres, chiffres, tirets et 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 encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
- USE_CASE : doit être défini sur 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 le moment où le contrôle doit être appliqué. Contient les champs suivants :
  - VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut contenir 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 requête. Lorsqu'il est défini sur true, il exige que SearchRequest.query corresponde entièrement à queryTerm.value. Lorsqu'il est défini sur false, il exige que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
  - START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage horaire.
  - END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant la fin d'une période.
- BOOST_VALUE : nombre à virgule flottante compris dans la plage [-1,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 mis en avant (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, rien ne change. Si ce champ est vide, l'augmentation s'applique à 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 mis en avant par ce contrôle. 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.

Associez le contrôle à 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 contrôles de diffusion de filtres

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

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

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.

Trouvez l'ID de votre application. Si vous avez déjà votre ID d'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.
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 entre 1 et 63 caractères (lettres, chiffres, tirets et 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 encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
- USE_CASE : doit être défini sur 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 le moment où le contrôle doit être appliqué. Contient les champs suivants :
  - VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut contenir 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 requête. Lorsqu'il est défini sur true, il exige que SearchRequest.query corresponde entièrement à queryTerm.value. Lorsqu'il est défini sur false, il exige que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
  - START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage horaire.
  - END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant 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 ne figure pas dans les résultats. Pour connaître la syntaxe de filtrage, consultez la section Syntaxe des expressions de filtre. Pour en savoir plus, consultez la section consacrée à filterAction. Remarque : Le champ de document title ne peut pas être filtré.

Associez le contrôle à 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

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

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

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.

Trouvez l'ID de votre application. Si vous avez déjà votre ID d'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.
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 entre 1 et 63 caractères (lettres, chiffres, tirets et 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 encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
- USE_CASE : doit être défini sur 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 le moment où le contrôle doit être appliqué. Contient les champs suivants :
  - VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut contenir 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 requête. Lorsqu'il est défini sur true, il exige que SearchRequest.query corresponde entièrement à queryTerm.value. Lorsqu'il est défini sur false, il exige que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
  - START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage horaire.
  - END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant 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, il est possible que vous ne receviez 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.

Associez le contrôle à 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 contrôles de diffusion de redirection

Une commande de diffusion de redirection permet de rediriger les utilisateurs vers un URI fourni. Les contrôles de redirection sont définis comme des contrôles 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.

Trouvez l'ID de votre application. Si vous avez déjà votre ID d'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.
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 entre 1 et 63 caractères (lettres, chiffres, tirets et 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 encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
- USE_CASE : doit être défini sur 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 le moment où le contrôle doit être appliqué. Contient les champs suivants :
  - VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut contenir 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 requête. Lorsqu'il est défini sur true, il exige que SearchRequest.query corresponde entièrement à queryTerm.value. Lorsqu'il est défini sur false, il exige que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
  - START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage horaire.
  - END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant la fin d'une période.
- REDIRECT_URI_N : URI vers lequel vous êtes redirigé. Ne doit pas comporter plus de 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". Dans cet exemple, l'URI de redirection devient "https://www.example.com/support". Pour en savoir plus, consultez la section consacrée à redirectAction.

Associez le contrôle à 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

Un contrôle de diffusion de promotion vous permet d'afficher un lien en tant que résultat sponsorisé. Cette commande est disponible pour les applications de recherche avec des magasins de données structurées ou non structurées, ainsi que pour les applications de recherche combinée.

Pour que le contrôle de promotion soit pris en compte, vous devez l'associer à la configuration de diffusion de l'application.

Les contrôles de promotion sont définis à 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 un contrôle de promotion de la diffusion.

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.

Trouvez l'ID de votre application. Si vous avez déjà votre ID d'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.
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_TRUE|FALSE
    }
  ],
  "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 entre 1 et 63 caractères (lettres, chiffres, tirets et 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 encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
- USE_CASE : doit être défini sur 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 : objet facultatif qui définit le moment où le contrôle doit être appliqué. Contient les champs suivants :
  - queryTerms :
    - VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000].
    - FULL_MATCH_TRUE|FALSE : valeur booléenne indiquant si le terme de requête doit correspondre exactement.
  - activeTimeRange :
    - START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage horaire.
    - END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant la fin d'une période.
- DATA_STORE_RESOURCE_PATH : chemin d'accès complet à 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.
Réponse

Vous devriez recevoir une réponse JSON de ce type :
```
{
 "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls/PROMOTE_CONTROL_ID",
 "displayName": "PROMOTE_CONTROL_NAME",
 "solutionType": "SOLUTION_TYPE_SEARCH",
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": true
       }
     ]
   }
 ],
 "useCases": [
   "SEARCH_USE_CASE_SEARCH"
 ],
 "promoteAction": {
   "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
   "searchLinkPromotion": {
     "title": "URI_TITLE",
     "uri": "URI",
     "description": "URI_DESCRIPTION",
     "enabled": ENABLED_TRUE|FALSE
  }
 }
}
```
La réponse contient des ID de contrôle de la promotion que vous devez associer à votre contrôle de la promotion dans votre application de recherche.

Associez le contrôle à 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 sponsorisés 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.

Étapes suivantes

Pour comprendre l'impact d'un contrôle de diffusion sur la qualité de la recherche d'une application, évaluez la qualité de la recherche.

Configurer des commandes de diffusion Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

À propos des commandes de diffusion

Types de commandes de diffusion

À propos des conditions

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

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

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

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

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

Réponse

Étapes suivantes

Configurer des commandes de diffusion