Esta página se ha traducido con Cloud Translation API.

Configurar los controles de publicación de la búsqueda

Los controles de publicación (también llamados controles) cambian el comportamiento predeterminado de cómo se publica una solicitud cuando se devuelven resultados. Los controles de publicación actúan a nivel de almacén de datos.

Por ejemplo, los controles pueden destacar y ocultar resultados, filtrar entradas de los resultados devueltos, asociar cadenas entre sí como sinónimos o redirigir resultados a URIs específicos.

En esta página se describen los controles de publicación de aplicaciones de búsqueda. Para obtener información sobre cómo usar los controles de publicación con recomendaciones de contenido multimedia, consulta Crear y gestionar configuraciones de publicación de contenido multimedia.

Acerca de los controles de publicación

Para cambiar los resultados de una solicitud, primero crea un control de publicación. A continuación, adjunta ese control a la configuración de servicio de una aplicación de búsqueda. Una configuración de servicio configura metadatos que se usan para generar resultados en tiempo de servicio, como resultados de búsqueda o respuestas. Un control de servicio solo afecta a las solicitudes que sirve la aplicación si el control está asociado a la configuración de servicio de la aplicación.

Algunos controles, como los de aumento, dependen de los almacenes de datos. Si se elimina un almacén de datos de una aplicación, los controles que dependan de ese almacén también se eliminarán de la aplicación y se desactivarán, pero no se borrarán.

Tipos de control de publicación

Están disponibles los siguientes tipos de controles de servicio:

Control	Descripción	Disponible para
Aumentar el control	Cambia el orden de los resultados devueltos.	Aplicaciones de búsqueda con almacenes de datos que admiten un esquema, como almacenes de datos que contienen datos estructurados, sitios web con datos estructurados (indexación avanzada de sitios web), datos no estructurados con metadatos o datos multimedia
Control de filtros	Elimina entradas de los resultados devueltos.	Aplicaciones de búsqueda con almacenes de datos que admiten un esquema, como almacenes de datos que contienen datos estructurados, sitios web (indexación avanzada de sitios web), datos sin estructurar con metadatos o datos multimedia
Control de sinónimos	Asocia las consultas entre sí	Aplicaciones de búsqueda con almacenes de datos de sitios web (indexación avanzada de sitios web), estructurados, sin estructurar o multimedia
Control de redirección	Redirige a un URI especificado.	Todas las aplicaciones de búsqueda
Promover el control	Promueve un enlace especificado para una consulta.	Todas las aplicaciones de búsqueda

Acerca de las condiciones

Al crear un control, puedes definir una condición que determine cuándo se aplica. Las condiciones se definen mediante campos de condición. Están disponibles los siguientes campos de condición:

Términos de consulta (queryTerms): control opcional que se aplica cuando se buscan consultas específicas. Cuando se usa la condición queryTerms, el control se aplica cuando el valor de queryTerms coincide con un término de SearchRequest.query. Los términos de consulta solo se pueden usar cuando Control.searchUseCase se define como SOLUTION_TYPE_SEARCH. Se pueden especificar hasta 10 queryTerms diferentes en un mismo Control.condition. Si no se especifican términos de consulta, se ignora el campo queryTerms.

En el caso de un control de publicación de promoción, no se puede especificar queryTerms si se especifica la condición queryRegex, que solo se aplica a la búsqueda básica en sitios web. Además, el campo fullMatch de la búsqueda básica en el sitio web debe tener el valor true si se especifica queryTerms. En el resto de las aplicaciones de búsqueda, solo se admite queryTerms y fullMatch se puede definir como true o false.
Intervalo de tiempo (activeTimeRange): control opcional que se aplica cuando se produce una solicitud dentro de un intervalo de tiempo especificado. Comprueba que la hora en la que se recibió una solicitud esté entre las activeTimeRange.startTime y las activeTimeRange.endTime. Se pueden especificar hasta 10 intervalos de activeTimeRange en un solo Control.condition. Si no se especifica el campo activeTimeRange, se ignora.
queryRegex. Solo está disponible para el control de servicio de promociones de la búsqueda básica en sitios web. Esta es una condición opcional que aplica el control cuando la consulta coincide con la expresión regular especificada. Esta condición no se puede especificar si se especifica la condición queryTerms.

Si se especifican varias condiciones para un control, este se aplica a la solicitud de búsqueda cuando se cumplen ambos tipos de condiciones. Si se especifican varios valores para la misma condición, solo es necesario que coincida uno de ellos para que se cumpla la condición.

