Configure os controlos de publicação para a pesquisa

Os controlos de publicação (também denominados controlos) alteram o comportamento predefinido de como um pedido é publicado quando são devolvidos resultados. Os controlos de publicação atuam ao nível do armazenamento de dados.

Por exemplo, os controlos podem aumentar e ocultar resultados, filtrar entradas dos resultados devolvidos, associar strings entre si como sinónimos ou redirecionar resultados para URIs especificados.

Esta página descreve os controlos de publicação para apps de pesquisa. Para ver informações sobre a utilização de controlos de publicação com recomendações de multimédia, consulte o artigo Crie e faça a gestão de configurações de publicação de multimédia.

Acerca dos controlos de publicação

Para alterar os resultados de um pedido, crie primeiro um controlo de publicação. Em seguida, anexe esse controlo à configuração de publicação de uma app de pesquisa. Uma configuração de publicação configura metadados que são usados para gerar resultados no momento da publicação, como resultados da pesquisa ou respostas. Um controlo de publicação só afeta os pedidos publicados pela app se o controlo estiver anexado à configuração de publicação da app.

Alguns controlos, como os controlos de aumento, têm dependências de repositórios de dados. Se uma loja de dados for removida de uma app, todos os controlos dependentes da loja de dados também são removidos dessa app e ficam inativos, mas não são eliminados.

Tipos de controlos de publicação

Estão disponíveis os seguintes tipos de controlos de publicação:

Controlo Descrição Disponível para
Controlo do aumento Altera a ordem dos resultados devolvidos Pesquise apps com arquivos de dados que suportam um esquema, como arquivos de dados que contêm dados estruturados, Websites com dados estruturados (indexação avançada de Websites), dados não estruturados com metadados ou dados multimédia
Controlo de filtros Remove entradas dos resultados devolvidos Pesquise apps com arquivos de dados que suportam um esquema, como arquivos de dados que contêm dados estruturados, Websites (indexação avançada de Websites), dados não estruturados com metadados ou dados multimédia
Controlo de sinónimos Associa consultas entre si Pesquise apps com Websites (indexação avançada de Websites), lojas de dados estruturados, não estruturados ou multimédia
Controlo de redirecionamento Redireciona para um URI especificado Todas as apps de pesquisa
Controlo de promoção Promove um link especificado para uma consulta Todas as apps de pesquisa

Acerca das condições

Quando cria um controlo, pode definir opcionalmente uma condição que determine quando o controlo é aplicado. As condições são definidas através de campos de condição. Os seguintes campos de condições estão disponíveis:

  • Termos de consulta (queryTerms). Um controlo opcional que é aplicado quando são pesquisadas consultas específicas. Quando a condição queryTerms é usada, o controlo é 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 estiver definido como SOLUTION_TYPE_SEARCH. É possível especificar até 10 queryTerms diferentes num único Control.condition. Se não forem especificados termos de consulta, o campo queryTerms é ignorado.

    Para um controlo de publicação de promoção, não é possível especificar queryTerms se estiver a especificar a condição queryRegex, que só é aplicável à pesquisa básica de Websites. Além disso, o campo fullMatch para a pesquisa básica de Websites tem de ser definido como true se queryTerms for especificado. Para todas as outras apps de pesquisa, apenas queryTerms é suportado e fullMatch pode ser definido como true ou false.

  • Intervalo de tempo (activeTimeRange). Um controlo opcional que é aplicado quando ocorre um pedido dentro de um intervalo de tempo especificado. Verifica se a hora em que um pedido foi recebido está entre activeTimeRange.startTime e activeTimeRange.endTime. É possível especificar até 10 intervalos de activeTimeRange num único Control.condition. Se o campoactiveTimeRange não estiver especificado, o campo é ignorado.

  • queryRegex. Só está disponível para um controlo de publicação de promoção apenas para a pesquisa básica de Websites. Esta é uma condição opcional que aplica o controlo quando a consulta corresponde à expressão regular especificada. Não é possível especificar esta condição se estiver a especificar a condição queryTerms.

Se forem especificadas várias condições para um controlo, o controlo é aplicado ao pedido de pesquisa quando ambos os tipos de condições são cumpridos. Se forem especificados vários valores para a mesma condição, apenas um dos valores tem de corresponder 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 é cumprida para um pedido com SearchRequest.query="gShoe" ou um pedido com SearchRequest.query="gBoot", mas não é cumprida com SearchRequest.query="gSandal" nem qualquer outra string.

Se não forem especificadas condições, o controlo é sempre aplicado.

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

Crie e anexe controlos de publicação de aumentos

