Configura los controles de publicación para la búsqueda

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

Por ejemplo, los controles pueden mejorar y ocultar resultados, filtrar entradas de los resultados que se muestran, asociar cadenas entre sí como sinónimos o redireccionar resultados a URIs especificados.

En esta página, se describen los controles de publicación para las apps de búsqueda. Para obtener información sobre el uso de controles de publicación con recomendaciones de contenido multimedia, consulta Crea y administra configuraciones de publicación.

Información acerca de los controles de publicación

Para cambiar los resultados de una solicitud, primero crea un control de publicación. Luego, adjunta ese control a la configuración de entrega de una app de búsqueda. Una configuración de entrega configura los metadatos que se usan para generar resultados del tiempo de entrega, como los resultados de la búsqueda o las respuestas. Un control de publicación solo afecta las solicitudes que entrega la app si el control está conectado a la configuración de publicación de la app.

Algunos controles, como los controles de aumento, tienen dependencias en los almacenes de datos. Si se quita un almacén de datos de una app, también se quitan de esa app todos los controles que dependen de él y se vuelven inactivos, pero no se borran.

Tipos de controles de publicación

Los siguientes tipos de controles de publicación están disponibles:

Información acerca de las condiciones

Cuando creas un control, puedes definir de manera opcional una condición que determine cuándo se aplica el control. Las condiciones se definen con campos de condición. Los siguientes campos de condiciones están disponibles:

• queryTerms: Es un 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 en SearchRequest.query. Los términos de consulta solo se pueden usar cuando Control.searchUseCase se establece como SOLUTION_TYPE_SEARCH. Se pueden especificar hasta 10 queryTerms diferentes en un solo Control.condition. Si no se especifican términos de consulta, se ignora el campo queryTerms.

• activeTimeRange: Es un control opcional que se aplica cuando se produce una solicitud dentro de un intervalo de tiempo especificado. Verifica que la hora en que se recibió una solicitud esté entre activeTimeRange.startTime y activeTimeRange.endTime. Se pueden especificar hasta 10 rangos de activeTimeRange en una sola Control.condition. Si no se especifica el campo activeTimeRange, se ignora.

Si se especifican ambos tipos de 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 uno de los valores debe coincidir para que se cumpla esa condición.

Por ejemplo, considera la siguiente condición con dos términos de consulta especificados:

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

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

Si no se especifican condiciones, el control siempre se aplica.

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

Crea y adjunta controles de publicación de anuncios de aumento

Un control de publicación de aumento se define como un control con un boostAction.

Usa las siguientes instrucciones para crear un control de publicación de aumento.

Para obtener detalles sobre los campos, consulta la referencia de la API de engines.controls y la referencia de la API de engines.controls.create.

1. Busca el ID de tu app. Si ya tienes el ID de tu app, ve al siguiente paso.

   1. En la consola de Google Cloud, ve a la página Agent Builder.

      Ve a Apps.

   2. En la página Apps, busca el nombre de tu app y obtén su ID de la columna ID.

2. Ejecuta los siguientes comandos de 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"
    }
   }'

   Reemplaza lo siguiente:

   • PROJECT_ID: El número o ID de tu proyecto de Google Cloud.
   • APP_ID: El ID de la app de Vertex AI Search.
   • CONTROL_ID: Un identificador único para el control. El ID puede contener [1-63] caracteres que pueden ser letras, dígitos, guiones y guiones bajos.
   • DISPLAY_NAME: Es el nombre legible para el control. Google recomienda que este nombre proporcione una indicación de cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de [1,128].
   • 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: Es un campo opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
     • VALUE: Es el valor de consulta específico con el que se debe hacer coincidir. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener como máximo tres términos separados por espacios.
     • FULL_MATCH: Es un valor booleano que indica si la búsqueda debe coincidir exactamente con el término de búsqueda. Cuando se establece en true, requiere que SearchRequest.query coincida por completo con queryTerm.value. Cuando se establece en false, requiere que SearchRequest.query contenga queryTerm.value como subcadena.
     • START_TIMESTAMP: Una marca de tiempo en formato "Zulu" UTC de RFC 3339 para indicar el inicio de un intervalo de tiempo.
     • END_TIMESTAMP: Una marca de tiempo en formato "Zulu" UTC de RFC 3339 para indicar el final de un intervalo de tiempo.
   • BOOST_VALUE: Un número de punto flotante en el rango [-1,1]. Cuando el valor es negativo, los resultados se degradan (aparecen más abajo en los resultados). Cuando el valor es positivo, los resultados se promocionan (aparecen más arriba en los resultados). Para obtener más información, consulta boostAction.
   • FILTER: Es una cadena que especifica los requisitos que debe cumplir el documento. Si el documento cumple con todos los requisitos, se aplica el aumento. De lo contrario, no se produce ningún cambio. Si este campo está vacío, el aumento se aplica a todos los documentos del almacén de datos. Para ver la sintaxis de filtro, consulta Sintaxis de la expresión de filtro. Nota: No se puede filtrar el campo de documento title.
   • DATA_STORE_RESOURCE_PATH: Es la ruta de acceso completa del recurso del almacén de datos cuyos documentos deben mejorarse con este control. El formato de la ruta de acceso completa del recurso es projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Este almacén de datos debe estar conectado al motor especificado en la solicitud.

