Visual Basic .NET

取用 SOAP WSDL

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

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

建立 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 的方案總管中。

使用 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 - 將所產生的程式碼匯出至您專案階層內的路徑。在此情況下,我們會將程式碼儲存到 SoftLayer_API.vb 檔案。

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

Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()

連結鑑別

透過定義 authenticate 物件,使用 API 使用者名稱和金鑰來鑑別 API 呼叫。將鑑別物件的 usernameapiKey 內容設為 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 服務的 Init 參數類別名稱是 SoftLayer_AccountInitParameters,而 SoftLayer_Hardware_Server 服務的 Init 參數類別名稱是 SoftLayer_Hardware_ServerInitParameters。Init 參數物件各有單一整數類型 ID 內容,其對應於您要查詢的 SoftLayer 物件的 ID 號碼。透過將 Init 參數物件設定至服務物件的 InitParameterValue 內容(其中 對應於您呼叫的 API 服務),即可將該物件連結至服務物件。
如果 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_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_AccountObjectMaskValueproperty 指派給物件遮罩物件,將物件遮罩連結至 SoftLayer_Account 服務物件。

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

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

使用結果限制

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

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

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

透過將服務物件的 resultLimitValue 內容設為您的結果限制物件,將新的結果限制連結至 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
 
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 服務,然後即可在您的專案中使用最新的 SoftLayer 供應項目。
如果您使用 wsdl.exe 從 SoftLayer 的 API WSDL 產生程式碼檔案,則重新執行完整的 wsdl.exe 指令,將 SoftLayer 的最新 API WSDL 重新匯入您的專案中。

參照的 API 元件

服務

資料類型

方法