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 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 app de pesquisa fornece o padrão parâmetros para uma consulta, como as fontes de dados a serem usadas, a ordem de classificação, filtros e atributos a serem solicitados. Se necessário, substitua esses parâmetros usando a API de consulta.

Para mais informações sobre os aplicativos de pesquisa, consulte Personalize 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 precisará gerar credenciais 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 e as bibliotecas de cliente do OAuth, consulte [Plataforma de identidade do Google](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.

Consultar o índice

Usar o search para realizar pesquisas no índice.

Cada solicitação precisa incluir duas informações: um texto query para corresponder os itens e um searchApplicationId identificando o ID do o 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

No mínimo, as interfaces de pesquisa devem mostrar o item title como bem como um link para o item original. É possível aprimorar ainda mais a exibição resultados da pesquisa aproveitando informações adicionais presentes nos resultados da pesquisa como o snippet e os metadados.

Processar resultados complementares

Por padrão, o Cloud Search retorna resultados complementares quando há resultados insuficientes para a consulta do usuário. A queryInterpretation na resposta indica quando os resultados complementares são retornados. Apenas se resultados complementares forem retornados, InterpretationType será definido como REPLACE. Se alguns resultados da consulta original são retornados resultados, InterpretationType é definido como BLEND. Em ambos os casos QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY:

Quando alguns resultados complementares forem retornados, considere incluir texto para indicar que resultados complementares foram retornados. Por exemplo, no caso de um REPLACE, você poderá exibir a string "Sua pesquisa pela consulta original não correspondem a nenhum resultado. Mostrando resultados para consultas semelhantes."

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

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 de funcionários para uma pessoa cujo nome é usado em uma consulta. O último tipo de resultado é uma função do Cloud O recurso Pesquisa de pessoas da Pesquisa e os resultados para essa consulta podem ser encontrados em as 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 os usuários veem os subordinados diretos de uma pessoa na organização. O resultado está disponível no campo structuredResults.

Para consultas sobre o gerente ou subordinados diretos de uma pessoa, a resposta tem um assistCardProtoHolder no structuredResults. A 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. contém a subject (a pessoa que foi incluída na consulta) e relatedPeople, que são o conjunto de pessoas relacionadas ao assunto. A O campo relationType retorna o valor MANAGER ou DIRECT_REPORTS.

O código a seguir mostra um exemplo de resposta para um subordinado direto correspondente consulta:

{
  "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. Você pode, No entanto, desative todas as otimizações ou apenas os resultados complementares aplicativo de pesquisa e nível da 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 durante a renderização. os resultados. O exemplo de javascript a seguir converte o snippet em Marcação HTML com cada intervalo correspondente unido 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

Usar o metadata campo para exibir informações adicionais sobre o item devolvido que podem ser relevantes aos usuários. O campo metadata inclui createTime e updateTime do item, bem como quaisquer dados estruturados retornáveis associados com o item.

Para mostrar os dados estruturados, use 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 de valores pares, conforme configurado no esquema.

Recuperar resultados extras

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

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

Classificar resultados

Usar o sortOptions campo para especificar a ordem de itens devolvidos. 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 tanto na app de pesquisa assim como na solicitação de pesquisa.

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

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

  • Filtros de objeto, por meio da propriedade filterOptions[].objectType, restringem itens correspondentes ao tipo especificado, conforme definido em um esquema personalizado.
  • Filtros de valor — restringe itens correspondentes com base em uma operador de consulta e o 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.

As facetas podem ser definidas em seu aplicativo de pesquisa. e substituído 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:

  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 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"
  }
]

Resultados de atributos com campos baseados em números inteiros

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

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

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

É possível modificar 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 usa as opções de agrupamento definidas no o esquema quando o aplicativo de pesquisa e a solicitação de consulta não tiverem um atributo definidas. Os atributos definidos na consulta têm precedência sobre aqueles definidos no aplicativo de pesquisa, e os atributos definidos nele precedência sobre os atributos definidos no esquema.

Resultados da faceta por tamanho ou data do documento

Você pode usar operadores reservados para refinar os resultados da pesquisa pelo tamanho do documento, medido em bytes, ou pelo um documento foi criado ou modificado. Não é preciso definir um esquema personalizado, mas você precisa especificar o valor operatorName no arquivo FacetOptions.

  • 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

O 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, uma lista de valores ou intervalos, chamados buckets é fornecido. 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.