Visual Basic .NET

使用 SOAP WSDL

可使用两种方法来将 SoftLayer 的 API WSDL 导入到项目中。Visual Studio 可以将 SOAP 服务融入到项目可访问的 Web 引用中。Visual Studio 还附带了一个名为
wsdl.exe 的实用程序,可以从命令提示符中执行该实用程序,该实用程序用于读取一个或多个 WSDL 文件并直接将这些文件转换为源代码来添加到项目中。在 Visual Studio 中,使用 Web Service 通常更方便一些,但如果您的项目使用了许多 SoftLayer API 服务,那么使用 Web Service 可能会很繁琐。当您的项目需要使用许多 API 服务时,Wsdl.exe 会很有用。

本文中的代码样本反映了 wsdl.exe 从 SoftLayer API 服务生成的代码。

创建 Web 引用

  1. 在 Visual Studio 中,单击项目菜单。
  2. 项目菜单下拉框中,选择添加服务引用
  3. 单击添加服务引用窗口中的高级按钮。
    注:此时将显示“服务引用设置”窗口。
  4. 单击服务引用设置窗口中的添加 Web 引用按钮。
  5. URL 字段中,输入您要使用的 SoftLayer API 服务的 WSDL URL
  6. 单击 URL 字段右侧的绿色箭头。
    注:Visual Studio 将下载 WSDL 文件,并分析其包含的方法和数据类型。
  7. Web 引用名称字段中,输入新 Web 引用的名称。
    注:对添加到项目中的 API 服务的所有引用都通过此名称进行引用。
  8. 单击添加引用按钮以导入新的 Web Service。
    注:现在,您将返回到您的项目,Visual Studio 的解决方案资源管理器中将显示新的 API 服务。

使用 Wsdl.exe

Wsdl.exe 位于
C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\ 中,应该在使用以下开关的情况下执行此工具,以便将 SoftLayer 的 API WSDL 转换为 Visual Basic 代码:

  • /language:VB - 通知 wsdl.exe 导出
    Visual Basic .NET 代码。
  • /sharetypes - SoftLayer 的 WSDL 文件共享一些相似的数据类型。/sharetypes 开关将这些数据类型编译为单一类文件,从而使源代码体积更小,并提高在 Visual Studio 中处理源代码的效率。
  • /out:C:\path\to\project\SoftLayer_API.vb - 将所生成的代码导出到项目层次结构中的某一路径中。在此情况下,我们会将代码保存至 fileSoftLayer_API.vb。

在该命令的结尾处输入您要导入的 API WSDL 的 URL 的空格分隔列表。您可以导入所需数目的 WSDL 文件。

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

注:要发出私有 API 调用,请将 https://api.softlayer.com
替换为 http://api.service.softlayer.com。请参阅入门文章,以获取有关发出私有 API 调用的更多信息。

如果您希望将更多 API 服务导入到项目中,请重新运行此命令。

创建代码文件后,必须将其添加到项目中。

  1. Visual Studio 解决方案资源管理器中,右键单击项目的名称。
  2. 滚动至所展开菜单中的添加选项。
  3. 单击添加菜单中的现有项按钮。
  4. 添加现有项对话框窗口中找到所生成的代码文件。
  5. 单击所生成的代码文件以使其突出显示。
  6. 单击确定按钮以继续。

最终,您的项目必须包含 System.Web.Services 服务引用,以通过导入的代码来发出 SOAP 调用。

  1. 在 Visual Studio 中,单击项目菜单以将其展开。
  2. 选择添加引用
  3. 单击 .NET 选项卡。
  4. 选择 System.Web.Services
  5. 单击确定按钮以将引用添加到项目中。

现在,您可使用 SoftLayer 的 API 对象作为项目中的本地对象。

发出 API 调用

创建服务对象

项目中的每一个 API 服务都有一个关联的服务类,该类负责发出 API 调用。根据您要调用的 API 服务来指定服务类。例如,SoftLayer_Account API 服务的类名是
SoftLayer_AccountServiceSoftLayer_Hardware_Serverservice 服务的类名是 SoftLayer_Hardware_ServerService
服务对象具有与 API 功能(例如,认证、初始化参数、对象掩码和结果限制)对应的属性。也可以直接对这些对象发出 API 方法调用。

Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()

绑定认证

通过定义 authenticate 对象,使用 API 用户名和密钥来认证 API 调用。将认证对象的 username
apiKey 属性设置为您的 API 用户名和密钥。通过将 API 服务对象的
authenticateValue 属性设置为您的认证对象,以将该认证对象与该 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
 
accountService.authenticateValue = authenticate

设置初始化参数

