Intégration de données du monde réel dans Coveo Search à l’aide du connecteur source générique de l’API REST / Blogs / Perficient

Ce blog vous guidera dans l’indexation du contenu des points de terminaison de l’API dans Coveo à l’aide du Source API REST générique. Cet outil permet l’indexation des données de n’importe quel service web exposant une API REST, comme des systèmes de gestion de contenu (CMS), des bases de données ou des plateformes tierces. Bien que l’API de démonstration ici soit à titre d’illustration, les étapes peuvent être adaptées à des scénarios réels, comme l’intégration de données Adobe Experience Manager (AEM) ou la récupération de contenu structuré, tel que des profils utilisateur ou des métadonnées, à partir de divers référentiels.

À la fin de ce guide, vous serez en mesure d’indexer et d’afficher des données structurées dans Coveo, améliorant ainsi la pertinence de la recherche et l’expérience utilisateur.

Pourquoi utiliser la source API REST générique de Coveo ?

La source API REST générique de Coveo est conçue pour extraire les données d’une API et les rendre disponibles pour la recherche et l’analyse. Il est très polyvalent et vous permet de :

• Indexez les données de n’importe quelle API sans connecteur dédié.
• Personnalisez l’indexation avec les configurations JSON pour les appels et les réponses API.
• Accédez au contenu de diverses applications Web à l’aide des API REST. Et gérez efficacement le contenu de divers référentiels.
• Simplifie la récupération et la gestion des données grâce à des appels d’API structurés.

Ce dont vous avez besoin

• Accès API : l’API doit exposer les données que vous souhaitez indexer. Pour ce blog, nous utilisons un exemple d’API.
• Accès à la console d’administration Coveo : vous aurez besoin des droits d’administrateur pour configurer les sources.
• Outil facultatif : utilisez Postman ou un client API similaire pour inspecter les réponses API avant la configuration.

Mise en œuvre étape par étape

Étape 1 : Explorez la sortie de l’API

Avant d’intégrer Coveo, examinez la réponse de l’API pour comprendre la structure des données. Pour ce blog, j’utilise une API fausse et fiable gratuite pour les tests et le prototypage.

Testez avec Postman ou cURL :

curl --location --request GET 'https://jsonplaceholder.typicode.com/users'

Appel API :

GET https://jsonplaceholder.typicode.com/users

Accept: application/json
Authorization: Bearer **********-****-****-****-************

Exemple de réponse API :

[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874"
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org"
  }
]

Structure de configuration JSON

Avant d’explorer les données de l’API, définissez une structure claire pour la configuration JSON. Cette structure détermine la manière dont Coveo récupère et organise les données de l’API.

• API (Root Node) : Le point d’entrée d’interaction, représentant la source de données externe (n’importe quelle API RESTful).
• Service : couche qui traite les requêtes adressées à l’API et prend en charge diverses sources de données ou services.
• Points de terminaison : chemins définis exposés par l’API (par exemple, /users, /comments, /albums).
• Mappage de données : chaque point de terminaison récupère des données spécifiques (par exemple, profils utilisateur de /users, commentaires de /comments, albums de /albums).

Identifier les champs à indexer

À partir de la réponse, des champs tels que l’identifiant, le nom, l’e-mail et l’adresse peuvent être mappés pour l’indexation.

Étape 2 : Créer le connecteur source API REST générique dans Coveo

• Connectez-vous à la console d’administration Coveo : accédez à Contenu > Sources et cliquez sur Ajouter une source.
• Sélectionnez le type de source : choisissez l’API REST parmi les options.
• Configurez les détails de base, le nom de la source : utilisez quelque chose de descriptif comme les profils utilisateur, etc.
• Ne le construisez pas ; gardez-le pour le moment.

Note:

• URL de l’API REST : https://jsonplaceholder.typicode.com/users
• Authentification : ignorer si l’API est publique. Si une authentification est requise, configurez-la sous l’onglet Authentification.

Étape 3 : configurer les paramètres JSON

• Après avoir enregistré la source, cliquez sur Modifier la configuration JSON dans le menu source.
• Remplacez le JSON par défaut par la configuration suivante :

{
  "services": [
    {
      "url": "https://jsonplaceholder.typicode.com",
      "paging": {
        "pageSize": 20,
        "offsetStart": 10,
        "offsetType": "item",
        "parameters": {
          "limit": "limit",
          "offset": "offset"
        }
      },
      "endpoints": [
        {
          "path": "/users",
          "method": "GET",
          "itemType": "userprofile",
          "uri": "%[coveo_url]/users/%[id]",
          "clickableUri": "%[coveo_url]/users/%[id]",
          "title": "%[name]",
          "metadata": {
            "id": "%[id]",
            "username": "%[username]",
            "email": "%[email]",
            "address": "%[address]",
            "phone": "%[phone]",
            "website": "%[website]",
            "company": "%[company]"
          }
        }
      ]
    }
  ]
}

