Visual Basic .NET

Consumo de WSDL SOAP

Hay dos formas de importar los WSDL de API de SoftLayer al proyecto. Visual Studio puede consumir un servicio SOAP en una referencia web accesible para el proyecto. Visual Studio también se suministra con un programa de utilidad denominado wsdl.exe, que se ejecuta desde un indicador de mandatos para leer uno o varios archivos WSDL y convertirlos directamente en código fuente que puede añadir al proyecto. Los servicios web normalmente son más fáciles de utilizar en Visual Studio, pero pueden complicarse si el proyecto utiliza muchos servicios de API de SoftLayer. Wsdl.exe es muy útil si el proyecto requiere muchos servicios de API.

Los ejemplos de código en este artículo reflejan el código generado en los servicios de API de SoftLayer por wsdl.exe.

Creación de referencias web

  1. Pulse el menú Project en Visual Studio.
  2. Seleccione Add Service Reference en el recuadro desplegable del menú Project.
  3. Pulse el botón Advanced en la ventana Add Service Reference.
    Nota: aparecerá la ventana Service Reference Settings.
  4. Pulse el botón Add Web Reference en la ventana Service Reference Settings.
  5. Especifique el valor de URL to the WSDL del servicio de API de SoftLayer que desee utilizar en el campo URL.
  6. Pulse la flecha verde a la derecha del campo URL.
    Nota: Visual Studio descargará el archivo WSDL y analizará los métodos y los tipos de datos que contiene.
  7. Especifique el nombre de la nueva referencia web en el campo Web reference name.
    Nota: toda referencia al servicio de API añadido al proyecto se conocerá por este nombre.
  8. Pulse el botón Add Reference para importar el nuevo servicio web.
    Nota: se abrirá de nuevo el proyecto y el nuevo servicio de API estará visible en el Solution Explorer de Visual Studio.

Utilización de wsdl.exe

Wsdl.exe se encuentra en C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\ y debe ejecutarse con los siguientes conmutadores para convertir los WSDK de API de SoftLayer en código de Visual Basic:

  • /language:VB - Indica a wsdl.exe que debe exportar el código .NET de Visual Basic.
  • /sharetypes - Los archivos WSDL de SoftLayer comparten varios tipos de datos similares. El conmutador /sharetypes compila estos tipos de datos en archivos de una sola clase, lo que ocupa menos espacio de origen y es más eficaz cuando se trabaja en Visual Studio.
  • /out:C:\path\to\project\SoftLayer_API.vb - Exporta el código generado a una vía de acceso en la jerarquía del proyecto. En este caso, se guardará el código en fileSoftLayer_API.vb.

Finalice el mandato con una lista separada por espacios de los URL de los WSDL de API que desee importar. Puede importar tantos archivos WSDL como desee.

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

Nota: para realizar llamadas de API privadas, sustituya https://api.softlayer.com
por http://api.service.softlayer.com. Consulte el artículo Cómo empezar para obtener más información sobre cómo realizar llamadas de API privadas.

Vuelva a ejecutar este mandato si desea importar más servicios de API al proyecto.

Una vez creado el archivo de código, debe añadirlo al proyecto.

  1. Pulse con el botón derecho el nombre del proyecto en Visual Studio Solution Explorer.
  2. Desplácese sobre la opción Add en el menú expandido.
  3. Pulse el botón Existing Item en el menú Add.
  4. Localice el archivo de código generado en la ventana de diálogo Add Existing Item.
  5. Pulse para resaltar el archivo de código generado.
  6. Pulse el botón OK para continuar.

Por último, el proyecto debe incluir la referencia de servicio System.Web.Services para poder realizar llamadas SOAP desde el código importado.

  1. Pulse para expandir el menú Project en Visual Studio.
  2. Seleccione Add Reference.
  3. Pulse la pestaña .NET.
  4. Seleccione System.Web.Services
  5. Pulse el botón OK para añadir la referencia al proyecto.

Ahora puede utilizar objetos de API de SoftLayer como objetos locales en el proyecto.

Realización de llamadas de API

Creación de objetos de servicio

Todo servicio de API en el proyecto tiene una clase de servicio asociada que es responsable de realizar las llamadas de API. Las clases de servicio se denominan según el servicio de API que desee invocar. Por ejemplo, el nombre de clase del servicio de API SoftLayer_Account es SoftLayer_AccountService y el nombre de clase de servicio de SoftLayer_Hardware_Serverservice es SoftLayer_Hardware_ServerService. Los objetos de servicio tienen propiedades correspondientes a características de la API como, por ejemplo, la autenticación, los parámetros de inicialización, las máscaras de objetos y los límites de resultados. Las llamadas de método de API también se realizan directamente con estos objetos.

Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()

Enlace de la autenticación

Para autenticar las llamadas de API con su nombre de usuario y la clave de API, defina un objeto authenticate. Establezca las propiedades username y apiKey de su objeto de autenticación en su nombre de usuario y la clave de API. Para enlazar el objeto de autenticación con el objeto de servicio de API, establezca la propiedad authenticateValue en su objeto de autenticación.

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

Establecimiento de los parámetros de inicialización

Los parámetros de inicialización (init) de la llamada de API también tienen clases definidas que corresponden al servicio de API que está invocando. Las clases de los parámetros init se denominan según el servicio de API que está invocando. Por ejemplo, el nombre de clase del parámetro init del servicio SoftLayer_Account es SoftLayer_AccountInitParameters y el nombre de clase del parámetro init del servicio SoftLayer_Hardware_Server es SoftLayer_Hardware_ServerInitParameters. Cada objeto de parámetro init tiene una única propiedad de ID de tipo entero correspondiente al número de ID del objeto de SoftLayer que desea consultar. Enlace el objeto de parámetro init con el objeto de servicio estableciéndolo en la propiedad InitParameterValue del objeto de servicio, donde corresponde al servicio de API que está invocando.
Si una llamada de API no se corresponde con un objeto de SoftLayer específico, no es necesario enlazar un valor de parámetro de inicialización con el objeto de servicio.

