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 de pesquisa em um aplicativo.

Para aplicativos da Web com requisitos mínimos, considere o uso do widget da Pesquisa. Para mais informações, 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 aplicativo de pesquisa
  2. Gerar credenciais do OAuth para o aplicativo
  3. Consultar o índice
  4. Exibir os resultados de consulta

É possível melhorar ainda mais a interface de pesquisa com recursos como paginação, classificação, filtragem, atributos e sugestão automática.

Configurar um aplicativo de pesquisa

Crie pelo menos um aplicativo de pesquisa para associar a cada interface de pesquisa criada. Um aplicativo de pesquisa fornece os parâmetros padrão para uma consulta, como as origens de dados a serem incluídas, a ordem de classificação, os filtros e os atributos a serem solicitados. Se necessário, é possível substituir esses parâmetros usando a API Query.

Para mais informações sobre aplicativos de pesquisa, consulte Criar uma experiência de pesquisa personalizada.

Gerar credenciais do OAuth para o aplicativo

Além das etapas em Configurar acesso à API REST do Google Cloud Search, é necessário gerar credenciais do OAuth para o aplicativo da Web. O tipo de credenciais criadas depende do contexto em que a API é usada.

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

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

Consultar o índice

Use o método search para realizar pesquisas no índice.

Cada solicitação precisa incluir duas informações: uma query de texto para corresponder aos itens e um searchApplicationId que identifica o ID do aplicativo de pesquisa a ser usado.

O snippet a seguir mostra uma consulta à origem de dados do filme Titanic:

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

Exibir resultados da consulta

Espera-se pelo menos que as interfaces de pesquisa exibam o title do item, bem como um link para o item original. É possível aproveitar informações extras presentes nos resultados de pesquisa, como o snippet e os metadados, para melhorar ainda mais a exibição dos resultados de pesquisa.

Destacar snippets

Para itens retornados contendo texto indexado ou conteúdo HTML, será retornado um snippet do conteúdo. Esse conteúdo ajuda os usuários a determinar a relevância do item retornado.

Se houver termos de consulta no snippet, um ou mais intervalos de correspondência que identificam o local dos termos também serão retornados.

Use o matchRanges para destacar o texto correspondente quando estiver renderizando os resultados. O exemplo de javascript a seguir converte o snippet em marcação HTML com cada intervalo de correspondência agrupado em uma tag <span>.

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 exibir mais informações sobre o item retornado que podem ser relevantes para os usuários. O campo metadata inclui o createTime e o updateTime do item, bem como quaisquer dados estruturados retornáveis associados ao item.

Para exibir os dados estruturados, use o campo displayOptions. O campo displayOptions contém o rótulo de exibição para o tipo de objeto e um conjunto de metalines. Cada metaline é uma matriz de rótulos de exibição e pares de valores, conforme configurado no esquema.

Recuperar resultados extras

Para recuperar resultados extras, defina o campo start na solicitação para o deslocamento desejado. É possível ajustar o tamanho de cada página com o campo pageSize.

Para exibir o número de itens retornados ou para exibir controles de paginação para ver os itens retornados, use o campo resultCount. Dependendo do tamanho do conjunto de resultados, será fornecido o valor real ou um valor estimado.

Classificar resultados

Use o campo sortOptions para especificar a ordem de itens retornados. O valor sortOptions é um objeto com dois campos:

  • operatorName: um operador da propriedade de dados estruturados para classificação. Para propriedades com vários operadores, só é possível fazer a classificação usando o operador principal de igualdade.
  • sortOrder: a direção da classificação, seja ASCENDING ou DESCENDING.

A relevância também é usada como chave de classificação secundária. Se nenhuma ordem de classificação for especificada em uma consulta, os resultados serão classificados apenas por relevância.

"sortOptions": {
      "operatorName": "priority",
      "sortOrder": "DESCENDING"
    }
    

Adicionar filtros

Além de expressões de consulta, é possível aplicar filtros para restringir ainda mais os resultados. É possível também especificar filtros no aplicativo de pesquisa e na solicitação de pesquisa.

