C Sharp

Consommation des WSDL SOAP

Vous pouvez importer les WSDL de l'API SoftLayer dans votre projet selon deux méthodes. Visual Studio peut consommer un service SOAP dans une référence Web accessible par votre projet. Visual Studio s'accompagne par ailleurs d'un utilitaire nommé wsdl.exe, lequel s'exécute à partir d'une invite de commande pour lire un ou plusieurs fichiers WSDL et pour convertir directement ces fichiers en code source que vous pouvez ajouter à votre projet. En règle générale, les services Web sont plus faciles à utiliser dans Visual Studio, mais ils peuvent devenir encombrants si votre projet utilise un grand nombre de services API de SoftLayer. Si tel est le cas, vous aurez grand intérêt à utiliser wsdl.exe.

Les exemples de code qui apparaissent dans cet article illustrent le code généré par wsdl.exe à partir des services API de SoftLayer.

Création de références Web

La création de références Web est la première chose à faire lorsque vous consommez des WSDL SOAP. Suivez les étapes ci-après pour créer une référence Web dans Visual Studio.

  1. Cliquez sur le menu Projet de Visual Studio.
  2. Sélectionnez Ajouter une référence de service dans la liste déroulante du menu Projet.
  3. Cliquez sur le bouton Avancé de la fenêtre Ajouter une référence de service.

    Remarque : La fenêtre Définition des références de service s'ouvre.

  4. Cliquez sur le bouton Ajouter une référence Web de la fenêtre Définition des références de service.
  5. Dans la zone URL, entrez l'URL WSDL pour le service API SoftLayer que vous voulez utiliser.
  6. Cliquez sur la flèche verte à droite de la zone URL.

    '''Remarque : Visual Studio va télécharger le fichier WSDL et analyser les méthodes et types de données qu'il contient.

  7. Entrez un nom pour votre nouvelle référence Web dans la zone Nom de la référence Web.
    '''Remarque : Toute référence au service API que vous aurez ajoutée au projet se verra attribuer le nom de ce projet.
  8. Cliquez sur le bouton Ajouter une référence pour importer le nouveau service Web.

    Remarque : Vous allez maintenant être redirigé vers votre projet et votre nouveau service API apparaîtra dans l'Explorateur de solutions de Visual Studio.

L'exemple ci-après crée une référence de service nommée "com.softlayer.api", mais vous pouvez attribuer tout nom de votre choix aux services Web que vous créez. Le nom de votre référence Web est un espace de nom au sein de votre projet. Entrez l'instruction using au début du votre programme de façon à n'avoir pas à taper le nom de la référence Web pour chacune de vos instructions API. Par exemple, vous entrerez l'instruction suivante :

using projectName.com.softlayer.api;

Remplacez "projectName" par le nom de votre projet Visual Studio afin de définir votre référence Web en tant qu'espace de nom par défaut.

Utilisation de wsdl.exe

La commande Wsdl.exe se trouve dans C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin. Execute Wsdl.exe avec les commutateurs suivants pour la conversion des WSDL de l'API SoftLayer en code C# :

  • /language:CS - Demande à wsdl.exe d'exporter le code C#.
  • /sharetypes - Les fichiers WSDL de SoftLayer partagent un certain nombre de types de données similaires. Le commutateur /sharetypes compile ces types de données en fichiers de classe uniques, ce qui réduit l'encombrement du source et permet de travailler plus efficacement dans Visual Studio.
  • /out:C:\path\to\project\SoftLayer_API.cs - Le code généré va être exporté vers un chemin au sein de la hiérarchie de votre projet. Ici, nous allons enregistrer le code dans fileSoftLayer_API.cs.

Pour compléter la commande, entrez une liste (avec espaces de séparation) répertoriant les URL des WSDL que vous voulez importer pour l'API. Vous pouvez importer autant de fichiers WSDL que vous voulez.

wsdl.exe /language:CS /out:"C:\Path\to\Project\SoftLayer_API.cs" /sharetypes 
https://api.softlayer.com/soap/v3/SoftLayer_Account?wsdl 
https://api.softlayer.com/soap/v3/SoftLayer_Hardware_Server?wsdl 
https://api.softlayer.com/soap/v3/SoftLayer_Dns_Domain?wsdl

