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 é atendida quando os resultados são retornados. Os controles de exibição atuam no nível do repositório de dados.

Por exemplo, os controles podem impulsionar e ocultar resultados, filtrar entradas dos resultados retornados, associar strings entre si 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 controles de exibição com recomendações de mídia, consulte Criar e gerenciar configurações de exibição de mídia.

Sobre os controles de veiculação

Para mudar os resultados de uma solicitação, primeiro crie um controle de exibiçã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 no momento da exibição, como resultados da pesquisa ou respostas. Um controle de veiculação só afeta as solicitações veiculadas pelo app se estiver anexado à configuração de veiculação dele.

Alguns controles, como os de reforço, têm dependências de repositórios de dados. Se um repositório de dados for removido de um app, todos os controles dependentes dele também serão removidos 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 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 com dados estruturados (indexação avançada de sites), dados não estruturados com metadados ou dados de mídia
Controle de filtros	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 de sites), dados não estruturados com metadados ou dados de mídia
Controle de sinônimos	Associa consultas entre si	Apps de pesquisa com repositórios de dados de sites (indexação avançada de sites), estruturados, não estruturados ou de mídia
Controle de redirecionamento	Redireciona para um URI especificado.	Todos os apps de pesquisa
Promover controle	Promove um link especificado para uma consulta.	Todos os apps de pesquisa

Sobre as condições

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

• Termos de consulta (queryTerms). Um controle opcional 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 de consulta só podem ser usados quando o Control.searchUseCase é definido como SOLUTION_TYPE_SEARCH. É possível especificar até 10 queryTerms diferentes em um único Control.condition. Se nenhum termo de consulta for especificado, o campo queryTerms será ignorado.

  Para um controle de veiculação de promoção, queryTerms não pode ser especificado se você estiver especificando a condição queryRegex, que se aplica apenas à pesquisa básica de sites. Além disso, o campo fullMatch para a pesquisa básica no site precisa ser definido como true se queryTerms for especificado. Para todos os outros apps de pesquisa, apenas queryTerms é compatível, e fullMatch pode ser definido como true ou false.

• Período (activeTimeRange): um controle opcional 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 um único Control.condition. Se o campo activeTimeRange não for especificado, ele será ignorado.

• queryRegex. Disponível apenas para um controle de veiculação de promoção para pesquisa básica no site. Essa é 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 os dois tipos de condição forem atendidos. Se vários valores forem especificados para a mesma condição, apenas um deles precisará corresponder para que a condição seja atendida.

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 com SearchRequest.query="gSandal" ou qualquer outra string.

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

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

Criar e anexar controles de veiculação de aumento

Um controle de veiculação de reforço reordena os resultados promovendo ou rebaixando-os com base nas condições aplicadas. O reforço funciona aplicando um fator de multiplicação ao ranking de um documento que atende às condições de reforço.

Para criar e anexar o controle de reforço, faça o seguinte:

Console

1. No console Google Cloud , acesse a página Aplicativos de IA.

   Aplicativos de IA

2. Selecione o app para o qual você quer criar o controle de aumento.

3. Na página de visão geral do app, verifique se você está na guia Visão geral do sistema.

4. Na etapa Indicador, clique no bloco Promover/Ocultar.

5. Clique em Criar controle.

6. No painel Criar controle, faça o seguinte:

   1. Em Nomeie seu controle, insira um nome para o controle de otimização/ocultação e clique em Continuar.

   2. Em Definir escopo e impacto da regra, defina as ações que você quer acionar com esse controle:

      1. Selecione um repositório de dados na lista. Se você quiser que a ação seja aplicada a vários repositórios de dados, crie um controle para cada um deles.

      2. Em Filtrar, adicione um filtro.

         É uma string que especifica os requisitos que o documento precisa atender. A condição de reforço só é aplicada se o documento corresponder a todos os requisitos. Caso contrário, não haverá mudança. Se você não especificar filtros, o aumento será aplicado a todos os documentos no repositório de dados.

         Para entender como escrever expressões de filtro, consulte Sintaxe da expressão de filtro e Exemplos de expressões de filtro.

      3. Em Valor de otimização/aumento, selecione um valor no intervalo [-1, 1] usando o controle deslizante. O controle deslizante se move em etapas de 0,01.

      4. Clique em Continuar.

   3. Em Opcional: quando esta regra é ativada, defina as seguintes condições que acionam o controle. Se nenhuma condição for configurada, o controle estará sempre em vigor:

      1. Adicione Termos de consulta de correspondência parcial. O controle entra em vigor quando esses termos de consulta têm uma correspondência parcial.

      2. Adicione termos de consulta com correspondência exata. O controle entra em vigor quando esses termos de consulta correspondem exatamente.

      3. Para adicionar um período ativo, clique em Adicionar período e defina Horário de início 1 e Horário de término 1. Isso define a janela em que a condição está ativa. É possível adicionar até 10 períodos.

      4. Clique em Continuar.

   4. Se quiser aplicar esse controle assim que ele for criado, em Configurações adicionais, ative Publicar este controle imediatamente e clique em Continuar.

