Configurar controles de exibição para a pesquisa

Os controles de exibição (também chamados de controles) mudam o comportamento padrão de como uma solicitação é exibida quando os resultados são retornados. Os controles de veiculação agem no nível do repositório de dados.

Por exemplo, os controles podem aumentar e ocultar resultados, filtrar entradas de resultados retornados, associar strings umas às outras como sinônimos ou redirecionar resultados para URIs especificados.

Esta página descreve os controles de exibição para apps de pesquisa. Para informações sobre como usar os controles de exibição com recomendações de mídia, consulte Criar e gerenciar configurações de exibição.

Sobre os controles de veiculação

Para mudar os resultados de uma solicitação, primeiro crie um controle de veiculação. Em seguida, anexe esse controle à configuração de exibição de um app de pesquisa. Uma configuração de exibição configura metadados usados para gerar resultados de tempo de exibição, como resultados da pesquisa ou respostas. Um controle de veiculação só afeta as solicitações veiculadas pelo app se o controle estiver anexado à configuração de veiculação do app.

Alguns controles, como os de aumento, têm dependências de repositórios de dados. Se um repositório de dados for removido de um app, todos os controles dependentes do repositório de dados também serão removidos desse app e ficarão inativos, mas não serão excluídos.

Tipos de controle de veiculação

Os seguintes tipos de controles de exibição estão disponíveis:

Controle	Descrição	Disponível para
Controle de boost	Muda a ordem de retorno dos resultados	Pesquisar apps com repositórios de dados que oferecem suporte a um esquema, como repositórios que contêm dados estruturados, sites com dados estruturados (indexação avançada de sites), dados não estruturados com metadados ou dados de mídia
Controle de filtro	Remove entradas dos resultados retornados	Pesquisar apps com repositórios de dados que oferecem suporte a um esquema, como repositórios de dados estruturados, sites (indexação avançada e pesquisa básica), dados não estruturados com metadados ou dados de mídia
Controle de sinônimos	Associa consultas umas às outras	Pesquisar apps com repositórios de dados de mídia, estruturados ou não estruturados e de sites (indexação avançada de sites)
Controle de redirecionamento	Redireciona para um URI especificado	Todos os apps de pesquisa
Promover controle	Promove um link especificado para uma consulta	Somente apps básicos de pesquisa no site

Sobre as condições

Ao criar um controle, você pode definir uma condição que determina quando o controle é aplicado. As condições são definidas usando campos de condição. Os seguintes campos de condição estão disponíveis:

• queryTerms: um controle opcional que é aplicado quando consultas específicas são pesquisadas. Quando a condição queryTerms é usada, o controle é aplicado quando o valor de queryTerms corresponde a um termo em SearchRequest.query. Os termos da consulta só podem ser usados quando a Control.searchUseCase está definida como SOLUTION_TYPE_SEARCH. Até 10 queryTerms diferentes podem ser especificados em uma única Control.condition. Se nenhum termo de consulta for especificado, o campo queryTerms será ignorado.

  Para um controle de veiculação de promoção, estas outras restrições são aplicáveis:

  • A condição queryTerms não pode ser especificada se você estiver especificando a condição queryRegex.
  • fullMatch precisa ser definido como true

• activeTimeRange: um controle opcional que é aplicado quando uma solicitação ocorre em um período especificado. Ele verifica se o horário em que uma solicitação foi recebida está entre activeTimeRange.startTime e activeTimeRange.endTime. É possível especificar até 10 intervalos de activeTimeRange em uma única Control.condition. Se o campo activeTimeRange não for especificado, ele será ignorado.

• queryRegex. Disponível apenas para um controle de promoção de exibição, uma condição opcional que aplica o controle quando a consulta corresponde à expressão regular especificada. Essa condição não pode ser especificada se você estiver especificando a condição queryTerms.

Se várias condições forem especificadas para um controle, ele será aplicado à solicitação de pesquisa quando ambos os tipos de condição forem atendidos. Se vários valores para a mesma condição forem especificados, apenas um dos valores precisará ser correspondente para que essa condição seja satisfeita.

Por exemplo, considere a seguinte condição com dois termos de consulta especificados:

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

A condição será atendida para uma solicitação com SearchRequest.query="gShoe" ou SearchRequest.query="gBoot", mas não será atendida com SearchRequest.query="gSandal" ou qualquer outra string.

