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

Créer un nouveau connecteur

1. If you select Start from an API definition, you must provide the API definition:

   • À 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. Sélectionnez continuer (continue).

Configurez votre connecteur

1. In the Confirm import window, you can:

   • Modifiez le Nom du fournisseur, le Nom de l'application, et le Nom du connecteur.

   • 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.

     • Use the Search bar to look for a specific resource.

   • Sélectionnez Créer.

     

2. The Settings window is now displayed.

3. In the Info tab you can configure the following fields:

   • Nom : cela se reflète dans votre clé de connecteur.
   • API type – This field is disabled by default, as only REST is currently supported.
   • Catégories : vous pouvez choisir parmi les catégories disponibles, telles que Intelligence artificielle ou Marketing, ou créer votre application.
   • Description – Enter a description for your connector.
   • Icône : sélectionnez Parcourir pour télécharger une image depuis votre ordinateur. Tous les types d'images sont pris en charge, mais nous recommandons d'utiliser un fichier SVG carré.

4. Catalog preview displays how your custom connector will appear in the Integration Service connector catalog.

5. Sélectionnez Enregistrer.

   

Configurer l'API de base

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

• Base URL – Automatically filled with the value declared at connector creation.

• 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 de plus amples informations, reportez-vous à la section Pagination .

• Pagination max – Default value is 100. If the vendor documentation doesn’t provide any details on pagination, keep the default value.

• 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 > API de base, en définissant les champs Type de pagination et Nombre de 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 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écifiez et configuriez le bon type de pagination.

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 les pages, comme expliqué dans la section Utilisation de la pagination dans l'API REST. Ils ont inclus l’URL de la page suivante dans l’en-tête de réponse pour faciliter l'implémentation, mais le mécanisme sous-jacent est basé sur les paramètres de requête Page et par 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 des résultats a un index de un (par exemple, page=1),
• La page commence par 0 fait référence à la pagination où la première page des résultats se trouve à l'index 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 les remplacer par les spécifications du fournisseur comme suit :

1. Sélectionnez votre ressource.
2. Sélectionnez l'onglet 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 pour 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 la pagination basée sur le curseur dans le générateur de connecteurs. La documentation de méta-pagination spécifie où dans chaque requête vous trouvez le jeton de page suivante et comprend une référence directe au jeton ou à l'URL complète. Nous pouvons utiliser ces exemples pour créer des pagination de ressources pour l'API Meta Graph.

1. Sur la ressource sélectionnée, mettez à jour le nom du jeton prochainPage et le nom de la taille de la page pour qu'il corresponde à l'API du fournisseur. Selon la documentation de l'API Meta Graph, le nom du jeton prochainPage est ajouté après et la taille de page est la limite.

2. Ensuite, identifiez où le jeton NextPage est disponible sur chaque requête. La documentation nous fournit ce fichier 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="  }}

Elle fait partie du corps de la réponse, vous pouvez donc configurer le jeton NextPage 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 décalée utilise des nombres d'enregistrement pour permettre la pagination dans tous les objets de réponse. Le paramètre Offset 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 pour 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 les remplacer par les spécifications du fournisseur comme suit :

1. Sélectionnez votre ressource.
2. Sélectionnez l'onglet 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 la pagination, définissez le Type de pagination sur Aucune.

Configuration des ressources

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

Pagination max.

Le champ Pagination max. fait référence au nombre maximum 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. Reportez-vous à lasection Types d’authentification pour de plus amples informations sur les options prises en charge.

Testez votre connexion

Once you have completed the authentication configuration, select Add connection from the drop-down menu:

If your connection is successful, the status is updated to 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. Sélectionnez les options supplémentaires pour configurer davantage chaque méthode. Vous pouvez :

   • Add method – Opens the Create new resource window.

   • Allow method deletion – Activates a Delete icon for each resource in the group.

   • Edit path – Edit the resource’s path. For example: [BASE URL]/pet = https://petstore.swagger.io/v2/pet

   • Delete – Deletes a resource group. A message warns you that the operation cannot be undone.

   • Dupliquer : ouvre la fenêtre Dupliquer la ressource , 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 de deux manières :
   • Vide: configurez les champs suivants :

     • Path - [Base URL]/[path]

     • Nom affiché

     • Select methods: 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 :

Depending on the resource method you select, the following configuration tabs are available: Parameters, Response/Request Fields, Pagination, Search.

Paramètres

Par exemple, les quatre onglets sont disponibles pour les méthodes GET. Pour les méthodes POST, seuls les onglets Paramètres (Parameters), Champs de demande (Request Fields) et Champs de réponse (Response Fields) s'affichent.

Dans Paramètres, 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é.

The Pet object corresponds to the Pet resource group, and the available fields are the ones set for the GETBYID resource:

Champs de réponse et de demande

Remarque :

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

The Response and Request fields for each resource are automatically generated upon sending a request.

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

In the Response/Request fields tab, the following options are also available:

• Case à cocher Remplacer lors de l'envoi de la demande - Si cette option est sélectionnée, lorsque vous exécutez une requête 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.

• Additional options button:

  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.

• Add row button - Adds new fields to the resource.

Sélectionnez l'icône Colonnes visibles pour ajouter ou supprimer des colonnes dans la table des champs.

Each color under the Methods column corresponds to a certain method: Get, Get by ID, Post, Put, Patch, Delete.

Pagination

Enable Pagination for a resource if you expect a list response. If you enable pagination, you also need to define the Response root key in the configuration tab, for nested lists.

Rechercher

Activate the Enable Search checkbox to allow search setup for a resource.

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