Configura los controles de entrega

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 o disminuir la visibilidad de los resultados, filtrar entradas de los resultados devueltos, asociar cadenas entre sí como sinónimos o redireccionar los resultados a URIs especificados.

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. Una configuración de entrega configura los metadatos que se usan para generar resultados en el momento de la entrega, como resultados de la búsqueda o respuestas. Un control de publicación solo afecta las solicitudes que publica la app si el control está asociado a la configuración de publicación 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 dependan 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:

Control Descripción Disponible para
Control de amplificación Cambia el orden de los resultados que se muestran Apps de búsqueda con almacenes de datos que admiten un esquema, como los que contienen datos estructurados o no estructurados con metadatos
Control de filtros Quita entradas de los resultados devueltos. Apps de búsqueda con almacenes de datos que admiten un esquema, como los que contienen datos estructurados o no estructurados con metadatos
Control de sinónimos Asocia las búsquedas entre sí Apps de búsqueda con almacenes de datos estructurados o no estructurados
Control de redireccionamiento Redirecciona a un URI especificado Todas las apps de búsqueda
Control de promoción Promueve un vínculo especificado para una búsqueda. Apps de búsqueda con almacenes de datos estructurados o no estructurados

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:

  • 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.

    Para crear un control de promoción correctamente, debes especificar el campo queryTerms con fullMatch establecido en true o false.

  • activeTimeRange: Es un control opcional que se aplica cuando se produce una solicitud dentro de un período 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.

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 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. El refuerzo funciona aplicando un factor de multiplicación a la clasificación de un documento que cumple con las condiciones de refuerzo.

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

Console

Para crear y adjuntar un control de refuerzo con la consola de Google Cloud , haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Gemini Enterprise.

    Gemini Enterprise

  2. Selecciona la app para la que quieres crear el control de aumento.

  3. Haz clic en Configurations y, luego, en la pestaña Control.

  4. Haz clic en Crear control.

  5. En ¿Qué quieres hacer?, especifica el nombre y el tipo de control:

    1. En Nombre del control, ingresa un nombre para tu control de impulso o entierro.

    2. En Tipo de control, selecciona Potenciar/ocultar.

    3. Haz clic en Continuar.

  6. En Establecer el permiso y el impacto de la regla, define las acciones que deseas activar con este control:

    1. Selecciona un almacén de datos de la lista. Si deseas que la acción se aplique a varios almacenes de datos, crea un control para cada uno de almacén de datos.

    2. En Filtro, agrega 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 con todos los requisitos. De lo contrario, no habrá cambios. Si no especificas un filtro, el refuerzo se aplica a todos los documentos del almacén de datos.

      Para obtener información sobre la sintaxis de filtrado, consulta Sintaxis de expresión de filtro.

    3. Para Mejorar/ocultar valor, selecciona un valor de mejora o ocultamiento en el rango [-1, 1] con el control deslizante. El control deslizante se mueve en incrementos de 0.01.

    4. Haz clic en Continuar.

  7. En Opcional: Cuando se activa esta regla, establece las siguientes condiciones que activan el control. Si no se configuran condiciones, el control está siempre activo:

    1. Agrega Términos de búsqueda de coincidencia parcial. El control entra en vigencia cuando estos términos de búsqueda coinciden parcialmente.

    2. Agrega términos de búsqueda de concordancia exacta. El control entra en vigencia cuando estos términos de búsqueda coinciden exactamente.

    3. Para agregar un intervalo de tiempo activo, haz clic en Agregar intervalo de tiempo y configura Hora de inicio 1 y Hora de finalización 1. Define el período durante el cual la condición está activa. Puedes agregar un máximo de 10 períodos.

    4. Haz clic en Continuar.

  8. En Configuración adicional, elige si quieres activar la regla:

    1. Si no quieres activar este control en cuanto se cree, desactiva la opción Publica este control de inmediato.

    2. Haz clic en Continuar.

  9. Haz clic en Enviar.

REST

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

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

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 Gemini Enterprise.

      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"
   }
 ]
},
"boostAction": {
  "boost": BOOST_VALUE,
  "filter": "FILTER",
  "dataStore": "DATA_STORE_RESOURCE_PATH"
 }
}'

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el número o ID de tu proyecto de Google Cloud .
    • APP_ID: ID de la app.
    • 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.
    • 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 refuerzo. De lo contrario, no habrá cambios. Si este campo está vacío, el refuerzo se aplica a todos los documentos del almacén de datos. Para conocer la sintaxis de filtrado, consulta Sintaxis de las expresiones de filtro. Nota: El campo del documento title no se puede filtrar.
    • DATA_STORE_RESOURCE_PATH: Es la ruta de acceso completa del recurso del almacén de datos cuyos documentos se deben potenciar 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 adjunto al motor especificado en la solicitud.

  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=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.

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

Console