3. Conecta el control a la configuración de publicación de la app con 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"]
   }'

   Reemplaza BOOST_ID_N por los IDs de control que creaste en el paso anterior.

Crea y adjunta controles de publicación de filtros

Un control de publicación de filtros se define como un control con un filterAction.

Usa las siguientes instrucciones para crear un control de publicación de filtros.

Para obtener detalles sobre los campos, consulta la referencia de la API de engines.controls y la referencia de la API de engines.controls.create.

1. Busca el ID de tu app. Si ya tienes el ID de tu app, ve al siguiente paso.

   1. En la consola de Google Cloud, ve a la página Agent Builder.

      Ve a Apps.

   2. En la página Apps, busca el nombre de tu app y obtén su ID de la columna ID.

2. Ejecuta los siguientes comandos de 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"
    }
   }'

   Reemplaza lo siguiente:

   • PROJECT_ID: El número o ID de tu proyecto de Google Cloud.
   • APP_ID: El ID de la app de Vertex AI Search.
   • CONTROL_ID: Un identificador único para el control. El ID puede contener [1-63] caracteres que pueden ser letras, dígitos, guiones y guiones bajos.
   • DISPLAY_NAME: Es el nombre legible para el control. Google recomienda que este nombre proporcione una indicación de cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de [1,128].
   • 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: Es un campo opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
     • VALUE: Es el valor de consulta específico con el que se debe hacer coincidir. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener como máximo tres términos separados por espacios.
     • FULL_MATCH: Es un valor booleano que indica si la búsqueda debe coincidir exactamente con el término de búsqueda. Cuando se establece en true, requiere que SearchRequest.query coincida por completo con queryTerm.value. Cuando se establece en false, requiere que SearchRequest.query contenga queryTerm.value como subcadena.
     • START_TIMESTAMP: Una marca de tiempo en formato "Zulu" UTC de RFC 3339 para indicar el inicio de un intervalo de tiempo.
     • END_TIMESTAMP: Una marca de tiempo en formato "Zulu" UTC de RFC 3339 para indicar el final de un intervalo de tiempo.
   • FILTER: Es una cadena que especifica los requisitos que debe cumplir el documento. Si el documento cumple con todos los requisitos, se muestra en los resultados. De lo contrario, el documento no aparecerá en los resultados. Para conocer la sintaxis de filtrado, consulta Sintaxis de expresión de filtro. Para obtener más información, consulta filterAction: Nota: No se puede filtrar el campo de documento title.

3. Conecta el control a la configuración de publicación de la app con 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"]
   }'

   Reemplaza FILTER_ID_N por los IDs de control que creaste en el paso anterior.

Crea y adjunta controles de publicación de sinónimos

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

Usa las siguientes instrucciones para crear un control de publicación de sinónimos.

Para obtener detalles sobre los campos, consulta la referencia de la API de engines.controls y la referencia de la API de engines.controls.create.

1. Busca el ID de tu app. Si ya tienes el ID de tu app, ve al siguiente paso.

   1. En la consola de Google Cloud, ve a la página Agent Builder.

      Ve a Apps.

   2. En la página Apps, busca el nombre de tu app y obtén su ID de la columna ID.