Se nenhuma condição for especificada, o controle será aplicado sempre.

Para mais informações, consulte o campo Condition na referência da API.

Criar e anexar controles de veiculação do aumento

Um controle de veiculação de aumento é definido como um controle com um boostAction.

Use as instruções a seguir para criar um controle de veiculação de aumento.

Para detalhes sobre os campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

1. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

   1. No console do Google Cloud , acesse a página Criador de agentes.

      Acessar "Apps".

   2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

2. Execute os comandos curl a seguir para criar os 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"
    }
   }'

   Substitua:

   • PROJECT_ID: o número ou ID do seu projeto Google Cloud .
   • APP_ID: o ID do app da Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo do controle. O ID pode conter [1-63] caracteres, como letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível para humanos do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com comprimento [1,128].
   • USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
   • CONDITION: um campo opcional que define quando o controle precisa ser aplicado. Contém os seguintes campos:
     • VALUE: o valor específico da consulta a ser comparado. É uma string UTF-8 com letras minúsculas e comprimento [1, 5000]. Se FULL_MATCH_1 for true, este campo poderá ter no máximo três termos separados por espaços.
     • FULL_MATCH: um booleano que indica se a consulta de pesquisa precisa corresponder exatamente ao termo da consulta. Quando definido como true, ele exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, ele exige que SearchRequest.query contenha queryTerm.value como uma substring.
     • START_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o início de um intervalo de tempo.
     • END_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o fim de um período.
   • BOOST_VALUE: um número de ponto flutuante no intervalo [-1,1]. Quando o valor é negativo, os resultados são rebaixados (eles aparecem mais abaixo nos resultados). Quando o valor é positivo, os resultados são promovidos (eles aparecem mais acima nos resultados). Para mais informações, consulte boostAction.
   • FILTER: uma string que especifica os requisitos que o documento precisa cumprir. Se o documento atender a todos os requisitos, o impulso será aplicado. Caso contrário, não há mudanças. Se esse campo estiver vazio, o aumento será aplicado a todos os documentos no repositório de dados. Para a sintaxe de filtragem, consulte Sintaxe da expressão de filtro. Observação: o campo de documento title não pode ser filtrado.
   • DATA_STORE_RESOURCE_PATH: o caminho completo do recurso da repositório de dados cujos documentos precisam ser impulsionados por esse controle. O formato do caminho completo do recurso é projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Esse repositório de dados precisa ser anexado ao mecanismo especificado na solicitação.

3. Anexe o controle à configuração de exibição do app usando o 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"]
   }'

   Substitua BOOST_ID_N pelos IDs de controle que você criou na etapa anterior.

Criar e anexar controles de veiculação de filtro

Um controle de veiculação de filtro é definido como um controle com um filterAction.

Use as instruções a seguir para criar um controle de veiculação de filtro.

Para detalhes sobre os campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

1. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

   1. No console do Google Cloud , acesse a página Criador de agentes.

      Acessar "Apps".

   2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

2. Execute os comandos curl a seguir para criar os 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"
    }
   }'

   Substitua:

   • PROJECT_ID: o número ou ID do seu projeto Google Cloud .
   • APP_ID: o ID do app da Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo do controle. O ID pode conter [1-63] caracteres, como letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível para humanos do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com comprimento [1,128].
   • USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
   • CONDITION: um campo opcional que define quando o controle precisa ser aplicado. Contém os seguintes campos:
     • VALUE: o valor específico da consulta a ser comparado. É uma string UTF-8 com letras minúsculas e comprimento [1, 5000]. Se FULL_MATCH_1 for true, este campo poderá ter no máximo três termos separados por espaços.
     • FULL_MATCH: um booleano que indica se a consulta de pesquisa precisa corresponder exatamente ao termo da consulta. Quando definido como true, ele exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, ele exige que SearchRequest.query contenha queryTerm.value como uma substring.
     • START_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o início de um intervalo de tempo.
     • END_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o fim de um período.
   • FILTER: uma string que especifica os requisitos que o documento precisa cumprir. Se o documento atender a todos os requisitos, ele será retornado nos resultados. Caso contrário, o documento não vai aparecer nos resultados. Para a sintaxe de filtragem, consulte Sintaxe da expressão de filtro. Veja mais informações em filterAction. Observação: o campo de documento title não pode ser filtrado.

