Créer une interface de recherche avec l'API Query

L'API Query fournit des méthodes de recherche et de suggestion pour créer une recherche. l'interface ou l'intégration de résultats de recherche dans une application.

Pour les applications Web avec des exigences minimales, envisagez d'utiliser le widget Recherche. Pour en savoir plus, consultez Créer une interface de recherche avec le widget Recherche

Créer une interface de recherche

La création d'une interface de recherche minimale nécessite plusieurs étapes:

  1. Configurer une application de recherche
  2. Générer des identifiants OAuth pour l'application
  3. Interroger l'index
  4. Afficher les résultats de la requête

Vous pouvez améliorer l'interface de recherche grâce à des fonctionnalités telles que la pagination, le tri, le filtrage, les attributs et la suggestion automatique.

Configurer une application de recherche

Vous devez créer au moins une application de recherche à associer à chaque de recherche que vous créez. Une application de recherche fournit paramètres d'une requête, tels que les sources de données à utiliser, l'ordre de tri des filtres et des attributs à demander. Si nécessaire, vous pouvez remplacer ces paramètres à l'aide de l'API Query.

Pour en savoir plus sur les applications de recherche, consultez Personnalisez l'expérience de recherche dans Cloud Search.

Générer des identifiants OAuth pour l'application

En plus des étapes décrites dans Configurer l'accès à l'API Google Cloud Search vous devez également générer des identifiants OAuth pour l'application Web. Le type d'identifiants que vous créez dépend du contexte dans lequel l'API est utilisée.

Utilisez les identifiants pour demander une autorisation au nom de l'utilisateur. Utilisez le le champ d'application https://www.googleapis.com/auth/cloud_search.query lors de la demande une autorisation.

Pour en savoir plus sur les options OAuth et les bibliothèques clientes, consultez [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}).

Interroger l'index

Utilisez le search pour effectuer des recherches par rapport à l'index.

Chaque requête doit inclure deux informations: un texte query pour faire correspondre les éléments et un searchApplicationId identifiant l'identifiant l'application de recherche à utiliser.

L'extrait suivant montre une requête envoyée à la source de données du film Titanic:

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

Afficher les résultats de la requête

Les interfaces de recherche doivent au minimum afficher l'élément title sous la forme ainsi qu'un lien vers l'élément d'origine. Vous pouvez améliorer l'affichage Résultats de recherche en exploitant les informations supplémentaires présentes dans les résultats de recherche comme l'extrait et les métadonnées.

Gérer les résultats supplémentaires

Par défaut, Cloud Search renvoie des résultats supplémentaires en cas de de résultats insuffisants pour la requête de l'utilisateur. La queryInterpretation dans la réponse indique quand des résultats supplémentaires sont renvoyés. Si seulement résultats supplémentaires sont renvoyés, InterpretationType est défini sur REPLACE. Si quelques résultats de la requête initiale s'affichent, ainsi que résultats, InterpretationType est défini sur BLEND. Dans les deux cas QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY

Lorsque des résultats supplémentaires sont renvoyés, pensez à fournir du texte pour indiquer que des résultats supplémentaires ont été renvoyés. Par exemple, dans le cas d'une REPLACE, vous pouvez afficher la chaîne "La recherche correspondant à votre requête d'origine a aucun résultat. Affichage des résultats pour des requêtes similaires."

Dans le cas d'une BLEND, vous pouvez afficher la chaîne "Votre recherche pour La requête d'origine ne correspondait pas à suffisamment de résultats. Inclusion des résultats pour des termes similaires requêtes."

Gérer les résultats des utilisateurs

Cloud Search renvoie deux types de "résultats de contacts" : les documents associés à un personne dont le nom est utilisé dans la requête et les informations sur l'employé concernant une personne dont le nom est utilisé dans une requête. Ce dernier type de résultat est une fonction la fonctionnalité Recherche de contacts. Les résultats de ce type de requête sont disponibles dans la structuredResults d'une réponse de l'API de requête:

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

Mise en correspondance des supérieurs directs

La mise en correspondance directe des rapports est une fonctionnalité de recherche de contacts de Cloud Search qui permet les utilisateurs voient les subordonnés directs d'une personne de leur organisation. Le résultat est disponible dans le champ structuredResults.

