跳至主要内容

先前的 v3 Rancher API 指南

Rancher v2.8.0 引入了 Rancher Kubernetes API (RK-API)。先前的 v3 Rancher API 仍然可用。本頁面描述 v3 API。有關 RK-API 的更多資訊,請參閱 RK-API 快速入門和參考指南。

如何使用 API​

先前的 v3 API 具有自己的使用者介面,可從網頁瀏覽器存取。這是檢視資源、執行操作以及檢視等效的 curl 或 HTTP 請求與回應的簡單方法。要存取它:

  1. 點選右上角的使用者頭像。
  2. 點選 Account & API Keys。
  3. 在 API Keys 區段下,找到 API Endpoint 欄位並點選連結。連結看起來類似 https://<RANCHER_FQDN>/v3,其中 <RANCHER_FQDN> 是您 Rancher 部署的完整網域名稱。

認證​

API 請求必須包含認證資訊。認證是使用 API 金鑰透過 HTTP 基本認證完成的。API 金鑰可以建立新叢集,並透過 /v3/clusters/ 存取多個叢集。叢集和專案角色適用於這些金鑰,並限制帳戶可以看到哪些叢集和專案以及可以執行哪些操作。

預設情況下,某些叢集級別的 API token 會以無限的存活時間 (ttl=0) 產生。換句話說,具有 ttl=0 的 API token 永不過期,除非您將其作廢。有關如何使其作廢的詳細資訊,請參閱 API token 頁面。

發出請求​

API 通常是 RESTful 的,但具有多項功能,使客戶端可以發現所有內容的定義,以便可以編寫通用客戶端,而不必為每種類型的資源編寫特定程式碼。有關通用 API 規範的詳細資訊,請參閱進一步的文件。

  • 每種類型都有一個 Schema,描述:
    • 用於存取此類型資源集合的 URL。
    • 資源可以擁有的每個欄位,以及它們的類型、基本驗證規則、是必填還是選填等。
    • 此類型資源上可能的每個操作,及其輸入和輸出 (也作為 schema)。
    • 允許篩選的每個欄位。
    • 集合本身或集合中的個別資源可用的 HTTP 動詞方法。

此設計允許您只載入 schema 列表並存取有關 API 的所有內容。API 的 UI 不包含任何特定於 Rancher 本身的程式碼。用於取得 Schema 的 URL 會作為 X-Api-Schemas 標頭在每個 HTTP 回應中傳送。從那裡,您可以遵循每個 schema 上的 collection 連結來了解在哪裡列出資源,並遵循回傳資源內的其他 links 以取得任何其他資訊。

實際上,您可能只想建構 URL 字串。我們強烈建議將此限制在頂層以列出集合 (/v3/<type>) 或取得特定資源 (/v3/<type>/<id>)。比這更深的任何內容在未來版本中都可能會變更。

資源之間具有稱為連結的關係。每個資源都包含一個 links 映射,其中包含連結的名稱和您可以擷取該資訊的 URL。同樣,您應該 GET 資源,然後遵循 links 映射中的 URL,而不是自己建構這些字串。

大多數資源都有操作,這些操作會執行某些操作或變更資源的狀態。要使用它們,請向您想要的操作的 actions 映射中的 URL 傳送 HTTP POST。某些操作需要輸入或產生輸出。請參閱每種類型的個別文件或 schema 以了解具體資訊。

要編輯資源,請向資源上的 links.update 連結傳送 HTTP PUT,並包含您想要變更的欄位。如果連結遺失,則您沒有更新資源的權限。未知欄位和不可編輯的欄位將被忽略。

要刪除資源,請向資源上的 links.remove 連結傳送 HTTP DELETE。如果連結遺失,則您沒有更新資源的權限。

要建立新資源,請向 schema 中的集合 URL (即 /v3/<type>) 傳送 HTTP POST。

篩選​

大多數集合可以使用 HTTP 查詢參數按常見欄位在伺服器端進行篩選。filters 映射會顯示可以篩選哪些欄位,以及您發出的請求的篩選值。API UI 具有設定篩選和顯示適當請求的控制項。對於簡單的「等於」匹配,只需使用 field=value。可以在欄位名稱中新增修飾符,例如,field_gt=42 表示「欄位大於 42」。有關完整詳細資訊,請參閱 API 規範。

排序​

大多數集合可以使用 HTTP 查詢參數按常見欄位在伺服器端進行排序。sortLinks 映射會顯示可用的排序方式,以及按該方式排序的集合的 URL。它還包含有關當前回應按什麼排序的資訊 (如果有指定)。

分頁​

API 回應預設每頁限制為 100 個資源的分頁。這可以透過 limit 查詢參數變更,最多為 1000,例如,/v3/pods?limit=1000。集合回應中的 pagination 映射會告訴您是否擁有完整的結果集,如果沒有,則會提供下一頁的連結。

擷取 v3 API 呼叫​

您可以使用瀏覽器開發者工具來擷取 v3 API 的呼叫方式。例如,您可以按照以下步驟使用 Chrome 開發者工具取得用於佈建 Rancher Kubernetes 發行版叢集的 API 呼叫:

  1. 在 Rancher UI 中,前往 Cluster Management 並點選 Create。
  2. 點選其中一種叢集類型。此範例使用 Digital Ocean。
  3. 填寫表單,包含叢集名稱和節點範本,但不要點選 Create。
  4. 您需要在建立叢集之前開啟開發者工具,以查看正在記錄的 API 呼叫。要開啟工具,請在 Rancher UI 上按右鍵並點選 Inspect。
  5. 在開發者工具中,點選 Network 標籤。
  6. 在 Network 標籤上,確保選擇了 Fetch/XHR。
  7. 在 Rancher UI 中,點選 Create。在開發者工具中,您應該會看到一個名為 cluster?_replace=true 的新網路請求。
  8. 在 cluster?_replace=true 上按右鍵並點選 Copy > Copy as cURL。
  9. 將結果貼上到任何文字編輯器中。您可以看到 POST 請求,包括傳送到的 URL、所有標頭和請求的完整主體。此指令可用於從命令列建立叢集。注意:請求應儲存在安全的地方,因為它包含憑證。

啟用在 API 中檢視​

您還可以檢視各自叢集和資源的已擷取 v3 API 呼叫。此功能預設未啟用。要啟用它:

  1. 點選 UI 右上角的 User Tile,並從下拉式選單中選擇 Preferences。
  2. 在 Advanced Features 區段下,點選 Enable "View in API"

勾選後,View in API 連結會顯示在 UI 中資源頁面的 ⋮ 子選單下。