C Sharp

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

La creación de referencias web es la primera tarea necesaria cuando se consumen WSDL SOAP. Siga estos pasos para crear una referencia web en Visual Studio.

  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 el proyecto
  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

Este ejemplo crea una referencia de servicio denominada "com.softlayer.api", pero puede crear servicios web con el nombre que prefiera. El nombre de las referencias web es un espacio de nombres en el proyecto. Utilice la sentencia using al principio del programa, para que no tenga que escribir el nombre de la referencia web con cada sentencia relacionada con la API que utilice. Por ejemplo, utilice la sentencia:

using projectName.com.softlayer.api;

Sustituya "projectName" por el nombre del proyecto de Visual Studio para establecer la referencia web como un espacio de nombres predeterminado.

Utilización de wsdl.exe

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

  • /language:CS - Indica a wsdl.exe que debe exportar el código C#.
  • /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.cs - 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.cs.

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: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

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. Para añadir el archivo de código que acaba de crear al proyecto, siga estos pasos:

  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

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_Server 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. Por ejemplo:
SoftLayer_AccountService 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.

String username = "set me";
String apiKey = "set me";
 
authenticate 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. El fragmento de código siguiente describe este caso de ejemplo:

int serverId = 1234;
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = 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. Utilice el código siguiente para completar esta acción:

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

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.

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

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_AccountObjectMaskValue 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:

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

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.

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

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. Por ejemplo:

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);
}

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