Visual Basic .NET

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

  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 ce nom.
  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.

Utilisation de wsdl.exe

Wsdl.exe se trouve dans le dossier C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\ et doit être exécuté avec les commutateurs suivants pour la conversion des WSDL de l'API SoftLayer en code Visual Basic :

  • /language:VB - Demande à wsdl.exe d'exporter le code Visual Basic .NET.
  • /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.vb - 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.vb.

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:VB /out:"C:\Path\to\Project\SoftLayer_API.vb" /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.

  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.

Vous pouvez maintenant utiliser les objets API de SoftLayer en tant qu'objets locaux dans 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.

Dim accountService As SoftLayer_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 objetauthenticate. 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.

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As 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.

Dim serverId As Integer = 1234
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = 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. Voici un exemple d'appel :

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
' Initialize the SoftLayer_Account API service.
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
Dim account as SoftLayer_Account = accountService.getObject()
 
 
' Work directly with the SoftLayer_Hardware_Server record with the 
' hardware id 1234.
Dim serverId As Integer = 1234
 
Dim hardwareServerService As SoftLayer_Hardware_ServerService = New SoftLayer_Hardware_ServerService()
hardwareServerService.authenticateValue = authenticate
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = New SoftLayer_Hardware_ServerInitParameters()
hardwareServerInitParameters.id = serverId
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters
 
Dim server as SoftLayer_Hardware_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.

Dim username As String = "set me"
Dim apiKey As String = "set me"
Dim domainId As Integer = 1234
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim domainService As SoftLayer_Dns_DomainService = New SoftLayer_Dns_DomainService()
domainService.authenticateValue = authenticate
 
Dim domainInitParameters As SoftLayer_Dns_DomainInitParameters = New SoftLayer_Dns_DomainInitParameters()
domainInitParameters.id = domainId
domainService.SoftLayer_Dns_DomainInitParametersValue = domainInitParameters
 
' Create a new A record in a domain.
Dim newRecord As SoftLayer_Dns_Domain_ResourceRecord_AType = 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 = Nothing
 
Dim domain As SoftLayer_Dns_Domain = New SoftLayer_Dns_Domain()
Dim domainResourceRecords As SoftLayer_Dns_Domain_ResourceRecord_AType() = {New SoftLayer_Dns_Domain_ResourceRecord_AType()}
domainResourceRecords(0).host = "@"
domainResourceRecords(0).data = "127.0.0.1"
domainResourceRecords(0).type = "a"
domain.name = "example.org"
domain.resourceRecords = domainResourceRecords
 
Dim newDomain As SoftLayer_Dns_Domain = domainService.createObject(domain)
Console.WriteLine("New A record 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_AccountObjectMaskValueproperty à 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 :

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_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.
Dim objectMask As SoftLayer_AccountObjectMask = New SoftLayer_AccountObjectMask()
objectMask.mask = New SoftLayer_Account
 
Dim objectMaskHardware As SoftLayer_Hardware_Server() = {New SoftLayer_Hardware_Server()}
Dim objectMaskHardwareNetworkComponents As SoftLayer_Network_Component() = {New SoftLayer_Network_Component()}
Dim objectMaskHardwareOperatingSystemPasswords As SoftLayer_Software_Component_Password() = {New SoftLayer_Software_Component_Password()}
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 UInteger
objectMaskHardware(0).processorCountSpecified = True
 
objectMask.mask.hardware = objectMaskHardware
accountService.SoftLayer_AccountObjectMaskValue = objectMask
 
Dim hardware As 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.

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
' Retrieve our first two open support tickets
Dim resultLimit As resultLimit = New resultLimit()
resultLimit.limit = 2
resultLimit.offset = 0
 
accountService.resultLimitValue = resultLimit
 
Dim tickets As SoftLayer_Ticket() = 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.

Dim username As String = "set me"
Dim apiKey As String = "an incorrect key"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
' Exit the script with the message:
' "Unable to retrieve account information: Invalid API key"
Try
    Dim account As SoftLayer_Account = accountService.getObject()
Catch ex As Exception
    Console.WriteLine("Unable to retrieve account information: " + ex.Message)
End Try

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

Services

Types de données

Méthodes