SoftLayer API 概觀

SoftLayer 的「應用程式設計介面 (API)」是開發介面,它讓開發者和系統管理者能夠與 SoftLayer 的後端系統直接互動。我們的 API 所公開的功能可讓使用者執行遠端伺服器管理、監視,以及從 SoftLayer 的各種系統擷取資訊,例如會計、庫存和 DNS。我們的 API 在 SoftLayer 客戶入口網站中賦予許多特性能力,這通常表示如果可以在「客戶入口網站」進行互動,則一樣可以在我們的 API 中進行。

誰應該使用 API?

SoftLayer API (SLAPI) 可免費提供給所有 SoftLayer 客戶使用。我們鼓勵具備物件導向程式設計基本知識的客戶充分利用 SLAPI 提供的功能。雖然 SoftLayer 客戶使用 SLAPI 執行各種不同的作業,然而以程式設計方式與 API 內 SoftLayer 環境的所有部分進行互動的能力,會導致大部分客戶都使用 SLAPI 執行自動化作業。

使用 SoftLayer API

開始之前

SLAPI 讓使用者能夠與執行「客戶入口網站」的物件直接互動。在針對 SLAPI 進行開發之前,瞭解基本物件導向程式設計概念將大有幫助,例如物件、內容、方法和繼承。SLAPI 的方法是針對後端系統中的服務物件執行,其傳回 SoftLayer 專用的資料類型物件和標準資料類型,如整數、布林和字串。
SLAPI 是「遠端程序呼叫」系統。每一個呼叫需要向 API 端點傳送資料,反過來則接收結構化資料。透過 SLAPI 傳送及接收資料時使用何種格式,視您選擇哪一個 API 實作而定。SLAPI 目前使用 SOAPXML-RPCREST 進行資料傳輸。在發出 API 呼叫之前,瞭解如何在程式設計中或 Scripting 語言中使用這些通訊協定會很有幫助。您可以在應用程式中使用任何實作。在我們的 Github 設定檔中,我們也提供了許多的服務專用 API 用戶端,有各種我們支援的語言版本。

建立 API 使用者

對 SLAPI 的每一個呼叫都是透過「客戶入口網站」帳戶加以鑑別。「客戶入口網站」上的帳戶可包含多個使用者,我們高度建議建立唯一的「客戶入口網站」使用者來執行 API 呼叫。不論您是開發應用程式或是使用其他人所開發的 API 型應用程式,都必須 在程式內進行鑑別,才能存取相關資訊以及與帳戶進行任何層面的互動。對 SLAPI 進行鑑別需要「客戶入口網站」使用者名稱和 API 金鑰(這是保留給 API 方法呼叫的特殊鑑別記號)。定義在「客戶入口網站」中的使用者許可權反映在 API 呼叫中。

選擇公有或私密網路

SLAPI 端點伺服器存在於 SoftLayer 的公有和私密網路上。您的 API 型應用程式可從網際網路上的任何主機進行連接;但是,SoftLayer 的私密網路提供額外一層資料安全。此外,SoftLayer 還提供各種不同的私密網路 API 端點,只有連接到該私密網路時才可加以存取。所有與 SoftLayer 帳戶相關聯的伺服器和運算執行實例,與私密網路之間都有直接連線,不需要進行額外的鑑別。如果您想要從另一個裝置使用私人端點,則需要透過 VPN 連線到我們的私密網路。

基本 API 概念

服務

