Skip to main content
Data Infrastructure Insights
本繁體中文版使用機器翻譯，譯文僅供參考，若與英文版本牴觸，應以英文版本為準。

Data Infrastructure InsightsAPI

貢獻者 netapp-alavoie dgracenetapp
PDF

Data Infrastructure InsightsAPI 使NetApp客戶和獨立軟體供應商 (ISV) 能夠將Data Infrastructure Insights與其他應用程式（例如 CMDB 或其他票務系統）整合。

您的Data Infrastructure Insights"功能集角色"將決定您可以存取哪些 API。使用者和來賓角色的權限比管理員角色的權限少。例如，如果您在監控和最佳化中具有管理員角色，但在報告中具有使用者角色，則您可以管理資料倉儲以外的所有 API 類型。

API 存取要求

  • API 存取令牌模型用於授予存取權限。

  • API 令牌管理由具有管理員角色的Data Infrastructure Insights使用者執行。

API 文件（Swagger）

透過登入Data Infrastructure Insights並導覽至 Admin > API Acccess 可以找到最新的 API 資訊。按一下*API 文件*連結。

API 類型

API 文件基於 Swagger，提供 API 的簡要描述和使用信息，並允許您在租戶中嘗試它。根據您的使用者角色和/或Data Infrastructure Insights版本，您可用的 API 類型可能會有所不同。

API Swagger 範例

API 存取令牌

在使用Data Infrastructure InsightsAPI 之前，您必須建立一個或多個 API 存取權杖。存取令牌用於指定的 API 類型，並且可以授予讀取和/或寫入權限。您也可以設定每個存取令牌的有效期。指定類型下的所有 API 對於存取令牌均有效。每個令牌都沒有使用者名稱或密碼。

若要建立存取權杖：

  • 點選“管理”>“API 存取”

  • 點選*+API 存取權令牌*

    • 輸入代幣名稱

    • 選擇 API 類型

    • 指定授予此 API 存取的權限

    • 指定令牌到期時間

註 您的令牌僅可在建立過程中複製到剪貼簿並儲存。令牌一旦創建就無法檢索，因此強烈建議複製令牌並將其保存在安全的位置。系統將提示您按一下「複製 API 存取令牌」按鈕，然後才能關閉令牌建立畫面。

您可以停用、啟用和撤銷令牌。已禁用的令牌可以啟用。

令牌從客戶角度授予對 API 的通用存取權；管理其自身租用戶範圍內對 API 的存取。客戶管理員可以授予和撤銷這些令牌，而無需Data Infrastructure Insights後端人員的直接參與。

使用者成功驗證並授權存取後，應用程式將收到存取令牌，然後在呼叫目標 API 時將存取令牌作為憑證傳遞。傳遞的令牌通知 API，令牌持有者已被授權存取 API 並執行授權期間授予的範圍指定的特定操作。

傳遞存取令牌的 HTTP 標頭是 X-CloudInsights-ApiKey:。

例如，使用以下命令檢索儲存資產：

 curl https://<tenant_host_name>/rest/v1/assets/storages -H 'X-CloudInsights-ApiKey:<API_Access_Token>'
其中 _<API_Access_Token>_ 是您在建立 API 存取期間所儲存的令牌。

請參閱 swagger 頁面以取得特定於您希望使用的 API 的範例。

API 類型

Data Infrastructure InsightsAPI 是基於類別的，目前包含以下類型：

  • ASSETS 類型包含資產、查詢和搜尋 API。

    • 資產：列舉頂級物件並檢索特定物件或物件層次結構。

    • 查詢：檢索和管理Data Infrastructure Insights查詢。

    • 導入：導入註釋或應用程式並將其指派給對象

    • 搜尋：無需知道物件的唯一 ID 或全名即可定位特定物件。

  • 資料收集類型用於檢索和管理資料收集器。

  • 資料攝取類型用於檢索和管理攝取資料和自訂指標，例如來自 Telegraf 代理程式的資料

  • LOG INGESTION 用於檢索和管理日誌數據

隨著時間的推移，可能會有更多類型和/或 API 可用。您可以在"API Swagger 文件"。

請注意，使用者可以存取的 API 類型也取決於"使用者角色"它們在每個Data Infrastructure Insights功能集（監控、工作負載安全、報告）中都有。

庫存遍歷

