Criar uma interface de pesquisa com a API Query

A API Query fornece métodos de pesquisa e sugestão para criar uma interface de pesquisa ou incorporar resultados em um aplicativo.

Para aplicativos da Web com requisitos mínimos, considere usar o widget de pesquisa. Consulte Criar uma interface de pesquisa com o widget de pesquisa.

Criar uma interface de pesquisa

A criação de uma interface de pesquisa mínima requer várias etapas:

Configure um app de pesquisa.
Gere credenciais do OAuth para o aplicativo.
Consulte o índice.
Exiba os resultados da consulta.

É possível melhorar a interface com recursos como paginação, classificação, filtragem, atributos e preenchimento automático.

Configurar um aplicativo de pesquisa

Crie pelo menos um aplicativo de pesquisa para cada interface de pesquisa. Um aplicativo de pesquisa fornece parâmetros padrão, como origens de dados, ordem de classificação, filtros e atributos. É possível substituir esses parâmetros usando a API Query.

Não é possível aumentar o número de origens de dados usadas em uma consulta além das configuradas no aplicativo de pesquisa. É possível restringir uma consulta a um subconjunto dessas fontes usando dataSourceRestrictions.

Para mais informações, consulte Personalizar a experiência de pesquisa.

Gerar credenciais do OAuth para o aplicativo

Além das etapas em Configurar o acesso à API Cloud Search, é necessário gerar credenciais do OAuth para seu aplicativo da Web.

Use as credenciais para solicitar autorização em nome do usuário. Use o escopo https://www.googleapis.com/auth/cloud_search.query.

Para mais informações sobre as opções do OAuth, consulte o Google Identity Platform.

Consultar o índice

Use o método search para pesquisar no índice.

Cada solicitação precisa incluir um query de texto e um searchApplicationId.

Este exemplo consulta uma fonte de dados de filmes:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  }
}

Exibir resultados da consulta

As interfaces de pesquisa precisam mostrar o item title e um link para o item original. Você também pode usar snippets e metadados para melhorar a exibição.

Processar resultados complementares

O Cloud Search retorna resultados complementares quando há correspondências insuficientes para uma consulta. O campo queryInterpretation indica isso. Se apenas resultados complementares forem retornados, InterpretationType será REPLACE. Se forem combinados, será BLEND.

Ao retornar resultados complementares, considere informar o usuário. Para um REPLACE, você pode dizer: "Sua pesquisa não encontrou resultados. Mostrando resultados para consultas semelhantes."

Processar resultados de pessoas

O Cloud Search retorna documentos relacionados a pessoas e informações de funcionários usando o recurso de pesquisa de pessoas. Os resultados estão no campo structuredResults:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

Correspondência de subordinados diretos

Com a correspondência de subordinados diretos, os usuários podem ver os subordinados diretos de uma pessoa. A resposta inclui um assistCardProtoHolder com um cardType de RELATED_PEOPLE_ANSWER_CARD.

Desativar otimizações

Otimizações como resultados complementares são ativadas por padrão. Você pode desativá-las:

Nível do aplicativo de pesquisa: defina force_verbatim_mode como true.
Nível da consulta: defina enableVerbatimMode como true.

Destacar snippets

O Cloud Search retorna um snippet para texto indexado ou HTML. Se houver termos de consulta, matchRanges vai identificar a localização deles. Use esses intervalos para destacar o texto.

function highlightSnippet(snippet) {
  let text = snippet.snippet;
  let formattedText = text;
  if (snippet.matchRanges) {
    let parts = [];
    let index = 0;
    for (let match of snippet.matchRanges) {
      let start = match.start || 0; // Default to 0 if omitted
      let end = match.end;
      if (index < start) { // Include any leading text before/between ranges
        parts.push(text.slice(index, start));
      }
      parts.push('<span class="highlight">');
      parts.push(text.slice(start, end));
      parts.push('</span>');
      index = end;
    }
    parts.push(text.slice(index)); // Include any trailing text after last range
    formattedText = parts.join('');
  }
  return formattedText;
}

Dado o snippet:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

A string HTML resultante será:

This is an <span class="highlight">example</span> snippet...

Exibir metadados

Use o campo metadata para informações como createTime, updateTime e dados estruturados. Use displayOptions para mostrar dados estruturados.

Recuperar resultados extras

Para recuperar mais resultados, defina o campo start como o deslocamento selecionado. Ajuste o tamanho da página com pageSize. Use resultCount para mostrar o total de itens ou as contagens estimadas.

Classificar resultados

Use sortOptions para especificar a ordem:

operatorName: a propriedade para classificação.
sortOrder: ASCENDING ou DESCENDING.

A relevância é a chave de classificação padrão e secundária.

Adicionar filtros

Restrinja os resultados com filtros no aplicativo de pesquisa ou na solicitação. Se ambos especificarem filtros para uma origem, os dois precisarão ser avaliados como verdadeiros.

Aplique filtros em dataSourceRestrictions.filterOptions[]. Tipos de filtro principal:

Filtros de objeto: restringem as correspondências a um tipo específico.
Filtros de valor: restringem as correspondências com base em um operador e um valor.

Os filtros compostos combinam vários filtros de valores.

Refinar resultados com atributos

Os atributos ajudam os usuários a refinar consultas de forma interativa. Quando você solicita atributos, o Cloud Search calcula os valores mais frequentes dessas propriedades.

Padrão típico: 1. Consulta que especifica propriedades de facets. 1. Renderize os resultados de pesquisa e atributo. 1. O usuário seleciona valores de atributo. 1. Repita a consulta com um filtro baseado nas seleções.

Marque uma propriedade de número inteiro como facetada para refinar os resultados por intervalos (por exemplo, "100-200" páginas). Defina isFacetable como true e defina opções de agrupamento padrão no esquema.

Use operadores reservados:

itemsize: para tamanho do arquivo em bytes.
createddatetimestamp: para data de criação.
lastmodified: para data de modificação.

Adicionar sugestões

Use a API suggest para o preenchimento automático com base no histórico de consultas, contatos e conteúdo de documentos.

Criar uma interface de pesquisa com a API Query