Um controlo de publicação de aumento reordena os resultados promovendo-os ou rebaixando-os com base nas condições aplicadas. A otimização funciona aplicando um fator de multiplicação à classificação de um documento que cumpre as condições de otimização.

Para criar e anexar o controlo de aumento, faça o seguinte:

Consola

  1. Na Google Cloud consola, aceda à página Aplicações de IA.

    Aplicações de IA

  2. Selecione a app para a qual quer criar o controlo do aumento.

  3. Na página de vista geral da app, selecione Aumentar/Diminuir apresentado na fase Sinal.

  4. Na página Sinal, clique em Criar controlo.

  5. No painel Criar controlo, faça o seguinte:

    1. Introduza um nome para o controlo de realce/ocultação e clique em Continuar.

    2. Defina as seguintes condições que acionam o controlo. Se não forem configuradas condições, o controlo está sempre em vigor:

      1. Adicione termos de consulta de correspondência parcial. O controlo entra em vigor quando estes termos de consulta correspondem parcialmente.

      2. Adicione termos de consulta de correspondência exata. O controlo entra em vigor quando estes termos de consulta correspondem exatamente.

      3. Para adicionar um intervalo de tempo ativo, clique em Adicionar intervalo de tempo e defina a Hora de início 1 e a Hora de fim 1. Isto define a janela quando a condição está ativa. Pode adicionar um máximo de 10 intervalos de tempo.

      4. Clique em Continuar.

    3. Defina as ações que quer acionar com este controlo:

      1. Selecione um arquivo de dados na lista. Se quiser que a ação seja aplicada a várias bases de dados, crie um controlo para cada base de dados.

      2. Adicione um filtro.

        Esta é uma string que especifica os requisitos que o documento tem de cumprir. A condição de aumento só é aplicada se o documento corresponder a todos os requisitos. Caso contrário, não há alterações. Se não especificar filtros, o aumento é aplicado a todos os documentos no arquivo de dados.

        Para compreender como escrever expressões de filtro, consulte os artigos Sintaxe de expressões de filtro e Exemplos de expressões de filtro.

      3. Selecione um valor de realce/ocultação no intervalo [-1, 1] através do controlo de deslize. O controlo de deslize move-se em passos de 0,01.

      4. Clique em Continuar.

    4. Se quiser aplicar o controlo assim que for criado, ative a opção Publicar este controlo imediatamente e clique em Continuar.

  6. Clique em Enviar.

  7. Para modificar a configuração de um controlo, faça o seguinte:

    1. Na página Sinal, na lista dos controlos de realce/ocultação da app, clique em para um controlo que pretende modificar e clique em Editar.

    2. Edite o controlo no painel Editar controlo.

  8. Para ativar ou desativar um controlo, na página Sinal, na lista dos controlos de aumento/diminuição da app, clique em para um controlo que quer ativar ou desativar e clique em Ativar ou Desativar, respetivamente.

  9. Para eliminar um controlo, na página Sinal, na lista dos controlos de aumento/diminuição da app, clique em para um controlo que quer eliminar e clique em Eliminar.

REST

Um controlo de publicação de aumento é definido como um controlo com um boostAction.

Siga as instruções abaixo para criar um controlo de publicação de aumento.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Aplicações de IA.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • CONDITION: um campo opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000]. Se FULL_MATCH_1 for true, este campo pode ter, no máximo, três termos separados por espaços.
      • FULL_MATCH: um valor booleano que indica se a consulta de pesquisa tem de corresponder exatamente ao termo de consulta. Quando definido como true, requer que o SearchRequest.query corresponda totalmente ao queryTerm.value. Quando definido como false, requer que SearchRequest.query contenha queryTerm.value como uma substring.
      • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
      • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • BOOST_VALUE: um número de vírgula flutuante no intervalo [-1,1]. Quando o valor é negativo, os resultados são despromovidos (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 tem de cumprir. Se o documento corresponder a todos os requisitos, o aumento é aplicado. Caso contrário, não existe nenhuma alteração. Se este campo estiver vazio, o aumento é aplicado a todos os documentos no arquivo de dados. Para a sintaxe de filtragem, consulte o artigo Sintaxe de expressão de filtro. Nota: não é possível filtrar o campo do documento title.
    • DATA_STORE_RESOURCE_PATH: o caminho completo do recurso do repositório de dados cujos documentos devem ser otimizados por este controlo. O formato do caminho completo do recurso é projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Esta loja de dados tem de estar anexada ao motor especificado no pedido.

  3. Associe o controlo à configuração de publicação da app através do 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 dos controlos que criou no passo anterior.

Crie e anexe controlos de publicação de filtros

Um controlo de publicação de filtros é definido como um controlo com um filterAction.

Use as instruções seguintes para criar um controlo de publicação de filtros.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Aplicações de IA.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • CONDITION: um campo opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000]. Se FULL_MATCH_1 for true, este campo pode ter, no máximo, três termos separados por espaços.
      • FULL_MATCH: um valor booleano que indica se a consulta de pesquisa tem de corresponder exatamente ao termo de consulta. Quando definido como true, requer que o SearchRequest.query corresponda totalmente ao queryTerm.value. Quando definido como false, requer que SearchRequest.query contenha queryTerm.value como uma substring.
      • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
      • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • FILTER: uma string que especifica os requisitos que o documento tem de cumprir. Se o documento corresponder a todos os requisitos, o documento é devolvido nos resultados. Caso contrário, o documento não é apresentado nos resultados. Para a sintaxe de filtragem, consulte o artigo Sintaxe das expressões de filtro. Para mais informações, consulte filterAction. Nota: não é possível filtrar o campo do documento title.

  3. Associe o controlo à configuração de publicação da app através do 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 dos controlos que criou no passo anterior.

