Filtrar a pesquisa de sites

Esta página explica como filtrar consultas de pesquisa para um app de pesquisa com dados de sites.

Antes de começar

Crie um app e um repositório de dados e ingira dados de sites no repositório. Para mais informações, consulte Criar um app de pesquisa.

Sobre expressões de filtro

Use expressões de filtro para criar filtros de pesquisa de sites. A forma como você cria os filtros varia dependendo se a indexação avançada de sites está ativada. Consulte uma das seções a seguir, dependendo se você tem a pesquisa básica de sites ou a indexação avançada de sites:

• Expressões de filtro para pesquisa básica de sites

• Expressões de filtro para indexação avançada de sites

Expressões de filtro para pesquisa básica de sites

Esta seção explica o comportamento da expressão de filtro com a pesquisa básica de sites (a indexação avançada de sites está desativada).

Sintaxe para pesquisa básica de sites

O formulário Backus–Naur estendido a seguir resume a sintaxe da expressão de filtro para criar um filtro de pesquisa de sites quando você tem a pesquisa básica de sites. As aspas duplas após os dois pontos em um filtro são aplicadas de forma estrita.

    # A single expression or multiple expressions that are joined by "AND".
  filter = expression, { "AND", expression };
  expression =
    # A simple expression applying to a text url string.
    | filter_key, ":", \"text_value\"
  filter_key = (cr | highRange | lowRange | fileType | lr | rights | siteSearch);
  text_value = string value to filter on;

Campos disponíveis para pesquisa básica de sites

Estes são os campos disponíveis para filtrar a pesquisa de sites quando você tem a pesquisa básica de sites:

• cr (string): restringe os resultados da pesquisa a documentos de um país específico. Para uma lista de valores aceitos, consulte Valores da coleção de países.

• highRange (string): especifica o limite superior do intervalo de pesquisa. Se um documento contiver um número, ele precisará ser igual ou menor que o valor de highRange para que o documento seja incluído na resposta. Especifique highRange e lowRange para criar uma consulta de pesquisa dentro do intervalo desses parâmetros.

• lowRange (string): especifica o limite inferior do intervalo de pesquisa. Se um documento contiver um número, ele precisará ser igual ou maior que o valor de lowRange para que o documento seja incluído na resposta. Especifique lowRange e highRange para criar uma consulta de pesquisa dentro do intervalo desses parâmetros.

• fileType (string): restringe os resultados da pesquisa a documentos com uma extensão especificada. Para uma lista de tipos de arquivo aceitos, consulte Tipos de arquivo indexáveis pelo Google.

• lr (string): restringe os resultados da pesquisa a documentos escritos em um idioma especificado. Para uma lista de idiomas aceitos, consulte Parâmetros de consulta (lr).

• rights (string): filtra os resultados da pesquisa com base no licenciamento. Para valores aceitos, consulte Parâmetros de consulta (rights).

• siteSearch (string): especifica um padrão do URL para as páginas da Web que sua consulta precisa pesquisar.

Exemplos para pesquisa básica de sites

Confira alguns exemplos de filtros para pesquisa básica de sites:

• {"filter": "cr:\"countryUS\" AND siteSearch:\"https://example.com/example_domain\""}

  Filtra documentos que são: (1) dos EUA e (2) no domínio https://example.com/example_domain.

• {"filter": "fileType:\".pdf\" AND lr:\"lang_en\""}

  Filtra documentos que são: (1) arquivos PDF e (2) em inglês.

• {"filter": "rights:\"cc_publicdomain\""}

  Filtra documentos que estão em domínio público.

Expressões de filtro com indexação avançada de sites

Esta seção explica o comportamento da expressão de filtro com a indexação avançada de sites (a indexação avançada de sites está ativada).

Observação: outra abordagem para usar filtros com a indexação avançada de sites é aplicar a filtragem de relevância no nível do documento. Para informações sobre esse recurso de visualização, consulte Filtrar pesquisas por relevância no nível do documento.

Campos disponíveis para indexação avançada de sites

Quando você tem a indexação avançada de sites, é possível filtrar a pesquisa de sites usando estes campos:

• siteSearch (string): um padrão do URL para as páginas da Web que sua consulta precisa pesquisar.
• Nomes de tags meta e nomes de atributos PageMap: dados estruturados das suas páginas da Web que podem ser adicionados ao esquema do repositório de dados para tornar os campos pesquisáveis, recuperáveis e indexáveis. Para mais informações, consulte Usar dados estruturados para indexação avançada de sites.

Sintaxe para indexação avançada de sites

