Esta página foi traduzida pela API Cloud Translation.

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:

Configurar um aplicativo de pesquisa
Gerar credenciais do OAuth para o aplicativo
Consultar o índice
Exibir os resultados da 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 usadas, a ordem de classificação, os filtros e os atributos a serem solicitados. Se necessário, é possível modificar esses parâmetros usando a API de consulta.

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

Gerar credenciais do OAuth para o aplicativo

Além das etapas em Configurar o acesso à API Google Cloud Search, você também precisa 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 ao solicitar autorização.

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

Consultar o índice

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

Cada solicitação precisa incluir duas informações: um query de texto para corresponder os itens e um searchApplicationId identificando 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 item title, bem como um link para o item original. É possível melhorar ainda mais a exibição dos resultados da pesquisa aproveitando outras informações presentes nos resultados da pesquisa, como o snippet e os metadados.

Processar resultados complementares

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 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, forneça um texto para indicar que eles foram retornados. Por exemplo, no caso de uma REPLACE, é possível exibir a string "Sua pesquisa para a consulta original não encontrou nenhum resultado. Mostrando resultados para consultas semelhantes."

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

Gerenciar 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 do funcionário para uma pessoa com o nome usado em uma consulta. O último tipo de resultado é uma função do recurso Pesquisa de pessoas do Cloud Search. Os resultados dessa consulta podem ser encontrados no campo structuredResults de uma resposta da API de consulta:

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

Correspondência de relatórios diretos

A correspondência de relatórios diretos é um recurso de pesquisa de pessoas do Cloud Search que permite aos usuários ver os subordinados diretos de uma pessoa na organização. O resultado está disponível no campo structuredResults.

Para consultas sobre o gerente ou os subordinados diretos de uma pessoa, a resposta tem um assistCardProtoHolder no structuredResults. O assistCardProtoHolder tem um campo chamado cardType, que será igual a RELATED_PEOPLE_ANSWER_CARD. O assistCardProtoHolder contém um cartão chamado relatedPeopleAnswerCard, que contém a resposta real. Ela contém subject (a pessoa que foi incluída na consulta) e relatedPeople, que é o conjunto de pessoas relacionadas ao assunto. O campo relationType retorna o valor MANAGER ou DIRECT_REPORTS.

O código a seguir mostra um exemplo de resposta para uma consulta correspondente aos relatórios diretos:

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

Desativar as otimizações, incluindo resultados complementares

Por padrão, as otimizações, como resultados complementares, estão ativadas. No entanto, é possível desativar todas as otimizações ou apenas os resultados complementares no nível do aplicativo de pesquisa e da consulta:

Para desativar todas as otimizações no nível do app de pesquisa, incluindo resultados complementares, sinônimos e correções ortográficas, defina QueryInterpretationConfig.force_verbatim_mode como true nos apps 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 app 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.

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 ao renderizar 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...

Metadados de exibição

Use o campo metadata para mostrar 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 todos os dados estruturados retornáveis associados a ele.

Para mostrar 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 adicionais, 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 perguntar aos itens retornados, use o campo resultCount. Dependendo do tamanho do conjunto de resultados, será fornecido o valor real ou um valor estimado.

Ordenar resultados

Use o campo sortOptions para especificar a ordem dos 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, 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 especificar filtros no app de pesquisa e na solicitação de pesquisa.

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

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

Filtros de objeto, usando a propriedade filterOptions[].objectType, restringem os itens correspondentes ao tipo especificado, conforme definido em um esquema personalizado.
Filtros de valor: restringem os itens correspondentes 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 correspondentes. Esses valores são retornados na resposta. Use esses valores para criar filtros que restringem os resultados em consultas subsequentes.

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

Faça uma consulta inicial especificando quais propriedades serão incluídas nos resultados do atributo.
Renderize os resultados de pesquisa e 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 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"
  }
]

Também é possível receber resultados da solicitação de atributos com campos baseados em números inteiros. Por exemplo, você pode marcar uma propriedade de número inteiro chamada book_pages como tabela para refinar os resultados de uma pesquisa sobre livros com páginas "100 a 200".

Ao configurar o esquema de campo da propriedade de número inteiro, defina isFacetable como true e adicione as opções de agrupamento por classes correspondentes a integerPropertyOptions. Isso garante que todas as propriedades com atributos de número inteiro tenham opções padrão de agrupamento por classes definidas.

Ao definir a lógica de opções de agrupamento por classes, forneça uma matriz de valores incrementais que representem intervalos. Por exemplo, se o usuário final especificar intervalos como 2, 5, 10, 100, os atributos de <2, [2-5), [5-10), [10-100) e >=100 serão calculados.

É possível modificar os atributos com base em números inteiros definindo as mesmas opções de agrupamento por classes para facetOptions na solicitação. Se necessário, o Cloud Search usará as opções de agrupamento por classes definidas no esquema quando nem o aplicativo de pesquisa nem a solicitação de consulta tiverem opções de atributo definidas. Os atributos definidos na consulta têm precedência sobre os definidos no aplicativo de pesquisa. Além disso, os atributos definidos no aplicativo de pesquisa têm precedência sobre os atributos definidos no esquema.

É possível usar operadores reservados para refinar os resultados da pesquisa pelo tamanho do arquivo do documento, medido em bytes ou pelo momento em que um documento foi criado ou modificado. Não é necessário definir um esquema personalizado, mas é necessário especificar o valor de operatorName no FacetOptions do aplicativo de pesquisa.

Para facetas por tamanho do documento, use itemsize e defina as opções de agrupamento por classes.
Para filtros de atributos por data de criação do documento, use createddatetimestamp.
Para filtros de atributos por data de modificação do documento, use lastmodified.

Como interpretar buckets de atributo

A propriedade facetResults na resposta da consulta de pesquisa inclui a solicitação de filtro exata do usuário no campo filter para cada bucket.

Para atributos que não são baseados em números inteiros, facetResults inclui uma entrada para cada propriedade solicitada. Para cada propriedade, é fornecida uma lista de valores ou intervalos chamado 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 fornecer preenchimento automático a 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.