AE API REST - Informations générales
Si vous êtes développeur ou administrateur système, vous pouvez utiliser l'API REST pour communiquer avec le système Automation Engine via une l'interface de dernière génération et indépendante en termes de technologie.
Cette rubrique contient les sujets suivants :
L'API REST AE propose une interface pour les applications tierces permettant d'interagir avec Automation Engine. L'API REST AE permet également à l'utilisateur de cibler Automation Engine non seulement depuis Java, mais aussi depuis de nombreux langages de programmation.
Les requêtes et réponses REST contiennent des données structurées JSON :
Les propriétés optionnelles dont la valeur est nulle peuvent être enlevées de la charge utile des réponses.
L'API REST AE prend en charge les protocoles HTTP et HTTPS (recommandé). Le protocole HTTPS peut être défini avec le paramètre sslEnabled dans le fichier de configuration Automation Engine (ucsrv.ini). Pour plus d'informations, voir Configuration HTTPS/SSL pour l'API REST AE.
La version actuelle de l'API REST AE est v1. Cette information se répercutant sur l'URI, elle est importante lorsque vous accédez à l'interface de votre API REST Automation Engine.
L'API REST AE peut être installée plusieurs fois. L'installation peut se faire soit avec des numéros de ports différents sur un nœud, soit sur différents nœuds avec le même numéro de port.
Remarques :
-
Toutes les valeurs d'horodatage sont renvoyées telles qu'elles ont été enregistrées dans la base de données sans être converties par Automation Engine. C'est le client REST qui prend en charge une conversion éventuelle.
-
Automation Engine ne vérifie pas la présence d'objets Fuseau horaire lorsqu'il exécute un objet. L'API REST AE ne la vérifie pas non plus.
-
Lorsque vous utilisez l'authentification AE et que vous importez un objet Utilisateur, l'utilisateur est verrouillé. Il doit être déverrouillé dans le client 0 et un nouveau mot de passe doit être défini. Ce comportement ne s'applique pas lorsqu'on utilise l'authentification LDAP.
API REST AE et ILM
Lors du fonctionnement quotidien d'un système Automation Engine, de grandes quantités de données de rapports, statistiques et historiques s'accumulent. Le partitionnement de la base de données avec ILM constitue une méthode efficace pour gérer cela et conserver la version des objets ainsi que les données des objets supprimés. Les actions ILM requièrent de désactiver des parties des tables de la base de données Automation Engine; par conséquent, aucune action sur la base de données ne doit avoir lieu lorsque vous travaillez avec ILM.
Important ! Le service web REST AE détecte automatiquement si des actions ILM sont en cours et, si tel est le cas, bloque certaines requêtes REST. Dans ce cas, un message d'erreur est renvoyé, signalant que l'API REST est momentanément indisponible en raison d'actions ILM.
Les messages de l'API REST sont par défaut en anglais. L'API REST AE ne prend aucune autre langue en charge.
Configurer plusieurs processus de l'API REST
L'installation de JCP est déterminante pour l'API REST AE et la recherche d'objet avancée. Vous pouvez installer un seul JCP. Dans ce cas, toutes les requêtes REST sont envoyées vers cette unique instance de l'API RESTAE et aucune API REST n'est disponible en cas d'arrêt du JCP.
Vous pouvez également configurer un système avec plusieurs JCP. Dans ce cas, deux JCP sont utilisés dans un cluster mais un seul est disponible à la fois.
Important ! En présence de plusieurs JCP, il est impératif que chaque JCP utilise son propre fichier de configuration Automation Engine (ucsrv.ini). Si un seul fichier INI est utilisé pour plusieurs JCP, le premier se connecte avec succès, tandis que les autres s'arrêtent lors de la tentative d'enregistrement du même port REST, si les deux sont exécutés sur le même nœud. Un message d'erreur expliquant le motif de l'arrêt est consigné dans le fichier journal du JCP.
Configurer un système avec plusieurs JCP peut s'avérer avantageux pour équilibrer et obtenir des fonctionnalités de basculement, car les requêtes REST ne sont envoyées et distribuées qu'aux JCP disponibles.
Pour utiliser cette configuration, il faut installer un JCP sur chaque nœud. Port1 et port2 peuvent avoir le même numéro (par exemple 8088, la valeur par défaut dans le fichier de configuration) car les services Web JCP/REST sont exécutés sur des hôtes différents (host1 et host2). Host3:port3 doit être disponible au public en tant que point de contact unique pour toutes les requêtes d'API REST AE. Host1:port1 et host2:port2 ne doivent être connus que par le proxy HTTP / HTTPS.
Si une adresse IP virtuelle est utilisée, les deux JCP peuvent être atteints via la même adresse IP, ce qui signifie que les points terminaux ont la même URI de base : http(s)://{host}:{port}/AE/api/v1/{client}/....
Le client REST ou un proxy HTTP / HTTPS envoie périodiquement une requête /ping pour vérifier la disponibilité des JCP. Selon le résultat, le proxy HTTP / HTTPS connaît les JCP disponibles à ce moment-là.
- En configuration Haute disponibilité active / active, les deux sont supposés être disponibles.
- En configuration Haute disponibilité active / passive, seul l'un deux est supposé être disponible.
Le client REST ou HTTP / HTTPS décide ensuite où envoyer les requêtes REST, en fonction de la stratégie de sélection du proxy. Lorsque le client REST envoie les requêtes au proxy HTTP / HTTPS (host3:port3), le proxy les distribue automatiquement à un service web JCP/REST.
- En configuration Haute disponibilité active / active, il les envoie à celui des deux qui est disponible. Celui qui est utilisé dépend de la stratégie de sélection du proxy (par exemple, charge de connexions la moins lourde).
- En configuration Haute disponibilité active / passive, il les envoie à celui qui est disponible.
Requêtes de vérification de santé
L'API REST AE propose deux différentes requêtes de vérification de santé :
-
une requête /ping rapide utilisée par les proxies HTTP / HTTPS garantissant la disponibilité du JCP et du service Web REST. Cette vérification de santé ne donne aucune information sur les composants de backend requis :
../ping
-
une vérification de santé des informations système qui donne des informations sur le JCP et le service Web REST. Cette vérification de santé donne également des informations sur les composants de backend requis :
../{client}/system/health
L'API REST AE prend en charge l'authentification de base. Les informations relatives à l'utilisateur, au département et au mot de passe font partie de l'en-tête HTTP(S) et sont donc utilisées pour l'authentification de base. Automation Engine décide si une requête dans le contexte utilisateur est ou non autorisée et y répond en conséquence.
L'API REST AE ne prend pas en charge le chiffrement du mot de passe pour le mot de passe de la requête REST. Il est recommandé d'utiliser le protocole HTTPS pour sécuriser la transmission de ces informations.
Autorisations
Un système efficace et sécurisé pour protéger l'accès aux données est un élément clé de notre concept de sécurité. La sécurité au niveau des données peut être aussi étendue que l'accès de l'administrateur à un rôle ou aussi restreinte que l'accès en lecture à un seul job d'un répertoire précis.
L'API REST AE requiert également certaines autorisations pour effectuer différentes opérations et vérifie si elles sont en place au moment de les effectuer.
-
Pour récupérer les variables, les commentaires et les rapports d'une exécution (GET) il vous faut l'autorisation S - Exécutions.
-
Pour ajouter des commentaires à une exécution (POST), il vous faut l'autorisation M - Modifier à l'exécution.
Pour plus d'informations, voir Accorder des autorisations Automation Engine.
Pour éviter l'expiration de délai des requêtes, l'objet à exécuter doit avoir défini l'attribut Générer la tâche à l'exécution. Lors de l'exécution d'un objet, le système vérifie si cet attribut a été défini en conséquence. S'il n'a pas été défini, l'exécution ne démarre pas.
En définissant cet attribut, le RunID est immédiatement renvoyé, de sorte que la réponse REST vient immédiatement après la requête.
Si cet attribut est défini par Générer la tâche à l'activation, la longueur du temps de traitement peut empêcher une réponse REST immédiate et entraîner une expiration du délai.
Remarque : Lors de la reprise d'une exécution, l'attribut Générer la tâche à l'exécution n'est pas défini.
Interrogation de l'API REST AE
Vous pouvez interroger le serveur pour vérifier le statut d'une séquence requête / réponse REST lorsque le résultat souhaité n'est pas encore disponible. Ainsi, vous pouvez interroger le serveur après l'exécution d'un objet et obtenir le RunID pour vérifier si l'exécution est terminée.
L'exemple suivant montre comment interroger le statut d'exécution via l'API REST AE :
Les variables PromptSet peuvent être transmises via la requête de l'API REST AE à l'exécution, à condition que les objets devant être exécutés aient au moins un promptset affecté.
Exemple de contenu de requête REST :
| Variable PromptSet | Champ Type | Recommandations |
|---|---|---|
| "&TEXT1#" | Champ texte | n/d |
| "&NUMBER1#" | Champ numérique | n/d |
| "&CHECKBOX_ARRAY#" | Champ Case à cocher* | Array=true |
| &CHECKBOX_STRING# | Champ Case à cocher | Array = false, separator = ";" |
| "&MULTILINE1#" | Champ de texte multilignes | Attribut "Multilignes" coché, \n pour sauts de lignes |
* Il est recommandé de définir un champ Case à cocher en tant que Tableau ("Array") lorsqu'il sert à transmettre des valeurs via l'API REST AE.
Remarques :
-
L'attribut "Array" du champ PromptSet CHECKBOX_ARRAY doit être vrai ("true") car Automation Engine doit le traiter comme un tableau.
-
Aucune variable d'objet ne peut être définie ici.
-
Certaines requêtes REST contiennent le paramètre inputs, qui répertorie les variables PromptSet. Ce contexte implique que ce ne sont que des variables et qu'il n'est pas nécessaire de mettre un "&" devant. Le "#" à la fin dépend de la définition de la variable.
Filtre de la liste des exécutions
La requête GET ../v1/{client}/executions renvoie une liste de toutes les exécutions. Vous pouvez ajouter des paramètres à la requête dans l'URI pour les filtrer.
Remarque : Interface Web Automic dispose de différents paramètres pour les vues liste, qui sont importants lorsque vous appliquez des filtres. La vue en arborescence qui, en présence de filtres, n'affecte que les tâches parents, et la vue liste qui affecte les deux (les tâches parents et enfants). L'API REST AE ne prend en charge que la vue liste.
Vous pouvez appliquer des filtres pour les paramètres d'exécution suivants :
-
name
Saisissez le nom (..?name=[NAME]) ou la partie de nom (..?name=[NAM]*) des tâches recherchées.
Remarque : Les paramètres d'une requête ne peuvent être utilisés qu'une seule fois.
-
alias
L'alias est un nom supplémentaire et optionnel donné à une tâche faisant partie d'un workflow. S'il est défini, l'alias s'affiche à la place de son nom.
Saisissez l'alias (..?alias=[NAME]) ou la partie d'alias (..?alias=[NAM]*) de l'exécution recherchée.
Remarque : Les paramètres d'une requête ne peuvent être utilisés qu'une seule fois.
Si vous souhaitez définir des caractères spéciaux pour l'alias d'exécution, vous devez définir le paramètre ALIAS_SPECIAL_CHARACTERS dans UC_CLIENT_SETTINGS - Divers paramètres du client du client correspondant.
-
type
Vous pouvez ajouter des paramètres à une requête pour filtrer les objets suivants : CALL, SCRI, JOBD, CPIT, JOBG, C_PERIOD, JOBF, REPORT (rapports de jobs d'agents uniquement), JSCH, JOBP, JOBS, JOBQ, EVNT, API, C_HOSTG.
Remarque : Ce paramètre vous permet d'utiliser plusieurs valeurs. Vous pouvez soit utiliser ce paramètre une fois et séparer les valeurs par des virgules (type=JOBS,JOBP), soit utiliser le paramètre plusieurs fois dans une requête (type=JOBS&type=JOBP).
-
Intervalle de temps
Utilisez une combinaison des paramètres suivants pour trouver les exécutions d'un intervalle de temps donné.
-
time_frame_option : Utilisez ce paramètre pour définir le type d'exécution que vous souhaitez trouver dans un certain intervalle de temps. Les valeurs autorisées sont :
-
toutes : toutes les exécutions qui commencent, se terminent ou s'exécutent dans l'intervalle de temps spécifié
-
activation : toutes les exécutions activées dans l'intervalle de temps spécifié
-
start : toutes les exécutions démarrées dans l'intervalle de temps spécifié
-
end : toutes les exécutions terminées dans l'intervalle de temps spécifié
-
-
time_frame_from : date de début et intervalle de temps
-
time_frame_to : date de fin et intervalle de temps
-
-
status
Ce paramètre vous permet de rechercher n'importe quel statut enregistré par Automation Engine. Pour plus d'informations, voir Codes retour système des objets exécutables.
Remarque : Ce paramètre vous permet d'utiliser plusieurs valeurs. Vous pouvez soit utiliser ce paramètre une fois et séparer les valeurs par des virgules (status=1900,1800), soit utiliser le paramètre plusieurs fois dans une requête (status=1900&status=1800).
-
agent
Saisissez le nom de l'agent (..?name=[NAME]) ou la partie de nom (..?name=[NAM]*) de l'exécution recherchée.
Remarque : Les paramètres d'une requête ne peuvent être utilisés qu'une seule fois.
-
platform
Ce paramètre vous permet de trouver les exécutions traitées par un type d'agent spécifique, telles que toutes les exécutions traitées par les agents Windows, par exemple.
Remarque : Ce paramètre vous permet d'utiliser plusieurs valeurs. Vous pouvez soit utiliser ce paramètre une fois et séparer les valeurs par des virgules (platform=WIN,LINUX), soit utiliser le paramètre plusieurs fois dans une requête (platform=WIN&platform=LINUX).
-
queue
Ce paramètre vous permet de rechercher les queues d'exécutions.
Remarque : Ce paramètre vous permet d'utiliser plusieurs valeurs. Vous pouvez soit utiliser ce paramètre une fois et séparer les valeurs par des virgules (queue=CLIENT_QUEUE,PRIO_QUEUE), soit utiliser le paramètre plusieurs fois dans une requête (queue=CLIENT_QUEUE&queue=PRIO_QUEUE).
-
include_deactivated
Le paramètre include_deactivated vous permet d'inclure les exécutions désactivées dans la recherche lorsque vous appliquez des filtres, car ils ne sont pas pris en compte par défaut.
Ce paramètre peut avoir un impact sur l'intervalle de temps :
-
Si le paramètre est =false ou manquant et qu'aucun intervalle de temps n'est défini, la valeur interne par défaut de l'intervalle de temps est illimitée
-
Si le paramètre est =true et qu'aucun intervalle de temps n'est défini, la valeur interne par défaut de l'intervalle de temps est de 12 heures.
-
Vous pouvez combiner les paramètres d'une requête selon les besoins pour générer des filtres simples ou complexes. Ainsi, vous pouvez :
-
Rechercher un nom d'exécution spécifique excluant les exécutions désactivées
../executions?name=JOBS.24
-
Rechercher un nom d'exécution spécifique incluant les exécutions désactivées
../executions?name=JOBS.24&include_deactivated=true
-
Rechercher un ensemble spécifique de types d'exécutions
../executions?type=JOBP&type=JOBS
../executions?type=JOBP,JOBS
-
Rechercher un intervalle de temps absolu
../executions?time_frame_option=all&time_frame_from=2017-07-04T12:43:45Z&time_frame_to=2017-07-04T06:23:12Z
-
Utiliser des caractères génériques (pris en charge pour nom, alias, agent, utilisateur et archive_key1&2)
Remarque : Si vous utilisez le caractères générique * dans votre recherche, vous ne pouvez utiliser qu'une seule fois le paramètre de requête concerné.
../executions?name=NAME
../executions?alias=NAM*
-
Utiliser des filtres complexes
../executions?name=OBJECT&type=JOBP&type=JOBS&queue=CLIENT_QUEUE&queue=PRIO_QUEUE&status=1900,1800&include_deactivated=true&time_frame_option=all&time_frame_from=2017-07-04T12:43:45Z&time_frame_to=2017-07-04T06:23:12Z
Pagination pour les enfants d'exécutions et les listes d'exécutions
La pagination peut s'avérer utile lorsqu'une requête d'API REST AE renvoie plusieurs résultats, car l'ensemble des résultats, susceptible de changer rapidement et souvent, est divisé en morceaux (pages) par requête / réponse. Ainsi, si vous envoyez une requête pour obtenir tous les enfants d'une exécution, vous risquez d'obtenir des milliers d'enregistrements. L'API REST AE vous permet d'utiliser la pagination pour faciliter la gestion des résultats.
Paramètres de limite
L'API REST AE vous permet de définir les paramètres de limite suivants :
-
max_results
Nombre maximal de résultats par page.
Valeur par défaut : 50
En l'absence de ce paramètre, c'est la valeur par défaut qui est utilisée.
-
start_at_run_id
RunID de la dernière entrée de la page précédente.
En l'absence de ce paramètre, c'est la première page qui est renvoyée.
Structure URI avec paramètres de pagination
L'URI contenant les paramètres de pagination se compose des éléments suivants :
http://{host}:{port}/AE/api/v1/{client}/executions/{runid}/children?max_results={number}&start_at_run_id={runid}
Par exemple :
http://192.168.40.116:8088/AE/api/v1/100/executions/1003003/children?max_results=10&start_at_run_id=100301
Dans cet exemple, la requête d'exécution parent demandée 1003003 a 25 requêtes d'exécutions enfants. La réponse paginée est répartie comme suit :
| Page | Requête URI | Charge utile de la réponse | Commentaire |
|---|---|---|---|
| 1 | ../executions/1003003/children?max_results=10 |
Liste des 10 premières exécutions RunID de la dernière exécution listée =1003045 "hasmore"=true(*) "total"=25(**) |
En l'absence du paramètre start_at_run_id, c'est la première page qui est renvoyée. |
| 2 | ../executions/1003003/children?max_results=10&start_at_run_id=1003045 |
Liste des 10 exécutions suivantes RunID de la première exécution listée <1003045 RunID de la dernière exécution listée =1003034 "hasmore"=true(*) "total"=25(**) |
Le RunID de la première exécution de la page 2 est inférieur à celui de la dernière exécution page 1, il n'y a donc pas de listing dupliqué. |
| 3 | ../executions/1003003/children?max_results=10&start_at_run_id=1003034 |
Liste des 5 prochaines exécutions RunID de la première exécution listée <1003034 RunID de la dernière exécution listée =1003028 "hasmore"=false(*) "total"=25(**) |
"hasmore"=false indique que c'est la dernière page. |
-
* total : indique le nombre total de ressources dans la collection et permet de déterminer le nombre de pages du résultat.
-
**hasmore : a les valeurs possibles suivantes :
-
true = d'autres pages sont disponibles
-
false = vous avez atteint la dernière page
-
Remarques :
-
Les exécutions qui s'affichent dans une page donnée sont classées par heure d'activation et RunID décroissants.
-
La pagination peut donner une liste incomplète d'exécutions enfants. Si, par exemple, une page P demandée liste toutes les exécutions dont l'heure d'activation est >=T1 et le RunID < R1 et qu'une nouvelle exécution E est générée ultérieurement avec la même heure d'activation, mais un RunID < R1, l'exécution E ne sera listée ni en page P, ni en page suivante.
La pagination est également utile lorsqu'un rapport est plutôt volumineux et que son contenu est fractionné en pages de rapport. L'API REST AE effectue la pagination de ces pages de rapport.
Paramètres de limite
-
max_results
Nombre maximal d'entrées (pages de rapport) retournées.
Valeur par défaut : 1
Si ce paramètre est zéro (0), aucune entrée n'est retournée.
-
start_at
Numéro de la page de début (entrée / page de rapport) retournée.
Valeur par défaut : 1
Si ce paramètre n'est pas défini, les entrées retournées commencent par la première page du rapport. Si la valeur définie est supérieure au nombre d'entrées disponibles, aucune information n'est renvoyée car la requête dépasse la plage de pages du rapport disponibles.
Par exemple :
-
...exectutions/{run id}/reports/REP renvoie la totalité du rapport (toutes les pages du rapport)
-
...exectutions/{run id}/reports/REP?max_results=3 renvoie la première partie des trois (3) pages du rapport (pages de rapport 1, 2 et 3)
-
...exectutions/{run id}/reports/REP?max_results=3&start_at=4 renvoie la première partie des trois (3) pages du rapport (pages de rapport 4, 5 et 6)
-
...exectutions/{run id}/reports/REP?start_at=2 renvoie toutes les pages du rapport à l'exception de la première
-
Important ! La requête de l'API REST AE ne peut porter que sur le contenu des rapports disponibles dans la base de données AE. Un rapport de job est enregistré dans la base de données si l'option Enregistrer dans : base de données a été sélectionnée dans la section Rapport du job de la page de définition du job. Cette option est sélectionnée par défaut.
Toutes les activités REST peuvent être tracées à des fins d'analyse. Pour ce faire, sélectionnez un JCP puis faites un clic droit pour sélectionner Options avancées. Cela ouvre une boîte de dialogue où vous pouvez spécifier les indicateurs de trace.
L'indicateur de trace peut également être défini dans le fichier (INI) de configuration Automation Engine. Pour ce faire définissez la clé JCL dans la section TRACE du fichier INI. Les valeurs importantes pour Agent RA Web Service REST sont :
- 0 : Trace désactivée
- 1 : Trace le contenu et les en-têtes REST
- 2 : Trace également les informations de login
Configuration du serveur Web
Le service Web REST Automation Engine utilise un serveur Web utilisant principalement une configuration prédéfinie. Si vous êtes administrateur système , vous pouvez personnaliser les paramètres répertoriés ici dans la section [REST] du fichier de configuration (ucsrv.ini) :
-
Cross-Origin Resource Sharing / Same Origin Policy (CORS/SOP)
-
corsSupportEnabled
-
corsAccessControlAllowOrigin
-
-
GZIP Compression
-
gzipSupportEnable
-
-
ThreadPool
-
minPoolSize
-
maxPoolSize
-
idleTimeout
-
CORS/SOP
La politique de même origine (SOP = Same Origin Policy) empêche les clients Web d'effectuer des demandes de différentes origines. Vous pouvez contourner cette politique en utilisant le partage de ressource de différentes origines (CORS = Cross-Origin Resource Sharing), afin d'autoriser les origines explicitement.
Par exemple :
L'hôte 3 demande un document Web d'origine 1 (Hôte 1, serveur Web) à http://host1:80 (port http par défaut). L'hôte 3 envoie ensuite une demande d'information de l'origine 2 (Hôte 2, AE) à http://host2:8080 (port de service Web REST AE par défaut). La plupart des navigateurs Web usuels vérifient si les demandes inter-domaines sont ou non autorisées. Si non, la demande vers la deuxième origine http://host2:8080 n'est pas autorisée.
Afin d'autoriser ce type de requêtes d'origine croisées, le service Web REST AE doit explicitement demander au navigateur Web d'autoriser la requête. Vous pouvez le définir via le paramètre CORS de la section [REST] du fichier de configuration Automation Engine (ucsrv.ini) :
- corsSupportEnabled=1
- corsAccessControlAllowOrigin=http://host1:80
Si le serveur Web est exécuté sur le même hôte local que le client Web ou le navigateur (Host1 = Host3), vous devez implémenter un simple client REST basé Web, en définissant le paramètre corsAccessControlAllowOrigin à http://localhost:80.
Compression
Un client REST peut demander que la charge utile de réponse soit compressée, afin d'améliorer les performances. Si le service Web REST prend en charge la compression, il renvoie la charge utile au format gzip.
La prise en charge de la compression est désactivée par défaut. Vous pouvez l'activer via le paramètre gzipSupportEnabled de la section [REST] du fichier de configuration Automation Engine (ucsrv.ini).
Thread Pooling
Le serveur Web utilisé par le service Web JCP/REST traite les requêtes à l'aide de threads. Plus on utilise de threads, plus on peut traiter de requêtes REST en parallèle.
Un thread pool conserve plusieurs threads en attente de traitement des requêtes REST. Plus il y a de requêtes entrantes, plus le serveur Web libère de threads automatiquement dans la plage définie dans minPoolSize >= N <= maxPoolSize. Lorsque certains des N threads restent inutilisés pendant un laps de temps supérieur au délai d'expiration défini dans le paramètre idleTimeout, ils sont supprimés afin de libérer des ressources dans le processus JCP.
Voir aussi :