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:
- Configurar um aplicativo de pesquisa
- Gerar credenciais OAuth para o aplicativo
- Consultar o índice
- 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.
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.
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": {...}
}]
}
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
comotrue
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
comotrue
na consulta de pesquisa.Para desativar os resultados complementares no nível do aplicativo de pesquisa, defina
QueryInterpretationOptions.forceDisableSupplementalResults
comotrue
na consulta de pesquisa.Para desativar os resultados complementares no nível da consulta de pesquisa, defina
QueryInterpretationOptions.disableSupplementalResults
comotrue
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
ouDESCENDING
.
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.
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 é:
- Faça uma consulta inicial especificando quais propriedades incluir nos resultados da faceta.
- Renderize os resultados da pesquisa e do atributo.
- O usuário seleciona um ou mais valores de atributo para refinar os resultados.
- Repita a consulta com um filtro baseado nos valores selecionados.
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.