Esta página foi traduzida pela API Cloud Translation.

Configurar controles de exibição

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

Por exemplo, os controles podem otimizar e ocultar resultados, filtrar entradas de resultados, associar consultas umas com as outras como sinônimos ou redirecionar consultas para nos URIs especificados.

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 otimização, têm dependências em repositórios de dados. Se um armazenamento de dados for removido de um app, todos os controles dependentes do armazenamento de dados também serão removidos desse app e ficarão inativos, mas não serão excluídos.

Ao criar um controle, é possível definir uma condição que determina quando o controle for 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 ocorre uma solicitação em um período específico.

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 otimização	Muda a ordem dos resultados retornados	Apps de pesquisa com repositórios de dados que oferecem suporte a um esquema, como armazenamentos de dados que contêm 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 site, estruturados, não estruturados ou de mídia
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 um boostAction é a seguinte:

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

BOOST: um ponto flutuante entre -1 e 1. Quando o valor for negativo, 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 corresponder a todas os requisitos, a otimização será aplicada. 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: Este repositório de dados deve ser anexado ao mecanismo especificado em da 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 um 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 lista. Para conferir a sintaxe de filtragem, consulte Sintaxe da expressão de filtro.

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

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

A sintaxe de um 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 a um URI fornecido.

Os controles de redirecionamento são definidos como um controle com um redirectAction.

Sintaxe para 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 para sua página de suporte técnico em vez de retornar (ou não retornar) resultados da 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 activeTimeRange podem ser especificados em uma única Control.condition. Se nenhum intervalo activeTimeRange for especificado, o campo será ignorada.

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 último horário (inclusive) em que o controle será aplicado. Esse horário deve ser no futuro.

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

Para alterar o comportamento padrão da solicitação de pesquisa, crie um controle de exibição e anexá-lo à configuração de veiculação padrão.

Antes de começar

Para criar controles de veiculação, entre em contato com seu equipe de conta e pedir 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.

Veja 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 seguintes comandos curl 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 ver o curl para criar um controle de filtros.

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 ver o 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 projeto do Google Cloud.
DATA_STORE_ID: o ID exclusivo do repositório de dados.
CONTROL_ID: um identificador exclusivo (em um armazenamento 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 de [1,128].
USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE Se SEARCH_USE_CASE_BROWSE for especificado, então 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 filtros. 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 seguinte comando curl para anexar um controle de otimização a uma exibição para ativar o uso nas solicitações de disponibilizaçã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 curl para um controle de filtros.

Execute o seguinte comando curl para anexar um controle de filtros a uma veiculação para ativar o uso nas solicitações de disponibilizaçã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 seguinte comando curl para anexar um controle de sinônimos a um app para ativar o uso na disponibilização de solicitações:

    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 as IDs de controle que você criou na etapa anterior.

Controle de redirecionamento: clique no curl para 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 as 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

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`