Exécution des commandes REST

De nombreux programmes peuvent exécuter des commandes REST. Pour exécuter la commande, vous appelez une méthode dans une ressource REST et transmettez des paramètres ou une demande au format JSON.

Remarque : L'utilisation de commandes REST requiert les mêmes droits d'accès que l'utilisation de l'interface Web. Pour des informations sur les droits d'accès, voir Rôles et autorisations.

Exemple : exécution de commandes REST simples avec curl

Le programme Linux curl permet d'exécuter des commandes REST facilement. Pour exécuter une commande REST, construisez l'adresse URL de l'une des ressources REST, spécifiez la méthode à utiliser et ajoutez les paramètres de votre choix. Par exemple, la commande curl suivante extrait la liste de tous les composants actifs. Elle appelle la méthode GET de la ressource component et transmet la valeur true pour le paramètre active :

curl -k -u jsmith:passw0rd 
  https://nomhôte:port/cli/component?active=true 
  -X GET

Remarque : Vous devez entrer cette commande sur une seule ligne. Elle apparaît ici sur plusieurs lignes pour plus de clarté.

Remarque : Cet exemple utilise le commutateur -k pour la connexion au serveur sans vérifier la validité du certificat SSL. Pour configurer l'authentification, voir Authentification pour les commandes REST.

Cet exemple utilise le nom d'utilisateur jsmith et le mot de passe passw0rd. Dans la plupart des cas, vous pouvez créer un compte utilisateur dédié pour les commandes REST pour utiliser et donner à ce compte les droits adéquats.

Indiquez le nom d'hôte et le port de votre serveur pour nomhôte et port. Par exemple, si le nom d'hôte est ucdeploy.example.org et que le port est la valeur par défaut 8443, la commande curl peut être similaire à l'exemple suivant :

curl -k -u jsmith:passw0rd 
  https://ucdeploy.example.org:8443/cli/component?active=true 
  -X GET

La réponse à cette commande est une liste au format JSONArray de tous les composants actifs sur le serveur. Pour un exemple de réponse, voir Get information about all components on the server.

Transmission de paramètres aux commandes REST

La plupart des commandes REST possèdent un ou plusieurs paramètres. Pour les transmettre, ajoutez-les à l'adresse URL. Par exemple, la méthode GET de la commande version/getLink admet trois paramètres : le nom ou l'ID de l'application, le nom ou l'ID de la version et le nom du lien. Voici un exemple de commande permettant d'obtenir un lien dans le composant JPetStore-APP :

curl -k -u jsmith:passw0rd 
  "https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/
  version/getLink?component=JPetStore-APP
  &version=1.0
  &linkName=Site%20Web%20IBM"

Dans ce cas, chaque paire paramètre-valeur est ajoutée à l'adresse URL, après un point d'interrogation (?). Une perluète (&) sépare chaque paire. Etant donné que curl est une commande Linux et que la perluète possède une signification spéciale sur la ligne de commande Linux, l'adresse URL, avec les paramètres, est placée entre guillemets.

Remarque : Toutes les valeurs de paramètre doivent être codées au format URL. L'exemple précédent transmet la valeur Site Web IBM pour le paramètre linkName. Pour inclure ce paramètre dans l'adresse URL, les espaces doivent être remplacés par la valeur de codage d'URL %20.

Transmission de chaînes JSON aux commandes

Pour des commandes plus complexes, vous devez envoyer un fichier ou une chaîne JSON à la place ou en plus des paramètres.

Par exemple, la méthode PUT de la ressource application/create crée une application. Pour utiliser cette commande, vous devez transmettre une chaîne JSON qui spécifie le nom, la description et certaines propriétés de la nouvelle application. La chaîne JSON pour cette commande doit respecter le modèle suivant :

{
  "description": "Description",
  "enforceCompleteSnapshots": "Specify true to require 
     an explicit version for each component",
  "name": "Application name or ID",
  "notificationScheme": "Notification scheme"
}

Ce modèle est répertorié dans les informations de référence relatives à la commande. Voir Create an application from a JSON file.

Par exemple, la chaîne JSON suivante représente une application appelée My Application :

{
  "description": "My new application",
  "enforceCompleteSnapshots": "false",
  "name": "My Application",
  "notificationScheme": "Default Notification Scheme"
}

Pour transmettre cette chaîne JSON à la ressource application/create, vous pouvez sauvegarder la chaîne dans un fichier ou l'inclure dans la commande. Par exemple, si vous sauvegardez la chaîne dans un fichier appelé newApplication.json, la commande est similaire à l'exemple suivant :

curl -k -u jsmith:passw0rd 
  https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/application/create 
  -X PUT -d @newApplication.json

Vous pouvez aussi transmettre la chaîne directement à la commande, conformément à l'exemple suivant :

curl -k -u jsmith:passw0rd 
  https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/application/create 
  -X PUT 
  -d {"description":"My new application",
      "enforceCompleteSnapshots":"false",
      "name":"My Application 67",
      "notificationScheme":"Default Notification Scheme"}

Remarque : La chaîne que vous transmettez à la commande doit être une chaîne JSON valide.

Composition de chaînes JSON

Vous pouvez obtenir le modèle de la chaîne JSON pour une commande de deux façons. Les modèles sont répertoriés dans les informations de référence de chaque commande. Vous pouvez aussi exécuter la commande de client de ligne de commande équivalente avec l'option -t. L'exécution de la commande d'interface de ligne de commande (CLI) avec cette option affiche le modèle JSON.

Etant donné que l'interface du serveur utilise l'API REST, vous pouvez aussi vous connecter au serveur comme d'habitude et surveiller les demandes que l'application Web génère. Vous pouvez les surveiller avec des extensions de navigateur Web ou des programmes externes. Par exemple, pour afficher la chaîne JSON pour la méthode PUT de la ressource resource/create, créez une ressource sur le serveur Web, puis recherchez la chaîne JSON dans la demande de navigateur, conformément à la figure ci-dessous. La chaîne JSON pour les commandes REST est la même ou est similaire à cette chaîne.

Utilisation d'une extension de navigateur Web pour surveiller les chaînes JSON que le serveur utilise

Réponses

Lorsqu'elles aboutissent, la plupart des commandes renvoient une valeur de chaîne simple ou une chaîne JSON.

En plus du résultat de la commande, les commandes renvoient des codes de statut HTTP standard. La liste ci-dessous répertorie les codes de statut les plus courants renvoyés par les commandes REST.

200

La commande a abouti.

400

Vous ne disposez pas des droits permettant d'exécuter la commande.
Vous n'avez pas spécifié un paramètre requis.
Le chemin de ressource dans l'adresse URL est incorrect.

404

L'objet que vous tentez d'extraire n'existe pas.

405

Le nom de la méthode HTTP est incorrect.

415

Le type de contenu dans l'en-tête de la demande est incorrect.

500

Le serveur a rencontré une erreur.

Retour d'informations