C Sharp

Consumindo WSDLs de SOAP

Há duas maneiras de importar WSDLs da API da SoftLayer para seu projeto. O Visual Studio pode consumir um serviço SOAP em uma referência da web acessível para seu projeto. O Visual Studio também é fornecido com um utilitário chamado wsdl.exe que é executado a partir de um prompt de comandos para ler um ou mais arquivos WSDL e convertê-los diretamente em código-fonte que pode ser incluído em seu projeto. Serviços da web geralmente são mais fáceis de usar no Visual Studio, mas podem se tornar ineficientes se seu projeto usar muitos serviços da API da SoftLayer. Wsdl.exe é útil se seu projeto precisar de muitos serviços da API.

As amostras de código neste artigo refletem códigos gerados a partir de serviços da API da SoftLayer por wsdl.exe.

Criando referências da web

A criação de referências da web é a primeira tarefa necessária ao consumir WSDLs de SOAP. Siga as etapas abaixo para criar uma Referência da web no Visual Studio.

  1. Clique no menu Projeto no Visual Studio
  2. Selecione Incluir referência de serviço na caixa suspensa do menu Projeto
  3. Clique no botão Avançado na janela Incluir referência de serviço

    Nota: a janela Configurações da referência de serviço aparecerá

  4. Clique no botão Incluir referência da web na janela Configurações da referência de serviço
  5. Insira a URL para o WSDL do serviço da API da SoftLayer que deseja usar no campo URL
  6. Clique na seta verde à direita do campo URL

    '''Nota: o Visual Studio fará download do arquivo WSDL e analisará os métodos e tipos de dados que ele contém.

  7. Insira um nome de sua nova referência da web no campo Nome da referência da web
    '''Nota: quaisquer referências ao serviço da API incluído no projeto serão referidas pelo projeto
  8. Clique no botão Incluir referência para importar seu novo serviço da web

    Nota: agora, você será retornado a seu projeto e seu novo serviço da API estará visível no Solution Explorer do Visual Studio

Este exemplo cria uma referência de serviço chamada "com.softlayer.api", mas você pode criar serviços da web com qualquer nome que preferir. O nome das referências da web é um namespace em seu projeto. Utilize a instrução using no início de seu programa para que não precise digitar o nome da referência da web com cada instrução relacionada à API que você usar. Por exemplo, use a instrução:

using projectName.com.softlayer.api;

Substitua "projectName" pelo nome do projeto do Visual Studio para configurar a referência da web como um namespace padrão.

Usando wsdl.exe

Wsdl.exe está localizado em C:\Arquivos de Programa\Microsoft SDKs\Windows\v7.0A\bin. Execute Wsdl.exe com os seguintes switches para converter os WSDLs da API SoftLayer em código C#:

  • /language:CS - Indica ao wsdl.exe para exportar o código C#.
  • /sharetypes - Os arquivos WSDL da SoftLayer compartilham diversos tipos de dados semelhantes. O comutador /sharetypes compila esses tipos de dados em arquivos de classe única, necessitando de uma área de código-fonte menor e mais eficiente ao trabalhar no Visual Studio.
  • /out:C:\path\to\project\SoftLayer_API.cs - Exporta código gerado para um caminho dentro da hierarquia do projeto. Nesse caso, vamos salvar código no fileSoftLayer_API.cs.

Termine o comando com uma lista separada por espaço das URLs dos WSDLS da API que deseja importar. É possível importar quantos arquivos WSDL desejar.

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 fazer chamadas privadas de API, substitua https://api.softlayer.com por http://api.service.softlayer.com. Consulte nosso artigo Introdução para obter mais informações sobre como fazer chamadas privadas de API.

Execute esse comando novamente se desejar importar mais serviços da API para seu projeto.