7. Clique em Enviar.

REST

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 reforço.

Para detalhes dos 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 Google Cloud , acesse a página Aplicativos de IA.

      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 seus 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 projeto do Google Cloud .
   • APP_ID: o ID do app Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível 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 tamanho [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 deve ser aplicado. Contém os seguintes campos:
     • VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com 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 de consulta. Quando definido como true, exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, exige que SearchRequest.query contenha queryTerm.value como uma substring.
     • START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
     • END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" 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 (aparecem mais abaixo nos resultados). Quando o valor é positivo, os resultados são promovidos (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 aumento será aplicado. Caso contrário, não haverá mudanças. Se este campo estiver vazio, o reforço 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: não é possível filtrar o campo de documento title.
   • DATA_STORE_RESOURCE_PATH: o caminho completo do recurso do repositório de dados cujos documentos devem ser promovidos 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 estar 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 filtros

Um controle de veiculação de filtro filtra por um determinado critério ou regra. Por exemplo, para um site de hotel, você pode aplicar um filtro para (price < 175 AND petfriendly = "true") que mostre apenas hotéis que aceitam animais de estimação com preço abaixo de US $175 por noite.

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

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

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

Console

1. No console Google Cloud , acesse a página Aplicativos de IA.

   Aplicativos de IA

2. Selecione o app para o qual você quer criar o controle de filtro.

3. Na página de visão geral do app, verifique se você está na guia Visão geral do sistema.

4. Na etapa Indicador, clique no bloco Filtro.

5. Clique em Criar controle.

6. No painel Criar controle, faça o seguinte:

   1. Em Nomeie seu controle, insira um nome para o controle de filtro e clique em Continuar.

   2. Em Escopo e impacto da regra, defina o seguinte:

      1. Selecione um repositório de dados na lista a que você quer anexar esse controle de filtro. Se você quiser que a ação seja aplicada a vários armazenamentos de dados, crie um controle para cada um repositório de dados.

      2. Em Filtro, informe à regra quais itens específicos devem ser procurados. É possível combinar termos de pesquisa usando AND, OR, NOT e agrupar termos com (). Para frases exatas, use aspas "". Exemplo: category: "electronics" AND price < 500, status: "open" AND priority:"P1".

         Para entender como escrever expressões de filtro, consulte Sintaxe da expressão de filtro e Exemplos de expressões de filtro.

      3. Clique em Continuar.

   3. Em Opcional: quando esta regra é ativada, defina as ações que você quer acionar com o controle. Se nenhuma condição for configurada, o controle estará sempre em vigor:

      1. Adicione Termos de consulta de correspondência parcial. O controle entra em vigor quando esses termos de consulta têm uma correspondência parcial.

      2. Adicione termos de consulta com correspondência exata. O controle entra em vigor quando esses termos de consulta correspondem exatamente.

      3. Para adicionar um período ativo, clique em Adicionar período e defina Horário de início 1 e Horário de término 1. Isso define a janela em que a condição está ativa. É possível adicionar até 10 períodos.

      4. Clique em Continuar.

   4. Se quiser aplicar esse controle assim que ele for criado, em Configurações adicionais, ative Publicar este controle imediatamente e clique em Continuar.

7. Clique em Enviar.

REST

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

   1. No console Google Cloud , acesse a página Aplicativos de IA.

      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 seus 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 projeto do Google Cloud .
   • APP_ID: o ID do app Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível 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 tamanho [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 deve ser aplicado. Contém os seguintes campos:
     • VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com 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 de consulta. Quando definido como true, exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, exige que SearchRequest.query contenha queryTerm.value como uma substring.
     • START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
     • END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" 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. Para ver mais informações, consulte filterAction. Observação: não é possível filtrar o campo de documento title.

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 exibição de sinônimos.

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

Console

1. No console Google Cloud , acesse a página Aplicativos de IA.

   Aplicativos de IA

2. Selecione o app para o qual você quer criar o controle de sinônimos.

3. Na página de visão geral do app, verifique se você está na guia Visão geral do sistema.

4. Na etapa Preparar, clique no bloco Sinônimos.

5. Clique em Criar controle.

6. No painel Criar controle, faça o seguinte:

   1. Em Nomeie seu controle, insira um nome para o controle de sinônimos e clique em Continuar.

   2. Em Escopo e impacto da regra:

      1. Insira os sinônimos que você quer considerar no controle. Por exemplo, digite gatos seguido de um retorno (não vírgula) e, em seguida, felino.

      2. Quando terminar de inserir sinônimos, clique em Continuar.

   3. Em Opcional: quando esta regra é ativada, defina as ações que você quer acionar com o controle. Se nenhuma condição for configurada, o controle estará sempre em vigor:

      1. Para adicionar um período ativo, clique em Adicionar período e defina Horário de início 1 e Horário de término 1. Isso define a janela em que a condição está ativa. É possível adicionar até 10 períodos.

      2. Clique em Continuar.

   4. Se quiser aplicar esse controle assim que ele for criado, em Configurações adicionais, ative Publicar este controle imediatamente e clique em Continuar.

7. Clique em Enviar.

REST

1. Execute os comandos curl a seguir para criar seus 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 projeto do Google Cloud .
   • APP_ID: o ID do app Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível 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 tamanho [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 deve ser aplicado. Contém os seguintes campos:
     • VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com 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 de consulta. Quando definido como true, exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, exige que SearchRequest.query contenha queryTerm.value como uma substring.
     • START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
     • END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" para indicar o fim de um período.
   • SYNONYMS_N: uma lista de strings associadas entre si, o que aumenta a probabilidade de cada uma mostrar resultados semelhantes. Embora seja mais provável que você receba resultados semelhantes, ao pesquisar cada uma das entradas de sinônimos, talvez não receba todos os resultados relevantes para todos os sinônimos associados. É preciso especificar pelo menos dois sinônimos, sendo possível especificar até 100. 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 do google" como sinônimos. Para ver mais informações, consulte synonymsAction.

2. 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 dos 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 Google Cloud , acesse a página Aplicativos de IA.

      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 seus 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 projeto do Google Cloud .
   • APP_ID: o ID do app Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível 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 tamanho [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 deve ser aplicado. Contém os seguintes campos:
     • VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com 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 de consulta. Quando definido como true, exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, exige que SearchRequest.query contenha queryTerm.value como uma substring.
     • START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
     • END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" 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 de consulta for "suporte", você poderá definir um redirecionamento para a página de suporte técnico em vez de retornar (ou não retornar) resultados da pesquisa para "suporte". Neste exemplo, o URI de redirecionamento se torna "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ção

Um controle de exibição de promoção permite mostrar um link como um resultado promovido e está disponível para os seguintes tipos de repositórios de dados de pesquisa:

• Repositórios de dados de sites com pesquisa básica no site: para esses repositórios, não é necessário anexar um controle de promoção à configuração de exibição do app. Criar e ativar um controle de promoção ativa esse controle. É possível ativar ou desativar um controle de promoção habilitando ou desabilitando-o.

• Repositórios de dados com dados estruturados e não estruturados, dados de sites com indexação avançada e apps de pesquisa combinada: para esses repositórios, é necessário anexar o controle de promoção à configuração de veiculação.

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

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

• queryTerms: essa condição não pode ser especificada se você estiver especificando a condição queryRegex, que se aplica apenas à pesquisa básica de sites. Para a pesquisa básica no site, fullMatch precisa ser definido como true se queryTerms for especificado. Para todos os outros apps de pesquisa, apenas queryTerms é compatível, e fullMatch pode ser definido como true ou false.
• queryRegex. Disponível apenas para um controle de veiculação de promoção para pesquisa básica no site. Essa condição 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.

Ou seja, para a pesquisa básica de sites, é necessário especificar o campo queryTerms com fullMatch definido como true ou especificar o campo queryRegex. Para todos os outros tipos de pesquisa, especifique o campo queryTerms com fullMatch definido como true ou false.

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

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

Console

1. No console Google Cloud , acesse a página Aplicativos de IA.

   Aplicativos de IA

2. Selecione o app para o qual você quer criar o controle de filtro.

3. Na página de visão geral do app, verifique se você está na guia Visão geral do sistema.

4. Na etapa Indicador, clique no bloco Promover.

5. Clique em Criar controle.

6. No painel Criar controle, faça o seguinte:

   1. Em Nomeie seu controle, insira um nome para o controle de filtro e clique em Continuar.

   2. Em Escopo e impacto da regra, defina o seguinte:

      1. Selecione um repositório de dados na lista a que você quer anexar esse controle de filtro. Se você quiser que a ação seja aplicada a vários armazenamentos de dados, crie um controle para cada um repositório de dados.

      2. Insira o título da promoção, como Confira o vídeo mais recente.

      3. Insira o URL de promoção, como o local do vídeo.

      4. Insira o URL da imagem de promoção, como uma miniatura ou captura de tela.

      5. Insira uma breve Descrição da promoção, como o assunto do vídeo. O máximo é de 250 caracteres.

   3. Em Opcional: quando esta regra é ativada, defina as ações que você quer acionar com o controle. Se nenhuma condição for configurada, o controle estará sempre em vigor:

      1. Adicione termos de consulta com correspondência exata. O controle entra em vigor quando esses termos de consulta correspondem exatamente.

      2. Para adicionar um período ativo, clique em Adicionar período e defina Horário de início 1 e Horário de término 1. Isso define a janela em que a condição está ativa. É possível adicionar até 10 períodos.

      3. Clique em Continuar.

7. Clique em Enviar.

REST

1. Execute os comandos curl a seguir para criar seus controles.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": true
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ],
     "queryRegex": "VALUE_REGEX"
   },
   "promoteAction": {
     "dataStore": "DATA_STORE_RESOURCE_PATH",
     "searchLinkPromotion": {
        "document": "DOCUMENT_RESOURCE_PATH",
        "title": "TITLE",
        "uri": "URI",
        "description": "DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE,
     }
    }
   }'

   Substitua:

   • PROJECT_ID: o número ou ID do projeto do Google Cloud .
   • APP_ID: o ID do app Vertex AI para Pesquisa.
   • CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
   • DISPLAY_NAME: o nome legível 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 tamanho [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 deve ser aplicado. Contém os seguintes campos:
     • queryTerms: não pode ser usado com o campo queryRegex.
       • VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com comprimento [1, 5000].
     • activeTimeRange:
       • START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
       • END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" para indicar o fim de um período.
     • queryRegex: disponível apenas para repositórios de dados com pesquisa básica de sites. Esse campo não pode ser usado com o campo queryTerms.
       • VALUE_REGEX: uma expressão regular para corresponder a consulta.
   • DATA_STORE_RESOURCE_PATH: o caminho completo do recurso do repositório de dados cujos resultados da 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 estar anexado ao mecanismo especificado na solicitação.
   • DOCUMENT_RESOURCE_PATH: um campo para especificar o caminho do recurso do documento a ser promovido:
     • Para repositórios de dados de pesquisa com dados estruturados e não estruturados, é necessário fornecer o caminho do recurso de documento no campo DOCUMENT_RESOURCE_PATH, o URI no campo URI ou ambos. O formato do caminho completo do recurso é projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.
     • Para repositórios de dados de sites, esse campo precisa estar desmarcado e o campo URI precisa ser definido.
   • TITLE: um campo obrigatório para especificar o título do documento ou da página da Web a ser promovida. Esse título é exibido no resultado da pesquisa.
   • URI: um campo obrigatório para especificar o link do URI em que o resultado da pesquisa direciona o usuário. Não é necessário incluir esse URI no repositório de dados.
     • Para repositórios de dados de pesquisa com dados estruturados e não estruturados, é necessário fornecer o caminho do recurso de documento no campo DOCUMENT_RESOURCE_PATH, o URI no campo URI ou ambos.
     • Para repositórios de dados de sites, esse é um campo obrigatório que precisa ser definido.
   • DESCRIPTION: um campo opcional para descrever o documento ou a página da Web a ser promovida, que é exibida 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. Esse campo é aplicável a repositórios de dados de sites com apenas pesquisa básica de sites. Quando você define esse campo como false, o controle de veiculação da promoção é desativado. Para que ele entre em vigor, é necessário 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
     }
    }
   }
   