Por ejemplo, supongamos que se especifica la siguiente condición con dos términos de consulta:

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

La condición se cumplirá en una solicitud con SearchRequest.query="gShoe" o con SearchRequest.query="gBoot", pero no con SearchRequest.query="gSandal" ni con ninguna otra cadena.

Si no se especifica ninguna condición, el control se aplica siempre.

Para obtener más información, consulta el campo Condition en la referencia de la API.

Crear y adjuntar controles de publicación de la mejora

Un control de servicio de impulso reordena los resultados promocionándolos o degradándolos en función de las condiciones aplicadas. La función de refuerzo funciona aplicando un factor de multiplicación a la clasificación de un documento que cumple las condiciones de refuerzo.

Para crear y adjuntar un control de aumento, sigue estos pasos:

Consola

En la Google Cloud consola, ve a la página Aplicaciones de IA.

Aplicaciones de IA
Selecciona la aplicación para la que quieras crear el control de aumento.
En la página de vista general de tu aplicación, selecciona Impulsar o enterrar en la fase Señal.
En la página Señal, haz clic en Crear control.
En el panel Crear control, haz lo siguiente:
1. Escribe un nombre para el control de aumentar o reducir y haz clic en Continuar.
2. Define las siguientes condiciones que activan el control. Si no se configura ninguna condición, el control siempre estará activo:
  1. Añade términos de consulta de coincidencia parcial. El control se aplica cuando estos términos de consulta coinciden parcialmente.
  2. Añade términos de consulta de concordancia exacta. El control se aplica cuando estos términos de consulta coinciden exactamente.
  3. Para añadir un intervalo de tiempo activo, haz clic en Añadir intervalo de tiempo y define Hora de inicio 1 y Hora de finalización 1. Define el periodo en el que la condición está activa. Puedes añadir un máximo de 10 intervalos de tiempo.
  4. Haz clic en Continuar.
3. Define las acciones que quieres activar con este control:
  1. Selecciona un almacén de datos de la lista. Si quieres que la acción se aplique a varios almacenes de datos, crea un control para cada uno de ellos.
  2. Añade un filtro.
    
    Es una cadena que especifica los requisitos que debe cumplir el documento. La condición de refuerzo solo se aplica si el documento cumple todos los requisitos. De lo contrario, no habrá ningún cambio. Si no especificas ningún filtro, el aumento se aplicará a todos los documentos del almacén de datos.
    
    Para saber cómo escribir expresiones de filtro, consulta Sintaxis de expresiones de filtro y Ejemplos de expresiones de filtro.
  3. Selecciona un valor de refuerzo o de ocultación en el intervalo [-1, 1] con el control deslizante. El control deslizante se mueve en incrementos de 0,01.
  4. Haz clic en Continuar.
4. Si quieres aplicar el control en cuanto se cree, activa Publicar este control inmediatamente y haz clic en Continuar.
Haz clic en Enviar.
Para modificar la configuración de un control, siga estos pasos:
1. En la página Señal, en la lista de controles de aumentar o reducir de la aplicación, haz clic en en el control que quieras modificar y, a continuación, en Editar.
2. Edita el control en el panel Editar control.
Para habilitar o inhabilitar un control, ve a la página Señal y, en la lista de controles de aumentar o reducir la visibilidad de la aplicación, haz clic en del control que quieras habilitar o inhabilitar y, a continuación, en Habilitar o Inhabilitar, respectivamente.
Para eliminar un control, en la página Señal, en la lista de controles de refuerzo o de ocultación de la aplicación, haz clic en del control que quieras eliminar y, a continuación, en Eliminar.

REST

Un control de servicio de impulso se define como un control con un boostAction.

Sigue estas instrucciones para crear un control de publicación de la mejora.

Para obtener información detallada sobre los campos, consulta la referencia de la API engines.controls y la referencia de la API engines.controls.create.

Busca el ID de tu aplicación. Si ya tienes el ID de tu aplicación, ve al siguiente paso.
1. En la Google Cloud consola, ve a la página Aplicaciones de IA.
  
  Ir a Aplicaciones