Étape 4 : Enregistrez et reconstruisez la source

• Cliquez sur Enregistrer pour appliquer les modifications.
• Revenez à la page source et cliquez sur Enregistrer et reconstruire.
• Surveillez les journaux pour garantir une indexation réussie à l’aide de l’outil navigateur de journaux.

La capture d’écran ci-dessous montre le processus de reconstruction ou les journaux confirmant la réussite de l’indexation.

Cartographie et affichage des données

Étape 5 : Mappez les champs API aux champs Coveo, puis associez-les à la source rest-api

• Accédez aux champs dans la console d’administration.
• Comme indiqué ci-dessous, créez de nouveaux champs pour des attributs tels que l’identifiant, le nom, l’e-mail, l’adresse et autres. Le champ « nom » a déjà été créé ; suivez la même démarche pour les autres champs.
• Mappez ces champs dans l’onglet Mappages de la configuration source.
  

Pour des informations plus détaillées sur les champs et les mappages Coveo, consultez les blogs suivants :

Pour afficher une configuration de mappage de champs plus détaillée pour votre source, consultez les étapes ci-dessous : Voir le mappage JSON ci-dessous :

[
  {
    "content": "%[filename]",
    "extractionMethod": "METADATA",
    "fieldName": "filename",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-qaut7yluelbrwf5b3x23ea2iji",
    "kind": "COMMON",
    "rules": [
      "%[filename]"
    ]
  },
  {
    "content": "%[clickableuri]",
    "extractionMethod": "METADATA",
    "fieldName": "clickableuri",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-qidgh3yqtqgxpt2zarqg5y2fki",
    "kind": "COMMON",
    "rules": [
      "%[clickableuri]"
    ]
  },
  {
    "content": "%[email]",
    "extractionMethod": "METADATA",
    "fieldName": "up_email",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-q66t3o5osh6wqdzc4rlwrlsc3m",
    "kind": "COMMON",
    "rules": [
      "%[email]"
    ]
  },
  {
    "content": "%[phone]",
    "extractionMethod": "METADATA",
    "fieldName": "up_phone",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-qr7g25pyvh3rl42wtyheppcopy",
    "kind": "COMMON",
    "rules": [
      "%[phone]"
    ]
  },
  {
    "content": "%[username]",
    "extractionMethod": "METADATA",
    "fieldName": "up_username",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-sfqu5sxfgk32iarhiaes22chhm",
    "kind": "COMMON",
    "rules": [
      "%[username]"
    ]
  },
  {
    "content": "%[website]",
    "extractionMethod": "METADATA",
    "fieldName": "up_website",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-qrti6wae2lzbq4iy7vd5zhkatq",
    "kind": "COMMON",
    "rules": [
      "%[website]"
    ]
  },
  {
    "content": "%[company]",
    "extractionMethod": "METADATA",
    "fieldName": "up_company",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-sxfkfclwtarbh3fvrjvtfr2iwe",
    "kind": "COMMON",
    "rules": [
      "%[company]"
    ]
  },
  {
    "content": "%[address]",
    "extractionMethod": "METADATA",
    "fieldName": "up_address",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-u6ajgmpuoedwigbmeuzhszkpvy",
    "kind": "COMMON",
    "rules": [
      "%[address]"
    ]
  },
  {
    "content": "%[id]",
    "extractionMethod": "METADATA",
    "fieldName": "up_id",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-udpex4lvcj5g7jaynzkwsc2fie",
    "kind": "COMMON",
    "rules": [
      "%[id]"
    ]
  },
  {
    "content": "%[month]",
    "extractionMethod": "METADATA",
    "fieldName": "month",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-qrz336tyq4qbvj2qizlqpwkaky",
    "kind": "COMMON",
    "rules": [
      "%[month]"
    ]
  },
  {
    "content": "%[title:crawler]",
    "extractionMethod": "METADATA",
    "fieldName": "title",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-r3agbznnaduqkgul7b7hudsarq",
    "kind": "COMMON",
    "rules": [
      "%[title:crawler]"
    ]
  },
  {
    "content": "%[year]",
    "extractionMethod": "METADATA",
    "fieldName": "year",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-rbfbf2soa6rzlgai7eygpfkgoq",
    "kind": "COMMON",
    "rules": [
      "%[year]"
    ]
  },
  {
    "content": "%[mobile]",
    "extractionMethod": "METADATA",
    "fieldName": "mobilephone",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-rdhx4wtyfy5znb6txno4qvcpba",
    "kind": "COMMON",
    "rules": [
      "%[mobile]"
    ]
  },
  {
    "content": "%[company]",
    "extractionMethod": "METADATA",
    "fieldName": "company",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-rdjy3kkqcxbs66phsdmcfdcpou",
    "kind": "COMMON",
    "rules": [
      "%[company]"
    ]
  },
  {
    "content": "%[permanentid]",
    "extractionMethod": "METADATA",
    "fieldName": "permanentid",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-rirzsjru43xswhpfwc4c7bkb4m",
    "kind": "COMMON",
    "rules": [
      "%[permanentid]"
    ]
  },
  {
    "content": "%[coveo_externalurl]",
    "extractionMethod": "METADATA",
    "fieldName": "relatedlink",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-rjuqiqtvi6fe5kbrwwvbc2sanu",
    "kind": "COMMON",
    "rules": [
      "%[coveo_externalurl]"
    ]
  },
  {
    "content": "%[office]",
    "extractionMethod": "METADATA",
    "fieldName": "office",
    "id": "ashwinitestorg6zfn7o3t-wktezkeyf53ibe2gryghnjsk6y-xsbc254qtlebiqu4dcqt6rcmn4",
    "kind": "COMMON",
    "rules": [
      "%[office]"
    ]
  }
]