本節介紹如何遍歷Data Infrastructure Insights物件的層次結構。

頂級對象

請求中的各個物件透過唯一的 URL（在 JSON 中稱為「self」）進行標識，並且需要了解物件類型和內部 ID。對於某些頂級物件（主機、儲存體等），REST API 提供對完整集合的存取。

API URL 的一般格式為：

 https://<tenant>/rest/v1/<type>/<object>
例如，要從名為 _mysite.c01.cloudinsights.netapp.com_ 的租戶檢索所有存儲，請求 URL 為：
https://mysite.c01.cloudinsights.netapp.com/rest/v1/assets/storages

子對象和相關對象

頂級物件（例如儲存）可用於遍歷其他子物件和相關物件。例如，要檢索特定儲存的所有磁碟，請將儲存「self」URL 與「/disks」連接起來，例如：

https://<tenant>/rest/v1/assets/storages/4537/disks

擴充

許多 API 命令支援 expand 參數，該參數提供有關物件或相關物件的 URL 的更多詳細資訊。

一個常見的擴充參數是_expands_。回應包含該物件所有可用的特定擴充功能的清單。

例如，當您要求以下內容時：

 https://<tenant>/rest/v1/assets/storages/2782?expand=_expands
API 傳回物件的所有可用擴展，如下所示：

擴充範例

每個擴充功能都包含資料、URL 或兩者。 expand 參數支援多個和嵌套屬性，例如：

 https://<tenant>/rest/v1/assets/storages/2782?expand=performance,storageResources.storage
擴充功能允許您在一次回應中引入大量相關數據。  NetApp建議您不要一次要求太多資訊；這可能會導致效能下降。

為了防止這種情況發生，頂級收藏的請求不能擴大。例如，您不能一次要求擴充所有儲存物件的資料。客戶端需要檢索物件列表，然後選擇特定物件進行擴充。

效能數據

性能數據作為單獨的樣本從許多設備上收集。每小時（預設），Data Infrastructure Insights都會匯總並總結效能樣本。

API 允許存取樣本和匯總資料。對於具有效能資料的對象，效能摘要可用 expand=performance 表示。效能歷史時間序列可透過巢狀的_expand=performance.history_取得。

效能資料物件的範例包括：

  • 儲存效能

  • 儲存池效能

  • 港口績效

  • 磁碟效能

績效指標具有描述和類型，並包含一系列績效摘要。例如，延遲、流量和速率。

效能摘要包含描述、單位、採樣開始時間、採樣結束時間以及在一定時間範圍內（1 小時、24 小時、3 天等）從單一效能計數器計算得出的總計值集合（目前值、最小值、最大值、平均值等）。

API 效能範例

產生的效能資料字典具有以下鍵：

  • “self” 是物件的唯一 URL

  • “history” 是時間戳記和計數器值映射的列表

  • 每個其他字典鍵（“diskThroughput”等等）都是效能指標的名稱。

每個效能資料物件類型都有一組獨特的效能指標。例如，虛擬機器效能物件支援“diskThroughput”作為效能指標。每個支援的表現指標都屬於指標字典中呈現的某個「表現類別」。Data Infrastructure Insights支援本文後面列出的幾種效能指標類型。每個性能指標字典還將具有“描述”字段，該字段是該性能指標的人類可讀的描述和一組性能摘要計數器條目。

性能摘要計數器是性能計數器的總和。它呈現計數器的典型聚合值，如最小值、最大值和平均值，以及最新觀察值、總計資料的時間範圍、計數器的單位類型和資料的閾值。只有閾值是可選的；其餘屬性都是必需的。

有以下類型的計數器的效能摘要：

  • 讀取——讀取操作摘要

  • 寫入 – 寫入操作摘要

  • 總計 – 所有操作的摘要。它可能高於讀取和寫入的簡單總和；它可能包括其他操作。

  • Total Max – 所有操作的摘要。這是指定時間範圍內的最大總值。

對象性能指標

API 可以傳回租用戶上物件的詳細指標，例如：

  • 儲存效能指標，例如 IOPS（每秒輸入/輸出請求數）、延遲或吞吐量。

  • 交換器效能指標，例如流量利用率、BB 信用零資料或連接埠錯誤。

查看"API Swagger 文件"有關每個物件類型的指標的資訊。