2. En la página Aplicaciones, busca el nombre de tu aplicación y consulta su ID en la columna ID.
Ejecuta los siguientes comandos curl para crear tus controles.
```
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"
 }
}'
```
Haz los cambios siguientes:
- PROJECT_ID: el número o el ID de tu Google Cloud proyecto.
- APP_ID: el ID de la aplicación Vertex AI Search.
- CONTROL_ID: identificador único del control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
- DISPLAY_NAME: nombre del control legible por humanos. Google recomienda que este nombre indique cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de entre 1 y 128 caracteres.
- USE_CASE: debe ser SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Si se especifica SEARCH_USE_CASE_BROWSE, no se puede usar Condition.queryTerms en la condición.
- CONDITION: campo opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
  - VALUE: el valor de consulta específico con el que se va a comparar. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener un máximo de tres términos separados por espacios.
  - FULL_MATCH: valor booleano que indica si la consulta de búsqueda debe coincidir exactamente con el término de consulta. Si se define como true, SearchRequest.query debe coincidir completamente con queryTerm.value. Si se le asigna el valor false, SearchRequest.query debe contener queryTerm.value como subcadena.
  - START_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" para indicar el inicio de un periodo.
  - END_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" que indica el final de un periodo.
- BOOST_VALUE: un número de punto flotante en el intervalo [-1,1]. Si el valor es negativo, los resultados se degradan (aparecen más abajo en los resultados). Si el valor es positivo, los resultados se promocionan (aparecen más arriba en los resultados). Para obtener más información, consulta boostAction.
- FILTER: una cadena que especifica los requisitos que debe cumplir el documento. Si el documento cumple todos los requisitos, se aplica el aumento. De lo contrario, no habrá ningún cambio. Si este campo está vacío, el aumento se aplica a todos los documentos del almacén de datos. Para obtener información sobre la sintaxis de los filtros, consulta Sintaxis de las expresiones de filtro. Nota: El campo de documento title no se puede filtrar.
- DATA_STORE_RESOURCE_PATH: la ruta completa del recurso del almacén de datos cuyos documentos se deben potenciar con este control. El formato de la ruta completa del recurso es projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Este almacén de datos debe estar asociado al motor especificado en la solicitud.

Adjunta el control a la configuración de servicio de la aplicación mediante el método 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"]
}'

Sustituye BOOST_ID_N por los IDs de los controles que has creado en el paso anterior.

Crear y adjuntar controles de publicación de filtros

Un control de servicio de filtros se define como un control con un filterAction.

Sigue estas instrucciones para crear un control de publicación de filtros.

Para obtener información detallada sobre los campos, consulta la referencia de la API engines.controls y la referencia de la API engines.controls.create.

Busca el ID de tu aplicación. Si ya tienes el ID de tu aplicación, ve al siguiente paso.
1. En la Google Cloud consola, ve a la página Aplicaciones de IA.
  
  Ir a Aplicaciones
2. En la página Aplicaciones, busca el nombre de tu aplicación y consulta su ID en la columna ID.
Ejecuta los siguientes comandos curl para crear tus controles.
```
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"
 }
}'
```
Haz los cambios siguientes:
- PROJECT_ID: el número o el ID de tu Google Cloud proyecto.
- APP_ID: el ID de la aplicación Vertex AI Search.
- CONTROL_ID: identificador único del control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
- DISPLAY_NAME: nombre del control legible por humanos. Google recomienda que este nombre indique cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de entre 1 y 128 caracteres.
- USE_CASE: debe ser SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Si se especifica SEARCH_USE_CASE_BROWSE, no se puede usar Condition.queryTerms en la condición.
- CONDITION: campo opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
  - VALUE: el valor de consulta específico con el que se va a comparar. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener un máximo de tres términos separados por espacios.
  - FULL_MATCH: valor booleano que indica si la consulta de búsqueda debe coincidir exactamente con el término de consulta. Si se define como true, SearchRequest.query debe coincidir completamente con queryTerm.value. Si se le asigna el valor false, SearchRequest.query debe contener queryTerm.value como subcadena.
  - START_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" para indicar el inicio de un periodo.
  - END_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" que indica el final de un periodo.
- FILTER: una cadena que especifica los requisitos que debe cumplir el documento. Si el documento cumple todos los requisitos, se devolverá en los resultados. De lo contrario, el documento no se incluirá en los resultados. Para obtener información sobre la sintaxis de los filtros, consulta Sintaxis de las expresiones de filtro. Para obtener más información, consulta filterAction. Nota: El campo de documento title no se puede filtrar.

Adjunta el control a la configuración de servicio de la aplicación mediante el método 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"]
}'

Sustituye FILTER_ID_N por los IDs de los controles que has creado en el paso anterior.

Crear y adjuntar controles de publicación de sinónimos