Crie e anexe controlos de publicação de sinónimos

Um controlo de publicação de sinónimos é definido como um controlo com um synonymsAction.

Use as instruções seguintes para criar um controlo de publicação de sinónimos.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Aplicações de IA.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • CONDITION: um campo opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000]. Se FULL_MATCH_1 for true, este campo pode ter, no máximo, três termos separados por espaços.
      • FULL_MATCH: um valor booleano que indica se a consulta de pesquisa tem de corresponder exatamente ao termo de consulta. Quando definido como true, requer que o SearchRequest.query corresponda totalmente ao queryTerm.value. Quando definido como false, requer que SearchRequest.query contenha queryTerm.value como uma substring.
      • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
      • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • SYNONYMS_N: uma lista de strings associadas entre si, o que aumenta a probabilidade de cada uma apresentar resultados semelhantes. Embora seja mais provável que obtenha resultados semelhantes, quando pesquisa cada uma das entradas de sinónimos, pode não receber todos os resultados relevantes para todos os sinónimos associados. Tem de especificar, pelo menos, dois sinónimos e pode especificar até 100 sinónimos. Cada sinónimo tem de estar codificado em UTF-8 e em letras minúsculas. Não são permitidas strings duplicadas. Por exemplo, pode adicionar "pixel", "telemóvel Android" e "telemóvel Google" como sinónimos. Para mais informações, consulte synonymsAction.

  3. Associe o controlo à configuração de publicação da app através do 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 dos controlos que criou no passo anterior.

Crie e anexe controlos de publicação de redirecionamentos

Um controlo de publicação de redirecionamentos permite redirecionar os utilizadores para um URI fornecido. Os controlos de redirecionamento são definidos como um controlo com um redirectAction.

Use as instruções seguintes para criar um controlo de publicação de redirecionamentos.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Aplicações de IA.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • CONDITION: um campo opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000]. Se FULL_MATCH_1 for true, este campo pode ter, no máximo, três termos separados por espaços.
      • FULL_MATCH: um valor booleano que indica se a consulta de pesquisa tem de corresponder exatamente ao termo de consulta. Quando definido como true, requer que o SearchRequest.query corresponda totalmente ao queryTerm.value. Quando definido como false, requer que SearchRequest.query contenha queryTerm.value como uma substring.
      • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
      • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • REDIRECT_URI_N: um URI para o qual é redirecionado. Pode ter um comprimento máximo de 2000 carateres. Por exemplo, se o valor do termo de consulta for "apoio técnico", pode definir um redirecionamento para a página de apoio técnico em vez de devolver (ou não devolver) resultados da pesquisa para "apoio técnico". Neste exemplo, o URI de redirecionamento passa a ser "https://www.example.com/support". Para mais informações, consulte redirectAction.

  3. Associe o controlo à configuração de publicação da app através do 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 dos controlos que criou no passo anterior.

Crie e anexe controlos de publicação de promoções

Um controlo de publicação de promoção permite-lhe apresentar um link como um resultado promovido e está disponível para os seguintes tipos de arquivos de dados de pesquisa:

  • Armazenamentos de dados de Websites com pesquisa básica de Websites: para estes armazenamentos de dados, não precisa de anexar um controlo de promoção à configuração de publicação da app. A criação e a ativação de um controlo de promoção ativam o controlo de promoção. Pode ativar ou desativar um controlo de promoção ativando-o ou desativando-o.

  • Armazenamentos de dados com dados estruturados e não estruturados, dados de Websites com indexação avançada de Websites e apps de pesquisa combinadas: para estes armazenamentos de dados, tem de anexar o controlo de promoção à configuração de publicação.

