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 o uso do 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:

1. Configurar um app de pesquisa.
2. Gerar credenciais do OAuth para o aplicativo.
3. Consultar o índice.
4. Exibir os resultados da consulta.

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

Configurar um app de pesquisa

Crie pelo menos um app de pesquisa para cada interface de pesquisa. Um app de pesquisa fornece parâmetros padrão, como fontes 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 fontes de dados usadas em uma consulta além das configuradas no app de pesquisa. É possível restringir uma consulta a um subconjunto dessas fontes usando dataSourceRestrictions.

Observação: o Cloud Search atualiza os aplicativos de pesquisa quando você atualiza ou exclui um esquema. Por exemplo, renomear um operador de esquema também o renomeia no app de pesquisa. Se uma atualização for incompatível, a atualização do esquema falhará.

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

Gerar credenciais do OAuth para o aplicativo

Além das etapas em Configurar acesso à API Cloud Search, é necessário gerar credenciais do OAuth para o 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 Google Identity Platform.

Consultar o índice

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

Cada solicitação precisa incluir um texto query 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 title do item e um link para o item original. Também é possível usar snippets e metadados para melhorar a exibição.

Observação: Se você não encontrar resultados, verifique se criou um aplicativo de pesquisa personalizado e ativou a fonte de dados para ele.

Processar resultados complementares

O Cloud Search retorna resultados complementares quando não há correspondências suficientes para uma consulta. O queryInterpretation campo indica isso. Se apenas resultados complementares forem retornados, InterpretationType será REPLACE. Se eles 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 Pesquisa de pessoas. Os resultados estão no structuredResults campo:

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

Observação: Se você definir mais de 20 atributos personalizados, a Pesquisa de pessoas usará apenas 20.

Correspondência de subordinados diretos

A correspondência de subordinados diretos permite que os usuários vejam os subordinados diretos de uma pessoa. A resposta inclui um assistCardProtoHolder com um cardType de RELATED_PEOPLE_ANSWER_CARD.

Desativar otimizações

As otimizações, como resultados complementares, são ativadas por padrão. É possível desativá-las:

• Nível do app de pesquisa: defina force_verbatim_mode como true.
• Nível de consulta: defina enableVerbatimMode como true.

Destacar snippets

O Cloud Search retorna um snippet para texto indexado ou HTML. Se os termos de consulta estiverem presentes, matchRanges 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...

Metadados de exibição

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

Recuperar resultados extras

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

Classificar resultados

Use sortOptions para especificar a ordem:

• operatorName: a propriedade a ser classificada.
• 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 app 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 principais:

• 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 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. Ao solicitar atributos, o Cloud Search calcula os valores mais frequentes dessas propriedades.

Padrão típico: 1. Consulta especificando propriedades de atributo. 1. Renderizar resultados de pesquisa e atributo. 1. O usuário seleciona valores de atributo. 1. Repetir a consulta com um filtro com base nas seleções.

**Observação**: apenas as propriedades de dados estruturados oferecem suporte a atributos.

Resultados de atributos com campos baseados em números inteiros

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

Resultados de atributos por tamanho ou data do documento

Use operadores reservados:

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

Adicionar sugestões

Use a API de sugestões para preenchimento automático com base no histórico de consultas, contatos e conteúdo do documento.