服務是與內部 SoftLayer 系統相關聯的端點。每一個服務都是可執行的方法或動作的集合。您可以在本網站的參照區段中找到所有 SLAPI 服務的清單。
在存取所要的 API 的「服務」區段時,所有可用服務的清單會顯示在螢幕左邊。所有 SoftLayer 服務的開頭都是 "SoftLayer_",並包含其他詞彙來定義該服務提供的一般功能:"Hardware"、"Account"、"Billing"、"Network" 等。每一個服務都是從該處延伸,其名稱定義服務該在特定子集內的特定功能。與 SoftLayer API 相關聯的每一個服務都有唯一名稱。雖然有些服務如 SoftLayer_Account 和 SoftLayer_Account_Address 可能共用共同的字首,但其互動未必類似,而且並未直接繼承類似名稱的服務。因此,每一個服務應個別處理之。
若要檢視特定服務的詳細資訊,請按一下服務名稱。每一個服務的頁面包括該服務可用的方法清單,其中有許多也包含簡要概觀來說明該服務。雖然每一個服務都提供一組唯一的方法,但有許多服務都提供 getObject 方法。您可以使用這些方法,從 API 擷取相同類型的物件。例如,對 SoftLayer_Network_Subnet 服務呼叫 getObject 方法將傳回 SoftLayer_Network_Subnet 資料類型物件。

方法

方法是可對 SLAPI 服務執行的特定動作。每一個方法傳回純量或結構化資料類型,而且可能需要特定的參數、許可權或標頭才能執行。方法參數應使用每一個語言或端點的文件所說明的技術來傳遞。在需要多個參數的狀況下,請依參數出現在「方法」頁面上的順序由上往下傳遞參數。以下的擷取畫面顯示 SoftLayer_Monitoring_Agent::getGraph 方法的必要參數。執行此方法時,請依下列順序傳遞參數:configurationValues、beginDate、endDate。
NOT FOUND: parameters.png
每一個「方法」頁面上有包含參數、許可權和標頭的完整清單。

資料類型

資料類型是一種結構,包含純量值和其他資料類型的集合。除了傳統純量值如字串、bool 或 int 之外,SLAPI 亦使用複式資料類型,其所含內容可定義 SLAPI 中透過方法所傳遞及傳回的物件。每一個資料類型可能包含許多的區域關聯式計數內容。

區域內容

區域內容是資料類型的直屬子項。一般在呼叫 getObject() 時會傳回區域內容。當呼叫 createObject() 來建立此資料類型的執行實例時,部分(縱使非全部)區域內容是必要項目。

關聯式內容

關聯式內容是資料類型的間接子項。關聯式內容是定義在其他資料類型或其內容中。例如,SoftLayer_Account 資料類型有硬體的關聯式內容。此關聯式內容是 SoftLayer_Hardware 資料類型的陣列。指定了物件遮罩時,此內容將傳回一個陣列,它包含該帳戶上每一個硬體裝置的 SoftLayer_Hardware 物件。

計數內容

計數內容是一項便利內容,可用來判定與某內容相關聯的物件總數。例如,我們可使用包含了 Softlayer_Hardware_Server->networkVlanCount 的物件遮罩,來擷取與特定伺服器相關聯的虛擬區域網路總數。

進階 API 概念

除了一般的建立、讀取、更新及刪除動作之外,SLAPI 還可讓開發者定義如何透過使用特殊 API 呼叫標頭,從每一個呼叫傳回資料。這些標頭對 API 傳回的資料量有多一層控制。

結果限制

結果限制是一種支援方法,可讓您定義偏移和傳回的物件量。它容許大型資料集分頁。

物件遮罩

物件遮罩可讓使用者指定要從方法傳回的區域內容,以及擷取在關聯式內容和計數內容中找到的資訊。會建立對映或遮罩,來定義要包含在回覆值中的特定資料。例如,可在呼叫 SoftLayer_Hardware_Server::getObject 時指定 networkVlans.id 的物件遮罩,來收集 SoftLayer_Hardware_Server 上每一個虛擬區域網路的 ID。

精通 SLAPI 這門藝術的工作之一是要導覽所有物件遮罩來達到所要的結果。不僅如此,有多個方法可到達特定的資料點,其中有些方法的效率更好。

何去何從

既然您已知道基本觀念,就可以開始撰寫程式了。請參閱我們的「開始使用指南」,以瞭解如何建立 API 使用者及發出您的第一個呼叫。我們也針對特定語言提供了許多手冊:

其他有用的鏈結: