Construire votre connecteur à partir d'une définition d'API

Créer un nouveau connecteur

1. Si vous sélectionnez Démarrer à partir d'une définition d'API (Start from an API definition), vous devez fournir la définition d'API :

   • À partir d'un fichier local - Téléchargez une collection Postman ou Swagger.
   • À partir d'une URL (From a URL) : saisissez une URL de fichier, telle que https://petstore.swagger.io/v2/swagger.json.
     
     

     

     
     
2. Cliquez sur Continuer (Continue).

Configurez votre connecteur

1. Dans la fenêtre Confirmer l'importation (Confirm import), vous pouvez :

   • Modifiez le Nom du fournisseur ( Provider name), le Nom de l'application ( Application name) et le Nom du connecteur ( Connector name).

   • Modifiez les ressources que vous souhaitez utiliser dans votre connecteur personnalisé. Toutes les ressources disponibles sont automatiquement activées ; désactiver celles que vous voulez exclure.

     • utiliser la barre de Recherche pour rechercher une ressource spécifique.

   • Cliquez sur Créer (Create).
     
     

     

     
     
2. La fenêtre Paramètres (Settings) est maintenant affichée.

3. Dans l'onglet Info, vous pouvez configurer les champs suivants :

   • Nom (Name) : cela se reflète dans votre clé de connecteur.
   • Type d'API (API type) : ce champ est désactivé par défaut, car seul REST est actuellement pris en charge.
   • Catégories - Vous pouvez sélectionner parmi les catégories disponibles, telles que Intelligence artificielle ou Marketing, ou créer vos propres catégories.
   • Description : saisissez une description pour votre connecteur.
   • Icône : cliquez sur Parcourir ( Browse ) pour télécharger une image depuis votre ordinateur. Tous les types d'images sont pris en charge, mais nous vous recommandons d'utiliser un SVG carré.
4. L'aperçu du catalogue (Catalog preview) vous montre comment votre connecteur personnalisé apparaîtra dans le catalogue de connecteurs Integration Service.
5. Sélectionnez Enregistrer (Save).

   
   

   

   
   

Configurer l'API de base

Dans l'onglet API de base , vous configurez l'URL de base pour l'API d'application et la pagination :

• URL de base ( Base URL) : automatiquement remplie avec la valeur déclarée lors de la création du connecteur.
• Type de pagination : les options disponibles dans la liste déroulante sont : Début de la page par 1, Début de la page par 0, Décalage, Personnalisé, Aucun. Si la documentation du fournisseur ne fournit aucun détail sur la pagination, conservez la valeur par défaut. Pour plus de détails, consultez la section Pagination .
• Pagination max – La valeur par défaut est 100. Si la documentation du fournisseur ne fournit aucun détail sur la pagination, conservez la valeur par défaut.
• En -tête Content-Type : ce champ est désactivé par défaut. Seul application/json est actuellement pris en charge.
• Accepter l'en-tête : ce champ est désactivé par défaut. Seul application/json est actuellement pris en charge.
  
  

  

  
  

Pagination

La pagination permet aux applications de fournisseurs de renvoyer certaines parties d'une réponse de manière incrémentielle plutôt que la totalité en même temps, optimisant ainsi le temps de réponse.

La pagination peut être mise en œuvre de différentes manières. Les connecteurs UiPath utilisent une configuration de pagination standardisée, garantissant que tous les connecteurs fonctionnent de la même manière.

Vous pouvez configurer les paramètres de pagination au niveau du connecteur dans Paramètres (Settings) > API de base (Base API) en définissant les champs Type de pagination (Pagination type) et Nombre max de pagination ( Pagination max ). Pour les activités basées sur une liste, vous pouvez configurer davantage la pagination au niveau de la ressource.

Types de pagination

Le champ Type de pagination ( Pagination type ) propose plusieurs options pour s'aligner sur les différentes spécifications du fournisseur :

• La page commence par 1

• Les pages commencent par 0

• Décalage

• Curseur

• Aucun (None)

Les activités du connecteur personnalisé fonctionneront dans votre environnement Studio quel que soit le type de pagination sélectionné. Cependant, pour vous assurer de recevoir des réponses complètes, il est important que vous spécifiiez et configuriez le type de pagination approprié.

La page commence par 1 et la page commence par 0

Les types de pagination basés sur la page reposent sur des paramètres de requête transmis au fournisseur pour indiquer quelle page de résultats doit être renvoyée et le nombre de résultats par page.

Par exemple, GitHub utilise une pagination basée sur la page, comme expliqué dans Utilisation de la pagination dans l'API REST ( Using pagination in the REST API). Ils ont inclus l'URL de la page suivante dans l'en-tête de la réponse pour une implémentation plus facile, mais le mécanisme sous-jacent est basé sur les paramètres de requête Page et per_page .

Dans Connector Builder, vous pouvez sélectionner l’une des options suivantes :

• La page commence par 1 fait référence à la pagination où la première page de résultats a un index de un (par exemple, page=1),
• La page commence par 0 fait référence à une pagination où la première page de résultats est à l'index de zéro (par exemple, page=0).

