Création des requêtes d'API

Tous les appels d’API Test Manager sont effectués à l’aide de méthodes HTTP vers l’URL Test Manager. L’URL d’Orchestrator présnte la syntaxe suivante : https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_ . Il est recommandé de chiffrer les données que vous envoyez via les appels API, en utilisant le protocole HTTPS.

Important :

Pour accéder aux ressources d'un dossier, chaque requête doit contenir le FolderId, le FolderPathou le FolderKey dans un en-tête HTTP. Cet en-tête peut être encodé (à l'aide de l'encodage Base64 UTF-16LE) ou en texte brut.

Par exemple :

• X-UIPATH-OrganizationUnitId "FolderId",
• X-UIPATH-FolderPath-Encoded "{Encoded FolderPath value}",
• X-UIPATH-FolderPath "PlainText FolderPath value", ou
• X-UIPATH-FolderKey "FolderKey".

L’ID de dossier FolderId peut être obtenu en envoyant une requête GET vers le point de terminaison /odata/Folders et en copiant la valeur « Id », ou bien à partir de l’URL d’Orchestrator - https://your-domain-server.com/? fid=2032 &tid=8. FolderId est de type Int 64.

Le FolderKey peut être obtenu en effectuant une requête GET au point de terminaison /odata/Folders et en copiant la valeur « Key ». FolderKey est de type ID/chaîne unique.

