Crie uma interface de pesquisa com a API de consulta

A API de consulta 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 usar o widget de pesquisa. Para obter mais informações, consulte Criar uma interface de pesquisa com o widget de pesquisa

Construir uma interface de pesquisa

Construir uma interface de pesquisa mínima requer várias etapas:

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

Você pode aprimorar ainda mais a interface de pesquisa com recursos como paginação, classificação, filtragem, facetas e sugestão automática.

Configurar um aplicativo de pesquisa

Você deve criar 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 fontes de dados a serem usadas, a ordem de classificação, os filtros e as facetas a serem solicitadas. Se necessário, você pode substituir esses parâmetros usando a API de consulta.

Observação: embora você possa substituir as configurações do aplicativo de pesquisa em chamadas para query , não é possível aumentar o número de fontes de dados usadas durante uma consulta além daquelas configuradas no aplicativo de pesquisa. Você pode restringir a consulta a um subconjunto das fontes de dados configuradas definindo dataSourceRestrictions na chamada da consulta.

Observação: quando um esquema é atualizado ou excluído, o aplicativo de pesquisa também é atualizado. Por exemplo, se um operador de esquema for renomeado, ele também será renomeado na configuração do aplicativo de pesquisa. Se a atualização do esquema for incompatível com o aplicativo de pesquisa e não for possível atualizar o aplicativo de pesquisa, a atualização do esquema falhará e um erro será enviado na resposta de atualização.

Para obter mais informações sobre aplicativos de pesquisa, consulte Personalizar a experiência de pesquisa no Cloud Search .

Gerar credenciais OAuth para o aplicativo

Além das etapas em Configurar o acesso à API REST do Google Cloud Search , você também deve gerar credenciais OAuth para o aplicativo da web. O tipo de credenciais que você cria 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 ao solicitar autorização.

