C Sharp

取用 SOAP WSDL

有兩種方法可將 SoftLayer 的 API WSDL 匯入到您的專案中。Visual Studio 可在您專案可存取的 Web 參照中取用 SOAP 服務。Visual Studio 還附帶一個公用程式,稱為 wsdl.exe,它是從命令提示字元執行,能讀取以一個以上的 WSDL 檔案,並將它們直接轉換成原始碼,讓您加入至專案中。Web 服務通常更容易用於 Visual Studio 中,但如果您的專案使用許多 SoftLayer API 服務,則 Web 服務會變得難以處理。如果專案需要許多 API 服務,則 Wsdl.exe 很有幫助。

本文章的程式碼範例反映出 wsdl.exe 從 SoftLayer API 服務產生的程式碼。

建立 Web 參照

建立 Web 參照是取用 SOAP WSDL 時所需要的第一個作業。請遵循下列步驟,在 Visual Studio 中建立「Web 參照」。

  1. 按一下 Visual Studio 中的「專案」功能表
  2. 專案功能表下拉方框中選取加入服務參照
  3. 按一下加入服務參照視窗中的進階按鈕

    附註:即會顯示服務參照設定視窗

  4. 按一下服務參照設定視窗中的加入 Web 參照按鈕
  5. URL 欄位中,輸入您想要使用的 SoftLayer API 服務的 WSDL 網址
  6. 按一下 URL 欄位右邊的綠色箭頭

    附註:Visual Studio 將下載 WSDL 檔案,並分析它包含的方法和資料類型。

  7. Web 參照名稱欄位中輸入新的 Web 參照的名稱
    附註:已加入該專案的 API 服務的任何參照都會透過此專案進行參照
  8. 按一下加入參照按鈕,以匯入新的 Web 服務

    附註:現在您將回到專案中,而且新的 API 服務將出現在 Visual Studio 的方案總管

此範例會建立一個稱為 "com.softlayer.api" 的服務參照,但您可以使用任何您喜歡的名稱來建立 Web 服務。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 - 將所產生的程式碼匯出至您專案階層內的路徑。在此情況下,我們會將程式碼儲存到 SoftLayer_API.cs 檔案。

指令的結尾處是您想要匯入的 API WSDLS 的網址清單(以空格分隔)。您可以匯入任意數量的 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_AccountService,而 SoftLayer_Hardware_Server 的服務類別名稱是 SoftLayer_Hardware_ServerService。服務物件有對應於 API 特性的內容,例如鑑別、起始設定參數、物件遮罩和結果限制。API 方法呼叫也是直接對這些物件發出。例如:

SoftLayer_AccountService accountService = new SoftLayer_AccountService();

連結鑑別

透過定義 authenticate 物件,使用 API 使用者名稱和金鑰來鑑別 API 呼叫。將鑑別物件的 usernameapiKey 內容設為 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 服務的 Init 參數類別名稱是 SoftLayer_AccountInitParameters,而 SoftLayer_Hardware_Server 服務的 Init 參數類別名稱是 SoftLayer_Hardware_ServerInitParameters。Init 參數物件各有單一整數類型 id 內容,其對應於您要查詢的 SoftLayer 物件的 ID 號碼。透過將 Init 參數物件設定至服務物件的 InitParameterValue 內容(其中 對應於您呼叫的 API 服務),即可將該物件連結至服務物件。
如果 API 呼叫未對應於特定的 SoftLayer 物件,您不需要將起始設定參數值連結至服務物件。下列程式碼 Snippet 概述此狀況:

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_AccountObjectMask,而 SoftLayer_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_AccountObjectMaskValue 內容指派給物件遮罩物件,將物件遮罩連結至 SoftLayer_Account 服務物件。

此範例會擷取帳戶的實際硬體記錄,以及該硬體的作業系統記錄、作業系統密碼、網路元件、該硬體所在的資料中心,和每一個硬體中的處理器數目:

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

使用結果限制

呼叫資料時,尤其是涉及從較大群組取回資訊 Snippet 的查詢,利用結果限制將大幅減少您等待傳回的時間。

透過建立新的 resultLimit 物件並將它連結到 API 服務物件,來限制 API 呼叫中的結果數。ResultLimit 有兩項內容:

  • limit:限制呼叫的結果數
  • offset:開始結果集的選用偏移

透過將服務物件的 resultLimitValue 內容設為您的結果限制物件,將新的結果限制連結至 API 服務物件。

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 服務。完成之後,即可在您的專案中使用最新的 SoftLayer 供應項目。

如果您使用 wsdl.exe 從 SoftLayer 的 API WSDL 產生程式碼檔案,則重新執行完整的 wsdl.exe 指令,將 SoftLayer 的最新 API WSDL 重新匯入您的專案中。

參照的 API 元件

服務

資料類型

方法