C Sharp

使用 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 引用

在使用 SOAP WSDL 时需要完成的第一项任务是创建 Web 引用。请执行以下步骤,在 Visual Studio 中创建 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 服务

此示例创建了名为“com.softlayer.api”的服务引用,但您可以使用自己期望的任何名称来创建 Web Service。您的 Web 引用名称将作为项目中的名称空间。请在程序开头处使用 using 语句,这样,您就不需要在所使用的每个 API 相关语句中输入该 Web 引用的名称。例如,使用以下语句:

using projectName.com.softlayer.api;

将“projectName”替换为 Visual Studio 项目的名称,从而将该 Web 引用设置为默认名称空间。

使用 wsdl.exe

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

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

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

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

注:要发出私有 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. 单击确定按钮以将引用添加到项目中

发出 API 调用

创建服务对象

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

绑定认证

通过定义 authenticate 对象,使用 API 用户名和密钥来认证 API 调用。将认证对象的 usernameapiKey 属性设置为您的 API 用户名和密钥。通过将 API 服务对象的 authenticateValue 属性设置为您的认证对象,以将该认证对象与该 API 服务对象绑定在一起。

String username = "set me";
String apiKey = "set me";
 
authenticate 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 对象相对应,那么您无需将初始化参数值与服务对象绑定在一起。以下代码片段概括了此场景:

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

发出 API 调用
准备好服务对象后,可对该服务对象直接进行 API 方法调用。使用以下代码来完成该操作:

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

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

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

使用对象掩码

通过先声明对象掩码对象,将对象掩码与您的 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_AccountObjectMaskValue 属性分配给对象掩码对象,将该对象掩码对象与该服务对象绑定在一起。

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

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

使用结果限制

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

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

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

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

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

错误处理

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

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

警告

在 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 组件

服务

数据类型

方法