3. Anexe o controle à configuração de exibição do app usando o 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"]
   }'

   Substitua FILTER_ID_N pelos IDs de controle que você criou na etapa anterior.

Criar e anexar controles de veiculação de sinônimos

Um controle de exibição de sinônimos é definido como um controle com um synonymsAction.

Use as instruções a seguir para criar um controle de veiculação de sinônimos.

Para detalhes sobre os campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

1. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

   1. No console do Google Cloud , acesse a página Criador de agentes.

      Acessar "Apps".

   2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

2. Execute os comandos curl a seguir para criar os 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"]
    }
   }'

   Substitua:

   • PROJECT_ID: o número ou ID do seu projeto Google Cloud .
   • APP_ID: o ID do app Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo do controle. O ID pode conter [1-63] caracteres, como letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível para humanos do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com comprimento [1,128].
   • USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
   • CONDITION: um campo opcional que define quando o controle precisa ser aplicado. Contém os seguintes campos:
     • VALUE: o valor específico da consulta a ser comparado. É uma string UTF-8 com letras minúsculas e comprimento [1, 5000]. Se FULL_MATCH_1 for true, este campo poderá ter no máximo três termos separados por espaços.
     • FULL_MATCH: um booleano que indica se a consulta de pesquisa precisa corresponder exatamente ao termo da consulta. Quando definido como true, ele exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, ele exige que SearchRequest.query contenha queryTerm.value como uma substring.
     • START_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o início de um intervalo de tempo.
     • END_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o fim de um período.
   • SYNONYMS_N: uma lista de strings associadas uma à outra, o que aumenta a probabilidade de cada uma delas mostrar resultados semelhantes. Embora seja mais provável que você receba resultados semelhantes, ao pesquisar cada uma das entradas de sinônimo, talvez você não receba todos os resultados relevantes para todos os sinônimos associados. É preciso especificar pelo menos dois sinônimos e é possível especificar até 100 sinônimos. Cada sinônimo precisa ser codificado em UTF-8 e estar em letras minúsculas. Não são permitidas strings duplicadas. Por exemplo, você pode adicionar "pixel", "smartphone Android" e "smartphone Google" como sinônimos. Para ver mais informações, consulte synonymsAction.

3. Anexe o controle à configuração de exibição do app usando o 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"]
   }'

   Substitua SYNONYMS_ID_N pelos IDs de controle que você criou na etapa anterior.

Criar e anexar controles de veiculação de redirecionamento

Um controle de veiculação de redirecionamento permite redirecionar os usuários para um URI fornecido. Os controles de redirecionamento são definidos como um controle com um redirectAction.

Use as instruções a seguir para criar um controle de veiculação de redirecionamento.

Para detalhes sobre os campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

1. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

   1. No console do Google Cloud , acesse a página Criador de agentes.

      Acessar "Apps".

   2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

2. Execute os comandos curl a seguir para criar os 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"
    }
   }'

   Substitua:

   • PROJECT_ID: o número ou ID do seu projeto Google Cloud .
   • APP_ID: o ID do app da Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo do controle. O ID pode conter [1-63] caracteres, como letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível para humanos do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com comprimento [1,128].
   • USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
   • CONDITION: um campo opcional que define quando o controle precisa ser aplicado. Contém os seguintes campos:
     • VALUE: o valor específico da consulta a ser comparado. É uma string UTF-8 com letras minúsculas e comprimento [1, 5000]. Se FULL_MATCH_1 for true, este campo poderá ter no máximo três termos separados por espaços.
     • FULL_MATCH: um booleano que indica se a consulta de pesquisa precisa corresponder exatamente ao termo da consulta. Quando definido como true, ele exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, ele exige que SearchRequest.query contenha queryTerm.value como uma substring.
     • START_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o início de um intervalo de tempo.
     • END_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o fim de um período.
   • REDIRECT_URI_N: um URI para onde você é redirecionado. Pode ter um comprimento máximo de 2.000 caracteres. Por exemplo, se o valor do termo da consulta for "support", você poderá definir um redirecionamento para sua página de suporte técnico em vez de retornar (ou não retornar) os resultados da pesquisa para "support". Neste exemplo, o URI de redirecionamento passa a ser "https://www.example.com/support". Veja mais informações em redirectAction.