Pour afficher les documents indexés avec leurs propriétés mappées, accédez à Contenu > Navigateur de contenu dans la console d’administration Coveo.

Cliquez sur l’option Propriétés dans le coin supérieur droit pour afficher les métadonnées, comme indiqué ci-dessous.

Voici les propriétés, comme indiqué ci-dessous

Étape 6 : configurer l’interface de recherche

Afficher les données indexées sur la page de recherche Coveo. Utilisez les composants Coveo JSUI Framework pour afficher les détails :

<script id="Default" class="result-template" type="text/html" data-layout="list">
    <div class="coveo-result-frame">
        <div class="coveo-result-cell" style="vertical-align:top;text-align:center;width:32px;"> <span class="CoveoIcon" data-small="true" data-with-label="false"></span>
            <div class="CoveoQuickview"></div>
        </div>
        <div class="coveo-result-cell" style="vertical-align: top;padding-left: 16px;">
            <div class="coveo-result-row" style="margin-top:0;">
                <div class="coveo-result-cell" style="vertical-align:top;font-size:16px;" role="heading" aria-level="2">
                    <a class="CoveoResultLink"></a>
                </div>
                <div class="coveo-result-cell" style="width:120px;text-align:right;font-size:12px">
                    <div class="coveo-result-row"> <span class="CoveoFieldValue" data-field="@date" data-helper="date"></span> </div>
                </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoExcerpt"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@up_id" data-text-caption="Id:" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@up_email" data-text-caption="Email" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@up_username" data-text-caption="Username" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@up_address" data-text-caption="Address" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@up_phone" data-text-caption="Phone" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@up_company" data-text-caption="Company" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@up_website" data-text-caption="Website" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@filetype" data-text-caption="File Type" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell"> <span class="CoveoFieldValue" data-field="@source" data-text-caption="Source" style="margin-right:30px;"></span> </div>
            </div>
            <div class="coveo-result-row" style="margin-top:10px;">
                <div class="coveo-result-cell">
                    <div class="CoveoPrintableUri"></div>
                </div>
            </div>
            <div class="coveo-result-row">
                <div class="coveo-result-cell">
                    <div class="CoveoMissingTerms"></div>
                </div>
            </div>
        </div>
    </div>
</script>

Interface de recherche affichant les champs mappés.

Conclusion

L’indexation des données d’API comme AEM dans Coveo à l’aide de la source API REST générique est simple. En suivant ce guide, vous pouvez configurer un pipeline robuste pour récupérer, cartographier et afficher les données API dans votre interface de recherche Coveo. Grâce à la flexibilité des configurations JSON et des composants de recherche de Coveo, il peut offrir des expériences de recherche puissantes et enrichies.

Liens utiles

Ajouter une source API REST | Plateforme Coveo

Utiliser le navigateur de journaux pour consulter les journaux d’indexation | Plateforme Coveo

Inspecter les éléments avec le navigateur de contenu | Plateforme Coveo

Partie 1 : Construire la source et les mappages correspondants dans Coveo Enterprise Search / Blogs / Perficient

Partie 2 : Construire la source et les mappages correspondants dans Coveo Enterprise Search / Blogs / Perficient