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 veiculação com recomendações de mídia, consulte Criar e gerenciar configurações de veiculaçã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 que contêm 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

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.

  • 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. Até 10 intervalos de activeTimeRange podem ser especificados em uma única Control.condition. Se o campo activeTimeRange não for especificado, ele será ignorado.

Se ambos os tipos de condições forem especificados 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 do 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 o 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, esse 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 precisam ser atendidos pelo documento. 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 do 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 do 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 o 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, esse 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 precisam ser atendidos pelo documento. 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 do 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 o 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, esse 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 do 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 o 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, esse 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 "suporte", 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 "suporte". 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.

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.