效能歷史數據

歷史資料在效能資料中以時間戳記和計數器對映對的列表形式呈現。

歷史計數器根據效能指標物件名稱命名。例如，虛擬機器效能物件支援“diskThroughput”，因此歷史記錄圖將包含名為“diskThroughput.read”、“diskThroughput.write”和“diskThroughput.total”的按鍵。

註 時間戳記採用 UNIX 時間格式。

以下是磁碟效能資料 JSON 的範例：

磁碟效能 JSON

具有容量屬性的對象

具有容量屬性的物件使用基本資料類型和CapacityItem來表示。

容量項目

CapacityItem 是容量的單一邏輯單位。它具有由其父對象定義的單位的“值”和“高閾值”。它還支援可選的細分圖，解釋容量值是如何建構的。例如，100 TB 儲存池的總容量將是值為 100 的 CapacityItem。細分結果可能顯示 60 TB 分配給“資料”，40 TB 分配給“快照”。

注意：「highThreshold」代表系統為相應指標定義的閾值，客戶端可以使用它來對超出可接受配置範圍的值產生警報或視覺提示。

下面顯示了具有多個容量計數器的 StoragePools 的容量：

儲存池容量範例

使用搜尋查找對象

搜尋 API 是系統的簡單入口點。 API 的唯一輸入參數是自由格式的字串，產生的 JSON 包含分類的結果清單。類型是與庫存不同的資產類型，例如儲存、主機、資料儲存等。每種類型都包含符合搜尋條件的該類型的物件清單。

Data Infrastructure Insights是一種可擴展（廣泛開放）的解決方案，允許與第三方編排、業務管理、變更控制和票務系統以及自訂 CMDB 整合。

Cloud Insight 的 RESTful API 是一個主要的整合點，它允許簡單有效地移動數據，並允許用戶無縫存取他們的數據。

停用或撤銷 API 令牌

若要暫時停用 API 令牌，請在 API 令牌清單頁面上，按一下 API 的「三個點」選單，然後選擇_停用_。您可以隨時使用相同的選單並選擇“啟用”來重新啟用令牌。

若要永久刪除 API 令牌，請從選單中選擇「撤銷」。您無法重新啟用已撤銷的令牌；您必須建立一個新的令牌。

停用或撤銷 API 令牌

輪換過期的 API 存取令牌

API 存取令牌有一個有效期限。當 API 存取令牌過期時，使用者需要產生一個新令牌（類型為“資料提取”，具有讀取/寫入權限）並重新配置 Telegraf 以使用新產生的令牌而不是過期的令牌。以下步驟詳細說明如何執行此操作。

Kubernetes

請注意，這些命令使用預設命名空間“netapp-monitoring”。如果您設定了自己的命名空間，請在這些命令和所有後續命令和檔案中取代該命名空間。

注意：如果您安裝了最新的NetApp Kubernetes Monitoring Operator 並使用可續訂的 API 存取令牌，則過期的令牌將自動被新的/刷新的 API 存取權令牌取代。無需執行下面列出的手動步驟。

  • 建立一個新的 API 令牌。

  • 請依照以下步驟操作"手動升級"，選擇新的 API 令牌。

注意：使用設定管理工具（例如 Kustomize）管理其NetApp Kubernetes Monitoring Operator 的客戶可以按照相同的步驟產生並下載一組更新的 YAML 以推送到他們的儲存庫。

RHEL/CentOS 和 Debian/Ubuntu

  • 編輯 Telegraf 設定文件，並用新的 API 令牌取代舊 API 令牌的所有實例。

     sudo sed -i.bkup ‘s/<OLD_API_TOKEN>/<NEW_API_TOKEN>/g’ /etc/telegraf/telegraf.d/*.conf
* 重新啟動 Telegraf。
    sudo systemctl restart telegraf

視窗

  • 對於 C:\Program Files\telegraf\telegraf.d 中的每個 Telegraf 設定文件，用新的 API 令牌取代舊 API 令牌的所有實例。

    cp <plugin>.conf <plugin>.conf.bkup
(Get-Content <plugin>.conf).Replace(‘<OLD_API_TOKEN>’, ‘<NEW_API_TOKEN>’) | Set-Content <plugin>.conf

  • 重新啟動 Telegraf。

    Stop-Service telegraf
Start-Service telegraf