Remarque : Pour effectuer des appels API privés, remplacez https://api.softlayer.com par http://api.service.softlayer.com. Pour plus de détails concernant les appels API privés, reportez-vous à notre article Mise en route.

Si vous souhaitez importer davantage de services API dans votre projet, réexécutez cette commande.

Une fois votre fichier de code créé, vous devez l'ajouter à votre projet. Pour cela, suivez les étapes ci-après :

  1. À l'aide du bouton droit de la souris, cliquez sur le nom du projet dans l'Explorateur de solutions de Visual Studio.
  2. Sélectionnez l'option Ajouter dans le menu développé.
  3. Cliquez sur le bouton Element existant du menu Ajouter.
  4. Localisez votre fichier de code généré dans la fenêtre de dialogue Ajouter un élément existant.
  5. Cliquez sur le fichier de code généré pour le mettre en évidence.
  6. Cliquez sur le bouton OK pour continuer.

Enfin, votre projet va devoir inclure la référence de service System.Web.Services pour l'exécution des appels SOAP depuis votre code importé.

  1. Cliquez sur le menu Projet de Visual Studio pour le développer.
  2. Sélectionnez Ajouter une référence.
  3. Cliquez sur l'onglet .NET.
  4. Sélectionnez System.Web.Services.
  5. Cliquez sur le bouton OK pour ajouter la référence à votre projet.

Exécution d'appels API

Création d'objets de service

À chaque service API de votre projet est associée une classe de service responsable de l'exécution des appels de l'API. Les classes de services sont nommées selon le service API que vous voulez appeler. Par exemple, le nom de classe pour le service API SoftLayer_Account sera SoftLayer_AccountService et le nom de classe pour le service SoftLayer_Hardware_Server sera SoftLayer_Hardware_ServerService. Les objets de service ont des propriétés correspondant à des fonctions API telles que l'authentification, les paramètres d'initialisation, les masques d'objet ou les limites de résultats. Par ailleurs, des appels de méthode API sont effectués directement sur ces objets. Exemple :
SoftLayer_AccountService accountService = new SoftLayer_AccountService();

Liaison de l'authentification

Authentifiez vos appels API avec votre nom d'utilisateur API et votre clé API en définissant un objet authenticate. Définissez les propriétés username et apiKey de l'objet d'authentification avec votre nom d'utilisateur API et votre clé API respectivement. Liez ensuite cet objet à votre objet de service API en définissant sa propriété authenticateValue avec le nom de votre objet d'authentification.

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
accountService.authenticateValue = authenticate;

Définition des paramètres d'initialisation

Les paramètres d'initialisation (init) des appels API ont également des classes définies qui correspondent au service API appelé. Les classes de paramètres init sont nommées selon le service API que vous appelez. Par exemple, le nom de classe de paramètres init pour le service SoftLayer_Account sera SoftLayer_AccountInitParameters et le nom de classe de paramètres init pour le service SoftLayer_Hardware_Server sera SoftLayer_Hardware_ServerInitParameters. Chaque objet de paramètre init a une propriété id de type entier unique qui correspond au numéro identifiant l'objet SoftLayer auquel s'applique votre requête. Liez votre objet de paramètre init à votre objet de service en l'associant à la propriété InitParameterValue de votre objet de service où correspond au nom du service API que vous appelez.
Si un appel API ne correspond pas à un objet SoftLayer spécifique, il ne vous est pas nécessaire de lier une valeur de paramètre d'initialisation à votre objet de service. Le fragment de code ci-dessous illustre ce scénario :

int serverId = 1234;
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = new SoftLayer_Hardware_ServerInitParameters();
hardwareServerInitParameters.id = serverId;
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters;

Exécution de l'appel API
Une fois que votre objet de service est prêt, dirigez votre appel de méthode API directement sur cet objet en utilisant le code ci-après :

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
// Initialize the SoftLayer_Account API service.
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
SoftLayer_Account account = accountService.getObject();
 
 
// Work directly with the SoftLayer_Hardware_Server record with the 
// hardware id 1234.
int serverId = 1234;
 
SoftLayer_Hardware_ServerService hardwareServerService = new SoftLayer_Hardware_ServerService();
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = new SoftLayer_Hardware_ServerInitParameters();
hardwareServerInitParameters.id = serverId;
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters;
 
