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:

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 para a mesma condição forem especificados, 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 otimização

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 à classificação de um documento que atende às condições de reforço.

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

Criar e anexar controles de veiculação de filtros

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.

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 seu projeto 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. Veja mais informações em 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.

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"
       }
     ]
   },
   "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 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.

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 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 seu projeto 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. A criação e a ativação de um controle de promoção ativam 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.

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": 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 seu projeto 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 leva 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 pesquisa básica de sites apenas. 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
     }
    }
   }
   

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

4. 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 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, 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"
    }
  ]
}

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.