Indexation du Hub de contenu dans Coveo / Blogs / Perficient

Introduction 📖

Dans le nouveau monde composable, il est courant que les solutions Sitecore de taille moyenne à grande incluent un système de recherche tel que Covéo et un outil de gestion des actifs numériques comme Centre de contenu Sitecore. Un cas d’utilisation typique consiste à créer des sources de recherche dans Coveo qui indexent le contenu résidant dans Content Hub. Ces index, à leur tour, peuvent ensuite être utilisés pour créer des expériences de recherche frontales. Dans cet article de blog, j’aimerais donner quelques conseils pour travailler avec l’API REST Content Hub afin de remplir les sources de recherche dans Coveo. Ces conseils sont basés sur mes expériences sur un projet récent qui utilisait l’API REST Content Hub pour indexer des documents PDF dans Coveo.

#1 – Savoir quelle API utiliser 🤔

N’ayant jamais utilisé l’API REST Content Hub auparavant, je ne savais pas au départ qu’il existe plusieurs points de terminaison. Voici un bref aperçu de quelques-uns d’entre eux :

API de requête (GET http://<hostname>/api/entities/query/)

La fonctionnalité de requête vous permet d’interroger des entités spécifiques à l’aide de champs de métadonnées indexées spécifiques. Cette requête de base contraste avec la fonctionnalité de recherche plus élaborée offerte par l’API M.Content.

API de défilement (GET http://<hostname>/api/entities/scroll/)

Vous pouvez utiliser l’API Scroll pour récupérer un grand nombre de résultats (ou même tous les résultats) à partir d’une seule requête.

Il ne prend pas en charge le paramètre skip et vous permet uniquement de demander la page suivante via la ressource. Vous pouvez continuer la pagination jusqu’à ce qu’elle ne renvoie plus de résultats ou que vous ayez atteint la dernière page.

API RechercheAprès (POST http://<HOSTNAME>/api/entities/searchafter/)

L’API SearchAfter est utilisée pour récupérer plusieurs pages de résultats de recherche de manière séquentielle. Pour commencer, une requête est effectuée pour la première page de résultats, qui inclut une valeur last_hit_data correspondant au dernier élément de la page. Cette valeur est ensuite utilisée pour récupérer les pages suivantes jusqu’à ce que tous les résultats soient récupérés.

Sur ce projet particulier, l’API Query a été utilisée pour extraire des PDF. De par sa conception, l’API Query renvoie un maximum de 10 000 résultats. Dans ce cas, tout allait bien : il y avait environ 9 000 ressources dans Content Hub à l’époque (sans aucun filtrage supplémentaire appliqué). Cependant, afin de pérenniser un peu la requête et d’éviter un traitement inutile de documents non PDF, il était logique de rendre la requête plus spécifique (voir #2, ci-dessous 👇).

Sortie nette : Si vous savez que vous devrez extraire plus de 10 000 éléments de Content Hub et les paginer efficacement, utilisez l’API SearchAfter. Si votre nombre d’actifs est inférieur à 10 000, l’API Query convient probablement. Notez que l’API SearchAfter sera bientôt obsolète et remplacera l’API Scroll, il est donc préférable d’éviter l’API Scroll pour tout nouveau travail.

#2 – Filtrage sur le type de média et le statut d’approbation 🔮

J’aime penser que je peux comprendre la plupart des choses si je lis la documentation. Cependant, lorsqu’il s’agissait de mettre à jour la requête pour filtrer les fichiers PDF approuvés pour l’indexation, je ne savais pas du tout comment procéder. Comme mentionné ci-dessus, l’API Query est limitée à 10 000 résultats et nous en étions assez proches en termes de nombre total d’actifs. Il était important d’être plus sélectif lors du retrait d’actifs tels que seulement les PDF approuvés ont été renvoyés.

Après avoir expérimenté sans succès pendant un certain temps, je suis tombé en panne et j’ai ouvert un ticket d’assistance Sitecore pour demander comment cela pouvait être accompli. J’ai eu une réponse… et ça a fonctionné, mais ce n’était pas aussi évident que je l’aurais souhaité. Qui aime les chiffres magiques ? 🧙‍♂️✨

Pour rechercher des ressources PDF : ... AND Parent('AssetMediaToAsset').id==1057.

Pour garantir que seuls les actifs approuvés sont inclus : ... AND Parent('FinalLifeCycleStatusToAsset')==544.

En l’assemblant, l’URL complète de la requête (sans tout ordre appliqué ; voir #3 ci-dessous 👇) était :

{baseURL}/api/entities/query?query=Definition.Name=='M.Asset' AND Parent('AssetMediaToAsset').id==1057 AND Parent('FinalLifeCycleStatusToAsset').id==544

Autrement dit:

Donnez-moi tous les éléments dont le type de fichier est PDF et dont le statut d’approbation est approuvé.

Maintenant je pense ces identifiants sont communs à toutes les instances de Content Hub mais, juste au cas où, assurez-vous qu’ils correspondent aux valeurs appropriées dans ton Instance Content Hub avant d’utiliser les mêmes ID dans vos requêtes. Vous pouvez trouver les ID de type de média d’élément sous Gestion des taxonomies dans Content Hub :

#3 – Trier 🔼

Lorsque vous créez une source API REST dans Coveo avec l’intention de parcourir des centaines ou des milliers d’actifs dans Content Hub, il est préférable de les renvoyer dans un ordre cohérent. À un moment donné lors du dépannage de certains problèmes d’indexation, le support Coveo a suggéré que l’API Content Hub renvoyait les résultats dans un ordre incohérent et que cela était potentiellement un facteur contributif. Même si cela n’a jamais été démontré de manière concluante, il fait Il est logique d’appliquer un tri, ne serait-ce que pour garantir que les actifs sont traités dans un ordre spécifique et prévisible.

La requête a été mise à jour pour trier createdOn ascendant (le plus ancien en premier); l’URL de requête mise à jour ressemblait à ceci :

{baseURL}/api/entities/query?query=Definition.Name=='M.Asset' AND Parent('AssetMediaToAsset').id==1057 AND Parent('FinalLifeCycleStatusToAsset').id==544&sort=createdOn&order=Asc

Chose intéressante, j’ai trouvé que created_on a également fonctionné, mais, selon le support de Sitecore, createdOn devrait être utilisé à la place.

#4 – Pagination 📃

Les sources de l’API REST dans Coveo seront presque toujours configurées pour paginer les résultats provenant de l’API externe, sinon seule la valeur des données de la première page sera traitée et indexée. Il est important de s’assurer que la pagination est correctement configurée pour permettre également des délais raisonnables de reconstruction et de nouvelle analyse de l’index. Dans ce cas, en utilisant l’API Query et avec une taille de page de 25 éléments par page, le paging La section de configuration dans la source de l’API REST Coveo ressemblait à ceci :

...
"paging": {
  "pageSize": 25,
  "offsetType": "url",
  "nextPageKey": "next.href",
  "parameters": {
    "limit": "take"
  },
  "totalCountKey": "total_items"
},
...

Les propriétés de pagination correspondantes renvoyées dans la réponse de l’API de requête (pour la première page) ressemblaient à ceci :

{
  "items": [ ... ],
  "total_items": 12345,
  "returned_items": 25,
  "next": {
    "href": "https://{baseURL}/api/entities/query?skip=25&take=25&query=Definition.Name%3D%3D%27M.Asset%27%20AND%20Parent(%27AssetMediaToAsset%27).id%3D%3D1057%20AND%20Parent(%27FinalLifeCycleStatusToAsset%27).id%3D%3D%20544&sort=createdOn&order=Asc",
    ...
  },
  ...
}

Notez que la configuration de la pagination devra peut-être être modifiée si vous utilisez un autre point de terminaison de l’API Content Hub. Pour plus d’informations sur la configuration de la pagination dans les sources de l’API Coveo REST, reportez-vous au site officiel Documentation.

#5 – La taille du fichier peut affecter les propriétés du document dans les extensions 🏋️‍♂️

Dans Coveo, la taille maximale d’un seul élément est d’environ 256 Mo (référence). Ce numéro inclut les autorisations, les métadonnées et le contenu de l’élément. Pour les fichiers plus volumineux, le contenu n’est pas indexé, uniquement les métadonnées. Cette limite est apparue indirectement sur ce projet récent.

Bien qu’en dehors de la portée de cet article, Coveo prend en charge les extensions qui peuvent être attachées aux sources de recherche. Les extensions sont des morceaux de code Python que Coveo exécutera dans le contexte de chaque document lors du traitement de la source. Sur ce projet, une extension a été utilisée pour faire des choses comme rejeter conditionnellement (ignorer l’indexation) des documents, définir des champs de métadonnées en fonction d’autres propriétés, etc. À un moment donné, l’extension a tenté de résoudre l’extension (type de fichier) du document en utilisant le code suivant :

filetype = document.get_meta_data_value("detectedfiletype")[0]

Pour tout document pas au-dessus de la taille maximale, le filetype la variable aurait la valeur attendue : "pdf". Pour tout document qui étaient au-dessus de la taille maximale, la variable avait une valeur générique qui, bien que non vide, était également pas le type de fichier attendu. Le document étant trop volumineux, le document l’objet disponible dans l’extension n’avait pas les valeurs attendues, notamment detectedfiletype. En conséquence, comme le fichier était volumineux, une partie de la logique au sein de l’extension a été brisée car ce cas n’a pas été pris en compte.

Après une enquête plus approfondie sur les fichiers PDF dans Content Hub, il a été noté que, parmi les 10 ou alors qui présentait systématiquement des problèmes d’indexation, tous d’entre eux avaient une taille de plus de 300 Mo.

Pour plus d’informations sur les extensions de pipeline d’indexation (IPE), veuillez consulter Présentation de l’extension du pipeline d’indexation.

Sortie nette : Si vous utilisez une extension sur une source et que vous remarquez que le document l’objet a une ou plusieurs propriétés qui ne renvoient pas ce que vous attendez, vérifiez que le document sous-jacent ne fait pas > 256 Mo et que vous n’essayez pas d’accéder aux propriétés de l’extension qui ne le seront jamais. résoudre correctement.

Merci pour la lecture! 🙏