Para obter informações adicionais sobre opções de OAuth e bibliotecas de cliente, consulte [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.

Consultar o índice

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

Cada solicitação deve incluir duas informações: uma query de texto para correspondência de itens e um searchApplicationId identificando o ID para o aplicativo de pesquisa usar.

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

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

Exibir resultados da consulta

No mínimo, espera-se que as interfaces de pesquisa exibam o title do item, bem como um link para o item original. Você pode aprimorar ainda mais a exibição dos resultados da pesquisa aproveitando as informações adicionais presentes nos resultados da pesquisa, como o snippet e os metadados.

Observação: se você não vir os resultados de uma fonte de dados, verifique se criou um aplicativo de pesquisa personalizado e se a fonte de dados está habilitada para esse aplicativo de pesquisa. Para obter mais informações sobre como criar aplicativos de pesquisa, consulte Personalizar a experiência de pesquisa no Cloud Search .

Gerenciar resultados suplementares

Por padrão, o Cloud Search retorna resultados complementares quando não há resultados suficientes para a consulta do usuário. O campo queryInterpretation na resposta indica quando os resultados complementares são retornados. Se apenas resultados complementares forem retornados, InterpretationType será definido como REPLACE . Se alguns resultados da consulta original forem retornados junto com os resultados complementares, InterpretationType será definido como BLEND . Em ambos os casos QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY .

Quando alguns resultados complementares forem retornados, considere fornecer texto para indicar que os resultados complementares foram retornados. Por exemplo, no caso de um REPLACE , você pode exibir a string "Sua pesquisa para sua consulta original não corresponde a nenhum resultado. Mostrando resultados para consultas semelhantes".

No caso de um BLEND , você pode exibir a string "Sua pesquisa para sua consulta original não correspondeu a resultados suficientes. Incluindo resultados para consultas semelhantes."

Lidar com resultados de pessoas

O Cloud Search retorna dois tipos de "resultados de pessoas": documentos relacionados a uma pessoa cujo nome é usado na consulta e informações de funcionários de uma pessoa cujo nome é usado em uma consulta. O último tipo de resultado é uma função do recurso People Search do Cloud Search e os resultados dessa consulta podem ser encontrados no structuredResults de uma resposta da API de consulta:

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

Observação: se mais de 20 atributos personalizados forem definidos no domínio do cliente, apenas 20 deles serão usados ​​para a Pesquisa de pessoas.

Desativar otimizações, incluindo resultados complementares

Por padrão, as otimizações, como resultados complementares, são habilitadas. No entanto, você pode desativar todas as otimizações ou apenas resultados complementares no aplicativo de pesquisa e no nível de consulta:

• Para desativar todas as otimizações no nível do aplicativo de pesquisa, incluindo resultados complementares, sinônimos e correções ortográficas, defina QueryInterpretationConfig.force_verbatim_mode como true nos aplicativos de pesquisa.

• Para desativar todas as otimizações no nível da consulta de pesquisa, incluindo resultados complementares, sinônimos e correções ortográficas, defina QueryInterpretationOptions.enableVerbatimMode como true na consulta de pesquisa.

• Para desativar os resultados complementares no nível do aplicativo de pesquisa, defina QueryInterpretationOptions.forceDisableSupplementalResults como true na consulta de pesquisa.

• Para desativar os resultados complementares no nível da consulta de pesquisa, defina QueryInterpretationOptions.disableSupplementalResults como true na consulta de pesquisa.

Destaque snippets

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

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

Use matchRanges para destacar o texto correspondente ao renderizar os resultados. O exemplo de javascript a seguir converte o snippet em marcação HTML com cada intervalo correspondente envolvido 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 trecho:

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

A string HTML resultante é:

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

Exibir metadados

Use o campo de metadata para exibir informações adicionais sobre o item devolvido que podem ser relevantes para os usuários. O campo de metadata inclui createTime e 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 adicionais

Para recuperar resultados adicionais, defina o campo start na solicitação para o deslocamento desejado. Você pode ajustar o tamanho de cada página com o campo pageSize .

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

Classificar resultados

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

• operatorName — um operador para classificar a propriedade de dados estruturados. Para propriedades com vários operadores, você só pode classificar usando o operador de igualdade principal.
• sortOrder — a direção para classificar, 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 das expressões de consulta, você pode restringir ainda mais os resultados aplicando filtros . Você pode especificar filtros tanto no aplicativo de pesquisa quanto na solicitação de pesquisa.

Observação: se os filtros de uma fonte de dados estiverem presentes no aplicativo de pesquisa e na solicitação de pesquisa, ambos os filtros deverão ser avaliados como verdadeiros para que um item seja retornado.

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

Há duas maneiras principais de filtrar ainda mais uma fonte de dados:

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

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

No exemplo de esquema de filme, você pode aplicar uma restrição de idade com base no usuário atual e restringir os filmes disponíveis com base na classificação 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 facetas

As facetas são propriedades indexadas que representam categorias para refinar os resultados da pesquisa. Use facetas para ajudar os usuários a refinar interativamente suas consultas e encontrar itens relevantes mais rapidamente.

As facetas podem ser definidas em seu aplicativo de pesquisa . e substituído pelas configurações em sua consulta.

Ao solicitar atributos, o Cloud Search calcula os valores mais frequentes para as propriedades solicitadas entre os itens correspondentes. Esses valores são retornados na resposta. Use esses valores para construir filtros que restringem os resultados em consultas subsequentes.

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

1. Faça uma consulta inicial especificando quais propriedades incluir nos resultados da faceta.
2. Renderize os resultados da pesquisa e do 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.

Observação: as facetas só podem ser usadas em itens com propriedades de dados estruturados.

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

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

Interpretando buckets de atributos

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 que ocorrem com mais frequência aparecem primeiro.

Quando um usuário seleciona um ou mais valores para filtrar, construa uma nova consulta com os filtros selecionados e consulte a API novamente.

Adicionar sugestões

Use a API de sugestão para fornecer preenchimento automático de consultas com base 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"
  }
}

Você pode exibir as sugestões resultantes conforme apropriado para seu aplicativo.