2. Para todos os apps de pesquisa, exceto a pesquisa básica de sites, anexe o controle à configuração de exibição do app usando o método engines.servingConfigs.patch. A ordem em que os promoteControlIds são anexados na solicitação a seguir é a ordem em que os resultados promovidos são retornados.

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

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

3. Opcional: para a pesquisa básica de sites, não é necessário anexar o controle à configuração de veiculação do app. No entanto, para a pesquisa básica de sites, é possível ativar ou desativar um controle de promoção depois que ele for criado. Para isso, 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 de consulta 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 em um repositório de dados com pesquisa básica no site:

{
 "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 search:

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, que está truncada. A resposta contém o campo searchLinkPromotions, que inclui 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"
    }
  ]
}

Modificar controles de veiculação

Para modificar a configuração de um controle, faça o seguinte:

1. No console Google Cloud , acesse a página Aplicativos de IA.

   Aplicativos de IA

2. Selecione o app para o qual você quer modificar os controles.

3. Na guia Visão geral do sistema, selecione a etapa Preparar ou Indicador em que seu controle está localizado.

4. Na lista de controles do app, clique em no controle que você quer modificar e clique em Editar.

5. Edite o controle no painel Editar controle.

6. Para ativar ou desativar um controle, na lista de controles de filtro do app, clique em para um controle que você quer ativar ou desativar e clique em Ativar ou Desativar, respectivamente.

7. Para excluir um controle, na lista de controles do app, clique em em um controle que você quer excluir e clique em Excluir.

A seguir

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