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

Los controles de publicación (también llamados controles) cambian el comportamiento predeterminado de una solicitud.

Por ejemplo, los controles pueden aumentar y ocultar resultados, filtrar entradas de los resultados que se muestran, asociar consultas entre sí como sinónimos o redireccionar consultas 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, adjúntalo a una app. Un control solo afecta a las solicitudes que entrega una app a la que está adjunto. Si un control no está conectado a una app, no tiene efecto.

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.

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. El control se aplica cuando se buscan consultas específicas.
  • activeTimeRange. El control se aplica cuando se produce una solicitud dentro de un intervalo de tiempo especificado.

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 servingConfigs.search en la referencia de la API.

Tipos de controles de publicación

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

Control Descripción Disponible para
Control de aumento Cambia el orden de los resultados que se muestran Apps de búsqueda con almacenes de datos que admiten un esquema, como almacenes de datos que contienen datos estructurados, sitios web con datos estructurados, datos no estructurados con metadatos o datos multimedia
Control de filtros Quita las entradas de los resultados que se muestran. Apps de búsqueda con almacenes de datos que admiten un esquema, como almacenes de datos que contienen datos estructurados, sitios web con datos estructurados, datos no estructurados con metadatos o datos multimedia
Control de sinónimos Asocia las consultas entre sí Apps de búsqueda con almacenes de datos de sitios web, estructurados, no estructurados o de contenido multimedia
Control de redireccionamiento Redirecciona a un URI especificado. Todas las apps de búsqueda

Acerca de los controles de publicación de anuncios mejorados

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

La sintaxis de un boostAction es la siguiente:

{
    "boost": "BOOST",
    "filter": "FILTER",
    "dataStore": "DATA_STORE_RESOURCE_PATH"
}
  • BOOST: Es un número de punto flotante entre -1 y 1. Cuando el valor es negativo, los resultados se degradan para aparecer más adelante en los resultados de la búsqueda. Cuando el valor es positivo, los resultados se promocionan para que aparezcan antes en los resultados de la búsqueda.
  • 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 conocer la sintaxis de filtrado, consulta Sintaxis de expresión de filtro.
  • DATA_STORE_RESOURCE_PATH: Es la ruta de acceso completa al recurso del almacén de datos cuyos documentos debe mejorar este control. El formato de la ruta de acceso completa del recurso es projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Este almacén de datos debe estar conectado al motor especificado en la solicitud.

Información acerca de los controles de publicación de filtros

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

La sintaxis de un filterAction es la siguiente:

{
    "filter": "FILTER"
}
  • FILTER: Es una cadena que especifica los requisitos que debe cumplir el documento. Si el documento cumple con todos los requisitos, el resultado se incluye en la lista de resultados. De lo contrario, el resultado se quita de la lista de resultados. Para conocer la sintaxis de filtrado, consulta Sintaxis de expresión de filtro.

Información acerca de los controles de publicación de sinónimos

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

La sintaxis de un synonymsAction es la siguiente:

{
    "synonyms": "SYNONYMS"
}
  • SYNONYMS: Son cadenas que se asociarán entre sí, lo que hace más probable que cada una muestre resultados similares. Debes especificar al menos dos cadenas y puedes especificar hasta 100. Las cadenas deben estar en UTF-8 y en minúsculas. No se permiten cadenas duplicadas.

Por ejemplo:

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

Información acerca de los controles de publicación de redireccionamientos

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.

Sintaxis de redirectAction:

{
    "redirect_uri": "REDIRECT_URI"
}
  • REDIRECT_URI: Es un URI de, como máximo, 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 de "asistencia".

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

Información acerca de la condición queryTerms

queryTerms es opcional. Úsalo si deseas que se use un control de publicación cuando se busquen 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.

La sintaxis de un solo queryTerm es la siguiente:

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}
  • VALUE_1: Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, puede tener como máximo tres términos separados por espacios.
  • FULL_MATCH_1: Es un valor booleano. 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.

Información acerca de la condición activeTimeRange

activeTimeRange es opcional. 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 especifican rangos de activeTimeRange, se ignora el campo.