SoftLayer_Hardware_Server server = hardwareServerService.getObject();

Le code importé dans votre projet définit des classes pour tous les types de données définis dans l'API SoftLayer. Instanciez des objets de type de données selon nécessité en tant que paramètres d'appel ou résultats d'appel.

String username = "set me";
String apiKey = "set me";
int domainId = 1234;
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_Dns_DomainService domainService = new SoftLayer_Dns_DomainService();
domainService.authenticateValue = authenticate;
 
SoftLayer_Dns_DomainInitParameters domainInitParameters = new SoftLayer_Dns_DomainInitParameters();
domainInitParameters.id = domainId;
domainService.SoftLayer_Dns_DomainInitParametersValue = domainInitParameters;
 
// Create a new A record in a domain.
SoftLayer_Dns_Domain_ResourceRecord_AType newRecord = domainService.createARecord("myhost", "127.0.0.1", 86400);
 
Console.WriteLine("New A record id: " + newRecord.id.ToString());
 
// Create a new domain record.
//
// This requires a null init parameter and a single SoftLayer_Dns_Domain
// object defined.
domainService.SoftLayer_Dns_DomainInitParametersValue = null;
 
SoftLayer_Dns_Domain domain = new SoftLayer_Dns_Domain();
SoftLayer_Dns_Domain_ResourceRecord_AType[] domainResourceRecords = new SoftLayer_Dns_Domain_ResourceRecord_AType[1];
domainResourceRecords[0].host = "@";
domainResourceRecords[0].data = "127.0.0.1";
domainResourceRecords[0].type = "a";
domain.name = "example.org";
domain.resourceRecords = domainResourceRecords;
 
SoftLayer_Dns_Domain newDomain = domainService.createObject(domain);
Console.WriteLine("New domain id: " + newDomain.id.ToString());

Utilisation de masques d'objet

Liez un masque d'objet à vos appels API en commençant par déclarer un objet de masque d'objet. Les classes de masques d'objet sont nommées selon le service API que vous utilisez, soit le nom de ce service suivi de ObjectMask. Par exemple, un masque d'objet pour le service API SoftLayer_Account prendra le nom de classe SoftLayer_AccountObjectMask et la classe de masques d'objet correspondant au service SoftLayer_Hardware_Server sera nommée SoftLayer_Hardware_ServerObjectMask.

Toutes les classes de masques d'objet mask ont une propriété qui modélise les données relationnelles que vous souhaitez extraire. La propriété mask définit un objet du type de données représenté par votre service API. Par exemple, SoftLayer_AccountObjectMask.mask est un objet SoftLayer_Account et SoftLayer_Hardware_ServerObjectMask.mask est un objet SoftLayer_Hardware_Server. Instanciez les propriétés relationnelles que vous souhaitez extraire dans la propriété mask de votre masque d'objet en tant que nouveaux objets représentant le type de données de ces propriétés. Si votre propriété relationnelle est de type tableau, vous déclarerez un tableau à un élément qui contient un unique objet représentant le type de données de la propriété relationnelle que vous voulez extraire.

Votre objet de service API a une propriété correspondant à une valeur de masque d'objet facultative. Le nom de chaque propriété de valeur de masque d'objet correspond au nom du service API que vous utilisez, soit le nom de ce service suivi de ObjectMaskValue. Liez le nouvel objet de masque d'objet à votre objet de service en l'associant à la propriété ObjectMaskValue de l'objet de service. Par exemple, vous lierez un masque d'objet à un objet de service SoftLayer_Account en affectant sa propriété SoftLayer_AccountObjectMaskValue à votre objet de masque d'objet.

L'exemple ci-après extrait les enregistrements de matériel physique d'un compte, ainsi que l'enregistrement du système d'exploitation de ce matériel, les mots de passe du système d'exploitation, les composants réseau, le centre de données où se situe le matériel et le nombre de processeurs de chaque élément matériel :

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
// Retrieve items related to hardware.
//
// Operating system, operating system passwords, all network components, the
// datacenter the server is located in, and the number of processors in each 
// server.
SoftLayer_AccountObjectMask objectMask = new SoftLayer_AccountObjectMask();
objectMask.mask = new SoftLayer_Account();
 