Quando seu arquivo de código for criado, ele deve ser incluído em seu projeto. Para incluir o novo arquivo de código criado no projeto, conclua as etapas abaixo:

  1. Clique com o botão direito no nome de seu projeto no Solution Explorer do Visual Studio
  2. Role até a opção Incluir no menu expandido
  3. Clique no botão Item existente no menu Incluir
  4. Localize seu arquivo de código gerado na janela de diálogo Incluir item existente
  5. Clique para destacar seu arquivo de código gerado
  6. Clique no botão OK para continuar

Por fim, seu projeto deve incluir a referência de serviço System.Web.Services para fazer chamadas SOAP a partir de seu código importado.

  1. Clique para expandir o menu Projeto no Visual Studio
  2. Selecione Incluir referência
  3. Clique na guia .NET
  4. Selecione System.Web.Services
  5. Clique no botão OK para incluir a referência em seu projeto

Fazendo chamadas de API

Criando objetos de serviço

Todo serviço da API em seu projeto tem uma classe de serviço associada que é responsável por fazer chamadas de API. As classes de serviço são denominadas de acordo com o serviço da API que você deseja chamar. Por exemplo, o nome da classe para o serviço da API SoftLayer_Account é SoftLayer_AccountService e o nome da classe de serviço para o serviço SoftLayer_Hardware_Server é SoftLayer_Hardware_ServerService. Objetos de serviço têm propriedades que correspondem aos recursos da API, como autenticação, parâmetros de inicialização, máscaras de objetos e limites de resultados. As chamadas de método da API também são feitas diretamente com relação a esses objetos. Por exemplo:
SoftLayer_AccountService accountService = new SoftLayer_AccountService();

Autenticação obrigatória

Autentique suas chamadas de API com seu nome do usuário e chave da API definindo um objeto authenticate. Configure as propriedades username e apiKey de seu objeto de autenticação para seu nome do usuário e chave da API. Autentique seu objeto de serviço da API configurando sua propriedade authenticateValue para o objeto de autenticação.

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

Configurando parâmetros de inicialização

Os parâmetros de inicialização (init) da chamada API também têm classes definidas que correspondem ao serviço da API que você está chamando. As classes do parâmetro de inicialização são denominadas de acordo com o serviço da API que você está chamando. Por exemplo, o nome da classe do parâmetro de inicialização para o serviço SoftLayer_Account é SoftLayer_AccountInitParameters e o nome da classe do parâmetro de inicialização para o serviço SoftLayer_Hardware_Server é SoftLayer_Hardware_ServerInitParameters. Os objetos do parâmetro de inicialização têm, cada um, uma propriedade id do tipo de número inteiro que corresponde ao número do ID do objeto da SoftLayer que você deseja consultar. Ligue o objeto do parâmetro de inicialização ao objeto de serviço configurando-o para a propriedade InitParameterValue do objeto de serviço, em que corresponde ao serviço da API que você está chamando.
Se uma chamada API não corresponder a um objeto específico da SoftLayer, então, você não precisa ligar um valor de parâmetro de inicialização ao objeto de serviço. O fragmento de código abaixo esboça esse cenário:

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

Fazendo a chamada API
Quando seu objeto de serviço estiver pronto, faça a chamada de método da API diretamente com relação ao objeto de serviço. Utilize o código abaixo para concluir essa ação:

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

O código importado para o projeto define classes para cada tipo de dados definido na API da SoftLayer. Instancie novos objetos de tipo de dados conforme necessário como parâmetros de chamada ou resultados de chamada.

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

Usando máscaras de objetos

Ligue uma Máscara de objeto às chamadas de API declarando primeiramente um objeto de máscara de objeto. Os nomes das classes de máscaras de objetos correspondem ao serviço da API que está sendo usado, iniciando com o nome do serviço da API seguido por ObjectMask. Por exemplo, uma máscara de objeto para o serviço da API SoftLayer_Account tem o nome de classe SoftLayer_AccountObjectMask e o nome da classe da máscara de objeto correspondente do serviço SoftLayer_Hardware_Server é SoftLayer_Hardware_ServerObjectMask.

