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 los resultados. Los controles de entrega actúan a nivel del almacén de datos.

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

Acerca de los controles de publicación

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 de tiempo de entrega, como resultados de la búsqueda o respuestas. Un control de entrega solo afecta las solicitudes que entrega la app si el control se adjunta a la configuración de entrega de la app.

Algunos controles, como los de impulso, tienen dependencias de los almacenes de datos. Si se quita un almacén de datos de una app, también se quitan de esa app los controles que dependen del almacén de datos y se desactivan, pero no se borran.

Tipos de controles de entrega

Están disponibles los siguientes tipos de controles de publicación:

Control Descripción Disponible para
Control de potenciación Cambia el orden en que se devuelven los resultados Apps de búsqueda con almacenes de datos que admiten un esquema, como almacenes de datos que contienen datos estructurados o no estructurados con metadatos
Control de filtro Quita entradas de los resultados devueltos Apps de búsqueda con almacenes de datos que admiten un esquema, como almacenes de datos 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 Promociona un vínculo especificado para una consulta 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 el 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.

    Para crear un control de promoción de forma correcta, 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 las activeTimeRange.startTime y las 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 ellos 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 se aplica siempre.

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

Crea y adjunta controles de publicación de impulso

Un control de entrega de aumento reordena los resultados promocionándolos o descendiendo su nivel según las condiciones aplicadas. La mejora funciona aplicando un factor de multiplicación a la clasificación de un documento que cumple con las condiciones de mejora.

Usa las siguientes instrucciones para crear un control de entrega de aumento.

Console

Para crear y adjuntar un control de aumento 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 Configuraciones 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 quieres 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.

    2. En Filtro, agrega un filtro.

      Esta es una cadena que especifica los requisitos que debe cumplir el documento. La condición de aumento se aplica solo si el documento cumple con todos los requisitos. De lo contrario, no hay cambios. Si no especificas un filtro, el aumento se aplica a todos los documentos del almacén de datos.

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

    3. En Valor de mejora/ocultamiento, selecciona un valor de mejora/ocultamiento en el rango [-1, 1] con el control deslizante. El control deslizante se mueve en pasos de 0.01.

    4. Haz clic en Continuar.

  7. En Opcional: Cuándo 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 se aplica cuando estos términos de búsqueda coinciden parcialmente.

    2. Agrega Términos de búsqueda de concordancia exacta. El control se aplica cuando estos términos de búsqueda coinciden exactamente.

    3. Para agregar un período activo, haz clic en Agregar período y establece Hora de inicio 1 y Hora de finalización 1. Esto define la ventana en la que 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 deseas activar la regla:

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

    2. Haz clic en Continuar.

  9. Haz clic en Enviar.

REST

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

Usa las siguientes instrucciones para crear un control de entrega de aumento.

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

  1. Encuentra el ID de tu app. Si ya tienes el ID de tu app, continúa con el 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 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: Es el 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 por humanos 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, entonces 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 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 una subcadena.
      • START_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" para indicar el inicio de un período.
      • END_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" para indicar el final de un período.
    • BOOST_VALUE: Es un número de punto flotante en el rango [-1,1]. Cuando el valor es negativo, los resultados se descienden de nivel (aparecen más abajo en los resultados). Cuando el valor es positivo, se promocionan los resultados (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 la mejora. De lo contrario, no habrá cambios. Si este campo está vacío, la mejora 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: 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 se deben impulsar 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. Adjunta 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 entrega de filtros

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

Sigue estas instrucciones para crear un control de entrega 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 Configuraciones 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 quieres 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 almacén de datos.

    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 (). Para 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 las expresiones de filtro.

    3. Haz clic en Continuar.

  7. En Opcional: Cuándo 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 se aplica cuando estos términos de búsqueda coinciden parcialmente.

    2. Agrega Términos de búsqueda de concordancia exacta. El control se aplica cuando estos términos de búsqueda coinciden exactamente.

    3. Para agregar un período activo, haz clic en Agregar período y establece Hora de inicio 1 y Hora de finalización 1. Esto define la ventana en la que 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 deseas activar la regla:

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

    2. Haz clic en Continuar.

  9. Haz clic en Enviar.

REST

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

  1. Encuentra el ID de tu app. Si ya tienes el ID de tu app, continúa con el 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 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: Es el 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 por humanos 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, entonces 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 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 una subcadena.
      • START_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" para indicar el inicio de un período.
      • END_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" 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 devuelve en los resultados. De lo contrario, el documento no se incluye en los resultados. Para obtener información sobre la sintaxis de filtrado, consulta Sintaxis de las expresiones de filtro. Para obtener más información, consulta filterAction. Nota: No se puede filtrar el campo de documento title.

  3. Adjunta 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.

Usa las siguientes instrucciones para crear un control de entrega 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 quieres crear el control de sinónimos.

  3. Haz clic en Configuraciones 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 Asigna un nombre a tu control, ingresa un nombre para el 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 quieres activar con este control:

    1. Ingresa los sinónimos que quieres que se consideren en el control. Por ejemplo, ingresa gatos seguido de un retorno (no una coma) y, luego, felino.

    2. Haz clic en Continuar.

  7. En Opcional: Cuándo 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 período activo, haz clic en Agregar período y establece Hora de inicio 1 y Hora de finalización 1. Esto define la ventana en la que 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 deseas activar la regla:

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

    2. Haz clic en Continuar.

  9. Haz clic en Enviar.

REST

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

  1. Encuentra el ID de tu app. Si ya tienes el ID de tu app, continúa con el 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 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: Es el 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 por humanos 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, entonces 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 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 una subcadena.
      • START_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" para indicar el inicio de un período.
      • END_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" para indicar el final de un período.
    • SYNONYMS_N: Es una lista de cadenas que están 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 pertinentes 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. Adjunta 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 redireccionamiento

Un control de publicación de redireccionamiento 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 entrega de redireccionamiento.

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

  1. Encuentra el ID de tu app. Si ya tienes el ID de tu app, continúa con el 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 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: Es el 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 por humanos 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, entonces 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 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 una subcadena.
      • START_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" para indicar el inicio de un período.
      • END_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" 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 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". En este ejemplo, el URI de redireccionamiento se convierte en "https://www.example.com/support". Para obtener más información, consulta redirectAction.

  3. Adjunta 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 promoción

Un control de entrega de promoción te permite mostrar un vínculo como un 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 tenga efecto, debes adjuntarlo a la configuración de entrega de la app.

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

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

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

Console

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

REST

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

  1. Encuentra el ID de tu app. Si ya tienes el ID de tu app, continúa con el 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 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: Es el 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 por humanos 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, entonces 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 coincidir. 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 RFC 3339 UTC "Zulú" para indicar el inicio de un período.
      • END_TIMESTAMP: Es una marca de tiempo en formato RFC 3339 UTC "Zulú" para indicar el final de un período.
    • DATA_STORE_RESOURCE_PATH: Es la ruta de acceso completa del recurso del almacén de datos cuyos resultados de la 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 conectado al motor especificado en la solicitud.

    • DOCUMENT_RESOURCE_PATH: Es un campo para especificar la ruta 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 del recurso es el siguiente: 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 el resultado de la búsqueda dirige 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 necesitas para adjuntar tu control de promoción a tu app de búsqueda.

  3. Adjunta 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.

Modifica los controles de publicación

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 Configuraciones y, luego, en la pestaña Control.

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

  5. Edita el control en el panel Editar control:

    1. Para habilitar o inhabilitar un control, en la lista de los controles de filtro de la app, haz clic en para un control que quieras habilitar o inhabilitar y 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?