Esta página foi traduzida pela API Cloud Translation.

Configurar controles de exibição para a pesquisa

Os controles de veiculação (também chamados de controles) mudam o comportamento padrão de uma solicitação.

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

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

Sobre os controles de veiculação

Para mudar os resultados de uma solicitação, primeiro crie um controle de veiculação. Em seguida, anexe esse controle a um app. Um controle só afeta as solicitações veiculadas por um app a que ele está anexado. Se um controle não estiver associado a um app, ele não terá efeito.

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

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

queryTerms. O controle é aplicado quando consultas específicas são procuradas.
activeTimeRange. O controle é aplicado quando uma solicitação ocorre em um período especificado.

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

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

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

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

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

Para mais informações, consulte servingConfigs.search na referência da API.

Tipos de controle de veiculação

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

Controle	Descrição	Disponível para
Controle de boost	Muda a ordem de retorno dos resultados	Apps de pesquisa com repositórios de dados que oferecem suporte a um esquema, como repositórios de dados estruturados, sites com dados estruturados, dados não estruturados com metadados ou dados de mídia
Controle de filtro	Remove entradas dos resultados retornados	Apps de pesquisa com repositórios de dados que oferecem suporte a um esquema, como repositórios de dados estruturados, sites com dados estruturados, dados não estruturados com metadados ou dados de mídia
Controle de sinônimos	Associa consultas umas às outras	Pesquisar apps com repositórios de dados de mídia, estruturados, não estruturados ou de sites
Controle de redirecionamento	Redireciona para um URI especificado	Todos os apps de pesquisa

Sobre os controles de veiculação do boost

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

A sintaxe de boostAction é a seguinte:

{
    "boost": "BOOST",
    "filter": "FILTER",
    "dataStore": "DATA_STORE_RESOURCE_PATH"
}

BOOST: um ponto flutuante entre -1 e 1. Quando o valor é negativo, os resultados são rebaixados para aparecer mais tarde nos resultados da pesquisa. Quando o valor é positivo, os resultados são promovidos para aparecer mais cedo nos resultados da pesquisa.
FILTER: uma string que especifica os requisitos que precisam ser atendidos pelo documento. Se o documento atender a todos os requisitos, o aumento será aplicado. Caso contrário, não há mudanças. Se este campo estiver vazio, o aumento será aplicado a todos os documentos na armazenagem de dados. Para a sintaxe de filtragem, consulte Sintaxe da expressão de filtro.
DATA_STORE_RESOURCE_PATH: o caminho de recurso completo do repositório de dados cujos documentos precisam ser impulsionados por esse controle. O formato do caminho completo do recurso é projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Esse repositório de dados precisa ser anexado ao mecanismo especificado na solicitação.

Sobre os controles de veiculação de filtros

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

A sintaxe de filterAction é a seguinte:

{
    "filter": "FILTER"
}

FILTER: uma string que especifica os requisitos que precisam ser atendidos pelo documento. Se o documento atender a todos os requisitos, o resultado será incluído na lista de resultados. Caso contrário, o resultado é removido da lista de resultados. Para a sintaxe de filtragem, consulte Sintaxe da expressão de filtro.

Sobre os controles de veiculação de sinônimos

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

A sintaxe de synonymsAction é a seguinte:

{
    "synonyms": "SYNONYMS"
}

SYNONYMS: strings que serão associadas entre si, tornando mais provável que cada uma mostre resultados semelhantes. É necessário especificar pelo menos duas strings e é possível especificar até 100 strings. As strings precisam ser UTF-8 e minúsculas. Não são permitidas strings duplicadas.

Exemplo:

{
    "synonyms": ["pixel", "android phone", "google phone"]
}

Sobre os 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.

Sintaxe de redirectAction:

{
    "redirect_uri": "REDIRECT_URI"
}

REDIRECT_URI: um URI de, no máximo, 2.000 caracteres.

Por exemplo, se o valor do termo de consulta for "suporte", você poderá definir um redirecionamento para sua página de suporte técnico em vez de retornar (ou não retornar) resultados de pesquisa para "suporte".

{
    "redirect_uri": ["https://www.example.com/support"]
}

Sobre a condição `queryTerms`

queryTerms é opcional. Use-o se quiser que um controle de veiculação seja usado quando consultas específicas forem pesquisadas. Quando a condição queryTerms é usada, o controle é aplicado quando o valor de queryTerms corresponde a um termo em SearchRequest.query.

Os termos da consulta só podem ser usados quando Control.searchUseCase está definido como SOLUTION_TYPE_SEARCH.

Até 10 queryTerms diferentes podem ser especificados em um único Control.condition. Se nenhum termo de consulta for especificado, o campo será ignorado.

A sintaxe de um único queryTerm é a seguinte:

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}

VALUE_1: uma string UTF-8 minúscula com comprimento [1, 5000]. Se FULL_MATCH_1 for true, ele poderá ter no máximo três termos separados por espaços.
FULL_MATCH_1: um booleano. Quando definido como true, ele exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, ele exige que SearchRequest.query contenha queryTerm.value como uma substring.

Sobre a condição `activeTimeRange`

activeTimeRange é opcional. Ele verifica se o horário em que uma solicitação foi recebida está entre activeTimeRange.startTime e activeTimeRange.endTime.

Até 10 intervalos de activeTimeRange podem ser especificados em uma única Control.condition. Se nenhum intervalo de activeTimeRange for especificado, o campo será ignorado.

A sintaxe de um único activeTimeRange é a seguinte:

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]