API 调用初始化 (init) 参数也定义了与您所调用 API 服务对应的类。Init 参数类根据所调用的 API 服务来命名。例如,SoftLayer_Account 服务的初始化参数类名为 SoftLayer_AccountInitParametersSoftLayer_Hardware_Server 服务的初始化参数类名为 SoftLayer_Hardware_ServerInitParameters
每个 Init 参数对象都有一个整数类型的 ID 属性,此属性与您要查询的 SoftLayer 对象的 ID 号相对应。通过将 Init 参数对象设置为服务对象的 InitParameterValue 属性(其中, 与所调用的 API 服务相对应),将该 Init 参数对象与该服务对象绑定在一起。
如果 API 调用没有与特定的 SoftLayer 对象相对应,那么您无需将初始化参数值与服务对象绑定在一起。

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

发出 API 调用

准备好服务对象后,可对该服务对象直接进行 API 方法调用。以下示例概括了如何发出 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()

导入到项目中的代码将为 SoftLayer API 中定义的每一种数据类型都定义类。实例化新的数据类型对象,与调用参数或调用结果一样有必要。

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

使用对象掩码

通过先声明对象掩码对象,将对象掩码与您的 API 调用绑定在一起。对象掩码类名称与所使用的 API 服务名称相对应,以 API 服务名称开头,后跟“ObjectMask”。
例如,SoftLayer_Account API 服务的对象掩码的类名为 SoftLayer_AccountObjectMaskSoftLayer_Hardware_Server 服务的对应对象掩码的类名为 SoftLayer_Hardware_ServerObjectMask

每个对象掩码类都具有 mask 属性,用于对您要检索的关系数据进行建模。mask 属性是 API 服务表示的数据类型的对象。例如,SoftLayer_AccountObjectMask.maskSoftLayer_Account 对象,SoftLayer_Hardware_ServerObjectMask.maskSoftLayer_Hardware_Server 对象。将要从对象掩码的 mask 属性中检索的关系属性实例化,使其作为新对象来表示这些属性的数据类型。
如果关系属性是数组类型,请声明仅包含单个对象的单项数组,该对象表示您要检索的关系属性的数据类型。

您的 API 服务对象具有与可选对象掩码值对应的属性。对象掩码值属性名称与所使用的 API 服务名称相对应,以 API 服务名称开头,后跟“ObjectMaskValue”。
通过将新对象掩码对象分配给服务对象的 ObjectMaskValue 属性,将该对象掩码对象与该服务对象绑定在一起。例如,通过将 SoftLayer_Account 服务对象的 SoftLayer_AccountObjectMaskValueproperty 分配给对象掩码对象,将该对象掩码对象与该服务对象绑定在一起。

此示例将检索帐户的物理硬件记录、该硬件的操作系统记录、操作系统密码、网络组件、该硬件所在的数据中心,以及每个硬件中的处理器数:

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

使用结果限制

当调用数据时,尤其是查询涉及到从较大组中抽取信息片段时,使用结果限制将极大地缩短返回的等待时间。

通过创建新的 resultLimit 对象并将其与 API 服务对象绑定在一起,以限制 API 调用中的结果数量。ResultLimit 具有两个属性:

  • limit:要为调用限制的结果数量。
  • offset:结果集开始的可选偏移量。

通过将 API 服务对象的 resultLimitValue 属性设置为新的结果限制对象,以将该结果限制对象与该服务对象绑定在一起。

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

错误处理

SoftLayer API 调用错误会作为异常发送到 .NET 的 SOAP 处理程序。在 Try/Catch 块中调用 SoftLayer 以确保正确处理。

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

警告

在 Visual Studio 中处理 SoftLayer API 生成的代码时,可能在创建或使用 SoftLayer API 对象时需要一个或两个额外步骤。这些步骤包括设置“指定的”属性和处理 API 服务的更改内容。

设置“指定的”属性

已生成代码中的一些对象类型具有“指定的”属性和对象的属性。如果您显式设置这些属性,那么必须将它们对应的指定属性设置为 True。使用 Visual Studio 的 IntelliSense 来确定哪些属性具有指定的关联属性。

API 服务更改时要执行的操作

SoftLayer 会在发布新产品和服务时更新 API WSDL。请重新使用这些 WSDL,以便使用这些新功能。
如果在项目中将 SoftLayer API 导入为 Web 引用,请在 Visual Studio 的“解决方案资源管理器”中右键单击该 Web 引用的名称,然后选择“更新 Web 引用”。Visual Studio 将需要一点时间来重新导入 Web Service,
在这之后,将可以在项目中使用最新的 SoftLayer 产品。
如果您使用 wsdl.exe 来通过 SoftLayer 的 API
WSDL 生成代码文件,请重新运行完整的 wsdl.exe 命令,以将 SoftLayer 的最新 API WSDL 重新导入到项目中。

被引用的 API 组件

服务

数据类型

方法