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

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

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

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

Acerca de los controles de entrega

Para cambiar los resultados de una solicitud, primero crea un control de entrega. 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 en el momento de la entrega, como resultados de búsqueda o respuestas. Un control de entrega solo afecta las solicitudes que entrega la app si el control está asociado a la configuración de entrega de la app.

Algunos controles, como los de potenciación, dependen de los almacenes de datos. Si se quita un almacén de datos de una app, también se quitarán de esa app los controles que dependen del almacén de datos y se desactivarán, pero no se borrarán.

Tipos de controles de entrega

Los siguientes tipos de controles de entrega están disponibles:

Acerca de las condiciones

Cuando creas un control, puedes definir de forma 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 condición están disponibles:

• Términos de búsqueda (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 búsqueda 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 búsqueda, 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 para la búsqueda básica en el sitio web debe establecerse en true si se especifica queryTerms. Para todas las demás apps de búsqueda, solo se admite queryTerms y fullMatch se puede establecer en true o false.

• Intervalo de tiempo (activeTimeRange): Es un control opcional que se aplica cuando se realiza 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 un solo Control.condition. Si no se especifica el campo activeTimeRange, se ignora.

• queryRegex. Solo está disponible para un control de publicación de promoción para la búsqueda básica en el sitio web. Esta es una condición opcional que aplica el control cuando la búsqueda 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 satisfacen 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 búsqueda 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 la potenciación

Un control de publicación de refuerzo reordena los resultados promoviéndolos o degradándolos según las condiciones aplicadas. La potenciación funciona aplicando un factor de multiplicación a la clasificación de un documento que cumple con las condiciones de potenciación.

Para crear y adjuntar el control de refuerzo, haz lo siguiente:

Crea y adjunta controles de publicación de filtros

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

Sigue estas 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 AI Applications.

      Ve a Apps.

   2. En la página Apps, busca el nombre de tu app y obtén su ID en 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: Es el número o ID de tu proyecto Google Cloud .
   • APP_ID: Es el ID de la app de Vertex AI Search.
   • CONTROL_ID: Es un identificador único para el control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
   • DISPLAY_NAME: Es el nombre legible del control. 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 [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 la búsqueda específico con el que se realizará la coincidencia. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener hasta 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 completamente con queryTerm.value. Cuando se establece en false, requiere que SearchRequest.query contenga queryTerm.value como subcadena.
     • START_TIMESTAMP: Es una marca de tiempo en formato "Zulu" de UTC según RFC 3339 para indicar el inicio de un período.
     • END_TIMESTAMP: Es una marca de tiempo en formato "zulu" de UTC según RFC 3339 para indicar el final de un período.
   • FILTER: Es una cadena que especifica los requisitos que debe cumplir el documento. Si el documento cumple con todos los requisitos, se mostrará 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: El campo del documento title no se puede filtrar.

3. Conecta el control a la configuración de entrega 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 entrega de sinónimos

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

Sigue estas 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 AI Applications.

      Ve a Apps.

   2. En la página Apps, busca el nombre de tu app y obtén su ID en 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: Es el número o ID de tu proyecto Google Cloud .
   • APP_ID: Es el ID de la app de Vertex AI Search.
   • CONTROL_ID: Es un identificador único para el control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
   • DISPLAY_NAME: Es el nombre legible del control. 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 [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 la búsqueda específico con el que se realizará la coincidencia. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener hasta 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 completamente con queryTerm.value. Cuando se establece en false, requiere que SearchRequest.query contenga queryTerm.value como subcadena.
     • START_TIMESTAMP: Es una marca de tiempo en formato "Zulu" de UTC según RFC 3339 para indicar el inicio de un período.
     • END_TIMESTAMP: Es una marca de tiempo en formato "zulu" de UTC según RFC 3339 para indicar el final de un período.
   • SYNONYMS_N: Es una lista de cadenas que se asocian entre sí, lo que hace que sea más probable 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 entrega 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 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.

Sigue estas 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 AI Applications.

      Ve a Apps.

   2. En la página Apps, busca el nombre de tu app y obtén su ID en 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: Es el número o ID de tu proyecto Google Cloud .
   • APP_ID: Es el ID de la app de Vertex AI Search.
   • CONTROL_ID: Es un identificador único para el control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
   • DISPLAY_NAME: Es el nombre legible del control. 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 [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 la búsqueda específico con el que se realizará la coincidencia. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000]. Si FULL_MATCH_1 es true, este campo puede tener hasta 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 completamente con queryTerm.value. Cuando se establece en false, requiere que SearchRequest.query contenga queryTerm.value como subcadena.
     • START_TIMESTAMP: Es una marca de tiempo en formato "Zulu" de UTC según RFC 3339 para indicar el inicio de un período.
     • END_TIMESTAMP: Es una marca de tiempo en formato "zulu" de UTC según RFC 3339 para indicar el final de un período.
   • 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 establecer 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". 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 entrega 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.

Crea y adjunta controles de publicación de la promoción

Un control de entrega de promoción te permite mostrar un vínculo 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 en sitios web: Para estos almacenes de datos, no es necesario que adjuntes un control de promoción al parámetro de configuración de entrega de la app. Crear y habilitar un control de promoción activa el control de promoción. Puedes activar o desactivar un control de promoción habilitándolo o inhabilitándolo.

• Almacenes de datos con datos estructurados y no estructurados, datos de sitios web con indexación avanzada de sitios web y apps de búsqueda combinada: Para estos almacenes de datos, debes adjuntar el control de promoción a la configuración de publicación.

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

Para crear correctamente un control de promoción, se requiere 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. Para la búsqueda básica en el sitio web, fullMatch se debe establecer en true si se especifica queryTerms. En el caso de todas las demás apps de búsqueda, solo se admite queryTerms, y fullMatch se puede establecer en true o false.
• queryRegex. Solo está disponible para un control de publicación de promoción para la búsqueda básica en el sitio web. Esta condición aplica el control cuando la búsqueda coincide con la expresión regular especificada. Esta condición no se puede especificar si se especifica la condición queryTerms.

Es decir, para la búsqueda básica en sitios web, debes especificar el campo queryTerms con fullMatch establecido en true o especificar el campo queryRegex. Para todos los demás tipos de búsqueda, especifica el campo queryTerms con fullMatch establecido en true o false.

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

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 AI Applications.

      Ve a Apps.

   2. En la página Apps, busca el nombre de tu app y obtén su ID en 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": 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,
     }
    }
   }'

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el número o ID de tu proyecto Google Cloud .
   • APP_ID: Es el ID de la app de Vertex AI Search.
   • CONTROL_ID: Es un identificador único para el control. El ID puede contener entre 1 y 63 caracteres, que pueden ser letras, dígitos, guiones y guiones bajos.
   • DISPLAY_NAME: Es el nombre legible del control. 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 [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 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: Es el valor de la búsqueda específico con el que se realizará la coincidencia. Es una cadena UTF-8 en minúsculas con una longitud de [1, 5000].
     • activeTimeRange:
       • START_TIMESTAMP: Es una marca de tiempo en formato "Zulu" de UTC según RFC 3339 para indicar el inicio de un período.
       • END_TIMESTAMP: Es una marca de tiempo en formato "zulu" de UTC según RFC 3339 para indicar el final de un período.
     • queryRegex: Solo está disponible para los almacenes de datos con búsqueda básica en el sitio web. Este campo no se puede usar con el campo queryTerms.
       • VALUE_REGEX: Es una expresión regular con la que se comparará la consulta.
   • DATA_STORE_RESOURCE_PATH: Es la ruta de acceso completa del almacén de datos cuyos resultados de búsqueda contienen la URL promocionada. 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 adjuntarse al motor especificado en la solicitud.
   • DOCUMENT_RESOURCE_PATH: Es un campo para especificar la ruta de acceso al recurso del documento que se promocionará:
     • En el caso de los almacenes de datos de búsqueda con datos estructurados y no estructurados, debes proporcionar la ruta de acceso al 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 configurar y, en su lugar, se debe establecer el campo URI.
   • TITLE: Es un campo obligatorio para especificar el título del documento o la página web que se promocionará. Este título se muestra en el resultado de la búsqueda.
   • URI: Es un campo obligatorio para especificar el vínculo URI al que dirige el resultado de la 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 no estructurados, debes proporcionar la ruta de acceso al recurso del documento en el campo DOCUMENT_RESOURCE_PATH, el URI en el campo URI o ambos.
     • Para los almacenes de datos de sitios web, este es un campo obligatorio que debes configurar.
   • DESCRIPTION: Es un campo opcional para describir el documento o la página web que se promocionará, y que se muestra en el resultado de la búsqueda.
   • ENABLED_TRUE|FALSE: Es un campo booleano opcional para indicar si el control de promoción está activado y adjunto a la app. Este campo solo se aplica a los almacenes de datos de sitios web con búsqueda básica de sitios web. Cuando configuras este campo como false, se desactiva el control de publicación de la promoción y, para que el control surta efecto, debes actualizarlo habilitándolo, como se explica en el siguiente paso. Para obtener más información, consulta promoteAction:

   Respuesta

   Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

   {
    "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
     }
    }
   }
   

3. Para todas las apps de búsqueda, excepto la búsqueda básica de sitios web, adjunta el control a la configuración de entrega de la app con el método engines.servingConfigs.patch. El orden en el que se adjuntan los objetos promoteControlIds en la siguiente solicitud es el orden en el que se muestran 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"]
   }'

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

4. Opcional: Para la búsqueda básica de sitios web, no es necesario que adjuntes el control a la configuración de entrega de la app. Sin embargo, para la búsqueda básica en el sitio web, puedes activar o desactivar un control de promoción después de que se cree, llamando 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 app con una búsqueda que coincide con la búsqueda o la expresión regular de búsqueda especificadas para el control de promoción, el vínculo promocionado aparece en la respuesta.

Por ejemplo, supongamos que creas un control de promoción con la siguiente configuración en un almacén de datos con búsqueda básica en sitios 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
  }
 }
}

Luego, envías 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 vínculo 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"
    }
  ]
}

¿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 personalizada, evalúa la calidad de la búsqueda. Para obtener más información, consulta Cómo evaluar la calidad de la búsqueda.