Un control de servicio de sinónimos se define como un control con un synonymsAction.

Sigue estas instrucciones para crear un control de servicio de sinónimos.

Para obtener información detallada sobre los campos, consulta la referencia de la API engines.controls y la referencia de la API engines.controls.create.

Busca el ID de tu aplicación. Si ya tienes el ID de tu aplicación, ve al siguiente paso.
1. En la Google Cloud consola, ve a la página Aplicaciones de IA.
  
  Ir a Aplicaciones
2. En la página Aplicaciones, busca el nombre de tu aplicación y consulta su ID en la columna ID.
Ejecuta los siguientes comandos curl para crear tus controles.
```
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"]
 }
}'
```
Haz los cambios siguientes:
- PROJECT_ID: el número o el ID de tu Google Cloud proyecto.
- APP_ID: el ID de la aplicación Vertex AI Search.
- CONTROL_ID: identificador único del control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
- DISPLAY_NAME: nombre del control legible por humanos. Google recomienda que este nombre indique cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de entre 1 y 128 caracteres.
- USE_CASE: debe ser SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Si se especifica SEARCH_USE_CASE_BROWSE, no se puede usar Condition.queryTerms en la condición.
- CONDITION: campo opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
  - VALUE: el valor de consulta específico con el que se va a comparar. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener un máximo de tres términos separados por espacios.
  - FULL_MATCH: valor booleano que indica si la consulta de búsqueda debe coincidir exactamente con el término de consulta. Si se define como true, SearchRequest.query debe coincidir completamente con queryTerm.value. Si se le asigna el valor false, SearchRequest.query debe contener queryTerm.value como subcadena.
  - START_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" para indicar el inicio de un periodo.
  - END_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" que indica el final de un periodo.
- SYNONYMS_N: lista de cadenas asociadas entre sí, lo que hace que sea más probable que cada una muestre resultados similares. Aunque es más probable que obtengas resultados similares, si buscas cada una de las entradas de sinónimos, es posible que no recibas todos los resultados relevantes de todos los sinónimos asociados. Debes especificar al menos dos sinónimos y puedes especificar hasta 100. Cada sinónimo debe estar codificado en UTF-8 y en minúsculas. No se permiten cadenas duplicadas. Por ejemplo, puedes añadir "pixel", "teléfono Android" y "teléfono de Google" como sinónimos. Para obtener más información, consulta synonymsAction.

Adjunta el control a la configuración de servicio de la aplicación mediante el método 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"]
}'

Sustituye SYNONYMS_ID_N por los IDs de los controles que has creado en el paso anterior.

Crear y adjuntar controles de publicación de redirecciones

Un control de servicio de redirección permite redirigir a los usuarios a un URI proporcionado. Los controles de redirección se definen como controles con un redirectAction.

Sigue estas instrucciones para crear un control de publicación de redirecciones.

Para obtener información detallada sobre los campos, consulta la referencia de la API engines.controls y la referencia de la API engines.controls.create.

Busca el ID de tu aplicación. Si ya tienes el ID de tu aplicación, ve al siguiente paso.
1. En la Google Cloud consola, ve a la página Aplicaciones de IA.
  
  Ir a Aplicaciones
2. En la página Aplicaciones, busca el nombre de tu aplicación y consulta su ID en la columna ID.
Ejecuta los siguientes comandos curl para crear tus controles.
```
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"
 }
}'
```
Haz los cambios siguientes:
- PROJECT_ID: el número o el ID de tu Google Cloud proyecto.
- APP_ID: el ID de la aplicación Vertex AI Search.
- CONTROL_ID: identificador único del control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
- DISPLAY_NAME: nombre del control legible por humanos. Google recomienda que este nombre indique cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de entre 1 y 128 caracteres.
- USE_CASE: debe ser SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Si se especifica SEARCH_USE_CASE_BROWSE, no se puede usar Condition.queryTerms en la condición.
- CONDITION: campo opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
  - VALUE: el valor de consulta específico con el que se va a comparar. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener un máximo de tres términos separados por espacios.
  - FULL_MATCH: valor booleano que indica si la consulta de búsqueda debe coincidir exactamente con el término de consulta. Si se define como true, SearchRequest.query debe coincidir completamente con queryTerm.value. Si se le asigna el valor false, SearchRequest.query debe contener queryTerm.value como subcadena.
  - START_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" para indicar el inicio de un periodo.
  - END_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" que indica el final de un periodo.