Configuration des ressources

Par défaut, la pagination basée sur la page attribue Page et TaillePage comme paramètres de pagination. Vous pouvez remplacer ces dernières par les spécifications du fournisseur comme suit :

1. Sélectionnez votre ressource.
2. Sélectionnez l'onglet Pagination (Pagination ).
3. Activez la pagination et mettez à jour les noms de paramètres afin qu’ils correspondent aux paramètres du fournisseur.

Pagination du curseur

La pagination basée sur le curseur repose sur un jeton de page renvoyé par le fournisseur plutôt que sur un numéro de page ou de décalage qui peut être transmis dans les appels suivants pour renvoyer la page de résultats suivante.

Lorsque vous effectuez une demande dans le générateur de connecteurs pour un connecteur qui utilise une pagination basée sur le curseur, les résultats renvoyés ne sont pas automatiquement paginés. Par conséquent, tous les résultats ne sont pas renvoyés sans inclure manuellement le curseur suivant dans un appel ultérieur.

Comme pour d'autres types de pagination, la pagination basée sur curseur inclut généralement une valeur permettant de spécifier le nombre de résultats par page.

Configuration des ressources

La pagination basée sur le curseur fournit des noms par défaut pour le curseur et la taille de la page (nextPage et pageSize), que vous pouvez remplacer afin qu’ils correspondent aux spécifications du fournisseur.

Identifier le chemin du jeton de page

Le curseur de la page suivante est souvent imbriqué dans les champs de réponse de l’API. Par conséquent, il est important de spécifier l'emplacement du curseur dans le schéma de réponse afin qu'Integration Service puisse extraire la valeur du jeton de page et l'utiliser dans une réponse ultérieure.

Vous pouvez spécifier l'emplacement dans le champ de réponse comme suit :

1. Identifiez où il se trouve dans la réponse (corps ou en-tête).

2. Identifiez le chemin du champ avec des points séparant chaque niveau.

Si le curseur est imbriqué dans une URL, vous pouvez utiliser un symbole de point d'interrogation (?) pour représenter le paramètre de requête à extraire.

Exemple

L'API Meta Graph offre un bon exemple d'utilisation de pagination basée sur le curseur dans le générateur de connecteurs. La documentation de la méta-pagination spécifie où dans chaque requête vous trouverez le jeton de page suivante et inclut une référence directe au jeton ou à l'URL complète. Nous pouvons utiliser ces exemples pour créer une pagination des ressources pour l'API Meta Graph.

1. Dans la ressource sélectionnée, mettez à jour le nom du jeton PageSuivante et le nom de la TaillePage afin qu'ils correspondent à l'API du fournisseur. Selon la documentation de l'API Meta Graph, le nom du jeton nextPage est après et pageSize est limit.

2. Ensuite, identifiez où le jeton PageSuivante est disponible sur chaque requête. La documentation nous fournit ce JSON qui mappe les emplacements :

   {
     "data": [
        ... Endpoint data is here
     ],
     "paging": {
       "cursors": {
         "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
         "before": "NDMyNzQyODI3OTQw"
       },
       "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
       "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
     }
   }

Cela fait partie du corps de la réponse, vous pouvez donc configurer le jeton PageSuivante de deux manières :

1. Mappage direct au jeton de page (préféré) : body.paging.cursors.after.
2. Utilisez l’URL suivante : body.paging.next?after.

Ces deux chemins fournissent au connecteur l'emplacement correct pour récupérer la valeur du jeton nextPage .

Décaler la pagination

La pagination de décalage utilise des numéros d'enregistrement pour permettre la pagination dans tous les objets de réponse. Le paramètre de décalage spécifie le nombre d'éléments à ignorer avant de commencer à renvoyer des résultats.

La pagination de décalage utilise souvent les deux paramètres suivants (les noms exacts peuvent varier)

• Décalage : indique l'enregistrement sur lequel commencer à renvoyer des résultats.

• Limite : indique le nombre de résultats par page.

Configuration des ressources

Par défaut, la pagination basée sur la page attribue Page et TaillePage comme paramètres de pagination. Vous pouvez remplacer ces dernières par les spécifications du fournisseur comme suit :

1. Sélectionnez votre ressource.
2. Sélectionnez l'onglet Pagination (Pagination ).
3. Activez la pagination et mettez à jour les noms de paramètres afin qu’ils correspondent aux paramètres du fournisseur.

Type de pagination Aucun

Si l'API du fournisseur n'utilise pas de pagination, définissez le type de pagination ( Pagination type) sur Aucun ( None).

Configuration des ressources

Si vous définissez le type de pagination sur Aucun, l'onglet Pagination est supprimé de la liste des ressources d'activité.

Pagination max.

Le champ Nombre maximal de pagination ( Pagination max ) fait référence au nombre maximal de résultats que le fournisseur peut renvoyer.

Integration Service a un seuil supérieur de 2 000 résultats. Pour améliorer l'efficacité, nous vous recommandons d'utiliser un nombre inférieur.

Définir la méthode d’authentification

