使用 APIs Explorer

本指南說明如何使用 APIs Explorer 試用 Cloud Monitoring API 方法。APIs Explorer 是附加至方法 REST API 參考資料頁面的小工具。這個面板的標題為「Try this API」(試試這個 API)。以下螢幕截圖顯示只有一個參數 (name) 的方法，在面板中會如何顯示：

APIs Explorer 小工具。

您可以使用 API Explorer 試用 Cloud Monitoring API 中的方法，完全不需要編寫任何程式碼。小工具會透過表單來顯示每個方法的參數。填寫表單、按一下「執行」按鈕，即可看到結果。

你也可以按一下 按鈕隱藏小工具，或按一下 按鈕將小工具展開為全螢幕。

「試試看！」按鈕

說明文件中可能會顯示如下的「試試看！」按鈕：

立即試用！

點選按鈕後，系統會開啟方法參考頁面上的 APIs Explorer。通常會填入適合範例的參數，但您可能必須編輯部分參數，才能與自己的專案相符，例如 [PROJECT_ID] 的值。

如要瞭解如何避免及修正錯誤，請參閱「疑難排解」一文。

存取 API Explorer

每個 REST API 方法的參考資料頁面都會附上 API Explorer。如要尋找小工具，請參閱方法的參考頁面，例如 metricDescriptors.list。

執行要求

大多數方法都有一些必要參數和一些選用參數。必填欄位會標上紅條，直到填寫完畢為止。為所有必要引數提供值後，即可執行要求。

metricDescriptors.list 方法會傳回專案中所有可用指標類型的描述元。唯一必要參數是 name 參數。

如要執行 metricDescriptors.list 方法，請按照下列步驟操作：

  1. 按一下「試試看！」
  2. 在 name 參數中，以 projects/[PROJECT_ID] 格式輸入專案 ID。請務必將 [PROJECT_ID] 替換為專案 ID。
  3. 按一下 [Execute] (執行)。如要執行指令，APIs Explorer 必須有權存取你的帳戶。出現提示時，選取帳戶並按一下「允許」。 存取權有時間限制，且僅限於您執行的 API 方法。

方法調用結果會顯示在具有綠色或紅色標題的方塊中。如果要求成功，方塊會顯示綠色標頭，內含 HTTP 狀態碼 200。方塊中會顯示呼叫結果：

方法呼叫成功的結果。

如果標題為紅色，表示含有 HTTP 失敗代碼，且方塊中含有錯誤訊息。如要瞭解如何解決錯誤，請參閱「疑難排解」。

提供其他參數

您看到的參數清單取決於 API 探索工具小工具附加的方法。舉例來說，metricDescriptors.list 方法的參數不只 name，但 name 是唯一必填的參數。

如果只提供專案名稱，您會取得專案中的所有指標描述元，數量相當龐大。如要將擷取範圍限制在較小的集合，請使用 filter 參數。

舉例來說，如要只列出名稱結尾為 utilization 的指標類型，請執行下列操作：

  1. 按一下「試試看！」

  2. 在 name 參數中，以 projects/[PROJECT_ID] 格式輸入專案 ID。請務必將 [PROJECT_ID] 替換為專案 ID。

  3. 確認 filter 參數的值為 metric.type=ends_with("utilization")

  4. 按一下「執行」，並完成授權對話方塊。

標準參數

根據預設，API Explorer 顯示的參數集會對應至相關聯方法的參數。不過，API Explorer 小工具也有一組額外參數，不屬於方法本身。如要顯示額外參數，請按一下「顯示標準參數」：

切換顯示標準參數。

如要隱藏顯示畫面中的額外參數，請按一下「隱藏標準參數」。

最有用的標準參數是 fields 參數。這個參數可讓您選取要顯示的傳回輸出內容中的欄位。

舉例來說，列出結尾為 utilization 的指標描述元，仍會傳回許多結果。如果您只想知道指標類型的名稱和說明，可以使用 fields 參數指定這項限制。

如要查看設定 fields 參數的結果，請按照下列步驟操作：

  1. 按一下「試試看！」

  2. 在 name 參數中，以 projects/[PROJECT_ID] 格式輸入專案 ID。請務必將 [PROJECT_ID] 替換為專案 ID。

  3. 確認 filter 參數的值為 metric.type=ends_with("utilization")

  4. 按一下「顯示標準參數」，確認「fields」參數的值為 metricDescriptors.type,metricDescriptors.description

  5. 按一下「執行」，並完成授權對話方塊。

執行這項要求只會傳回每個指標的 type (簡短名稱) 和 description。

疑難排解

本節說明使用 API Explorer 時的常見問題。

如要進一步瞭解如何使用 Cloud Monitoring API，請參閱「排解 Cloud Monitoring API 問題」。

篩選器語法無效

您複製多行運算式並貼到 API Explorer 顯示的欄位中，但 API Explorer 顯示錯誤訊息。

做法：確保字串位於同一行。

"query": "sum by (instance_name) (rate({\"compute.googleapis.com/instance/disk/read_bytes_count\", monitored_resource=\"gce_instance\"}[5m]))"

請勿：複製及貼上換行或新行字元。

舉例來說，如果您在 timeSeries.query 方法中加入下列內容，API Explorer 就會顯示 Select an underlined section to see more details 錯誤訊息：

"query": "sum by (instance_name) (
                   rate(
                      {\"compute.googleapis.com/instance/disk/read_bytes_count\",
                          monitored_resource=\"gce_instance\"
                     }[5m]
                  )
               )"

專案 ID 無效

如果專案 ID 無效，API 要求就會失敗，並傳回 HTTP 400 錯誤。

如要解決這個問題，請確認文字 [PROJECT_ID] 已替換為專案 ID。

表單值無效

如果 API 要求失敗或傳回非預期的值，請檢查所有表單參數。

API Explorer 參數需要特定格式。格式設定錯誤可能會導致錯誤，也可能被接受，但會視為 API 方法中的拼字錯誤：

  • 請勿在任何類型的參數值前後加上引號。

  • 除非需要保護子字串，否則請勿使用反斜線。

    舉例來說，以下範例適用於 API 方法，您會以 JSON 格式輸入內容，而不是填寫個別表單參數。由於 filter 的值是字串，因此子字串 k8s_cluster 會受到反斜線保護：

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }
  • 篩選器內顯示的字串加上引號。請使用雙引號 (")，而非單引號 (')。如需範例，請參閱「提供其他參數」。
  • 請勿在表單中使用網址編碼。如果 API 方法需要進行網址編碼，小工具會在您執行方法時進行轉換。

傳回的資料過多

如要限制傳回的結果數量，請在 pageSize 參數中輸入值，例如 2。pageSize 參數會定義傳回的結果數上限，適用於大多數 API 方法。

如要選取要傳回的特定欄位，請使用 fields 參數。詳情請參閱標準參數。

驗證

API Explorer 頁面上有「憑證」部分。建議您保留這些欄位的預設值。預設驗證機制為 Google OAuth 2.0。

如要瞭解方法所需的 API 範圍，請按一下「顯示範圍」。根據預設，系統會授予所有必要範圍。

如要進一步瞭解這些概念，請參閱「使用身分與存取權管理功能控管存取權」一文。