Dim serverId As Integer = 1234
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = New SoftLayer_Hardware_ServerInitParameters()
hardwareServerInitParameters.id = serverId
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters

Realización de la llamada de API

Cuando el objeto de servicio esté preparado, realice la llamada de método de API directamente con el objeto de servicio. En el ejemplo siguiente se describe cómo se realiza la llamada de API.

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()

El código importado al proyecto define las clases de cada tipo de datos definido en la API de SoftLayer. Cree una instancia de los nuevos objetos de tipo de datos según sea necesario como parámetros de llamada o resultados de llamada.

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())

Utilización de máscaras de objeto

Enlace una máscara de objeto con las llamadas de API declarando primero un objeto de máscara de objeto. Los nombres de clase de máscara de objeto corresponden al servicio de API que está utilizando, empezando por el nombre del servicio de API seguido de "ObjectMask". Por ejemplo, una máscara de objeto del servicio de API SoftLayer_Account tiene el nombre de clase SoftLayer_AccountObjectMask y el nombre de la clase de máscara de objeto correspondiente del servicio SoftLayer_Hardware_Server es SoftLayer_Hardware_ServerObjectMask.

Toda clase de máscara de objeto tiene una propiedad mask que modela los datos relacionales que desea recuperar. La propiedad mask está en el objeto del tipo de datos representado por el servicio de API. Por ejemplo, SoftLayer_AccountObjectMask.mask es un objeto SoftLayer_Account y SoftLayer_Hardware_ServerObjectMask.mask es un objeto SoftLayer_Hardware_Server. Cree una instancia de las propiedades relacionales que desee recuperar en la propiedad mask de la máscara de objeto como nuevos objetos que representan el tipo de datos de estas propiedades. Si la propiedad relacional es un tipo de matriz, declare una matriz de un elemento que contenga un único objeto que represente el tipo de datos de la propiedad relacional que desea recuperar.

El objeto de servicio de API tiene una propiedad correspondiente a un valor de máscara de objeto opcional. Los nombres de propiedad de valor de máscara de objeto corresponden al nombre del servicio de API que está utilizando, empezando por el nombre del servicio de API seguido de "ObjectMaskValue". Enlace el nuevo objeto de máscara de objeto con el objeto de servicio asignándolo a la propiedad ObjectMaskValue del objeto de servicio. Por ejemplo, enlace una máscara de objeto a un objeto de servicio SoftLayer_Account asignando la propiedad SoftLayer_AccountObjectMaskValueproperty al objeto de máscara de objeto.

En este ejemplo, se recuperan los registros de hardware físico de una cuenta, junto con el registro del sistema operativo del hardware, las contraseñas del sistema operativo, los componentes de red, el centro de datos donde se encuentra el hardware y el número de procesadores en cada hardware:

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()

Utilización de los límites de resultados

Cuando se invocan datos, especialmente en las consultas que implican la extracción de fragmentos de código de información de grupos de gran tamaño, el uso de límites de resultados disminuye significativamente el tiempo de espera de la devolución.

Para limitar el número de resultados en la llamada de API, cree un nuevo objeto resultLimit y enlácelo con el objeto de servicio de API. ResultLimit tiene dos propiedades:

  • limit: el número de resultados al que se limita la llamada.
  • offset: un desplazamiento opcional para iniciar el conjunto de resultados.

Enlace el nuevo límite de resultados con el objeto de servicio de API estableciendo la propiedad resultLimitValue del objeto de servicio en el objeto de límite de resultados.

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()

Manejo de errores

Los errores de llamada de API de SoftLayer se envían al manejador SOAP de .NET como excepciones. Realice llamadas a SoftLayer en bloques Try/Catch para garantizar un manejo correcto.

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

Advertencias

El trabajo con el código generado de la API de SoftLayer en Visual Studio puede requerir uno o dos pasos adicionales cuando se crean o se utilizan objetos de API de SoftLayer. Estos pasos incluyen el establecimiento de las propiedades “especificadas” y el manejo de cambios en los servicios de API.

Establecimiento de las propiedades "especificadas"

Algunos tipos de objetos en el código generado tienen una propiedad "especificada", junto con la propiedad del objeto. Si establece explícitamente estas propiedades, debe establecer su propiedad especificada correspondiente en True. Utilice IntelliSense de Visual Studio para determinar qué propiedades tienen propiedades especificadas asociadas.

Qué hacer cuando cambian los servicios de API

SoftLayer actualiza los WSDL de API cuando se presentan nuevos productos y servicios. Vuelva a consumir estos WSDL para poder utilizar las nuevas características.
Si la API de SoftLayer se importa como una referencia web en el proyecto, pulse con el botón derecho el nombre de la referencia web en Solution Explorer de Visual Studio y seleccione "Update Web Reference". Visual Studio tardará unos momentos en volver a importar el servicio web. Cuando finalice, estarán disponibles en el proyecto las últimas ofertas de SoftLayer.
Si ha utilizado wsdl.exe para generar archivos de código a partir de los WSDL de API de SoftLayer, vuelva a ejecutar el mandato wsdl.exe completo para volver a importar los últimos WSDL de API de SoftLayer al proyecto.

Componentes de API referenciados

Servicios

Tipos de datos

Métodos