Dans l'onglet Authentification , vous configurez le type d'authentification pour votre connecteur. Pour plus d'informations sur les options prises en charge, consultez les Types d'authentification.

Testez votre connexion

Une fois que vous avez terminé la configuration de l'authentification, sélectionnez Ajouter une connexion (Add connection ) dans le menu déroulant :

Si votre connexion est réussie, le statut est mis à jour sur Connecté(Connected) .

Ressources

Le générateur de connecteurs génère la liste des ressources en fonction de la définition d'API fournie. Le menu de gauche affiche la liste des ressources disponibles, organisées en groupes.

1. Cliquez sur Plus d’options (More Options) menu à boutons pour configurer davantage chaque méthode. Vous pouvez :
   • Ajouter une méthode (Add method ) : ouvre la fenêtre Créer une nouvelle ressource (Create new resource).
   • Autoriser la suppression de la méthode ( Allow method suppression ) : active une icône Supprimer (Delete) pour chaque ressource du groupe.
   • Modifier le chemin ( Edit path ) – Modifiez le chemin de la ressource. Par exemple : [BASE URL]/pet = https://petstore.swagger.io/v2/pet
   • Supprimer ( Delete ) – Supprime un groupe de ressources. Un message vous avertit que l'opération ne peut pas être annulée.
   • Dupliquer (Duplicate) : ouvre la fenêtre Dupliquer la ressource (Duplicate resource), dans laquelle vous pouvez modifier le chemin, choisir un nom complet et sélectionner des méthodes.
     
     

     

     
     

2. Vous pouvez également Créer un nouveau groupe de ressources (Create new resource group) de deux manières :

   • vide: configurez les champs suivants :
     • Chemin - [Base URL]/[path]
     • Nom affiché
     • Sélectionnez les méthodes: Get, Get By Id, Post, Put, Patch, Delete
       
       

       

       
       
   • Depuis cURL: saisissez une commande cURL.

Configurez vos ressources

Lorsque vous sélectionnez une ressource, la fenêtre suivante s'affiche :

Selon la méthode de ressource que vous sélectionnez, les onglets de configuration suivants sont disponibles : Paramètres(Parameters), Champs de réponse/demande ( Response/Request Fields), Pagination, Rechercher(Search).

Paramètres

Par exemple, les quatre onglets sont disponibles pour les méthodes GET. Pour les méthodes POST, vous ne pouvez voir que les onglets Paramètres (Parameters), Champs de requête (Request Fields) et Champs de réponse (Response Fields).

Dans Paramètres ( Parameters), vous pouvez afficher la liste des paramètres disponibles pour la ressource sélectionnée, ajouter de nouveaux paramètres ou importer des paramètres à partir d'une ressource existante.

Les paramètres répertoriés dans ce tableau sont ceux que vous utiliserez dans Studio lors de la création d'automatisations à l'aide de votre connecteur personnalisé.

L'objet Pet correspond au groupe de ressources Pet, et les champs disponibles sont ceux définis pour la ressource GETBYID :

Champs de réponse et de demande

Remarque :

Les objets de tableau imbriqué ne sont actuellement pas pris en charge.

Les champs Réponse et Demande de chaque ressource sont générés automatiquement lors de l'envoi d'une demande.

Dans chaque onglet respectif, vous pouvez modifier ou supprimer n'importe quel champ. Si vous cliquez sur l'icône Modifier (Edit), la fenêtre de configuration suivante s'affiche :

Dans l'onglet Champs de réponse/demande ( Response/Request fields), les options suivantes sont également disponibles :

• Case à cocher Remplacer lors de l'envoi de la demande : si cette option est cochée, lorsque vous exécutez une demande d'envoi, la liste des champs est régénérée. Ne sélectionnez pas cette option si vous avez ajouté de nouveaux champs à votre ressource.

• Bouton d'options supplémentaires :

  Option	Ce qu’il fait
  Mettre à jour la clé racine de la réponse	Définissez la clé de réponse lorsque vous traitez des tableaux imbriqués dans la réponse.
  Supprimer tous les champs de la méthode	Supprime tous les champs de la méthode sélectionnée.
  Générer à partir de la charge utile	Utilisez un exemple de charge utile de la documentation du service ou un appel d'API pour générer les champs de ressource.

• Bouton Ajouter une ligne (Add row ) : ajoute de nouveaux champs à la ressource.

Cliquez sur l'icône Colonnes visibles ( Visible columns ) pour ajouter ou supprimer des colonnes dans la table des champs.

Chaque couleur sous la colonne Méthodes correspond à une certaine méthode : Get, Get by ID, Post, Put, Patch, Delete.

Pagination

Activez la pagination pour une ressource si vous attendez une réponse sous forme de liste. Si vous activez la pagination, vous devez également définir la clé racine de la réponse dans l'onglet de configuration, pour les listes imbriquées.

Rechercher

Cochez la case Activer la recherche ( Enable Search) pour autoriser la configuration de la recherche pour une ressource.

Après avoir configuré tout ce dont vous avez besoin, vous pouvez continuer avec .