SoftLayer_Hardware_Server[] objectMaskHardware = new SoftLayer_Hardware_Server[1];
SoftLayer_Network_Component[] objectMaskHardwareNetworkComponents = new SoftLayer_Network_Component[1];
SoftLayer_Software_Component_Password[] objectMaskHardwareOperatingSystemPasswords = new SoftLayer_Software_Component_Password[1];
objectMaskHardware[0].operatingSystem = new SoftLayer_Software_Component_OperatingSystem();
objectMaskHardware[0].operatingSystem.passwords = objectMaskHardwareOperatingSystemPasswords;
objectMaskHardware[0].networkComponents = objectMaskHardwareNetworkComponents;
objectMaskHardware[0].datacenter = new SoftLayer_Location_Datacenter();
objectMaskHardware[0].processorCount = new uint();
objectMaskHardware[0].processorCountSpecified = true;
objectMask.mask.hardware = objectMaskHardware;
accountService.SoftLayer_AccountObjectMaskValue = objectMask;
 
SoftLayer_Hardware_Server[] hardware = (SoftLayer_Hardware_Server[])accountService.getHardware();

Utilisation de limites de résultats

Lors de l'appel de données, et notamment s'il s'agit d'extraire des fragments d'information relevant de structures plus importantes, vous réduirez sensiblement votre temps d'attente en fixant des limites pour les résultats.

Pour limiter le nombre de résultats de votre appel API, vous devez créer un nouvel objet resultLimit et le lier à votre objet de service API. Cet objet ResultLimit a deux propriétés :

  • limit: Nombre maximal de résultats pour votre appel.
  • offset: Décalage à partir duquel doit s'afficher votre ensemble de résultats (facultatif).

Vous lierez votre nouvelle limite de résultats à votre objet de service API en définissant la propriété resultLimitValue de cet objet de service avec le nom de votre objet de limite de résultats.

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
// Retrieve our first two open support tickets
resultLimit resultLimit = new resultLimit();
resultLimit.limit = 2;
resultLimit.offset = 0;
 
accountService.resultLimitValue = resultLimit;
 
SoftLayer_Ticket[] tickets = accountService.getOpenTickets();

Traitement des erreurs

Les erreurs d'appel de l'API SoftLayer sont transmises au gestionnaire SOAP de .NET en tant qu'exceptions. Pour un traitement approprié, vous placerez les appels SoftLayer dans des blocs try/catch. Exemple :

String username = "set me";
String apiKey = "an incorrect key";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
// Exit the script with the message:
// "Unable to retrieve account information: Invalid API key"
try 
{
    SoftLayer_Account account = accountService.getObject();
}
catch (Exception ex)
{
    Console.WriteLine("Unable to retrieve account information: " + ex.Message);
}

Mises en garde

Lorsque vous travaillez sur le code généré de l'API SoftLayer dans Visual Studio, une ou deux étapes supplémentaires peuvent être nécessaires si vous créez ou utilisez des objets API SoftLayer. Ces étapes consistent à définir des propriétés "spécifiées" et à gérer les changements dans les services API.

Définition de propriétés "spécifiées"

Certains types d'objet dans le code généré ont une propriété "spécifiée" en plus de la propriété de l'objet. Si vous définissez cette dernière propriété de façon explicite, vous devez attribuer la valeur True à la propriété spécifiée correspondante. Pour déterminer quelles sont les propriétés auxquelles sont associées des propriétés spécifiées, utilisez la fonctionnalité IntelliSense de Visual Studio.

Que faire en cas de changements dans les services API

SoftLayer met à jour les WSDL de l'API quand de nouveaux produits et services sont mis à disposition. Vous devez reconsommer ces WSDL pour pouvoir utiliser ces nouveaux produits et services.

Si l'API SoftLayer est importée en tant que référence Web dans votre projet, faites un clic droit sur le nom de cette référence dans l'Explorateur de solutions de Visual Studio, puis sélectionnez "Mettre à jour la référence Web". Visual Studio aura besoin de quelques instants pour réimporter le service Web, après quoi les toutes dernières offres de SoftLayer seront à disposition dans votre projet.

Si vous avez utilisé la commande wsdl.exe pour générer des fichiers de code à partir des WSDL de l'API SoftLayer, vous devrez réexécuter cette commande wsdl.exe intégralement pour réimporter les derniers WSDL dans votre projet.

Composants API référencés

financiers

Types de données

Méthodes