La sintaxis de un solo activeTimeRange es la siguiente:

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]
  • START_TIMESTAMP_1: Define la primera hora (inclusive) en la que se aplicará el control. Las marcas de tiempo están en formato RFC 3339 UTC “Zulu”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios, por ejemplo, "2023-10-02T15:01:23Z".
  • END_TIMESTAMP_1: Define la hora más reciente (inclusive) en la que se aplicará el control. Esta hora debe ser futura.

Instrucciones de la API: Cambia el comportamiento predeterminado de las solicitudes de búsqueda con controles de publicación

Para cambiar el comportamiento predeterminado de la solicitud de búsqueda, crea un control de entrega y agrégalo a la configuración de entrega predeterminada.

Antes de comenzar

Si quieres crear controles de publicación, comunícate con tu equipo de Cuentas de Google y solicita que te agreguen a la lista de entidades permitidas para los controles de publicación.

Crea un control de entrega

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

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

  1. Busca el ID de tu almacén de datos. Si ya tienes el ID del almacén de datos, ve al siguiente paso.

    1. En la consola de Google Cloud, ve a la página Agent Builder y, en el menú de navegación, haz clic en Almacenes de datos.

      Ve a la página Almacenes de datos.

    2. Haz clic en el nombre de tu almacén de datos.

    3. En la página Datos de tu almacén de datos, obtén el ID del almacén de datos.

  2. Elige el tipo de condición y los valores de campo para tu control.

    El siguiente es un ejemplo truncado de una condición:

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

  3. Ejecuta los siguientes comandos de curl para crear tus controles.

    Control de aumento: Haz clic para ver el comando curl para crear un control de aumento.

    Ejecuta el siguiente comando de curl:

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

    Control de filtro: Haz clic para ver el comando curl para crear un control de filtro.

    Ejecuta el siguiente comando de curl:

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

    Control de sinónimos: Haz clic para ver el comando curl para crear un control de sinónimos.

    Ejecuta el siguiente comando de curl:

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

    Control de redireccionamiento: Haz clic para ver el comando curl para crear un control de redireccionamiento.

    Ejecuta el siguiente comando de curl:

        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: El número o ID de tu proyecto de Google Cloud.
    • DATA_STORE_ID: El ID único del almacén de datos.
    • CONTROL_ID: Es un identificador único (dentro de un almacén de datos) para el control. El ID puede contener letras en minúscula, 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 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: (Opcional) Define cuándo se debe aplicar el control.
    • BOOST_ACTION: Se usa para definir un control de aumento. Consulta la referencia de la API de boostAction.
    • FILTER_ACTION: Se usa para definir un control de filtro. Consulta la referencia de la API de filterAction.
    • SYNONYMS_ACTION: Se usa para definir un control de sinónimos. Consulta la referencia de la API de synonymsAction.
    • REDIRECT_ACTION: Se usa para especificar un URI de redireccionamiento. Consulta la referencia de la API de redirectAction.

  4. Adjunta el control a la app.

    Control de aumento: Haz clic para obtener el comando curl de un control de aumento.

    Ejecuta el siguiente comando curl para adjuntar un control de aumento a una configuración de publicación para habilitar el uso en solicitudes de publicación:

        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 y BOOST_ID_2: Representan los IDs de control que creaste en el paso anterior.

    Control de filtros: Haz clic en el comando curl para obtener un control de filtros.

    Ejecuta el siguiente comando curl para adjuntar un control de filtro a una configuración de publicación para habilitar el uso en solicitudes de publicación:

        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 y FILTER_ID_2: Representan los IDs de control que creaste en el paso anterior.

    Control de sinónimos: Haz clic para obtener el comando curl de un control de sinónimos.

    Ejecuta el siguiente comando de curl para adjuntar un control de sinónimos a una app y habilitar el uso en solicitudes de publicación:

        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 y SYNONYM_ID_2: Representan los IDs de control que creaste en el paso anterior.

    Control de redireccionamiento: Haz clic para obtener el comando curl de un control de redireccionamiento.

    Ejecuta el siguiente comando curl para adjuntar un control de redireccionamiento a una app y habilitar el uso en las solicitudes de publicación:

        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 y REDIRECT_ID_2: Representan 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.