Pour les questions concernant le responsable ou les subordonnés d'une personne, la réponse contient une assistCardProtoHolder dans le structuredResults. La assistCardProtoHolder comporte un champ appelé cardType, qui sera égal à RELATED_PEOPLE_ANSWER_CARD L'élément assistCardProtoHolder contient une carte. appelé relatedPeopleAnswerCard, qui contient la réponse réelle. Elle contient subject (la personne qui a été incluse dans la requête) et relatedPeople, qui correspondent à l'ensemble de personnes associées au sujet. La Le champ relationType renvoie la valeur MANAGER ou DIRECT_REPORTS.

Le code suivant présente un exemple de réponse pour une correspondance requête:

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

Désactiver les optimisations, y compris les résultats supplémentaires

Par défaut, les optimisations, telles que les résultats supplémentaires, sont activées. Vous pouvez Vous devez toutefois désactiver toutes les optimisations ou simplement les résultats supplémentaires application de recherche et niveau des requêtes:

Mettre les extraits en surbrillance

Pour les articles renvoyés contenant du texte ou du contenu HTML indexé, un extrait du contenu est renvoyé. Ce contenu aide les utilisateurs à déterminer la pertinence de l'article renvoyé.

Si l'extrait contient des termes de requête, une ou plusieurs plages de correspondance identifiant l'emplacement des termes sont également renvoyés.

Utiliser matchRanges pour mettre en surbrillance le texte correspondant lors de l'affichage les résultats. L'exemple de code JavaScript suivant convertit l'extrait en Balisage HTML avec chaque plage correspondante encapsulée dans une balise <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;
}

Voici l'extrait de code:

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

La chaîne HTML obtenue est la suivante:

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

Afficher les métadonnées

Utilisez le metadata pour afficher des informations supplémentaires sur l'article renvoyé qui peuvent être pertinentes aux utilisateurs. Le champ metadata inclut les champs createTime et updateTime de l'article, ainsi que toute donnée structurée pouvant être retournée associée avec l'article.

Pour afficher les données structurées, utilisez la méthode displayOptions. . Le champ displayOptions contient le libellé d'affichage du type d'objet et un ensemble de metalines. Chaque métaligne est un tableau d'étiquettes d'affichage et des paires de valeurs, comme indiqué dans le schéma.

Récupérer des résultats supplémentaires

Pour récupérer des résultats supplémentaires, définissez start dans la requête au décalage souhaité. Vous pouvez ajuster la taille de chaque page avec le paramètre pageSize .

Pour afficher le nombre d'éléments renvoyés ou pour afficher les commandes de pagination les articles renvoyés, utilisez la méthode resultCount . Selon la taille de l'ensemble de résultats, la valeur réelle ou une valeur estimée est fournie.

Trier les résultats

Utilisez le sortOptions pour spécifier l'ordre des articles retournés. La valeur sortOptions est un objet comportant deux champs:

  • operatorName : opérateur utilisé pour le tri de la propriété de données structurées. Pour les propriétés comportant plusieurs opérateurs, vous ne pouvez trier qu'en utilisant l'égalité principale .
  • sortOrder : sens du tri (ASCENDING ou DESCENDING).

La pertinence est également utilisée comme clé de tri secondaire. Si aucun ordre de tri n'est spécifié dans une requête, les résultats sont classés uniquement par pertinence.

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

Ajouter des filtres

Outre les expressions de requête, vous pouvez restreindre davantage les résultats en appliquant filtres Vous pouvez spécifier des filtres application de recherche ainsi que dans la requête de recherche.

Pour ajouter des filtres à une application de requête ou de recherche, ajoutez-les dans la section dataSourceRestrictions.filterOptions[].

Il existe deux façons principales de filtrer davantage une source de données:

  • Filtres d'objets, via la propriété filterOptions[].objectType : restreignent des éléments correspondants au type spécifié, tel que défini dans un schéma personnalisé.
  • Filtres de valeur — limite les éléments correspondants en fonction d'une opérateur de requête et la valeur fournie.

Filtres composites permettent de combiner plusieurs filtres de valeur dans des expressions logiques pour obtenir des requêtes complexes.