START_TIMESTAMP_1: define o primeiro horário (inclusive) em que o controle será aplicado. Os carimbos de data/hora estão no formato UTC "Zulu" RFC 3339, com resolução de nanossegundos e até nove dígitos fracionários, por exemplo, "2023-10-02T15:01:23Z".
END_TIMESTAMP_1: define o horário mais recente (inclusive) em que o controle será aplicado. O horário precisa estar no futuro.

Instruções da API: mudar o comportamento padrão de solicitações de pesquisa com controles de veiculação

Para mudar o comportamento padrão da solicitação de pesquisa, crie um controle de exibição e anexe-o à configuração de exibição padrão.

Antes de começar

Se você quiser criar controles de veiculação, entre em contato com a equipe de contas do Google e peça para ser adicionado à lista de permissões para controles de veiculação.

Criar um controle de exibição

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

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

Encontre o ID do repositório de dados. Se você já tiver o ID do repositório de dados, pule para a próxima etapa.
1. No console do Google Cloud, acesse a página Criador de agentes e, no menu de navegação, clique em Repositórios de dados.
  
  Acesse a página "Repositórios de dados"
2. Clique no nome do seu repositório de dados.
3. Na página Dados do seu repositório de dados, encontre o ID do repositório.

Escolha o tipo de condição e os valores de campo para o controle.

Confira a seguir um exemplo truncado de uma condição:

{
  "queryTerms": [
      {
        "value": "VALUE_1",
        "fullMatch": FULL_MATCH_1
      },
      {
        "value": "VALUE_2",
        "fullMatch": FULL_MATCH_2
      },
    ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP_1",
      "endTime": "END_TIMESTAMP_1"
    },
    {
      "startTime": "START_TIMESTAMP_2",
      "endTime": "END_TIMESTAMP_2"
    },
  ]
}

Execute os comandos curl a seguir para criar os controles.

Boost control: clique para conferir o comando curl para criar um boost control.

Execute o seguinte comando curl:

    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/dataStores/DATA_STORE_ID/controls?CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "boostAction": "BOOST_ACTION",
    }'

Controle de filtro: clique para conferir o comando curl para criar um controle de filtro.

Execute o seguinte comando curl:

    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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "filterAction": "FILTER_ACTION",
    }'

Controle de sinônimos: clique para conferir o comando curl para criar um controle de sinônimos.

Execute o seguinte comando curl:

    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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "synonymsAction": "SYNONYMS_ACTION",
    }'

Controle de redirecionamento: clique para conferir o comando curl para criar um controle de redirecionamento.

Execute o seguinte comando curl:

    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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "redirectAction": "REDIRECT_ACTION",
    }'

PROJECT_ID: o número ou ID do projeto do Google Cloud.
DATA_STORE_ID: o ID exclusivo do repositório de dados.
CONTROL_ID: um identificador exclusivo (em um repositório de dados) para o controle. O ID pode conter letras minúsculas, dígitos, hifens e sublinhados.
DISPLAY_NAME: o nome legível para o controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string UTF-8 com comprimento [1,128].
USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
CONDITION: (opcional) define quando o controle precisa ser aplicado.
BOOST_ACTION: usado para definir um controle de aumento. Consulte a referência da API boostAction.
FILTER_ACTION: usado para definir um controle de filtro. Consulte a referência da API filterAction.
SYNONYMS_ACTION: usado para definir um controle de sinônimos. Consulte a referência da API synonymsAction.
REDIRECT_ACTION: usado para especificar um URI de redirecionamento. Consulte a referência da API redirectAction.

Anexe o controle ao app.

Controle de aumento: clique para conferir o comando curl de um controle de aumento.

Execute o comando curl a seguir para anexar um controle de boost a uma configuração de veiculação e permitir o uso em solicitações de veiculação:

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
    -d '{
      "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2" … ]
    }'

BOOST_ID_1 e BOOST_ID_2: representam os IDs de controle que você criou na etapa anterior.

Controle de filtro: clique no comando curl para um controle de filtro.

Execute o comando curl a seguir para anexar um controle de filtro a uma configuração de veiculação e permitir o uso em solicitações de veiculação:

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
    -d '{
      "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2" … ]
    }'

FILTER_ID_1 e FILTER_ID_2: representam os IDs de controle que você criou na etapa anterior.

Controle de sinônimos: clique para ver o comando curl de um controle de sinônimos.

Execute o comando curl a seguir para anexar um controle de sinônimos a um app e ativar o uso em solicitações de veiculação:

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
    -d '{
     "synonymsControlIds": ["SYNONYM_ID_1", "SYNONYM_ID_2" … ]
    }'

SYNONYM_ID_1 e SYNONYM_ID_2: representam os IDs de controle que você criou na etapa anterior.

Controle de redirecionamento: clique para conferir o comando curl de um controle de redirecionamento.

Execute o comando curl a seguir para anexar um controle de redirecionamento a um app e ativar o uso em solicitações de veiculação:

    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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
    -d '{
      "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2" … ]
    }'

REDIRECT_ID_1 e REDIRECT_ID_2: representam os IDs de controle que você criou na etapa anterior.

A seguir

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

Configurar controles de exibição para a pesquisa

Sobre os controles de veiculação

Tipos de controle de veiculação

Sobre os controles de veiculação do boost

Sobre os controles de veiculação de filtros

Sobre os controles de veiculação de sinônimos

Sobre os controles de veiculação de redirecionamento

Sobre a condição queryTerms

Sobre a condição activeTimeRange

Instruções da API: mudar o comportamento padrão de solicitações de pesquisa com controles de veiculação

Antes de começar

Criar um controle de exibição

A seguir

Sobre a condição `queryTerms`

Sobre a condição `activeTimeRange`