Para adicionar filtros em um aplicativo de pesquisa ou uma solicitação, adicione o filtro no campo dataSourceRestrictions.filterOptions[].

Existem duas maneiras principais de filtrar ainda mais uma origem de dados:

  • Filtros de objeto, por meio da propriedade filterOptions[].objectType: restringem os itens de correspondência ao tipo especificado, conforme definido em um esquema personalizado.
  • Filtros de valor: restringem os itens de correspondência com base em um operador de consulta e no valor fornecido.

Os filtros compostos permitem combinar vários filtros de valores em expressões lógicas para consultas mais complexas.

No exemplo do esquema de filme, é possível aplicar uma restrição de idade com base no usuário atual e restringir os filmes disponíveis com base na classificação da MPAA.

{
      "query": "adventure",
      "requestOptions": {
        "searchApplicationId": "<search_app_id>"
      },
      "dataSourceRestrictions": [
        {
          "source": {
            "name": "datasources/<data_source_id>"
          },
          "filterOptions": [
            {
              "objectType": "movie",
              "filter": {
                "compositeFilter": {
                  "logicOperator": "AND"
                  "subFilters": [
                    {
                      "compositeFilter": {
                      "logicOperator": "OR"
                      "subFilters": [
                        {
                          "valueFilter": {
                            "operatorName": "rated",
                            "value": {
                              "stringValue": "G"
                            }
                          }
                        },
                        {
                          "valueFilter": {
                            "operatorName": "rated",
                            "value": {
                              "stringValue": "PG"
                            }
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            }
          ]
        }
      ]
    }
    

Refinar resultados com atributos

Atributos são propriedades indexadas que representam categorias para refinar os resultados da pesquisa. Use atributos para ajudar os usuários a refinar consultas de forma interativa e encontrar itens relevantes com mais rapidez.

Os atributos podem ser definidos em seu aplicativo de pesquisa e substituídos pelas configurações na consulta.

Ao solicitar atributos, o Cloud Search calcula os valores mais frequentes das propriedades solicitadas entre os itens de correspondência. Esses valores são retornados na resposta. Use esses valores para criar filtros que restrinjam os resultados em consultas subsequentes.

O padrão típico de interação com atributos é o seguinte:

  1. Faça uma consulta inicial especificando quais propriedades serão incluídas nos resultados do atributo.
  2. Renderize os resultados de pesquisa e atributo.
  3. O usuário seleciona um ou mais valores de atributo para refinar os resultados.
  4. Repita a consulta com um filtro baseado nos valores selecionados.

Por exemplo, para ativar o refinamento de consultas a filmes por ano e pela classificação da MPAA, inclua a propriedade facetOptions na consulta.

"facetOptions": [
      {
        "sourceName": "datasources/<data_source_id>",
        "operatorName": "year"
      },
      {
        "sourceName": "datasources/<data_source_id>",
        "operatorName": "rated"
      }
    ]
    

Como interpretar intervalos de atributo

A propriedade facetResults na resposta inclui uma entrada para cada propriedade solicitada. Para cada propriedade, é fornecida uma lista de valores ou intervalos chamados de buckets. Os valores mais frequentes são exibidos primeiro.

Quando um usuário selecionar um ou mais valores a serem filtrados, crie uma nova consulta com os filtros selecionados e consulte a API novamente.

Adicionar sugestões

Use a API de sugestões para que o preenchimento automático seja usado em consultas baseadas no histórico de consultas pessoais do usuário, bem como nos contatos e no corpus de documentos.

Por exemplo, a chamada a seguir fornece sugestões para a frase parcial jo.

{
      "query": "jo",
      "requestOptions": {
        "searchApplicationId": "<search_app_id>",
        "peoplePhotoOptions": {
          "peoplePhotoUrlSizeInPx": 32
        },
        "timeZone": "America/Denver"
      }
    }
    

É possível exibir as sugestões resultantes conforme apropriado para o aplicativo.