2. Ejecuta los siguientes comandos de 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"]
    }
   }'

   Reemplaza lo siguiente:

   • PROJECT_ID: El número o ID de tu proyecto de Google Cloud.
   • APP_ID: El ID de la app de Vertex AI Search.
   • CONTROL_ID: Un identificador único para el control. El ID puede contener [1-63] caracteres que pueden ser letras, dígitos, guiones y guiones bajos.
   • DISPLAY_NAME: Es el nombre legible para el control. Google recomienda que este nombre proporcione una indicación de cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de [1,128].
   • 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: Es un campo opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
     • VALUE: Es el valor de consulta específico con el que se debe hacer coincidir. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener como máximo tres términos separados por espacios.
     • FULL_MATCH: Es un valor booleano que indica si la búsqueda debe coincidir exactamente con el término de búsqueda. Cuando se establece en true, requiere que SearchRequest.query coincida por completo con queryTerm.value. Cuando se establece en false, requiere que SearchRequest.query contenga queryTerm.value como subcadena.
     • START_TIMESTAMP: Una marca de tiempo en formato "Zulu" UTC de RFC 3339 para indicar el inicio de un intervalo de tiempo.
     • END_TIMESTAMP: Una marca de tiempo en formato "Zulu" UTC de RFC 3339 para indicar el final de un intervalo de tiempo.
   • SYNONYMS_N: Es una lista de cadenas asociadas entre sí, lo que aumenta la probabilidad de que cada una muestre resultados similares. Si bien es más probable que obtengas resultados similares, cuando busques cada una de las entradas de sinónimos, es posible que no recibas todos los resultados relevantes para 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 agregar "pixel", "teléfono Android" y "teléfono de Google" como sinónimos. Para obtener más información, consulta synonymsAction.

3. Conecta el control a la configuración de publicación de la app con 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"]
   }'

   Reemplaza SYNONYMS_ID_N por los IDs de control que creaste en el paso anterior.

Crea y adjunta controles de entrega de redireccionamiento

Un control de publicación de redireccionamientos permite redireccionar a los usuarios a un URI proporcionado. Los controles de redireccionamiento se definen como un control con un redirectAction.

Usa las siguientes instrucciones para crear un control de publicación de redireccionamientos.

Para obtener detalles sobre los campos, consulta la referencia de la API de engines.controls y la referencia de la API de engines.controls.create.

1. Busca el ID de tu app. Si ya tienes el ID de tu app, ve al siguiente paso.

   1. En la consola de Google Cloud, ve a la página Agent Builder.

      Ve a Apps.

   2. En la página Apps, busca el nombre de tu app y obtén su ID de la columna ID.

2. Ejecuta los siguientes comandos de 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"
    }
   }'

   Reemplaza lo siguiente:

   • PROJECT_ID: El número o ID de tu proyecto de Google Cloud.
   • APP_ID: El ID de la app de Vertex AI Search.
   • CONTROL_ID: Un identificador único para el control. El ID puede contener [1-63] caracteres que pueden ser letras, dígitos, guiones y guiones bajos.
   • DISPLAY_NAME: Es el nombre legible para el control. Google recomienda que este nombre proporcione una indicación de cuándo o por qué usar el control. Debe ser una cadena codificada en UTF-8 con una longitud de [1,128].
   • 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: Es un campo opcional que define cuándo se debe aplicar el control. Contiene los siguientes campos:
     • VALUE: Es el valor de consulta específico con el que se debe hacer coincidir. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener como máximo tres términos separados por espacios.
     • FULL_MATCH: Es un valor booleano que indica si la búsqueda debe coincidir exactamente con el término de búsqueda. Cuando se establece en true, requiere que SearchRequest.query coincida por completo con queryTerm.value. Cuando se establece en false, requiere que SearchRequest.query contenga queryTerm.value como subcadena.
     • START_TIMESTAMP: Una marca de tiempo en formato "Zulu" UTC de RFC 3339 para indicar el inicio de un intervalo de tiempo.
     • END_TIMESTAMP: Una marca de tiempo en formato "Zulu" UTC de RFC 3339 para indicar el final de un intervalo de tiempo.
   • REDIRECT_URI_N: Es un URI al que se te redirecciona. Puede tener una longitud máxima de 2,000 caracteres. Por ejemplo, si el valor del término de búsqueda es "asistencia", puedes configurar un redireccionamiento a tu página de asistencia técnica en lugar de mostrar (o no mostrar) los resultados de la búsqueda para "asistencia". En este ejemplo, el URI de redireccionamiento se convierte en "https://www.example.com/support". Para obtener más información, consulta redirectAction:

3. Conecta el control a la configuración de publicación de la app con 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"]
   }'

   Reemplaza REDIRECT_ID_N por los IDs de control que creaste en el paso anterior.

¿Qué sigue?

• Para comprender el impacto de un control de publicación en la calidad de la búsqueda de una app de búsqueda genérica, evalúa la calidad de la búsqueda. Para obtener más información, consulta Evalúa la calidad de la búsqueda.