- REDIRECT_URI_N: un URI al que se te redirige. Puede tener una longitud máxima de 2000 caracteres. Por ejemplo, si el valor del término de consulta es "asistencia", puede configurar una redirección a su página de asistencia técnica en lugar de devolver (o no devolver) resultados de búsqueda para "asistencia". En este ejemplo, el URI de redirección pasa a ser "https://www.example.com/support". Para obtener más información, consulta redirectAction.

Adjunta el control a la configuración de servicio de la aplicación mediante el método 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"]
}'

Sustituye REDIRECT_ID_N por los IDs de los controles que has creado en el paso anterior.

Crear y adjuntar controles de publicación de promociones

Un control de servicio de promoción te permite mostrar un enlace como resultado promocionado y está disponible para los siguientes tipos de almacenes de datos de búsqueda:

Almacenes de datos de sitios web con búsqueda básica de sitios web: en estos almacenes de datos, no es necesario adjuntar un control de promoción a la configuración de servicio de la aplicación. Si creas y habilitas un control de promoción, este se activará. Puedes activar o desactivar un control de promoción habilitándolo o inhabilitándolo.
Almacenes de datos con datos estructurados y sin estructurar, datos de sitios web con indexación avanzada de sitios web y aplicaciones de búsqueda combinada: en estos almacenes de datos, debes adjuntar el control de promoción a la configuración de servicio.

Los controles de promoción se definen mediante un promoteAction.

Para crear un control de promoción correctamente, se debe incluir uno de los siguientes campos en la solicitud de creación:

queryTerms: esta condición no se puede especificar si se especifica la condición queryRegex, que solo se aplica a la búsqueda básica en sitios web. En el caso de la búsqueda básica en sitios web, fullMatch debe definirse como true si se especifica queryTerms. En el resto de las aplicaciones de búsqueda, solo se admite queryTerms y fullMatch se puede definir como true o false.
queryRegex. Solo está disponible para el control de servicio de promociones de la búsqueda básica en sitios web. Esta condición aplica el control cuando la consulta coincide con la expresión regular especificada. Esta condición no se puede especificar si se especifica la condición queryTerms.

Es decir, para realizar una búsqueda básica en un sitio web, debe especificar el campo queryTerms con el valor fullMatch definido como true o especificar el campo queryRegex. Para el resto de los tipos de búsqueda, especifica el campo queryTerms con el valor fullMatch definido como true o false.

Sigue estas instrucciones para crear un control de publicación de promociones.

Para obtener información detallada sobre los campos, consulta la referencia de la API engines.controls y la referencia de la API engines.controls.create.

Busca el ID de tu aplicación. Si ya tienes el ID de tu aplicación, ve al siguiente paso.
1. En la Google Cloud consola, ve a la página Aplicaciones de IA.
  
  Ir a Aplicaciones
2. En la página Aplicaciones, busca el nombre de tu aplicación y consulta su ID en la columna ID.
Ejecuta los siguientes comandos curl para crear tus controles.
```
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": true
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ],
  "queryRegex": "VALUE_REGEX"
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "DESCRIPTION",
     "enabled": ENABLED_TRUE|FALSE,
  }
 }
}'
```
Haz los cambios siguientes:
- PROJECT_ID: el número o el ID de tu Google Cloud proyecto.
- APP_ID: el ID de la aplicación Vertex AI Search.
- CONTROL_ID: identificador único del control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
- DISPLAY_NAME: nombre del control legible por humanos. Google recomienda que este nombre indique cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de entre 1 y 128 caracteres.
- USE_CASE: debe ser SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Si se especifica SEARCH_USE_CASE_BROWSE, no se puede usar Condition.queryTerms en la condición.
- Condition: objeto opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
  - queryTerms: no se puede usar con el campo queryRegex.
    - VALUE: el valor de consulta específico con el que se va a comparar. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000].
  - activeTimeRange:
    - START_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" para indicar el inicio de un periodo.
    - END_TIMESTAMP: marca de tiempo en formato RFC 3339 UTC "Zulu" que indica el final de un periodo.
  - queryRegex: solo está disponible para almacenes de datos con búsqueda básica en sitios web. Este campo no se puede usar con el campo queryTerms.
    - VALUE_REGEX: expresión regular con la que se compara la consulta.
