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

L'API Query fournit des méthodes de recherche et de suggestion permettant de créer une interface de recherche ou d'intégrer les résultats dans une application.

Pour les applications Web qui n'ont pas d'exigences particulières, envisagez d'utiliser le widget Recherche. Consultez Créer une interface de recherche avec le widget Recherche.

Créer une interface de recherche

La procédure de création d'une interface de recherche minimale comprend les étapes suivantes :

  1. Configurez une application de recherche.
  2. Générez des identifiants OAuth pour l'application.
  3. Interrogez l'index.
  4. Affichez les résultats de requête.

Vous pouvez enrichir l'interface avec des fonctionnalités telles que la pagination, le tri, le filtrage, les facettes et la saisie semi-automatique.

Configurer une application de recherche

Vous devez créer au moins une application de recherche pour chaque interface de recherche. Une application de recherche fournit des paramètres par défaut, tels que les sources de données, l'ordre de tri, les filtres et les facettes. Vous pouvez remplacer ces paramètres à l'aide de l'API Query.

Vous ne pouvez pas augmenter le nombre de sources de données utilisées dans une requête au-delà de celles configurées dans l'application de recherche. Vous pouvez limiter une requête à un sous-ensemble de ces sources à l'aide de dataSourceRestrictions.

Pour en savoir plus, consultez Personnaliser l'expérience de recherche.

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

Outre les étapes décrites sur la page Configurer l'accès à l'API Cloud Search, vous devez générer des identifiants OAuth pour votre application Web.

Les identifiants permettent de demander une autorisation au nom de l'utilisateur. Utilisez le champ d'application https://www.googleapis.com/auth/cloud_search.query.

Pour en savoir plus sur les options OAuth, consultez la page Google Identity Platform.

Interroger l'index

Utilisez la méthode search pour effectuer des recherches dans l'index.

Chaque requête doit inclure un query et un searchApplicationId.

Cet exemple interroge une source de données de films :

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

Afficher les résultats de la requête

Les interfaces de recherche doivent afficher l'attribut title de l'élément, ainsi qu'un lien permettant d'accéder à l'élément original. Vous pouvez également utiliser des extraits et des métadonnées pour améliorer l'affichage.

Gérer les résultats complémentaires

Cloud Search renvoie des résultats supplémentaires lorsqu'il n'y a pas assez de correspondances pour une requête. Le champ queryInterpretation indique cette information. Si seuls des résultats supplémentaires sont renvoyés, InterpretationType est défini sur REPLACE. Si elles sont fusionnées, il s'agit de BLEND.

Lorsque vous renvoyez des résultats supplémentaires, pensez à en informer l'utilisateur. Pour une REPLACE, vous pouvez dire : "Aucun résultat ne correspond à votre recherche. Résultats pour des requêtes similaires".

Gérer les résultats concernant les personnes

Cloud Search renvoie des documents liés à des personnes et des informations sur les employés à l'aide de la fonctionnalité Recherche de personnes. Les résultats se trouvent dans le champ structuredResults :

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

Correspondance des subordonnés directs

La fonctionnalité Correspondance des collaborateurs directs permet aux utilisateurs de voir les collaborateurs directs d'une personne. La réponse inclut un assistCardProtoHolder avec un cardType de RELATED_PEOPLE_ANSWER_CARD.

Désactiver les optimisations

Les optimisations, comme les résultats supplémentaires, sont activées par défaut. Vous pouvez les désactiver :

Mettre en surbrillance les extraits

Cloud Search renvoie un extrait pour le texte ou le code HTML indexés. Si des termes de requête sont présents, matchRanges identifie leur emplacement. Utilisez ces plages pour mettre en surbrillance du texte.

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