Dans l'exemple de schéma de film, vous pouvez appliquer une contrainte d'âge basée sur l'utilisateur actuel et limiter les films disponibles en fonction de la classification 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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Affiner les résultats à l'aide d'attributs

Les attributs sont des propriétés indexées qui représentent des catégories permettant d'affiner la recherche résultats. Utilisez les facettes pour aider les utilisateurs à affiner leurs requêtes de manière interactive et à trouver les articles pertinents plus rapidement.

Les attributs peuvent être définis application de recherche Google. et remplacés par des paramètres dans votre requête.

Lorsque vous demandez des attributs, Cloud Search calcule les valeurs les plus fréquentes pour les attributs les propriétés demandées parmi les éléments correspondants. Ces sont renvoyées dans la réponse. Utiliser ces valeurs pour créer des filtres qui restreignent les résultats lors des requêtes suivantes.

Le modèle d'interaction typique avec les attributs est le suivant:

  1. Effectuer une requête initiale spécifiant les propriétés à inclure dans l'attribut résultats.
  2. Affichez les résultats de recherche et d'attributs.
  3. L'utilisateur sélectionne une ou plusieurs valeurs d'attribut pour affiner les résultats.
  4. Répétez la requête avec un filtre basé sur les valeurs sélectionnées.

Par exemple, pour affiner les requêtes de films par année et classification MPAA, inclure la propriété facetOptions dans la requête.

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

Résultats d'attributs avec des champs basés sur des nombres entiers

Vous pouvez également demander des résultats avec des champs basés sur des nombres entiers. Par exemple : peut marquer une propriété de nombre entier appelée book_pages comme attribut permettant de l'affiner résultats pour une recherche de livres avec "100-200" .

Lorsque vous configurez le schéma de votre champ de propriété d'entier, définissez isFacetable à true et ajouter les options de binning correspondantes à la integerPropertyOptions Cela garantit que chaque propriété pouvant contenir un nombre entier dispose d'un binning par défaut définies.

Lorsque vous définissez la logique des options de binning, fournissez un tableau de valeurs incrémentielles indiquant des plages. Par exemple, si l'utilisateur final spécifie des plages 2, 5, 10, 100, puis les facettes pour <2, [2-5), [5-10), [10-100), >=100 sont calculés.

Vous pouvez remplacer les attributs basés sur des entiers en définissant les mêmes options de binning pour facetOptions dans la demande. Si nécessaire, Cloud Search utilise les options de binning définies dans le schéma lorsque ni l'application de recherche, ni la requête de requête ne comportent d'attribut définies. Les attributs définis dans la requête prévalent sur les attributs définis dans l'application de recherche, et les attributs définis dans celle-ci prennent sur les attributs définis dans le schéma.

Résultats d'attributs par taille ou date de document

Vous pouvez utiliser opérateurs réservés pour affiner les résultats de recherche en fonction de la taille de fichier du document (mesurée en octets) ou du moment un document a été créé ou modifié. Vous n'avez pas besoin de définir un schéma personnalisé, Toutefois, vous devez spécifier la valeur operatorName dans le fichier FacetOptions

  • Pour créer des attributs par taille de document, utilisez itemsize et définissez les options de binning.
  • Pour créer des attributs par date de création du document, utilisez createddatetimestamp.
  • Pour les attributs par date de modification du document, utilisez lastmodified.

Interpréter les buckets d'attributs

facetResults dans la réponse à la requête de recherche inclut la requête de filtrage exacte de l'utilisateur dans le champ filter pour chaque bucket

Pour les attributs qui ne sont pas basés sur des entiers, facetResults inclut une entrée pour chaque propriété demandée. Pour chaque propriété, une liste de valeurs ou de plages, appelée buckets est fourni. Les valeurs les plus fréquentes apparaissent en premier.

Lorsqu'un utilisateur sélectionne une ou plusieurs valeurs pour le filtrage, construisez une nouvelle requête avec avec les filtres sélectionnés et interroger l'API à nouveau.

Ajouter des suggestions

Utiliser l'API suggest pour proposer une saisie semi-automatique pour les requêtes en fonction des requêtes, des contacts et de leur corpus de documents.

Par exemple, l'appel suivant donne des suggestions pour l'appel partiel pour l'expression jo.

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

Vous pouvez ensuite afficher les suggestions en fonction de votre application.