- DATA_STORE_RESOURCE_PATH: la ruta completa del recurso del almacén de datos cuyos resultados de búsqueda contienen la URL promocionada. El formato de la ruta completa del recurso es projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Este almacén de datos debe estar asociado al motor especificado en la solicitud.
- DOCUMENT_RESOURCE_PATH: un campo para especificar la ruta del recurso del documento que se va a promocionar:
  - En el caso de los almacenes de datos de búsqueda con datos estructurados y sin estructurar, debe proporcionar la ruta del recurso del documento en el campo DOCUMENT_RESOURCE_PATH, el URI en el campo URI o ambos. El formato de la ruta de acceso completa al recurso es projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.
  - En el caso de los almacenes de datos de sitios web, este campo debe estar sin definir y, en su lugar, se debe definir el campo URI.
- TITLE: un campo obligatorio para especificar el título del documento o de la página web que se va a promocionar. Este título se muestra en el resultado de búsqueda.
- URI: campo obligatorio para especificar el enlace URI al que lleva el resultado de búsqueda al usuario. No es necesario incluir este URI en el almacén de datos.
  - En el caso de los almacenes de datos de búsqueda con datos estructurados y sin estructurar, debe proporcionar la ruta del recurso del documento en el campo DOCUMENT_RESOURCE_PATH, el URI en el campo URI o ambos.
  - En el caso de los almacenes de datos de sitios web, este campo es obligatorio y debe configurarlo.
- DESCRIPTION: campo opcional para describir el documento o la página web que se va a promocionar, que se muestra en el resultado de búsqueda.
- ENABLED_TRUE|FALSE: campo booleano opcional para indicar si el control de promoción está activado y asociado a la aplicación. Este campo se aplica a los almacenes de datos de sitios web con búsqueda básica en sitios web únicamente. Si asignas el valor false a este campo, el control de publicación de la promoción se desactivará y, para que el control surta efecto, debes actualizarlo habilitándolo, tal como se explica en el paso siguiente. Para obtener más información, consulta promoteAction.
Respuesta

Deberías recibir una respuesta JSON similar a la siguiente:
```
{
 "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
  }
 }
}
```

En todas las aplicaciones de búsqueda, excepto en la búsqueda básica de sitios web, adjunta el control a la configuración de servicio de la aplicación mediante el método engines.servingConfigs.patch. El orden en el que se adjuntan los promoteControlIds en la siguiente solicitud es el orden en el que se devuelven los resultados promocionados.

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

Sustituye PROMOTE_ID_N por los IDs de los controles que has creado en el paso anterior.

Opcional: Para realizar búsquedas básicas en el sitio web, no es necesario adjuntar el control a la configuración de publicación de la aplicación. Sin embargo, para la búsqueda básica en sitios web, puedes activar o desactivar un control de promoción después de crearlo. Para ello, llama al método engines.control.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/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled" \
-d '{
"promoteAction": {
  "searchLinkPromotion": {
     "enabled": ENABLED_TRUE|FALSE,
  }
}
}'

Ejemplo

Cuando envías una solicitud de búsqueda a la aplicación con una consulta que coincide con la consulta o la expresión regular de la consulta especificada para el control de promoción, el enlace promocionado aparece en la respuesta.

Por ejemplo, supongamos que crea un control de promoción con la siguiente configuración en un almacén de datos con búsqueda básica en el sitio web:

{
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "artificial intelligence",
         "fullMatch": true
       }
     ]
   }
 ]"
 ...
 promoteAction": {
  "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \
  "searchLinkPromotion": {
    "title": "What is AI?",
    "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
    "description": "Explain what is AI"
    "enabled": true
  }
 }
}

A continuación, envía la siguiente solicitud de búsqueda:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \
  -d '{
"query": "artificial intelligence"
}'

Deberías recibir una respuesta JSON similar a la siguiente respuesta truncada. La respuesta contiene el campo searchLinkPromotions, que incluye el enlace promocionado.

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

Siguientes pasos

Para saber cómo afecta un control de publicación a la calidad de búsqueda de una aplicación de búsqueda personalizada, evalúa la calidad de búsqueda. Para obtener más información, consulta el artículo Evaluar la calidad de la búsqueda.

Configurar los controles de publicación de la búsqueda Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Acerca de los controles de publicación

Tipos de control de publicación

Acerca de las condiciones

Crear y adjuntar controles de publicación de la mejora

Consola

REST

Crear y adjuntar controles de publicación de filtros

Crear y adjuntar controles de publicación de sinónimos

Crear y adjuntar controles de publicación de redirecciones

Crear y adjuntar controles de publicación de promociones

Respuesta

Ejemplo

Siguientes pasos

Configurar los controles de publicación de la búsqueda