3. Anexe o controle à configuração de exibição do app usando o 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"]
   }'

   Substitua REDIRECT_ID_N pelos IDs de controle que você criou na etapa anterior.

Criar e anexar controles de veiculação de promoções

Com um controle de veiculação de promoção, você pode mostrar um link como resultado promovido. Esse controle está disponível apenas para repositórios de dados de sites com pesquisa básica no site.

Ao contrário de outros controles de veiculação, não é necessário anexar um controle de promoção à configuração de veiculação do app. Criar e ativar um controle de promoção para um app ativa o controle de promoção. Além disso, ao contrário de outros controles de veiculação, você pode ativar ou desativar um controle de promoção.

Os controles de promoção são definidos usando um promoteAction.

Para criar um controle de promoção, um dos seguintes campos é necessário na solicitação de criação:

• O campo queryTerms com fullMatch definido como true
• Campo queryRegex

Use as instruções a seguir para criar um controle de veiculação de promoção.

Para detalhes sobre os campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

1. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

   1. No console do Google Cloud , acesse a página Criador de agentes.

      Acessar "Apps".

   2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

2. Execute os comandos curl a seguir para criar os 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": {
        "title": "URI_TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE,
     }
    }
   }'

   Substitua:

   • PROJECT_ID: o número ou ID do seu projeto Google Cloud .
   • APP_ID: o ID do app da Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo do controle. O ID pode conter [1-63] caracteres, como letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível para humanos do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com comprimento [1,128].
   • USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
   • Condition: um objeto opcional que define quando o controle precisa ser aplicado. Contém os seguintes campos:
     • queryTerms: não pode ser usado com o campo queryRegex.
       • VALUE: o valor específico da consulta a ser comparado. É uma string UTF-8 com letras minúsculas e comprimento [1, 5000].
     • activeTimeRange:
       • START_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o início de um período.
       • END_TIMESTAMP: um carimbo de data/hora no formato "Zulu" UTC RFC 3339 para indicar o fim de um período.
     • queryRegex: não pode ser usado com o campo queryTerms.
       • VALUE_REGEX: uma expressão regular para corresponder à consulta. Essa opção só está disponível para o controle de veiculação de promoção.
   • DATA_STORE_RESOURCE_PATH: o caminho de recurso completo do repositório de dados cujos resultados de pesquisa contêm o URL promovido. O formato do caminho completo do recurso é projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Esse repositório de dados precisa ser anexado ao mecanismo especificado na solicitação.
   • URI_TITLE: um campo obrigatório para especificar o título do URI, que é exibido no resultado da pesquisa.
   • URI: um campo obrigatório para especificar o link do URI para onde o resultado da pesquisa leva o usuário. Esse URI não precisa ser incluído no repositório de dados.
   • URI_DESCRIPTION: um campo opcional para descrever o URI, que é exibido no resultado da pesquisa.
   • ENABLED_TRUE|FALSE: um campo booleano opcional para indicar se o controle de promoção está ativado e anexado ao app. Quando você define esse campo como false, o controle de veiculação de promoção é desativado e, para que o controle entre em vigor, você precisa atualizar o controle ativando-o, conforme explicado na próxima etapa. Veja mais informações em promoteAction.

   Resposta

   Você receberá uma resposta JSON semelhante a esta:

   {
    "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. Opcional: para ativar ou desativar um controle de promoção depois que ele for criado, chame o 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,
     }
   }
   }'

Exemplo

Quando você envia uma solicitação de pesquisa para o app com uma consulta que corresponde à consulta ou expressão regular especificada para o controle de promoção, o link promovido aparece na resposta.

Por exemplo, suponha que você crie um controle de promoção com a seguinte configuração:

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

Em seguida, envie a seguinte solicitação de pesquisa:

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

Você vai receber uma resposta JSON semelhante a esta resposta truncada. A resposta contém o campo searchLinkPromotions que contém o link promovido.

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

A seguir

• Para entender o impacto de um controle de veiculação na qualidade da pesquisa de um app de pesquisa genérico, avalie a qualidade da pesquisa. Para mais informações, consulte Avaliar a qualidade da pesquisa.