Para crear y adjuntar un control de filtro con la consola de Google Cloud , haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Gemini Enterprise.

    Gemini Enterprise

  2. Selecciona la app para la que quieres crear el control de filtro.

  3. Haz clic en Configurations y, luego, en la pestaña Control.

  4. Haz clic en Crear control.

  5. En ¿Qué quieres hacer?, especifica el nombre y el tipo de control:

    1. En Nombre del control, ingresa un nombre para el control de filtro.

    2. En Tipo de control, selecciona Filtro.

    3. Haz clic en Continuar.

  6. En Establecer el permiso y el impacto de la regla, define las acciones que deseas 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.

    2. En Filtro, dile a la regla qué elementos específicos debe buscar. Puedes combinar términos de búsqueda con AND, OR NOT y agrupar términos con (). En el caso de frases exactas, usa comillas (""). Por ejemplo: category: "electronics" AND price < 500, status: "open" AND priority:"P1".

      Para obtener información sobre la sintaxis de filtrado, consulta Sintaxis de expresión de filtro.

    3. Haz clic en Continuar.

  7. En Opcional: Cuando se activa esta regla, establece las siguientes condiciones que activan el control. Si no se configuran condiciones, el control está siempre activo:

    1. Agrega Términos de búsqueda de coincidencia parcial. El control entra en vigencia cuando estos términos de búsqueda coinciden parcialmente.

    2. Agrega términos de búsqueda de concordancia exacta. El control entra en vigencia cuando estos términos de búsqueda coinciden exactamente.

    3. Para agregar un intervalo de tiempo activo, haz clic en Agregar intervalo de tiempo y configura Hora de inicio 1 y Hora de finalización 1. Define el período durante el cual la condición está activa. Puedes agregar un máximo de 10 períodos.

    4. Haz clic en Continuar.

  8. En Configuración adicional, elige si quieres activar la regla:

    1. Si no quieres activar este control en cuanto se cree, desactiva la opción Publica este control de inmediato.

    2. Haz clic en Continuar.

  9. Haz clic en Enviar.

REST

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 Gemini Enterprise.

      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 de Google Cloud .
    • APP_ID: ID de la app.
    • 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 devolverá en los resultados. De lo contrario, el documento no aparecerá en los resultados. Para obtener información sobre 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 publicación de sinónimos se define como un control con un synonymsAction.

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

Console

Para crear y adjuntar un control de sinónimos con la consola de Google Cloud , haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Gemini Enterprise.

    Gemini Enterprise

  2. Selecciona la app para la que deseas crear el control de sinónimos.

  3. Haz clic en Configurations y, luego, en la pestaña Control.

  4. Haz clic en Crear control.

  5. En ¿Qué quieres hacer?, especifica el nombre y el tipo de control:

    1. En Name Your Control, ingresa un nombre para tu control de sinónimos.

    2. En Tipo de control, selecciona Sinónimos.

    3. Haz clic en Continuar.

  6. En Establecer el permiso y el impacto de la regla, define las acciones que deseas activar con este control:

    1. Ingresa los sinónimos que deseas que se tengan en cuenta en el control. Por ejemplo, ingresa gatos y, luego, presiona Intro (no uses comas). A continuación, ingresa felino.

    2. Haz clic en Continuar.

  7. En Opcional: Cuando se activa esta regla, establece las siguientes condiciones que activan el control. Si no se configuran condiciones, el control está siempre activo:

    1. Para agregar un intervalo de tiempo activo, haz clic en Agregar intervalo de tiempo y configura Hora de inicio 1 y Hora de finalización 1. Define el período durante el cual la condición está activa. Puedes agregar un máximo de 10 períodos.

    2. Haz clic en Continuar.

  8. En Configuración adicional, elige si quieres activar la regla:

    1. Si no quieres activar este control en cuanto se cree, desactiva la opción Publica este control de inmediato.

    2. Haz clic en Continuar.

  9. Haz clic en Enviar.

REST

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 Gemini Enterprise.

      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 de Google Cloud .
    • APP_ID: ID de la app.
    • 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 Gemini Enterprise.

      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 de Google Cloud .
    • APP_ID: ID de la app.
    • 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 publicación de promoción te permite mostrar un vínculo como resultado promocionado. Este control está disponible para las apps de búsqueda con almacenes de datos estructurados o no estructurados, y para las apps de búsqueda combinada.

Para que el control de promoción surta efecto, debes adjuntarlo a la configuración de publicación de la app.

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

Para crear un control de promoción correctamente, debes especificar el campo queryTerms con fullMatch establecido en true o false.

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

Console

Para crear un control de publicación de promoción, sigue las instrucciones de la pestaña REST.

REST

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 Gemini Enterprise.

      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"
    }
  ]
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "URI_DESCRIPTION"
  }
 }
}'

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el número o ID de tu proyecto de Google Cloud .
    • APP_ID: ID de la app.
    • 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].
      • FULL_MATCH: Es un valor booleano que indica si el término de búsqueda debe coincidir por completo.
      • 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.
    • 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 estar adjunto al motor especificado en la solicitud.

    • DOCUMENT_RESOURCE_PATH: Es un campo para especificar la ruta de acceso del recurso del documento que se promocionará. Debes proporcionar el ID 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.

    • 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 para especificar el URI al que dirige el resultado de la búsqueda al usuario. Debes proporcionar el ID del documento en el campo DOCUMENT_RESOURCE_PATH, el URI en el campo URI o ambos.

    • URI_DESCRIPTION: Es un campo opcional para describir el URI, que se muestra en el resultado de la búsqueda.

    La respuesta contiene los IDs de control de promoción que debes adjuntar a tu control de promoción en tu app de búsqueda.

  3. Conecta el control a la configuración de entrega de la app con el método engines.servingConfigs.patch. El orden en el que adjuntas el 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"]
}'

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

Cómo modificar los controles de entrega

Para modificar la configuración de un control, haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Gemini Enterprise.

    Gemini Enterprise

  2. Selecciona la app para la que quieres modificar los controles.

  3. Haz clic en Configurations y, luego, en la pestaña Control.

  4. En la lista de controles de la app, haz clic en para el control que quieras modificar y, luego, en Editar.

  5. Edita el control en el panel Editar control:

    1. Para habilitar o inhabilitar un control, en la lista de controles de filtro de la app, haz clic en para el control que quieras habilitar o inhabilitar y, luego, haz clic en Habilitar o Inhabilitar, respectivamente.

    2. Para borrar un control, en la lista de controles de la app, haz clic en para el control que deseas borrar y, luego, en Borrar.

¿Qué sigue?