O formulário Backus–Naur estendido a seguir resume a sintaxe da expressão de filtro para criar um filtro de pesquisa de sites quando você tem a indexação avançada de sites. As aspas duplas após os dois pontos em um filtro são aplicadas de forma estrita.

Ao filtrar por siteSearch, a sintaxe EBNF é:

    # A single expression or multiple expressions that are joined by "OR".
  filter = expression, { "OR", expression };
    # Expressions can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
    # A simple expression applying to a text url string.
    | filter_key, ":", \"url_string\"
  filter_key = siteSearch;
  url_string = double quoted string representing a URL;

Ao filtrar por nomes de tags meta e nomes de atributos PageMap, a sintaxe EBNF é:

    # A single expression or multiple expressions that are joined by "OR".
  filter = expression, { "OR", expression };
    # Expressions can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
   # Function "ANY" returns true if the field exactly matches any of the literals.
    | text_field, ":", "ANY", "(", literal, { ",", literal }, ")"
  literal = double quoted string;
  # text_field corresponds to the meta tag or PageMap Attribute name, for example, category
  text_field = text field;

Exemplos para indexação avançada de sites

Confira alguns exemplos de filtros para indexação avançada de sites com siteSearch:

• {"filter": "siteSearch:\"https://example.com/example_domain\""}

  Filtra documentos que estão no domínio https://example.com/example_domain. Por exemplo, https://example.com/example_domain/index.html.

• {"filter": "siteSearch:\"https://example.com/subdomains/*\""}

  Filtra documentos que estão em qualquer domínio correspondente a https://example.com/subdomains/*. Por exemplo, https://example.com/subdomains/example_subdomain_page.

• {"filter": "siteSearch:\"https://altostrat.com/subdomain/pages/*\" OR siteSearch:\"http://cymbalgroup.com/pages/*\""}

  Filtra documentos que estão em qualquer domínio correspondente ao primeiro ou segundo padrão do URL. Por exemplo, https://altostrat.com/subdomain/pages/title_page, https://cymbalgroup.com/subdomain/pages/title_page ou https://altostrat.com/subdomain/pages/INFO.

Confira alguns exemplos de filtragem de nomes de atributos meta ou PageMap:

• {"filter": "product: ANY(\"networking\",\"compute\")"}

  Filtra documentos que contêm a tag meta ou o atributo PageMap chamado product, com o valor networking ou compute.

• {"filter": "NOT product: ANY(\"storage\")"}

  Filtra documentos que não contêm a tag meta ou o nome do atributo PageMap product com o valor storage.

• {"filter": "dateModified>= \"2025-07-31T00:00:00Z\")"}

  Filtra documentos que têm a data da última modificação como 31 de julho de 2025. O formato precisa estar em conformidade com o formato no esquema do documento. Para mais informações, consulte DATETIME.

Para mais informações sobre meta nomes de tags e nomes de atributos PageMap usados para indexação, consulte Exemplo de caso de uso para tags meta e Exemplo de caso de uso para PageMaps.

Filtrar uma pesquisa de sites

Para filtrar uma pesquisa de sites, siga estas etapas:

Observação: é possível pesquisar em um app usando o engines.servingConfigs.search método e em um repositório de dados usando o dataStores.servingConfigs.search método. Para o procedimento a seguir, o Google recomenda pesquisar usando o método engines.servingConfigs.search.

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

   1. No Google Cloud console, 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. Para filtrar uma pesquisa de sites, use o filter campo com o engines.servingConfigs.search método.

   Termo-chave: na Pesquisa do agente, o termo app pode ser usado de forma intercambiável com o termo mecanismo no contexto das APIs.

   curl -X POST -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
   -d '{
    "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search",
   "query": "QUERY",
   "filter": "FILTER"
   }'
   

   Substitua:

   • PROJECT_ID: ID do projeto.
   • APP_ID: ID do app.
   • QUERY: o texto da consulta a ser pesquisado.

   • FILTER: um campo de texto para filtrar a pesquisa usando uma expressão de filtro. O valor padrão é uma string vazia.

     Para informações sobre como criar um filtro para pesquisa básica de sites, consulte Expressões de filtro com pesquisa básica de sites.

     Para informações sobre como criar um filtro para indexação avançada de sites, consulte Expressões de filtro com indexação avançada de sites.

   Solução de problemas: se você usar um operador OR na expressão de filtro e receber a seguinte mensagem de erro, a indexação avançada de sites não estará ativada para seu app:
   Parsing filter failed with error: Unsupported expression type in filter. Supported expression types are: (1) expression without logical joiner. (2) expressions joint by AND..