Visual Basic .NET

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

  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 para sua nova referência da web no campo Nome da referência da web.
    Nota: qualquer referência ao serviço da API incluído no projeto será referida por esse nome.
  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.

Usando Wsdl.exe

Wsdl.exe está localizado em C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\ e deve ser executado com os comutadores a seguir para converter os WSDLs de API da SoftLayer em código do Visual Basic:

  • /language:VB - Indique ao wsdl.exe para exportar o código do Visual Basic .NET.
  • /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.vb - Exporte código gerado para um caminho dentro da hierarquia do projeto. Nesse caso, vamos salvar código no fileSoftLayer_API.vb.

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

  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.

Agora, você pode usar objetos de API da SoftLayer como objetos locais 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 SoftLayer_Hardware_Serverservice é 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.

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

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

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 único 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, você não precisa ligar um valor de parâmetro de inicialização ao objeto de serviço.

Dim serverId As Integer = 1234
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = 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. O exemplo abaixo esboça como fazer a chamada 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()

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.

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

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

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

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.

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

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.

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

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, então, 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, entã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, então, execute novamente o comando wsdl.exe completo para reimportar os WSDLs da Software API mais recentes para o projeto.

Componentes da API referidos

Serviços

Tipos de dados

Métodos