Os controlos de promoção são definidos através de um promoteAction.

Para criar com êxito um controlo de promoção, um dos seguintes campos é obrigatório no pedido de criação:

  • queryTerms: não é possível especificar esta condição se estiver a especificar a condição queryRegex, que se aplica apenas à pesquisa básica de Websites. Para a pesquisa básica de Websites, fullMatch tem de estar definido como true se queryTerms for especificado. Para todas as outras apps de pesquisa, apenas o queryTerms é suportado e o fullMatch pode ser definido como true ou false.
  • queryRegex. Só está disponível para um controlo de publicação de promoção apenas para a pesquisa básica de Websites. Esta condição aplica o controlo quando a consulta corresponde à expressão regular especificada. Não é possível especificar esta condição se estiver a especificar a condição queryTerms.

Ou seja, para a pesquisa básica de Websites, tem de 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.

Siga as instruções abaixo para criar um controlo de publicação de promoções.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Aplicações de IA.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app Vertex AI Search.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • Condition: um objeto opcional que define quando o controlo 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 com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000].
      • activeTimeRange:
        • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
        • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
      • queryRegex: apenas disponível para arquivos de dados com pesquisa básica de Websites. Não é possível usar este campo com o campo queryTerms.
        • VALUE_REGEX: uma expressão regular para fazer corresponder à 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. Esta loja de dados tem de estar anexada ao motor especificado no pedido.
    • DOCUMENT_RESOURCE_PATH: um campo para especificar o caminho do recurso do documento a ser promovido:
      • Para armazenamentos de dados de pesquisa com dados estruturados e não estruturados, tem de fornecer o caminho do recurso do 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 armazenamentos de dados de Websites, este campo tem de ser anulado e, em alternativa, definir o campo URI.
    • TITLE: um campo obrigatório para especificar o título do documento ou da página Web a promover. Este título é apresentado no resultado da pesquisa.
    • URI: um campo obrigatório para especificar o link do URI para onde o resultado da pesquisa direciona o utilizador. Este URI não tem de ser incluído no arquivo de dados.
      • Para armazenamentos de dados de pesquisa com dados estruturados e não estruturados, tem de fornecer o caminho do recurso do documento no campo DOCUMENT_RESOURCE_PATH, o URI no campo URI ou ambos.
      • Para as lojas de dados de Websites, este é um campo obrigatório e tem de o definir.
    • DESCRIPTION: um campo opcional para descrever o documento ou a página Web a promover, que é apresentado no resultado da pesquisa.
    • ENABLED_TRUE|FALSE: um campo booleano opcional para indicar se o controlo de promoção está ativado e associado à app. Este campo aplica-se a arquivos de dados de Websites apenas com a pesquisa básica de Websites. Quando define este campo como false, o controlo de publicação de promoções é desativado e, para que o controlo tenha efeito, tem de o atualizar ativando-o, conforme explicado no passo seguinte. Para mais informações, consulte promoteAction.

  3. Para todas as apps de pesquisa, exceto a pesquisa básica de Websites, anexe o controlo à configuração de publicação da app através do método engines.servingConfigs.patch. A ordem pela qual os promoteControlIds são anexados no pedido seguinte é a ordem pela qual os resultados promovidos são devolvidos.

    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 dos controlos que criou no passo anterior.

  4. Opcional: para a pesquisa básica de Websites, não precisa de anexar o controlo à configuração de publicação da app. No entanto, para a pesquisa básica de Websites, pode ativar ou desativar um controlo de promoção depois de o controlo ser criado, chamando 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 envia um pedido de pesquisa para a app com uma consulta que corresponde à consulta ou à expressão regular da consulta especificada para o controlo de promoção, o link promocional é apresentado na resposta.

Por exemplo, suponha que cria um controlo de promoção com a seguinte configuração num arquivo de dados com pesquisa básica de Websites:

{
 "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, envia o seguinte pedido 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"
}'

Deve receber uma resposta JSON semelhante à seguinte resposta truncada. A resposta contém o campo searchLinkPromotions que contém o link promovido.

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

O que se segue?

  • Para compreender o impacto de um controlo de publicação na qualidade da pesquisa de uma app de pesquisa personalizada, avalie a qualidade da pesquisa. Para mais informações, consulte Avalie a qualidade da pesquisa.