Si vous modifiez le plan de licence de votre compte Orchestrator (par exemple, d'Enterprise Trial à Enterprise), la valeur FolderId change également, tandis que la valeur FolderKey reste la même.

Si vous avez effectué une mise à niveau et que les unités d'organisation ont été activées dans votre instance précédente d'Orchestrator, chaque unité d'organisation est migrée en tant que nouveau dossier classique.

Les chemins d'accès relatifs aux dossiers sont pris en charge dans un en-tête X-UIPATH-FolderPath-Encoded comme suit :

• Chemin d'accès commençant par / : commence à partir du dossier root de l'arborescence dont il fait partie.
• Chemin d'accès commençant par . : commence à partir du dossier.
• Chemin commençant par .. : commence un niveau au-dessus dans la hiérarchie du dossier pour chaque .. dans le chemin d'accès (par exemple ../ pour un niveau au-dessus, ../../ pour deux niveaux au-dessus dans la hiérarchie).

Notez que les barres obliques finales ne sont pas acceptées.

Important : Lors de l'utilisation de l'API Orchestrator avec MSXML, la réponse 204 Pas de contenu (No Content) peut entraîner un code d'état 1223 et provoquer des erreurs.

Requêtes GET

Les requêtes GET sont généralement les plus simples à effectuer. Elles permettent de récupérer des données et d'utiliser des clauses OData génériques :

• $top
• $filtrer (Filter)
• $Expand
• $select
• $commandepar
• $ignorer

$top

Cette clause permet de limiter la quantité de données que vous récupérez. Elle comprend un plafond supérieur déterminé par le point de terminaison vers lequel vous effectuez des appels et par le nombre de ces ressources qui existent dans vos instances d'Orchestrator.

Par exemple, cette requête https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$top=10 renvoie les 10 premiers environnements disponibles dans l'édition communautaire d'Orchestrator. S'il existe seulement 5 environnements, cependant, seuls ceux-ci sont récupérés.

$filtrer (Filter)

Cette clause OData permet de filtrer une ressource spécifique en fonction de ses propriétés.

Par exemple, il est possible de filtrer en fonction des éléments suivants :

• les propriétés numériques :
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=Id%20eq%2015 : demande un environnement spécifique selon son ID
• les propriétés textuelles :
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=contains(Name,'N')&$top=10 : renvoie les 10 premiers environnements dont le nom commence par la lettre « N »
• les propriétés booléennes :
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true : renvoie tous les processus qui contiennent le mot « test » et qui représentent la dernière version
• les propriétés énumérables :
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems?$filter=Priority%20eq%20'High' : renvoie tous les éléments de file d'attente ayant une haute priorité
• la propriété d'une propriété :
  • https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation' : renvoie les 10 premières tâches exécutées par n'importe quel Robot qui existe sur la machine « Documentation »

Les paramètres de filtre peuvent être combinés à l'aide d'opérateurs logiques « et », « ou » et/ou « pas » et peuvent être regroupés avec des parenthèses « ( ) », telle que la requête suivante :

• https://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10&$filter=Robot/MachineName eq 'LAVINIA-PC' and (not(Source eq 'Manual') or StartTime gt 2017-10-28T12:13:00.07Z) : affiche les 10 premières tâches exécutées manuellement ou après « 2017-10-28T12:13:00.07Z », par un Robot déployé sur la machine « LAVINIA-PC ».

Problème connu

Les requêtes de filtrage OData contenant une expression qui compare un objet complexe imbriqué à null ne fonctionnent pas. Par exemple, l’utilisation de l’expression Release ne null renvoie une erreur, car Release est un objet complexe qui inclut ses propres propriétés imbriquées.

Dans ces cas-là, nous vous recommandons de remplacer l’objet complexe par un objet simple.

Exemples :

• Vous pouvez remplacer Release ne null par ReleaseName ne null, car ReleaseName est un objet simple existant.
  Remarque : vous ne pouvez pas remplacer Machine ne null par MachineName ne null, car MachineName n’existe pas.
• Vous pouvez utiliser une propriété imbriquée pour l’objet complexe à des fins de comparaison. Par exemple, Release/Name ne null peut remplacer Release ne null, et Machine/Name ne null peut remplacer Machine ne null.

$Expand

Cette clause permet de charger entièrement les propriétés de navigation de la ressource demandée.

$select

La clause OData permet de spécifier un sous-ensemble de propriétés de ressources à renvoyer. Pour extraire plusieurs ressources, vous pouvez les séparer à l'aide d'une virgule.

$commandepar

La clause $orderby permet de trier les ressources récupérées. Comme avec la clause $select, les ressources à organiser sont séparées par des virgules, et elles peuvent être triées par ordre croissant (asc) ou par ordre décroissant (desc). Si aucun de ces opérateurs n'est spécifié, les ressources sont automatiquement triées par ordre croissant.

$ignorer

Cette clause vous permet d'ignorer le premier nombre d'éléments, dans un filtre indiqué.

Requêtes POST

Le verbe POST HTTP permet de créer des éléments, subordonnés à d'autres ressources. Lors de la création d'une ressource, envoyez une requête POST au parent, et Orchestrator gère l'association de la nouvelle ressource au parent, en attribuant un ID et d'autres informations souhaitées. Les données sont ajoutées au corps de la requête, et la réponse est l'objet entier créé.

Vous pouvez ajouter des éléments à une file d'attente, créer des actifs, environnements ou processus, attribuer un réviseur à une ou plusieurs transactions ayant échoué, etc.

Remarque : Vous ne pouvez pas échapper les caractères spéciaux dans le corps des requêtes POST. Pour utiliser des caractères spéciaux, vous devez d'abord déclarer le paramètre pour les utiliser en tant que chaîne, à l'aide du format "[e-mail]": "#String" suivant. Pour mieux comprendre, observez comment le paramètre Specific Content a été rempli dans l'exemple ci-dessous.

Requêtes PUT

PUT est généralement requis lorsque vous souhaitez mettre à jour le contenu d'une ressource. En général, les requêtes sont adressées à une entité spécifique en ajoutant son Id dans l'URL. Notez qu'un appel PUT remplace l'entité existante par le contenu de la demande ou, s'il n'en existe pas à l'emplacement désigné, tente de la créer.

Il est possible de mettre à jour les files d'attente, les environnements, les unités d'organisation, les commentaires sur les transactions, les processus et autres détails des ressources.

Requêtes de PATCH

PATCH est utilisé pour mettre à jour le contenu d'une entité existante, avec l'entité souhaitée spécifiée en ajoutant son Id dans l'URL. Le corps de la demande ne contient que le contenu que vous souhaitez modifier. Il se distingue d'un appel PUT qui remplace l'entité actuelle par le contenu de la demande suivante.

Il est possible d'utiliser une requête PATCH pour mettre à jour les entités Machines, Processus, Robots, Locataires (Tenants), Utilisateurs (sauf l'Unité d'organisation et les Rôles) et les Webhooks.

Requêtes DELETE

L'utilisation du verbe HTTP permet de marquer un élément spécifié comme supprimé dans la base de données. La ressource est généralement indiquée à l'aide de son ID dans l'URL vers laquelle vous effectuez l'appel. Une réponse 204 doit vous informer de la réussite de la requête.

Il est possible de supprimer des actifs, des environnements, des commentaires sur les éléments de la file d'attente, des processus, des rôles, des locataires, des utilisateurs, etc.