Toda classe de máscara de objeto tem uma propriedade mask que modela os dados relacionais que você deseja recuperar. A propriedade mask está no objeto de tipo de dados representado pelo serviço da API. Por exemplo, SoftLayer_AccountObjectMask.mask é um objeto SoftLayer_Account e SoftLayer_Hardware_ServerObjectMask.mask é um objeto SoftLayer_Hardware_Server. Instancie as propriedades relacionais que você deseja recuperar na propriedade mask da máscara de objeto como novos objetos que representam o tipo de dados dessas propriedades. Se sua propriedade relacional for um tipo de matriz, então, declare uma matriz de um item contendo um único objeto que representa o tipo de dados da propriedade relacional que você deseja recuperar.

O objeto de serviço da API tem uma propriedade que corresponde a um valor de máscara de objeto opcional. Os nomes das propriedades dos valores das máscaras de objetos correspondem ao nome do serviço da API que está sendo usado, iniciando com o nome do serviço da API seguido por ObjectMaskValue. Ligue o novo objeto da máscara de objeto ao objeto de serviço designando-o à propriedade ObjectMaskValue do objeto de serviço. Por exemplo, ligue uma máscara de objeto a um objeto de serviço SoftLayer_Account designando a propriedade SoftLayer_AccountObjectMaskValue ao objeto da máscara de objeto.

Este exemplo recupera os registros de hardware físico de uma conta com o registro do sistema operacional desse hardware, senhas do sistema operacional, componentes da rede, o datacenter no qual o hardware está localizado e o número de processadores em 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();

Usando limites de resultados

Ao chamar dados, principalmente consultas que envolvem puxar fragmentos de informações de grupos maiores, usar limites de resultados irá reduzir muito seu tempo de espera pelo retorno.

Limite o número de resultados na chamada API criando um novo objeto resultLimit e ligando-o ao objeto de serviço da API. ResultLimit tem duas propriedades:

  • limit: O número de resultados para limitar sua chamada
  • offset: Um deslocamento opcional para iniciar o conjunto de resultados

Ligue o novo limite de resultado ao objeto de serviço da API configurando a propriedade resultLimitValue do objeto de serviço para o objeto de limite de resultado.

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

Manipulação de erros

Os erros da chamada API da SoftLayer são enviados ao manipulador de SOAP do .NET como exceções. Faça chamadas à SoftLayer em blocos de tentar/capturar para assegurar a manipulação adequada. Por exemplo:

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

Advertências

Trabalhar com o código gerado da API da SoftLayer no Visual Studio pode requerer uma ou duas etapas adicionais ao criar ou usar objetos da API da SoftLayer. Essas etapas incluem configurar propriedades "especificadas" e manipular mudanças em serviços da API.

Configurando propriedades "especificadas"

Alguns tipos de objetos no código gerado têm uma propriedade "especificada" com a propriedade do objeto. Se estiver configurando essas propriedades explicitamente, deve-se configurar a propriedade especificada correspondente para True. Use IntelliSense do Visual Studio para determinar quais propriedades têm propriedades especificadas associadas.

O que fazer quando os serviços da API mudam

O SoftLayer atualiza os WSDLs da API quando novos produtos e serviços são liberados. Consuma esses WSDLs novamente para usar esses novos recursos.

Se a API da SoftLayer for importada como uma referência da web em seu projeto, clique com o botão direito no nome da referência da web no Solution Explorer do Visual Studio e selecione "Atualizar referência da web". O Visual Studio levará alguns instantes para reimportar o serviço da web. Após a conclusão, as ofertas mais recentes da SoftLayer estarão disponíveis em seu projeto.

Se tiver usado o wsdl.exe para gerar arquivos de código a partir de WSDLs da API da SoftLayer, execute novamente o comando wsdl.exe completo para reimportar os WSDLs da API da SoftLayer mais recentes para o projeto.

Componentes da API referidos

Serviços

Tipos de dados

Métodos